Método parse() Automático
Nesta página
Atualizado a 3 de novembro de 2026. Com base na documentação Structured Outputs da xAI e no SDK
openai3.42.1: ao apontar o SDK da OpenAI para a xAI, o método éclient.chat.completions.parse, que devolve uma conclusão onde o objeto tipado é lido emchoices[0].message.parsed;client.chat.parsenão existe (o SDK da xAI oferecechat.parse(Schema)numa conversa, que devolve um par objeto-resposta). Fonte: Structured Outputs.
A Via Rápida: parse()
O método parse() é a forma mais simples de utilizar saídas estruturadas com a API do Grok. Recebe um modelo Pydantic como entrada e devolve diretamente um objeto tipado — sem JSON para analisar, sem validação manual.
Definir o Modelo Pydantic
Cria uma classe Python que descreve a estrutura esperada.
Chamar client.chat.completions.parse()
Passas o modelo Pydantic como `response_format`.
Receber o Tuplo (Resposta, ModeloAnalisado)
O objeto tipado está pronto para ser usado no teu código.
Exemplo Completo
Eis como extrair uma crítica de filme estruturada:
from openai import OpenAI
from pydantic import BaseModel
client = OpenAI(
api_key="your-xai-key",
base_url="https://api.x.ai/v1"
)
class MovieReview(BaseModel):
title: str
rating: float
summary: str
recommend: bool
completion = client.chat.completions.parse(
model="grok-4.20-0309-reasoning",
messages=[{
"role": "user",
"content": "Write a review of the movie Inception"
}],
response_format=MovieReview
)
parsed = completion.choices[0].message.parsed
# parsed é um objeto MovieReview tipado
print(parsed.title) # "Inception"
print(parsed.rating) # 9.2
print(parsed.recommend) # True
print(type(parsed)) # <class 'MovieReview'>
O Que o parse() Devolve
O método parse() devolve um tuplo de dois elementos:
response: O objeto de Resposta completo da API (com metadados, tokens utilizados, etc.)parsed: O teu modelo Pydantic instanciado com os dados extraídos
Podes aceder a ambos conforme necessário:
completion = client.chat.completions.parse(...)
parsed = completion.choices[0].message.parsed
# Aceder aos metadados
print(completion.usage.total_tokens)
print(completion.model)
# Aceder aos dados estruturados
print(parsed.title)
print(parsed.rating)
Modelos Aninhados
O parse() lida com estruturas complexas sem esforço. Podes aninhar modelos Pydantic:
class Actor(BaseModel):
name: str
role: str
class Review(BaseModel):
title: str
director: str
year: int
rating: float
main_actors: list[Actor]
genres: list[str]
strengths: list[str]
weaknesses: list[str]
completion = client.chat.completions.parse(
model="grok-4.20-0309-reasoning",
messages=[{
"role": "user",
"content": "Complete analysis of the movie Interstellar"
}],
response_format=Review
)
parsed = completion.choices[0].message.parsed
for actor in parsed.main_actors:
print(f"{actor.name} plays {actor.role}")
Quando Utilizar o parse()
O parse() é o caminho mais curto entre uma resposta do modelo e um objeto Python utilizável: se trabalhas com Pydantic, esta é a escolha padrão. O método encapsula tudo — envio do esquema, validação da resposta, instanciação do objeto — e entrega-te diretamente uma instância tipada, sem json.loads nem verificações manuais. É o código mais conciso possível e, na vasta maioria dos casos, esta simplicidade não tem custos: só abres mão do controlo de análise granular se realmente precisares dele, o que é raro. A próxima lição cobre exatamente esses casos em que o controlo manual se justifica.
Pontos-chave
parse()devolve um tuplo(Resposta, ModeloAnalisado)— análise automática- O objeto devolvido é uma instância Pydantic tipada e validada
- Modelos aninhados e listas de objetos funcionam nativamente
- Este é o método recomendado para a maioria dos casos de uso em Python
- Não é necessário usar
json.loads()nem validação manual