Ir al contenido principal
Español— Elegir un idioma
Menú

Versionado de prompts y gestión del catálogo

Lección 14 de 16 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Versionado de prompts y gestión del catálogo
  2. Por qué versionar los prompts
  3. Estructura del catálogo
  4. Uso del catálogo en tu aplicación
  5. Versionado con Git
  6. Buenas prácticas
  7. Prueba del catálogo con una reversión
  8. Puntos clave

Lección actualizada el 3 de noviembre de 2026 según la documentación de OpenAI: temperature y top_p solo se aceptan con un esfuerzo de razonamiento de none, mientras que los modelos GPT-5.6 razonan por defecto (medium). Por tanto, las llamadas que establezcan estos parámetros deben especificar reasoning={"effort": "none"} (API de Responses) o reasoning_effort="none" (Chat Completions). Fuentes: Uso de GPT-6 · GPT-5.6 Terra.

En producción, tus prompts evolucionan tanto como tu código. Sin un sistema de versionado, pierdes el rastro de los cambios, no puedes revertir a versiones anteriores y desconoces qué versión se está ejecutando en producción. Esta lección te muestra cómo gestionar los prompts como artefactos de software.

Por qué versionar los prompts

Un cambio en un prompt puede alterar radicalmente el comportamiento de tu aplicación. A diferencia del código, estos cambios suelen ser sutiles y difíciles de detectar sin pruebas automatizadas: una frase reformulada, una palabra desplazada, y el modelo comienza a clasificar mal uno de cada diez casos límite. Ninguna prueba unitaria estándar detectará esta brecha, pero el equipo de soporte la señalará tres semanas después como una queja vaga sobre tickets mal derivados.

El versionado responde a cuatro necesidades distintas. Primero, la trazabilidad: saber quién cambió qué y cuándo convierte un debate estéril en el equipo en una simple consulta del historial. Segundo, la reversión (rollback): cuando aparece una regresión, el objetivo inmediato no es entender el porqué, sino restaurar un comportamiento conocido. Tercero, la comparación de rendimiento: esto exige que las versiones antiguas sigan siendo ejecutables exactamente como fueron, con su modelo y configuración originales. Por último, la auditoría: para sistemas sujetos al RGPD (Reglamento General de Protección de Datos) u otros marcos de cumplimiento, debes demostrar qué instrucciones estaban vigentes en una fecha determinada; una captura de pantalla no es suficiente.

La clase PromptCatalog satisface estas necesidades con una infraestructura mínima: una carpeta por prompt, un archivo JSON por versión, numerados secuencialmente. Cada archivo agrupa el texto del prompt del sistema junto con el modelo y la temperatura asociados; un prompt ajustado a 0,1 y ese mismo prompt a 0,7 no son lo mismo, y bloquearlos juntos evita restaurar el texto olvidando su configuración.

El campo status rastrea el ciclo de vida. Una versión comienza como draft (borrador), lo que permite la preparación y las pruebas sin afectar al tráfico en vivo. Llamar a activate la cambia a active (activa) y degrada automáticamente la versión anterior a deprecated (obsoleta), garantizando que solo una versión sirva tráfico en cualquier momento. Este método hace que la reversión sea trivial: reactivar una versión anterior es una única llamada, no un despliegue. Tu aplicación llama a get_active en producción, mientras que list_versions facilita las revisiones y auditorías.

import json
from datetime import datetime
from pathlib import Path

