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

Anti-patrones de la API

Lección 12 de 16 Actualizado el 2 de noviembre de 2026 Desarrollador
En esta página
  1. Errores que cuestan dinero en producción
  2. Tratar una respuesta truncada como completa
  3. Dejar que el historial de conversación crezca sin límites
  4. Asumir que la red siempre responde
  5. Pedir al modelo que haga lo que no puede hacer
  6. Desplegar sin dejar rastro
  7. Una rutina de depuración
  8. Puntos clave

Errores que cuestan dinero en producción

Tras repasar las buenas prácticas, es momento de ver la otra cara de la moneda. Los anti-patrones siguientes son las trampas más habituales al usar la API de Chat Completions y comparten un rasgo desagradable: no aparecen durante el desarrollo. De diez peticiones de prueba, todo funciona bien. Es en producción donde estallan, provocando costes inesperados, respuestas incoherentes, alta latencia o, peor aún, fugas de datos sensibles.

Tratar una respuesta truncada como completa

El error más común es ignorar finish_reason. Pides un contrato, recibes texto, lo guardas en la base de datos: salvo que max_tokens=100 cortó la generación en mitad de una cláusula y nadie se da cuenta hasta que el cliente firma. La solución requiere tres líneas de código y debe convertirse en un reflejo.

# MAL — sin verificación
response = client.chat.complete(
    model="mistral-large-latest",
    messages=[{"role": "user", "content": "Redacta un contrato completo."}],
    max_tokens=100  # ¡Demasiado corto para un contrato!
)
contract = response.choices[0].message.content  # ¡Potencialmente truncado!

# BIEN — verificación sistemática
response = client.chat.complete(
    model="mistral-large-latest",
    messages=[{"role": "user", "content": "Redacta un contrato completo."}],
    max_tokens=4000
)

if response.choices[0].finish_reason == "length":
    print("AVISO: Respuesta truncada, aumenta max_tokens")
else:
    contract = response.choices[0].message.content

Dejar que el historial de conversación crezca sin límites

La segunda trampa se activa lentamente. Un bucle de chat que envía todo el historial de conversación en cada turno funciona perfectamente durante los primeros diez intercambios, cuesta el doble en el vigésimo y, finalmente, supera la ventana de contexto en el centésimo, con la factura siguiendo la misma curva. La solución consiste en mantener el prompt del sistema (innegociable) y conservar solo los últimos N mensajes.

# MAL — el historial crece indefinidamente
conversation = []
while True:
    user_input = input("Tú: ")
    conversation.append({"role": "user", "content": user_input})
    response = client.chat.complete(
        model="mistral-large-latest",
        messages=conversation  # ¡100 turnos = miles de tokens!
    )
    reply = response.choices[0].message.content
    conversation.append({"role": "assistant", "content": reply})

# BIEN — ventana deslizante con recorte
MAX_MESSAGES = 20

def trim_conversation(messages: list, max_messages: int = MAX_MESSAGES) -> list:
    """Mantiene el prompt del sistema + los últimos N mensajes."""
    system = [m for m in messages if m["role"] == "system"]
    history = [m for m in messages if m["role"] != "system"]

    if len(history) > max_messages:
        history = history[-max_messages:]

    return system + history

Asumir que la red siempre responde

Una llamada a la API en bruto asume que nada saldrá mal: ni tiempos de espera agotados, ni 429, ni 500. En producción, los tres ocurren, y el tercero sucede en el peor momento posible. Observa la distinción en el código: un 429 justifica un retroceso exponencial, un error del servidor merece un segundo de paciencia, pero un error del cliente como un 400 o un 401 nunca debe reintentarse; tu clave no se volverá válida al tercer intento; solo retrasarás el diagnóstico.

# MAL — sin gestión de errores
response = client.chat.complete(
    model="mistral-large-latest",
    messages=[{"role": "user", "content": "Hola"}]
)
# Falla en timeout, 429, 500...

# BIEN — reintento con retroceso exponencial
from mistralai.client.errors import SDKError
import time

def safe_complete(client, messages, max_retries=3, **kwargs):
    """Llamada a la API con reintento y retroceso exponencial."""
    for attempt in range(max_retries):
        try:
            return client.chat.complete(messages=messages, **kwargs)
        except SDKError as e:
            if e.status_code == 429:
                wait = 2 ** attempt
                print(f"Límite de tasa alcanzado, esperando {wait}s...")
                time.sleep(wait)
            elif e.status_code >= 500:
                time.sleep(1)
            else:
                raise  # Error del cliente (400, 401) — no reintentar
    raise Exception("Fallo tras 3 intentos")

Pedir al modelo que haga lo que no puede hacer

Aquí convergen tres anti-patrones. El primero es el lenguaje subjetivo: «corto», «muchos», «interesante» no se refieren a nada verificable, y el modelo decidirá de forma distinta en cada llamada. Sustituye cada adjetivo por un número o un criterio observable.

