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

Buenas prácticas para producción

Lección 17 de 22 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Buenas prácticas para producción
  2. 1. Arquitectura del cliente
  3. 2. Gestión de prompts
  4. 3. Tiempos de espera y límites
  5. 4. Recuperación ante fallos de modelo (Fallback)
  6. 5. Procesamiento por lotes
  7. 6. Pruebas y validación
  8. 7. Lista de comprobación para despliegue en producción
  9. 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.

Buenas prácticas para producción

Esta lección cubre las buenas prácticas esenciales para desplegar una aplicación basada en la API de OpenAI en producción. Piensa en esto como tu lista de comprobación previa al lanzamiento. Las lecciones anteriores te han proporcionado los bloques de construcción: gestión de errores, límites de tasa, resiliencia, observabilidad y costes. Ahora es el momento de ensamblarlos en una aplicación que un compañero pueda asumir y ejecutar sin tu intervención.

1. Arquitectura del cliente

Singleton con configuración centralizada

Instanciar un cliente de OpenAI en cada llamada desperdicia la conexión HTTP subyacente y, lo que es más grave, dispersa tu configuración. Acabas teniendo un tiempo de espera de 30 segundos aquí y el valor predeterminado allá, sin forma de saber cuál se aplica en producción. El decorador lru_cache garantiza una única instancia, configurada en un solo lugar.

from openai import OpenAI
from functools import lru_cache

@lru_cache(maxsize=1)
def get_client() -> OpenAI:
    """Cliente singleton con configuración de producción."""
    return OpenAI(
        max_retries=3,
        timeout=30.0,
    )

# En cualquier parte de tu código:
client = get_client()

Variables de entorno

El mismo principio se aplica a los ajustes que varían entre entornos. Comprueba las variables requeridas al inicio: es preferible que un servicio se niegue a arrancar con un mensaje claro a que arranque y falle en la primera llamada de usuario. Esto permite ajustar el modelo, el límite de tokens y la temperatura sin necesidad de un nuevo despliegue.

import os

# REQUERIDO: nunca hardcodees claves
REQUIRED_ENV = ["OPENAI_API_KEY"]

for var in REQUIRED_ENV:
    if not os.environ.get(var):
        raise RuntimeError(f"Falta la variable {var}")

# Configuración específica del entorno
MODEL = os.environ.get("OPENAI_MODEL", "gpt-5.6-terra")
MAX_TOKENS = int(os.environ.get("OPENAI_MAX_TOKENS", "4096"))
TEMPERATURE = float(os.environ.get("OPENAI_TEMPERATURE", "0.7"))

2. Gestión de prompts

Separa los prompts del código

Un prompt es un activo empresarial, al igual que una regla de negocio. Enterrarlo en una f-string dentro de una función hace imposible que alguien que conoce el negocio pero no Python pueda revisarlo. Aíslalo como una plantilla parametrizada: la función se reduce entonces a formatear y llamar, y una temperatura de 0,0 hace que la clasificación sea reproducible.

# prompts/classification.txt
PROMPT_CLASSIFICATION = """Eres un clasificador de texto.
Clasifica el siguiente texto en una de estas categorías:
{categories}

Texto: {texte}

Responde solo con el nombre de la categoría."""

def classifier(texte: str, categories: list[str]) -> str:
    prompt = PROMPT_CLASSIFICATION.format(
        categories=", ".join(categories),
        texte=texte
    )
    response = get_client().responses.create(
        model=MODEL,
        reasoning={"effort": "none"},  # temperature requiere effort none
        input=prompt,
        temperature=0.0
    )
    return response.output_text.strip()

Versiona tus prompts

Cambiar un prompt modifica el comportamiento del sistema con la misma certeza que cambiar el código, pero sin que ninguna prueba unitaria lo detecte. Mantén versiones sucesivas y selecciona la activa mediante configuración. Esto te permite comparar dos formulaciones con tráfico real y revertir a la anterior con una variable de entorno si la nueva degrada los resultados.

PROMPTS = {
    "classification_v1": "Clasifica: {texte}",
    "classification_v2": "Analiza y clasifica con precisión: {texte}",
}

# En producción, usa una versión específica
ACTIVE_PROMPT = os.environ.get("PROMPT_VERSION", "classification_v2")

3. Tiempos de espera y límites

Acota cualquier entrada externa antes de que llegue a la API. Un usuario que pegue un PDF de 200 páginas en tu campo de entrada no debe poder desencadenar una llamada de varios dólares ni provocar que la solicitud falle por desbordamiento del contexto. El truncamiento preventivo, combinado con el límite de salida y la temperatura desde la configuración, hace predecibles el coste y la latencia de cada llamada.

def appel_avec_garde_fous(prompt: str) -> str:
    """Llamada a la API con todas las salvaguardas."""
    # Limitar tamaño del prompt
    MAX_PROMPT_CHARS = 50000
    if len(prompt) > MAX_PROMPT_CHARS:
        prompt = prompt[:MAX_PROMPT_CHARS]
        print(f"Prompt truncado a {MAX_PROMPT_CHARS} caracteres")

    response = get_client().responses.create(
        model=MODEL,
        reasoning={"effort": "none"},  # temperature requiere effort none
        input=prompt,
        max_output_tokens=MAX_TOKENS,
        temperature=TEMPERATURE,
    )

    return response.output_text

4. Recuperación ante fallos de modelo (Fallback)