class PromptCatalog:
    """Gestor de catálogo de prompts con versionado."""

    def __init__(self, catalog_dir: str = "prompts/"):
        self.catalog_dir = Path(catalog_dir)
        self.catalog_dir.mkdir(parents=True, exist_ok=True)

    def save_prompt(self, name: str, system_prompt: str,
                    model: str, temperature: float,
                    metadata: dict = None) -> str:
        """Guarda una nueva versión de un prompt."""
        prompt_dir = self.catalog_dir / name
        prompt_dir.mkdir(exist_ok=True)

        # Determinar el número de versión
        versions = sorted(prompt_dir.glob("v*.json"))
        version = len(versions) + 1
        version_str = f"v{version:03d}"

        # Guardar
        prompt_data = {
            "name": name,
            "version": version_str,
            "created_at": datetime.now().isoformat(),
            "model": model,
            "temperature": temperature,
            "system_prompt": system_prompt,
            "metadata": metadata or {},
            "status": "draft"  # draft | active | deprecated
        }

        filepath = prompt_dir / f"{version_str}.json"
        filepath.write_text(json.dumps(prompt_data, indent=2,
                                        ensure_ascii=False))

        return version_str

    def get_prompt(self, name: str,
                   version: str = "latest") -> dict:
        """Recupera un prompt por nombre y versión."""
        prompt_dir = self.catalog_dir / name

        if version == "latest":
            versions = sorted(prompt_dir.glob("v*.json"))
            if not versions:
                raise FileNotFoundError(f"Prompt '{name}' no encontrado")
            filepath = versions[-1]
        else:
            filepath = prompt_dir / f"{version}.json"

        return json.loads(filepath.read_text())

    def get_active(self, name: str) -> dict:
        """Recupera la versión activa de un prompt."""
        prompt_dir = self.catalog_dir / name
        for filepath in sorted(prompt_dir.glob("v*.json"),
                               reverse=True):
            data = json.loads(filepath.read_text())
            if data["status"] == "active":
                return data
        raise FileNotFoundError(
            f"No hay versión activa para '{name}'"
        )

    def activate(self, name: str, version: str):
        """Activa una versión y desactiva las demás."""
        prompt_dir = self.catalog_dir / name

        for filepath in prompt_dir.glob("v*.json"):
            data = json.loads(filepath.read_text())
            if data["version"] == version:
                data["status"] = "active"
            elif data["status"] == "active":
                data["status"] = "deprecated"
            filepath.write_text(json.dumps(data, indent=2,
                                            ensure_ascii=False))

    def list_versions(self, name: str) -> list[dict]:
        """Lista todas las versiones de un prompt."""
        prompt_dir = self.catalog_dir / name
        versions = []
        for filepath in sorted(prompt_dir.glob("v*.json")):
            data = json.loads(filepath.read_text())
            versions.append({
                "version": data["version"],
                "status": data["status"],
                "created_at": data["created_at"],
                "model": data["model"]
            })
        return versions

Uso del catálogo en tu aplicación

Por parte del llamador, la regla es simple: tu código no contiene texto de prompt; solicita la versión activa al catálogo. Esto mantiene los prompts modificables sin tocar el código de la aplicación y evita que cadenas de treinta líneas queden enterradas en medio de una función. Los metadatos guardados durante el almacenamiento —autor, descripción, registro de cambios— no tienen efecto en la ejecución, pero hacen que el historial sea legible seis meses después, cuando nadie recuerda por qué cambió la redacción.

El detalle crítico reside al final de classifier_ticket: la respuesta devuelta incluye prompt_version. Registra este campo con cada resultado y el análisis de incidentes será posible; sabrás que los tickets mal clasificados de la tarde del martes provenían todos de la v004, sin necesidad de cruzar marcas de tiempo de despliegue.

from openai import OpenAI

client = OpenAI()
catalog = PromptCatalog("prompts/")

# Guardar un prompt
catalog.save_prompt(
    name="ticket-classifier",
    system_prompt="""Eres un clasificador de tickets de soporte.
Categoriza cada ticket como: bug, feature, question, billing.
Responde en JSON con category, priority (1-5), summary.""",
    model="gpt-5.6-terra",
    temperature=0.1,
    metadata={
        "author": "marie.dupont",
        "description": "Clasificación automática de tickets de Zendesk",
        "changelog": "Versión inicial"
    }
)