# MAL — subjetivo, no medible
"Escribe un resumen corto."           # ¿Corto = 1 frase? ¿1 párrafo?
"Da muchos ejemplos."                # ¿Muchos = 3? ¿10? ¿50?
"Responde de manera interesante."    # ¿Interesante según qué criterios?

# BIEN — criterios objetivos
"Escribe un resumen de 50 a 80 palabras."
"Da exactamente 5 ejemplos, uno por línea."
"Comienza cada respuesta con una estadística relevante."

El segundo es dejar que el modelo cuente. Los LLM son notoriamente malos contando palabras, caracteres y elementos: pedir «exactamente 280 caracteres» producirá texto de 240 o 310. Contar corresponde a tu aplicación, no al modelo.

# MAL — el modelo no puede contar con precisión
"Escribe exactamente 280 caracteres para un tuit."

# BIEN — cuenta en el lado de la aplicación
response = client.chat.complete(
    model="mistral-large-latest",
    messages=[{"role": "user", "content": "Escribe un tuit sobre la IA en Francia."}],
    max_tokens=100
)

tweet = response.choices[0].message.content
if len(tweet) > 280:
    tweet = tweet[:277] + "..."

print(f"Tuit ({len(tweet)} caracteres): {tweet}")

El tercero cae en la misma familia: las escalas numéricas. «Puntúa del 1 al 5» asume que el modelo tiene una representación estable de la brecha entre 3 y 4, lo cual no es cierto. Una escala verbal donde cada paso está definido por un criterio ofrece valoraciones mucho más reproducibles.

# MAL — los modelos interpretan mal las escalas numéricas
"Puntúa la calidad de este texto del 1 al 5."

# BIEN — escala verbal con definiciones
"""Puntúa la calidad de este texto según la siguiente escala:
- EXCELENTE: Claro, bien estructurado, sin errores
- BUENO: Generalmente correcto, posibles mejoras menores
- MEDIO: Comprensible pero carece de estructura o contiene errores
- MALO: Difícil de entender, errores significativos
- MUY MALO: Incomprensible o fuera de tema

Responde solo con la etiqueta en mayúsculas."""

Desplegar sin dejar rastro

El último anti-patrón es el más discreto: llamar a la API, devolver el contenido y no guardar nada. El día que un usuario informe de una respuesta aberrante, no tendrás ni el ID de la solicitud, ni el modelo servido realmente, ni el consumo de tokens. El registro estructurado por llamada cuesta unos pocos milisegundos y hace posible la investigación.

# MAL — sin rastro
response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages
)
return response.choices[0].message.content

# BIEN — registro estructurado
import logging
import json

logger = logging.getLogger("mistral_api")

def logged_complete(client, messages, **kwargs):
    """Llamada a la API con registro estructurado."""
    response = client.chat.complete(messages=messages, **kwargs)

    logger.info(json.dumps({
        "request_id": response.id,
        "model": response.model,
        "prompt_tokens": response.usage.prompt_tokens,
        "completion_tokens": response.usage.completion_tokens,
        "finish_reason": response.choices[0].finish_reason
    }))

    return response

Una rutina de depuración

Cuando una respuesta no cumple tus expectativas, la tentación es reescribir el prompt. En su lugar, comienza con cinco comprobaciones mecánicas, en orden: ¿Está completa la respuesta? ¿Respondió el modelo correcto? ¿Cuántos tokens se consumieron? ¿Está vacía la respuesta? ¿Es plausible la relación salida/entrada? Una relación inferior al 1 % en un prompt grande casi siempre indica que el modelo se negó a procesar la solicitud en lugar de gestionarla mal.

def debug_response(response):
    """Lista de comprobación de depuración para respuestas inesperadas."""
    choice = response.choices[0]

    # 1. ¿Está completa la respuesta?
    if choice.finish_reason == "length":
        print("PROBLEMA: Respuesta truncada — aumenta max_tokens")

    # 2. ¿Se usó el modelo correcto?
    print(f"Modelo: {response.model}")

    # 3. ¿Cuántos tokens se consumieron?
    print(f"Tokens de entrada: {response.usage.prompt_tokens}")
    print(f"Tokens de salida: {response.usage.completion_tokens}")

    # 4. ¿Está vacía la respuesta?
    if not choice.message.content or not choice.message.content.strip():
        print("PROBLEMA: Respuesta vacía")

    # 5. ¿Relación entrada/salida sospechosa?
    ratio = response.usage.completion_tokens / max(response.usage.prompt_tokens, 1)
    if ratio < 0.01:
        print(f"AVISO: Relación salida/entrada muy baja ({ratio:.4f})")

Puntos clave

  • Siempre comprueba finish_reason para detectar truncamientos
  • Limita el historial de conversación con una ventana deslizante
  • Implementa reintentos con retroceso exponencial para errores de red
  • Usa criterios objetivos y medibles en tus prompts
  • Nunca dejes que el modelo cuente; valida en el lado de la aplicación
  • Registra cada llamada a la API en producción para depuración y seguimiento de costes