Guía de integración de la API de Mistral

Comprender el cambio de la URL base

Tu código envía solicitudes a una URL base y adjunta una clave. Para cambiar a otro endpoint compatible con OpenAI, solo modificas esos dos valores y nada más. La ruta /v1/chat/completions se mantiene igual, por lo que el cuerpo de la solicitud y el cuerpo de la respuesta mantienen su forma.

Mantén la URL base antigua en un valor de configuración en lugar de en el código. De esa manera, puedes volver atrás en un solo paso si aparece un problema en producción.

Compatibilidad con SDK: Clientes de OpenAI vs Mistral

La mayoría de las bibliotecas de clientes aceptan una URL base personalizada. El SDK oficial de OpenAI, LangChain y LlamaIndex todos lo hacen, y un cliente HTTP simple también funciona. Establece la URL base en https://mistralapibaseurl.com/v1 y pasa la nueva clave.

• Verifica la versión del SDK, porque las versiones muy antiguas ignoran la configuración de la URL base.
• Verifica que el cliente envíe la clave en el Authorization header como token bearer.

Configurando el ID del modelo

Envía el id del modelo uncensored. Es el único modelo que ofrece el servicio, por lo que el id no cambia entre solicitudes y no necesitas lógica de selección de modelo.

Ejecuta una solicitud con un prompt corto. Una respuesta y un bloque de uso significan que la URL base, la clave y el model id son correctos.

Implementación de respuestas en streaming

Establecer stream: true para recibir la respuesta como eventos enviados por el servidor. Cada evento contiene un pequeño fragmento de texto, y el evento final contiene las cifras de uso.

Muestra los fragmentos a medida que llegan y mantén el texto completo en un búfer, de modo que el mensaje se almacene una vez que termine la transmisión. Mide el tiempo hasta el primer token; esa cifra muestra qué tan receptivo se siente el chat para un usuario.

Habilitando Llamada de Funciones y Herramientas

Pasa el array de tools en el mismo formato que ya utilizas. El modelo devuelve una llamada a herramienta con un nombre de función y argumentos JSON. Ejecuta la función en tu código, envía el resultado de vuelta como un mensaje de herramienta y lee la respuesta final.

1. Define una herramienta con dos argumentos obligatorios y pruébala por separado.
2. Prueba un caso donde se necesitan dos llamadas de herramientas en secuencia.
3. Valida los argumentos antes de ejecutar cualquier cosa que cambie datos.

Gestión de ventanas de contexto y tokens

La ventana de contexto es de 100.000 tokens. Las conversaciones largas la llenan, así que recorta los turnos antiguos o resúmelos antes de alcanzar el límite. Cada solicitud puede devolver hasta 16.000 tokens de salida, y el predeterminado es de 2.048, así que establece max_tokens para las respuestas que esperas.

Cuenta los tokens desde el campo de uso de cada respuesta. Las estimaciones basadas en el conteo de palabras a menudo están muy desviadas para código y texto en idiomas no ingleses.

Gestión de límites de velocidad y reintentos

Cada clave permite 300 solicitudes por minuto y 8 solicitudes al mismo tiempo. Cuando superas el límite, obtienes una respuesta 429. Reintenta solo las respuestas 429 y 5xx, con retroceso exponencial y un límite en el tiempo total de espera.

Nunca reintentes un 400 o un 401, porque la misma solicitud falla de la misma manera otra vez. Arregla la solicitud o la clave primero.

Depuración de errores comunes de API

Estado	Causa habitual	Qué hacer
400	JSON malformado o campo desconocido	Comprueba el cuerpo de la solicitud frente al formato que envías
401	Clave faltante o incorrecta	Copia la clave de nuevo y verifica el encabezado Authorization
402	Crédito agotado	Recarga el saldo; las recargas comienzan en $20
429	Límite de velocidad alcanzado	Espere y reintente más tarde

Registra el código de estado y el ID de la solicitud para cada fallo, para poder rastrear un problema rápidamente.

Migrando desde APIs de la competencia

Planifica el cambio en tres etapas: un entorno de prueba, una pequeña parte del tráfico en vivo y luego el cambio completo. Mantén ambas URL base en la configuración durante la etapa intermedia y compara las respuestas y la latencia con los mismos prompts.

Compara el coste en tu propio uso, no en los precios de lista. Multiplica los tokens de entrada y salida del campo de uso por $0.15 y $0.50 por cada 1M de tokens y compáralo con tu factura actual.