Anti-patrones de la API
En esta página
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_reasonpara 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