# En producción: usar la versión activa
def classifier_ticket(ticket_text: str) -> dict:
    """Clasifica un ticket usando el prompt activo."""
    prompt_config = catalog.get_active("ticket-classifier")

    response = client.responses.create(
        model=prompt_config["model"],
        reasoning={"effort": "none"},  # temperature requiere effort none
        instructions=prompt_config["system_prompt"],
        input=ticket_text,
        temperature=prompt_config["temperature"]
    )

    return {
        "result": json.loads(response.output_text),
        "prompt_version": prompt_config["version"]
    }

Versionado con Git

Para equipos, guarda tus prompts en un repositorio Git dedicado. El árbol siguiente sigue una convención simple: una carpeta por prompt, que contiene su definición, casos de prueba y registro de cambios. Mantener las pruebas junto al prompt que verifican no es cosmético; una pull request modifica ambos juntos, y el revisor juzga el cambio basándose en pruebas y no en intenciones declaradas.

prompts/
  ticket-classifier/
    prompt.yaml
    tests/
      test_cases.json
    CHANGELOG.md
  invoice-extractor/
    prompt.yaml
    tests/
      test_cases.json
    CHANGELOG.md

YAML reemplaza aquí a JSON por una razón específica: los prompts son textos multilínea, y la sintaxis | los muestra exactamente como se envían, sin caracteres de escape ni \n extraños. Un diff de Git en este archivo se lee como un diff de prosa: el revisor ve que se ha añadido una frase. El esquema de salida viaja en el mismo archivo, de modo que la configuración completa de una llamada cabe en un único artefacto.

# prompts/ticket-classifier/prompt.yaml
name: ticket-classifier
model: gpt-5.6-terra
temperature: 0.1
max_output_tokens: 500
system_prompt: |
  Eres un clasificador de tickets de soporte.
  Categoriza cada ticket como: bug, feature, question, billing.
  Responde en JSON con category, priority (1-5), summary.
schema:
  type: object
  properties:
    category:
      type: string
      enum: [bug, feature, question, billing]
    priority:
      type: integer
    summary:
      type: string
  required: [category, priority, summary]
  additionalProperties: false

Buenas prácticas

Lo que separa un catálogo vivo de una carpeta de archivo se reduce a unas pocas reglas de mantenimiento. Mantén un prompt por archivo: mezclar múltiples prompts en un solo documento hace que los diffs sean ilegibles y las reversiones imposibles de dirigir. Exige un registro de cambios que documente no qué cambió —el diff ya muestra eso—, sino por qué: «añadida instrucción sobre tickets multilingües tras comentarios de soporte» vale más que diez líneas de descripción técnica.

Asocia sistemáticamente un conjunto de pruebas a cada prompt; de lo contrario, serán los usuarios los primeros en avisarte cuando una modificación rompa un comportamiento establecido. Canaliza los cambios de prompt a través del mismo proceso de revisión de código que el código mismo: un prompt que llega a producción sin revisión produce las mismas sorpresas que un código no revisado. Verifica que la reversión tome menos de un minuto y pruébala en un día tranquilo, no durante un incidente. Por último, marca las versiones desplegadas con etiquetas para vincular sin ambigüedades el comportamiento observado con un estado específico del repositorio.

Prueba del catálogo con una reversión

Configura un PromptCatalog para tres prompts reales de tu aplicación y registra dos o tres versiones de cada uno evolucionando las instrucciones en pequeños pasos: una instrucción de tono, una categoría añadida. El versionado demuestra su valía en estos cambios de grano fino, porque son los que no recordarás haber hecho. Configura la activación y desactivación, y adjunta un conjunto de pruebas a cada prompt.

Termina con el ejercicio más instructivo: activa deliberadamente una versión degradada, observa la regresión mediante las pruebas y ejecuta la reversión cronometrándola. Si la operación supera el minuto, arregla el procedimiento antes de añadir un solo prompt al catálogo; una reversión lenta no es una reversión, es un incidente prolongado.

Puntos clave

  • Los prompts son artefactos de software que requieren versionado
  • Cada versión es un archivo JSON o YAML con metadatos
  • El estado (draft, active, deprecated) permite un despliegue gradual
  • Almacena los prompts en Git con pruebas y un registro de cambios
  • La reversión debe ser instantánea en caso de regresión