Ir al contenido principal
Español— Elegir un idioma
Menú

Modo JSON frente a salidas estructuradas personalizadas

Lección 2 de 12 Actualizado el 29 de julio de 2026 Desarrollador
En esta página
  1. Dos enfoques, dos filosofías
  2. Modo JSON: flexibilidad
  3. Salidas estructuradas personalizadas: rigor
  4. Comparación detallada
  5. Cómo decidir en la práctica
  6. Puntos clave

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

CriterioModo JSONSalidas estructuradas personalizadas
Activaciónresponse_format: {"type": "json_object"}response_format: MyModel (Pydantic/Zod)
Método de APIclient.chat.complete()client.chat.parse()
Garantía de esquemaNo — solo JSON válidoSí — se aplica el esquema exacto
Análisis automáticoNo — json.loads() manualSí — .parsed devuelve un objeto tipado
FlexibilidadAlta — estructura libreBaja — estructura fija
Caso de uso idealPrototipado, exploración, esquemas variablesProducción, canalizaciones críticas, APIs
Validación requeridaSí — obligatoria del lado del clienteMí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