Uso de client.chat.parse()
En esta página
El método parse(): el corazón de las salidas estructuradas personalizadas
client.chat.parse() es el equivalente estructurado de client.chat.complete(). En lugar de devolver texto libre o JSON crudo que debas analizar tú mismo, retorna un objeto tipado que coincide directamente con tu modelo de Pydantic. El cambio puede parecer cosmético, pero en realidad elimina una capa entera de código.
El contraste es más claro si se observan lado a lado. Con complete(), recuperas una cadena y la transformas manualmente. Con parse(), el objeto llega listo para usar, y el JSON crudo sigue disponible si lo necesitas.
# Modo JSON — complete() devuelve texto JSON
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
response_format={"type": "json_object"}
)
raw_json: str = response.choices[0].message.content
data = json.loads(raw_json) # Análisis manual
# Personalizado — parse() devuelve un objeto tipado
response = client.chat.parse(
model="mistral-large-latest",
messages=messages,
response_format=MonSchema
)
obj: MonSchema = response.choices[0].message.parsed # Objeto Pydantic
raw_json: str = response.choices[0].message.content # JSON crudo también disponible
La diferencia radica en el acceso a .parsed: un objeto Pydantic directamente utilizable con autocompletado del IDE y validación de tipos.
Una llamada completa de extremo a extremo
El siguiente ejemplo recorre los cinco pasos de una extracción real: definir el esquema con descripciones claras, crear el cliente, llamar a parse(), utilizar el objeto devuelto y recuperar la representación JSON si es necesario.
from mistralai.client import Mistral
from pydantic import BaseModel, Field
from typing import Optional
# 1. Definir el esquema
class BookInfo(BaseModel):
title: str = Field(description="Book title")
authors: list[str] = Field(description="List of authors")
year: Optional[int] = Field(default=None, description="Publication year")
genre: str = Field(description="Main literary genre")
summary: str = Field(description="Summary in 2-3 sentences")
# 2. Crear el cliente
client = Mistral(api_key="your-api-key")
# 3. Llamar a parse()
response = client.chat.parse(
model="mistral-large-latest",
messages=[
{
"role": "system",
"content": "You are an expert librarian. Extract information about the mentioned book."
},
{
"role": "user",
"content": "I loved '1984' by George Orwell. It's a dystopian novel published in 1949 describing a totalitarian society under constant surveillance."
}
],
temperature=0
)
# 4. Utilizar el objeto analizado
book = response.choices[0].message.parsed
print(f"Title: {book.title}")
print(f"Authors: {', '.join(book.authors)}")
print(f"Year: {book.year}")
print(f"Genre: {book.genre}")
print(f"Summary: {book.summary}")
# 5. El JSON crudo también está disponible
raw = response.choices[0].message.content
print(f"\nRaw JSON: {raw}")
Fíjate en lo que el mensaje del sistema no contiene: ninguna descripción del formato esperado.
El mensaje del sistema añadido automáticamente
El SDK se encarga de esto. Cuando utilizas parse(), Mistral añade automáticamente un prefijo al mensaje del sistema:
Your output should be an instance of a JSON object following this schema: { ... }
Este prefijo contiene el esquema JSON generado a partir de tu modelo de Pydantic. No necesitas describir el formato en tu indicación (prompt); el SDK lo hace por ti. Esto libera tu mensaje del sistema para que haga lo que mejor sabe hacer: proporcionar contexto de negocio y establecer requisitos de calidad, como la precisión para importes o cómo gestionar datos faltantes.
response = client.chat.parse(
model="mistral-large-latest",
messages=[
{
"role": "system",
# No es necesario describir el formato JSON; es automático
# Céntrate en el CONTEXTO y la CALIDAD
"content": """You are an expert financial analyst.
Be precise with amounts and percentages.
If data is not available in the text, use null."""
},
{"role": "user", "content": report_text}
],
response_format=FinancialReport
)
.parsed frente a .content: dos usos distintos
El objeto tipado, accesible mediante .parsed, es lo que manipulas en la lógica de tu aplicación. Expone atributos con sus tipos, admite iteración, se convierte a diccionario con model_dump() y se serializa con model_dump_json().
book = response.choices[0].message.parsed
# Acceso tipado con autocompletado del IDE
print(book.title) # str
print(book.authors) # list[str]
print(book.year) # Optional[int]
# Iterar sobre listas
for author in book.authors:
print(f" - {author}")
# Convertir a diccionario
book_dict = book.model_dump()
# Serializar a JSON
book_json = book.model_dump_json(indent=2)
El JSON crudo, por otro lado, sigue siendo útil en los límites del sistema: para el registro (logging), el almacenamiento en bases de datos o para pasar la respuesta tal cual a otra API.
raw = response.choices[0].message.content
# Esto es una cadena JSON, útil para:
# - Registro (logging)
# - Almacenamiento en base de datos
# - Envío a otra API
import json
data = json.loads(raw)
Qué puede seguir fallando
Un esquema garantizado no hace que tu código sea inmune a todo. La API puede devolver un error de red o de servicio, y .parsed puede ser None si la respuesta se interrumpió. El patrón siguiente gestiona ambos casos por separado: SDKError para la API y ValidationError para el esquema, reintentando solo un número limitado de veces.
from mistralai.client import Mistral
from mistralai.client.errors import SDKError
from pydantic import ValidationError
client = Mistral(api_key="your-api-key")
def extract_structured(text: str, schema, max_retries: int = 2):
"""Extracción estructurada con gestión de errores."""
for attempt in range(max_retries + 1):
try:
response = client.chat.parse(
model="mistral-large-latest",
messages=[
{"role": "system", "content": "Extract the requested information."},
{"role": "user", "content": text}
],
response_format=schema,
temperature=0,
max_tokens=1024
)
parsed = response.choices[0].message.parsed
if parsed is None:
raise ValueError("Parsed is None—response may be truncated")
return parsed
except SDKError as e:
print(f"API error (attempt {attempt + 1}): {e}")
if attempt == max_retries:
raise
except ValidationError as e:
print(f"Validation error (attempt {attempt + 1}): {e}")
if attempt == max_retries:
raise
# Uso
try:
book = extract_structured("'The Little Prince' by Saint-Exupéry, 1943", BookInfo)
print(f"Extracted: {book.title} by {', '.join(book.authors)}")
except Exception as e:
print(f"Final failure: {e}")
El reflejo visto con el Modo JSON sigue aplicándose aquí: una respuesta cortada por max_tokens produce un objeto incompleto o nulo, y finish_reason te lo indica antes de que lo descubras más adelante en la canalización.
response = client.chat.parse(
model="mistral-large-latest",
messages=messages,
response_format=MonSchema,
max_tokens=256
)
if response.choices[0].finish_reason != "stop":
print(f"Warning: finish_reason = {response.choices[0].finish_reason}")
# "length" = respuesta truncada, aumenta max_tokens
Puntos clave
client.chat.parse()sustituye aclient.chat.complete()para salidas estructuradas personalizadas.parseddevuelve un objeto Pydantic tipado;.contentdevuelve JSON crudo- El esquema se añade automáticamente al mensaje del sistema; no es necesario describir el formato
- Comprueba siempre
finish_reasony gestiona los erroresSDKErroryValidationError - Utiliza
model_dump()para convertir el objeto analizado en un diccionario de Python