Buenas prácticas y siguientes pasos
En esta página
Resumen del curso
Has cubierto todos los fundamentos del uso de la API de Mistral: creación de cuenta, gestión de claves, selección de plan, instalación de los SDK de Python y TypeScript, transmisión (streaming), conversaciones multi-turno, migración V1/V2 y despliegue en los principales proveedores de nube. Lo que sigue ya no trata sobre aprender la API en sí, sino sobre la diferencia entre un script que funciona y una aplicación que se mantiene en producción.
Asegurar tus claves de API
Esta es la causa más frecuente de incidentes en producción, casi siempre por la misma razón: una clave hardcodeada «solo para pruebas» y luego olvidada en un commit. Una clave de API nunca debe aparecer en el código fuente; debe residir en una variable de entorno o, mejor aún, en un gestor de secretos como AWS Secrets Manager, Azure Key Vault o HashiCorp Vault.
La segregación es el siguiente paso. Usa una clave por entorno (desarrollo, preproducción, producción) para evitar que una prueba fallida consuma la cuota de tu servicio en vivo. Usa una clave por aplicación para limitar el radio de explosión: si una clave se filtra, solo revocas la de la aplicación afectada. Planifica la rotación cada 90 días en producción y configura alertas en la Consola de Mistral para detectar usos anómalos: una clave comprometida se manifiesta primero como una curva de uso que se dispara sin motivo aparente.
Gestión de errores
En producción, cualquier llamada a la API puede fallar. La cuestión no es si ocurrirá, sino cuándo. Cuatro códigos de estado cubren la mayoría de los casos que encontrarás:
| Código | Significado | Acción |
|---|---|---|
| 401 Unauthorized | Clave de API inválida o caducada | Comprueba tu variable de entorno |
| 429 Too Many Requests | Límite de tasa alcanzado | Reintenta con retroceso exponencial |
| 500 Internal Server Error | Problema en el lado de Mistral | Reintento automático tras unos segundos |
| 503 Service Unavailable | Sobrecarga temporal | Reintenta con retroceso |
La distinción es crucial: nunca solucionas un 401 reintentando; el fallo está en tu configuración. Los otros tres son transitorios, y la respuesta correcta es reintentar con retrasos progresivamente mayores: un segundo, luego dos, luego cuatro. Reintentar inmediatamente en bucle ante un 429 solo agrava la saturación que estás experimentando.
Este es el patrón en Python: máximo tres intentos, propaga la excepción si el último falla y duplica el tiempo de espera tras cada fallo usando 2 ** attempt.
import time
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
def call_with_retry(messages, max_retries=3):
for attempt in range(max_retries):
try:
response = client.chat.complete(
model="mistral-small-latest",
messages=messages,
)
return response
except Exception as e:
if attempt == max_retries - 1:
raise
waitTime = 2 ** attempt # 1s, 2s, 4s
print(f"Error: {e}. Reintentando en {waitTime}s...")
time.sleep(waitTime)
La traducción a TypeScript sigue exactamente la misma lógica, salvo que el tiempo de espera se expresa en milisegundos y la pausa se construye con una promesa y setTimeout:
async function callWithRetry(
client: Mistral,
messages: Array<{ role: string; content: string }>,
maxRetries = 3
) {
for (let attempt = 0; attempt < maxRetries; attempt++) {
try {
return await client.chat.complete({
model: 'mistral-small-latest',
messages,
});
} catch (error) {
if (attempt === maxRetries - 1) throw error;
const waitTime = Math.pow(2, attempt) * 1000;
console.log(`Error. Reintentando en ${waitTime}ms...`);
await new Promise((r) => setTimeout(r, waitTime));
}
}
}
Convivir con los límites de tasa
Los límites de tasa protegen la API del abuso, y la lógica de reintentos por sí sola no basta para respetarlos: solo arregla las cosas a posteriori. Consulta tus límites en la Consola de Mistral (solicitudes por segundo, tokens por minuto) e implementa luego una limitación (throttling) del lado del cliente para evitar excederlos. Las solicitudes excedentes deben ponerse en cola, no descartarse: un usuario prefiere esperar dos segundos a recibir un error.
Cuando se produce un 429 a pesar de tus mejores esfuerzos, la respuesta incluye una cabecera Retry-After que indica cuándo volver a intentarlo; leerla es mejor que adivinar. Y si tu uso legítimo supera consistentemente los límites del plan Scale, solicita un aumento de cuota a través del soporte en lugar de multiplicar los parches.
Control de costes
La primera palanca, y con diferencia la más eficaz, es la selección del modelo. La clasificación, la extracción de campos o la reformulación no requieren un razonamiento elaborado: mistral-small-latest los gestiona muy bien. Reserva mistral-large-latest para tareas donde la calidad del razonamiento marca la diferencia (análisis, síntesis compleja, escritura de formato largo) y usa codestral-latest para la generación de código. No pagues por Mistral Large 3 para hacer lo que Mistral Small puede hacer igual de bien: a volumen de producción, la diferencia se mide en órdenes de magnitud.
La segunda palanca concerne al número de tokens intercambiados. Un prompt conciso, despojado de instrucciones redundantes acumuladas en iteraciones, cuesta menos en cada llamada. En conversaciones multi-turno, envía solo los mensajes necesarios: repetir un historial de treinta intercambios por cada pregunta dispara la factura muy rápido. Ajusta max_tokens a lo que realmente esperas y almacena en caché las respuestas recurrentes: la solicitud más barata es la que no se hace.
Observar lo que ocurre
En producción, registra (log) cada llamada. Sin esto, no sabrás por qué se truncó una respuesta ni qué uso explica la factura del mes. La función siguiente envuelve la llamada con dos trazas: lo que sale y lo que entra, incluyendo el recuento total de tokens y el motivo de parada.
import logging
logger = logging.getLogger("mistral")
def logged_call(client, messages, model="mistral-small-latest"):
logger.info(f"Llamada a la API — modelo: {model}, mensajes: {len(messages)}")
response = client.chat.complete(model=model, messages=messages)
logger.info(
f"Respuesta — tokens: {response.usage.total_tokens}, "
f"finalización: {response.choices[0].finish_reason}"
)
return response
Estas dos líneas responden a la mayoría de las preguntas que te harás más adelante. Un finish_reason que señala un límite de longitud explica una respuesta cortada por la mitad; una media de tokens a la deriva revela un prompt que ha crecido o un historial que no se purgó correctamente.
¿Qué sigue?
Con los fundamentos asentados, se abren varios caminos. La llamada a funciones (function calling) permite al modelo invocar tus propias funciones y APIs. RAG (Generación Aumentada por Recuperación) enriquece las respuestas con tus datos internos, mientras que los embeddings, que transforman texto en vectores, forman el bloque de construcción de la búsqueda semántica. El ajuste fino (fine-tuning) adapta un modelo a tu dominio cuando el prompting ya no basta, los agentes encadenan llamadas para construir sistemas autónomos, y la evaluación te ofrece una forma de medir la calidad de la respuesta en lugar de estimarla a ojo.
Cada uno de estos temas cuenta con cursos dedicados en el catálogo de Corsen Academy.
Puntos clave
- Asegura tus claves de API con un gestor de secretos y una rotación regular
- Implementa sistemáticamente el reintento con retroceso exponencial
- Elige el modelo más ligero capaz de realizar tu tarea
- Registra cada llamada a la API para diagnóstico y optimización de costes
- La API de Mistral es tu base; los siguientes pasos (llamada a funciones, RAG, agentes) se construyen sobre todo lo aprendido
Pon a prueba tus conocimientos
Consola, SDK, proveedores de nube: ¿está asentada la base de la API?
1. ¿Qué reflejos debes tener con la clave de API nada más crearla?
Respuesta: Guárdala de forma segura (solo se muestra una vez), mantenla fuera del código mediante variables de entorno, usa una clave por entorno y rótala si tienes dudas.
2. ¿Qué diferencia los planes Experiment y Scale?
Respuesta: Cuotas y precios: Experiment para descubrimiento y prototipado, Scale para producción; consulta tus límites en la consola antes de dimensionar.
3. ¿Cuál es el esqueleto de una primera llamada en Python?
Respuesta: Cliente inicializado con la clave, llamada chat con el modelo y la lista de mensajes, lectura del contenido de la respuesta; y la transmisión (streaming) activada para una visualización progresiva.
4. ¿Cómo se gestiona una conversación multi-turno vía API?
Respuesta: Manteniendo tú mismo el historial: cada solicitud envía la lista completa de mensajes (usuario y asistente); la API no guarda estado.
5. ¿Qué debes saber sobre los despliegues vía Azure, Vertex o Bedrock?
Respuesta: Los modelos de Mistral están disponibles allí con la autenticación y facturación de la nube elegida; misma familia de modelos, distinto punto de acceso, útil para restricciones de infraestructura.
Clave asegurada, historial gestionado, plan adaptado: las buenas prácticas finales transforman esta base en un cimiento para producción.