Buenas prácticas para producción
En esta página
De la prueba de concepto al despliegue
Ya dominas todos los parámetros de la API de Chat Completions. La parte más compleja sigue siendo tender un puente entre un cuaderno que funciona y un servicio que otros utilizan sin tu intervención. Esta última lección consolida todo el curso en una lista de comprobación accionable para producción y, a continuación, señala el camino hacia los cursos de seguimiento.
Autenticación y versionado de modelos
Antes de escribir la primera línea de lógica de negocio hay que tomar dos decisiones. La primera afecta a la clave de API: debe residir en una variable de entorno, nunca en el código, y una aserción al arranque evita que un None se propague tres niveles hacia abajo hasta convertirse en un mensaje de error incomprensible. Planifica también la rotación: crea la nueva clave, despliégala y, solo entonces, revoca la antigua, en ese orden, si quieres evitar dejar el servicio fuera de línea.
import os
# SIEMPRE: clave de API en variable de entorno
api_key = os.getenv("MISTRAL_API_KEY")
assert api_key, "MISTRAL_API_KEY not defined"
# NUNCA: clave hardcodeada en el código
# api_key = "sk-abc123..." # PROHIBIDO en producción
# SIEMPRE: rotación periódica de claves
# Crea una nueva clave, despliégala y, después, revoca la antigua
La segunda decisión afecta al identificador del modelo. En desarrollo, -latest te proporciona mejoras sin esfuerzo. En producción, ese mismo alias implica que un cambio de versión por parte del proveedor puede alterar el comportamiento de tu aplicación sin aviso, un martes por la mañana, sin ningún commit que lo explique. Fija la versión.
# DESARROLLO — última versión
model = "mistral-large-latest"
# PRODUCCIÓN — versión fija para reproducibilidad
model = "mistral-large-2512"
# ¿Por qué? Un cambio en "latest" puede alterar el comportamiento
# de tu aplicación sin aviso.
Un cliente que gestiona incidentes
El corazón de una integración en producción no es la llamada a la API, sino todo lo que la rodea. La clase siguiente agrupa tres responsabilidades en un único punto de control: reintentos con retroceso exponencial ante errores 429, una pausa breve ante errores de servidor y la escalada inmediata de errores de cliente que ningún reintento va a solucionar. Además, normaliza la respuesta en un diccionario estable —contenido, finish_reason, uso, modelo, ID— para que el resto de tu código ya no dependa de la forma exacta del objeto devuelto por el SDK. El logger.warning en los truncamientos ya justifica por sí solo esta encapsulación: es la única manera de descubrir que un ajuste de max_tokens es demasiado estricto antes de que los usuarios lo reporten.
from mistralai.client import Mistral
from mistralai.client.errors import SDKError
import time
import logging
logger = logging.getLogger(__name__)
class MistralClient:
"""Cliente de producción con reintentos, timeout y registro."""
def __init__(self, api_key: str, max_retries: int = 3):
self.client = Mistral(api_key=api_key)
self.max_retries = max_retries
def complete(self, messages: list, **kwargs) -> dict:
for attempt in range(self.max_retries):
try:
response = self.client.chat.complete(
messages=messages,
**kwargs
)
result = {
"content": response.choices[0].message.content,
"finish_reason": response.choices[0].finish_reason,
"usage": {
"prompt": response.usage.prompt_tokens,
"completion": response.usage.completion_tokens,
"total": response.usage.total_tokens,
},
"model": response.model,
"id": response.id,
}
# Alertar si la respuesta se ha truncado
if result["finish_reason"] == "length":
logger.warning(f"Response truncated — req_id={response.id}")
return result
except SDKError as e:
if e.status_code == 429:
wait = 2 ** attempt
logger.warning(f"Rate limit, retry {attempt+1}/{self.max_retries} in {wait}s")
time.sleep(wait)
elif e.status_code >= 500:
logger.error(f"Server error {e.status_code}, retry {attempt+1}")
time.sleep(1)
else:
logger.error(f"Client error {e.status_code}: {e.message}")
raise
raise Exception(f"Failed after {self.max_retries} attempts")
Seguimiento de costes en tiempo real
Descubrir tu consumo en la factura mensual es un lujo que pocos equipos pueden permitirse. El rastreador siguiente escribe una línea JSONL por llamada —marca de tiempo, modelo, tokens de entrada y salida, finish_reason, ID de solicitud— y mantiene un total de sesión que puedes consultar en cualquier momento. El formato JSONL no es un detalle: se agrega con cualquier herramienta de analítica sin necesidad de un paso de análisis, y la presencia del ID de solicitud te permite vincular una anomalía de coste a una llamada concreta.
import json
from datetime import datetime, timezone
class CostTracker:
"""Seguimiento de costes de la API en tiempo real."""
def __init__(self, log_path: str = "api_costs.jsonl"):
self.log_path = log_path
self.session_tokens = {"prompt": 0, "completion": 0}
def log(self, response_data: dict):
usage = response_data["usage"]
self.session_tokens["prompt"] += usage["prompt"]
self.session_tokens["completion"] += usage["completion"]
entry = {
"ts": datetime.now(timezone.utc).isoformat(),
"model": response_data["model"],
"prompt_tokens": usage["prompt"],
"completion_tokens": usage["completion"],
"finish_reason": response_data["finish_reason"],
"id": response_data["id"],
}
with open(self.log_path, "a") as f:
f.write(json.dumps(entry) + "\n")
def report(self) -> str:
total = self.session_tokens["prompt"] + self.session_tokens["completion"]
return (
f"Session — Prompt: {self.session_tokens['prompt']:,} | "
f"Completion: {self.session_tokens['completion']:,} | "
f"Total: {total:,} tokens"
)
Validación en ambos extremos
Una aplicación robusta no confía ni en lo que entra ni en lo que sale. En la entrada, rechaza mensajes vacíos, limita la longitud a 10.000 caracteres para evitar que un copiar y pegar desafortunado dispare tu factura y elimina caracteres de control que alteren la tokenización. En la salida, no rechaces nada, pero genera advertencias: respuesta posiblemente truncada, respuesta anormalmente corta (menos de cinco caracteres) o anormalmente larga (más de 50.000). Estas tres señales detectan la gran mayoría de fallos silenciosos.
def validate_input(user_message: str) -> str:
"""Validar y limpiar la entrada del usuario."""
if not user_message or not user_message.strip():
raise ValueError("Empty message")
if len(user_message) > 10_000:
raise ValueError("Message too long (max 10,000 characters)")
# Limpiar caracteres de control
cleaned = "".join(c for c in user_message if c.isprintable() or c in "\n\t")
return cleaned.strip()
def validate_output(content: str, finish_reason: str) -> dict:
"""Validar la salida de la API."""
warnings = []
if finish_reason == "length":
warnings.append("Response potentially truncated")
if not content or len(content.strip()) < 5:
warnings.append("Abnormally short response")
if len(content) > 50_000:
warnings.append("Abnormally long response")
return {"content": content, "warnings": warnings, "valid": len(warnings) == 0}
Gestionar la ventana de contexto
Un último problema: la deriva lenta de las conversaciones largas. La función siguiente estima el volumen en un token por cada cuatro caracteres en francés —una aproximación basta, pero suficiente como barrera de seguridad— y deja pasar las solicitudes mientras se mantengan por debajo del 80 % del límite. Más allá de ese umbral, conserva el prompt del sistema y elimina los mensajes más antiguos hasta bajar del 70 %. Esta brecha entre los dos umbrales es deliberada: recortar solo hasta el umbral de activación haría que la función volviera a superar el límite con el siguiente mensaje.
def manage_context(messages: list, max_tokens: int = 100_000) -> list:
"""Mantener los mensajes dentro del límite de tokens del modelo."""
# Estimación: 1 token ~ 4 caracteres en francés
total_chars = sum(len(m["content"]) for m in messages)
estimated_tokens = total_chars // 4
if estimated_tokens < max_tokens * 0.8:
return messages # Todo cabe
# Conservar sistema + primer y último mensajes
system = [m for m in messages if m["role"] == "system"]
history = [m for m in messages if m["role"] != "system"]
# Eliminar los mensajes más antiguos
while estimated_tokens > max_tokens * 0.7 and len(history) > 2:
removed = history.pop(0)
estimated_tokens -= len(removed["content"]) // 4
return system + history
Qué te llevas de este curso
El recorrido ha seguido cuatro pasos. Primero, los fundamentos: el endpoint, los roles, los parámetros básicos y la estructura de la respuesta. A continuación, la transmisión en streaming, con el protocolo SSE, su implementación en Python, las secuencias de parada y el endurecimiento mediante safe_prompt y barreras de seguridad. La ingeniería de prompts ocupó la tercera fase: prompts de sistema para producción, few-shot, estructuración con XML y Markdown, y anti-patrones. Los parámetros avanzados cerraron el ciclo: temperatura y Top P en detalle, penalizaciones de presencia y frecuencia, N completaciones y esta lista de comprobación para producción.
La configuración siguiente destila estas elecciones en un punto de partida defendible para un primer despliegue en producción: versión fija, techo de tokens adecuado al caso de uso, temperatura baja para coherencia factual, top_p sin tocar puesto que se ajusta la temperatura, penalizaciones neutras salvo que una necesidad específica las justifique y safe_prompt activado.
# Configuración típica para una aplicación en producción
PRODUCTION_CONFIG = {
"model": "mistral-large-2512", # Versión fija
"max_tokens": 2000, # Adecuado al caso de uso
"temperature": 0.3, # Consistente y factual
"top_p": 1.0, # Sin tocar si se ajusta la temperatura
"presence_penalty": 0.0, # Por defecto salvo necesidad específica
"frequency_penalty": 0.0, # Por defecto salvo necesidad específica
"safe_prompt": True, # Seguridad activada
}
Para profundizar con la API de Mistral, cuatro cursos complementarios siguen en Corsen Academy:
- Embeddings y RAG — Búsqueda semántica con
mistral-embedy bases de datos vectoriales - Llamada a funciones — Conectar el modelo a tus herramientas y APIs externas
- Ajuste fino — Adaptar un modelo a tu dominio específico
- Producción y evaluación — Métricas, evaluaciones automatizadas y optimización de costes
Puntos clave
- Usa modelos versionados en producción, nunca
-latest - Implementa reintentos + retroceso + registro desde el primer despliegue
- Valida tanto las entradas COMO las salidas de cada llamada a la API
- Rastrea los costes en tiempo real con un rastreador de tokens
- Gestiona la ventana de contexto para conversaciones largas
- Activa
safe_promptcomo red de seguridad mínima - Prueba tus prompts con casos límite antes de cada lanzamiento a producción
Pon a prueba tus conocimientos
¿Ya no quedan secretos en el endpoint chat/completions? Vamos a comprobarlo.
1. ¿Qué roles estructuran la lista de mensajes?
Respuesta: system (el marco), user (solicitudes), assistant (respuestas del modelo); el historial completo se reinicia en cada llamada, ya que la API no mantiene estado.
2. ¿Qué encuentras en el campo usage de la respuesta?
Respuesta: Tokens consumidos en entrada y salida; la base para la facturación y la métrica que debes vigilar para dimensionamiento y costes.
3. ¿Cómo funciona la transmisión SSE?
Respuesta: La respuesta llega como eventos Server-Sent, fragmento a fragmento: los muestras según llegan y los concatenas para obtener el mensaje final.
4. ¿Para qué sirven las secuencias de parada?
Respuesta: Para cortar la generación tan pronto como aparece una cadena dada: controlar la longitud, detenerse en un delimitador y garantizar formatos limpios.
5. Temperatura, Top P, penalizaciones: ¿qué uso en producción?
Respuesta: La temperatura y Top P fijan el determinismo por tarea; las penalizaciones de presencia y frecuencia limitan la repetición. Son ajustes que debes fijar por caso de uso y documentar junto a tus prompts.
Roles, uso, streaming, paradas, ajuste: los fundamentos se mantienen; las buenas prácticas para producción anteriores los ponen en orden.