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

Método parse() Automático

Aula 4 de 12 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. A Via Rápida: parse()
  2. Exemplo Completo
  3. O Que o parse() Devolve
  4. Modelos Aninhados
  5. Quando Utilizar o parse()
  6. Pontos-chave

Atualizado a 3 de novembro de 2026. Com base na documentação Structured Outputs da xAI e no SDK openai 3.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 em choices[0].message.parsed; client.chat.parse não existe (o SDK da xAI oferece chat.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.

1

Definir o Modelo Pydantic

Cria uma classe Python que descreve a estrutura esperada.

2

Chamar client.chat.completions.parse()

Passas o modelo Pydantic como `response_format`.

3

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:

  1. response: O objeto de Resposta completo da API (com metadados, tokens utilizados, etc.)
  2. 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