Cuando un modelo está saturado o no disponible temporalmente, devolver un error no es tu única opción. Cambiar a un modelo secundario degrada la calidad pero preserva el servicio; una compensación a menudo preferible para un asistente de soporte, menos para el análisis de contratos. El bucle itera por los modelos en orden de preferencia y lanza una excepción solo si todos fallan.

from openai import RateLimitError, InternalServerError

def appel_avec_fallback(prompt: str) -> str:
    """Intenta con Terra y luego recurre a Luna en caso de error."""
    modeles = ["gpt-5.6-terra", "gpt-5.6-luna"]

    for modele in modeles:
        try:
            response = get_client().responses.create(
                model=modele,
                input=prompt
            )
            return response.output_text
        except (RateLimitError, InternalServerError) as e:
            print(f"{modele} no disponible: {e}")
            continue

    raise RuntimeError("Todos los modelos no están disponibles")

5. Procesamiento por lotes

Para procesar mil documentos, las llamadas secuenciales son demasiado lentas y las simultáneas disparan tus límites de tasa. Un semáforo logra el equilibrio adecuado. Dos detalles hacen robusta esta implementación: return_exceptions=True evita que un único fallo cancele todo el lote, y ordenar por índice restaura el orden original, algo que asyncio.gather no garantiza en tiempo de ejecución.

import asyncio
from openai import AsyncOpenAI

async def traiter_batch(prompts: list[str], max_concurrent: int = 5) -> list:
    """Procesa un lote de prompts con concurrencia limitada."""
    client = AsyncOpenAI()
    semaphore = asyncio.Semaphore(max_concurrent)
    resultats = []

    async def traiter_un(index: int, prompt: str):
        async with semaphore:
            response = await client.responses.create(
                model="gpt-5.6-terra",
                input=prompt
            )
            return index, response.output_text

    tasks = [traiter_un(i, p) for i, p in enumerate(prompts)]
    results = await asyncio.gather(*tasks, return_exceptions=True)

    # Ordenar por índice para mantener el orden
    sorted_results = sorted(
        [(idx, res) for idx, res in results if not isinstance(res, Exception)],
        key=lambda x: x[0]
    )
    return [res for _, res in sorted_results]

# prompts = ["Pregunta 1", "Pregunta 2", "Pregunta 3"]
# résultats = asyncio.run(traiter_batch(prompts))

6. Pruebas y validación

Necesitas dos tipos de pruebas diferentes. La primera verifica la fontanería: la clave funciona, la red pasa, el modelo responde; encaja bien en una comprobación de estado al arrancar. La segunda, más original, prueba la calidad del propio prompt: envías un caso donde conoces la respuesta correcta y verificas que aparezca. Estas aserciones son tu red de seguridad contra regresiones cuando reformulas una plantilla.

def test_api_disponible():
    """Verifica que la API es accesible."""
    try:
        response = get_client().responses.create(
            model="gpt-5.6-terra",
            input="test",
            max_output_tokens=5
        )
        assert response.output_text is not None
        print("API OK")
        return True
    except Exception as e:
        print(f"API KO: {e}")
        return False

def test_prompt_quality(prompt: str, attendu: str) -> bool:
    """Verifica que un prompt devuelve un resultado consistente."""
    response = get_client().responses.create(
        model="gpt-5.6-terra",
        reasoning={"effort": "none"},  # temperature requiere effort none
        input=prompt,
        temperature=0.0
    )
    resultat = response.output_text.lower()
    return attendu.lower() in resultat

# Pruebas de regresión de prompts
assert test_prompt_quality(
    "Clasifica 'producto excelente': positivo o negativo?",
    "positive"
)

Construye una docena de casos de prueba como este, representativos de tus casos de uso reales, y ejecútalos cada vez que modifiques un prompt. Una suite de pruebas de diez minutos te ahorrará semanas de dudas sobre la calidad percibida.

7. Lista de comprobación para despliegue en producción

Antes de desplegar, verifica cada punto:

Infraestructura

  • Variables de entorno configuradas (OPENAI_API_KEY, etc.)
  • Tiempos de espera y max_retries configurados
  • Registro estructurado implementado
  • Monitorización de costes activada

Resiliencia

  • Gestión completa de errores (todos los códigos HTTP)
  • Retroceso exponencial para reintentos
  • Interruptor de circuito para interrupciones prolongadas
  • Recuperación (fallback) a un modelo alternativo

Seguridad

  • Clave de API nunca expuesta en código ni registros
  • Validación de entrada de usuario
  • Limitación de tasa del lado del cliente
  • Sin datos sensibles en los prompts

Rendimiento

  • Streaming activado para interfaces de usuario
  • Procesamiento por lotes para tareas de alto volumen
  • Caché para solicitudes repetitivas
  • Elección del modelo adaptada a cada tarea

Costes

  • Presupuesto diario definido
  • Alertas configuradas
  • max_output_tokens establecido donde sea posible
  • Modelo más rentable seleccionado por tarea

Puntos clave

  • Centraliza la configuración del cliente con un singleton
  • Separa y versiona tus prompts fuera del código
  • Implementa recuperación ante fallos de modelo para alta disponibilidad
  • Usa procesamiento por lotes con concurrencia limitada para volumen
  • Prueba tus prompts con aserciones de calidad
  • Sigue la lista de comprobación completa antes de cada despliegue en producción