Utilização de client.chat.parse()
Nesta página
O Método parse(): O Coração das Saídas Estruturadas Personalizadas
client.chat.parse() é o equivalente estruturado de client.chat.complete(). Em vez de devolver texto livre ou JSON bruto que terá de analisar manualmente, devolve diretamente um objeto tipado correspondente ao seu modelo Pydantic. A alteração pode parecer cosmética, mas elimina na realidade uma camada inteira de código.
O contraste é mais evidente quando comparados lado a lado. Com complete(), obtém uma cadeia de caracteres e transforma-a você mesmo. Com parse(), o objeto chega pronto a usar, e o JSON bruto permanece disponível caso dele necessite.
# Modo JSON — complete() devolve 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álise manual
# Personalizado — parse() devolve um 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 bruto também disponível
A diferença reside no acesso a .parsed: um objeto Pydantic diretamente utilizável, com preenchimento automático no IDE e validação de tipos.
Uma Chamada Completa de Ponta a Ponta
O exemplo seguinte percorre os cinco passos de uma extração real: definir o esquema com descrições claras, criar o cliente, chamar parse(), utilizar o objeto devolvido e recuperar a representação JSON se necessário.
from mistralai.client import Mistral
from pydantic import BaseModel, Field
from typing import Optional
# 1. Definir o 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. Criar o cliente
client = Mistral(api_key="your-api-key")
# 3. Chamar 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 o objeto analisado
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. O JSON bruto também está disponível
raw = response.choices[0].message.content
print(f"\nRaw JSON: {raw}")
Repare no que o prompt do sistema não contém: nenhuma descrição do formato esperado.
O Prompt do Sistema Adicionado Automaticamente
O SDK trata disto. Quando utiliza parse(), a Mistral adiciona automaticamente um prefixo ao prompt do sistema:
Your output should be an instance of a JSON object following this schema: { ... }
Este prefixo contém o esquema JSON gerado a partir do seu modelo Pydantic. Não precisa de descrever o formato no seu prompt; o SDK fá-lo por si. Isto liberta a sua mensagem de sistema para fazer o que faz de melhor: fornecer contexto empresarial e definir requisitos de qualidade, como a precisão para valores ou como lidar com dados em falta.
response = client.chat.parse(
model="mistral-large-latest",
messages=[
{
"role": "system",
# Não é necessário descrever o formato JSON — é automático
# Foque-se no CONTEXTO e na QUALIDADE
"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 vs .content: Dois Usos Distintos
O objeto tipado, acessível via .parsed, é o que manipula na lógica da sua aplicação. Expõe atributos com os respetivos tipos, suporta iteração, converte para um dicionário com model_dump() e serializa com model_dump_json().
book = response.choices[0].message.parsed
# Acesso tipado com preenchimento automático no 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}")
# Converter para dicionário
book_dict = book.model_dump()
# Serializar para JSON
book_json = book.model_dump_json(indent=2)
O JSON bruto, por outro lado, mantém a sua utilidade nas fronteiras do sistema: para registo (logging), armazenamento em base de dados ou para passar a resposta tal como está para outra API.
raw = response.choices[0].message.content
# Isto é uma cadeia JSON, útil para:
# - Registo (logging)
# - Armazenamento em base de dados
# - Envio para outra API
import json
data = json.loads(raw)
O Que Pode Ainda Falhar
Um esquema garantido não torna o seu código imune a tudo. A API pode devolver um erro de rede ou de serviço, e .parsed pode ser None se a resposta tiver sido interrompida. O padrão abaixo trata ambos os casos separadamente — SDKError para a API, ValidationError para o esquema — e tenta novamente apenas um número limitado de vezes.
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):
"""Extração estruturada com tratamento de erros."""
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
# Utilização
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}")
O reflexo observado com o Modo JSON ainda se aplica aqui: uma resposta cortada por max_tokens produz um objeto incompleto ou nulo, e finish_reason indica-lhe isto antes de o descobrir mais adiante no pipeline.
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" = resposta truncada, aumente max_tokens
Pontos-chave
client.chat.parse()substituiclient.chat.complete()para Saídas Estruturadas Personalizadas.parseddevolve um objeto Pydantic tipado;.contentdevolve JSON bruto- O esquema é adicionado automaticamente ao prompt do sistema — não é necessário descrever o formato
- Verifique sempre
finish_reasone trate os errosSDKErroreValidationError - Utilize
model_dump()para converter o objeto analisado num dicionário Python