Modo JSON frente a salidas estructuradas personalizadas
En esta página
Dos enfoques, dos filosofías
La API de Mistral ofrece dos mecanismos distintos para generar salidas estructuradas. No compiten entre sí; sirven a diferentes etapas del ciclo de vida de un proyecto. Tu elección depende de tu caso de uso, de tu pila tecnológica y del nivel de fiabilidad que necesites mantener.
Modo JSON: flexibilidad
El Modo JSON es el enfoque más sencillo. Activas un parámetro en tu solicitud y Mistral garantiza que la salida será un JSON válido. Eso es todo. El modelo sigue teniendo libertad para elegir la estructura: claves, tipos y profundidad de anidamiento. Guías el formato deseado mediante tu prompt, pero ninguna restricción técnica vincula el esquema.
# Modo JSON — el modelo elige la estructura
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Analyze this text and return the result in JSON."}],
response_format={"type": "json_object"}
)
Este minimalismo es su principal ventaja: solo hay que añadir un parámetro, no hace falta definir ningún esquema de antemano y ofrece total flexibilidad cuando estás explorando un problema o creando prototipos con rapidez. La desventaja es simétrica. Nada garantiza la estructura exacta del JSON que recibes: el modelo podría omitir un campo, añadir otro o cambiar el nombre de una clave de una llamada a otra. Por tanto, la validación del lado del cliente se vuelve obligatoria, y eso es código que tienes que escribir y mantener tú mismo.
Salidas estructuradas personalizadas: rigor
Las salidas estructuradas personalizadas trasladan esta restricción al lado de la API. Defines un esquema preciso —usando Pydantic en Python o Zod en TypeScript— y Mistral obliga al modelo a adherirse a él exactamente.
from pydantic import BaseModel
class Analyse(BaseModel):
sentiment: str
score: float
keywords: list[str]
# Personalizado — se aplica el esquema
response = client.chat.parse(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Analyze this text."}],
response_format=Analyse
)
La ventaja es inmediata: todos los campos están presentes con el tipo correcto y recibes un objeto analizado listo para usar —una instancia de un modelo Pydantic o Zod— con autocompletado completo en el IDE. Este es el modo para entornos de producción y canalizaciones críticas. La contrapartida se resume en una frase: debes definir un modelo de datos de antemano, lo que hace que la exploración sea menos flexible e impone una ligera sobrecarga inicial de desarrollo.
Comparación detallada
| Criterio | Modo JSON | Salidas estructuradas personalizadas |
|---|---|---|
| Activación | response_format: {"type": "json_object"} | response_format: MyModel (Pydantic/Zod) |
| Método de API | client.chat.complete() | client.chat.parse() |
| Garantía de esquema | No — solo JSON válido | Sí — se aplica el esquema exacto |
| Análisis automático | No — json.loads() manual | Sí — .parsed devuelve un objeto tipado |
| Flexibilidad | Alta — estructura libre | Baja — estructura fija |
| Caso de uso ideal | Prototipado, exploración, esquemas variables | Producción, canalizaciones críticas, APIs |
| Validación requerida | Sí — obligatoria del lado del cliente | Mínima — el esquema hace el trabajo |
Cómo decidir en la práctica
Tres señales apuntan hacia el Modo JSON. La primera es la fase del proyecto: cuando estás creando un prototipo y el esquema aún no es estable, fijar un modelo de datos te frena sin aportar valor. La segunda es la naturaleza de la tarea: si la estructura de la salida varía legítimamente según la entrada, como en un análisis exploratorio donde las dimensiones relevantes no se conocen de antemano, una estructura fija sería una camisa de fuerza. La tercera es técnica: en un lenguaje sin soporte para Pydantic o Zod, el Modo JSON sigue siendo tu único punto de entrada.
Las salidas estructuradas personalizadas toman el relevo tan pronto como la situación se invierte. Estás en producción y un fallo en la extracción tiene un coste real; el esquema de salida es conocido y estable; trabajas en Python o TypeScript; y quieres manipular objetos tipados en lugar de diccionarios anónimos. En concreto, una canalización que clasifica tickets de soporte todo el día usando los mismos cuatro campos no tiene razón para permanecer en Modo JSON.
Esto se alinea con la documentación oficial de Mistral, que recomienda usar salidas estructuradas personalizadas siempre que sea posible. El Modo JSON sigue siendo un buen punto de partida, pero las salidas personalizadas ofrecen una fiabilidad superior y reducen significativamente el código de validación del lado del cliente.
Puntos clave
- Modo JSON = JSON válido garantizado, estructura libre, sencillo de activar
- Salidas estructuradas personalizadas = esquema exacto garantizado, análisis automático, ideal para producción
- Empieza con el Modo JSON para prototipar y migra a Personalizado para producción
- Los dos enfoques son complementarios, no mutuamente excluyentes