Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Utilização de client.chat.parse()

Aula 8 de 12 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. O Método parse(): O Coração das Saídas Estruturadas Personalizadas
  2. Uma Chamada Completa de Ponta a Ponta
  3. O Prompt do Sistema Adicionado Automaticamente
  4. .parsed vs .content: Dois Usos Distintos
  5. O Que Pode Ainda Falhar
  6. Pontos-chave

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() substitui client.chat.complete() para Saídas Estruturadas Personalizadas
  • .parsed devolve um objeto Pydantic tipado; .content devolve JSON bruto
  • O esquema é adicionado automaticamente ao prompt do sistema — não é necessário descrever o formato
  • Verifique sempre finish_reason e trate os erros SDKError e ValidationError
  • Utilize model_dump() para converter o objeto analisado num dicionário Python