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

Resposta manual com response_format

Aula 5 de 12 Atualizada a 30 de julho de 2026 Programador
Nesta página
  1. Mais controlo com response_format
  2. Fluxo de trabalho
  3. Exemplo completo
  4. Diferenças em relação a parse()
  5. Análise sem Pydantic
  6. Quando escolher response_format
  7. Gestão de erros
  8. Pontos-chave

Mais controlo com response_format

O método manual via response_format oferece-lhe controlo total sobre a análise. Ao contrário de parse(), que devolve um objeto tipado, esta abordagem devolve uma cadeia JSON que você analisa manualmente; o modelo Pydantic fornece apenas o esquema (model_json_schema()) e valida posteriormente. Escolha este método quando necessitar de flexibilidade ou quando trabalhar num ambiente sem Pydantic.

Fluxo de trabalho

Com response_format, o processo ocorre em duas etapas:

  1. A API devolve o JSON como uma cadeia em response.choices[0].message.content
  2. Você analisa esta cadeia usando o método da sua escolha

Exemplo completo

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

response = client.chat.completions.create(
    model="grok-4.20-0309-reasoning",
    messages=[{
        "role": "user",
        "content": "Review the movie Inception"
    }],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "movie_review",
            "schema": MovieReview.model_json_schema()
        }
    }
)

# O conteúdo é uma cadeia JSON
json_string = response.choices[0].message.content
print(type(json_string))  # <class 'str'>
print(json_string)
# {"title": "Inception", "rating": 9.2, "summary": "...", "recommend": true}

# Análise manual com Pydantic
parsed = MovieReview.model_validate_json(json_string)
print(parsed.title)  # "Inception"

Diferenças em relação a parse()

Aspetoparse()response_format
Retorno(Response, ParsedModel)Apenas Response
AnáliseAutomáticaManual
Acesso aos dadosparsed.fieldjson.loads() ou model_validate_json()
FlexibilidadePadrãoMáxima
Gestão de errosIntegradaDa sua responsabilidade

Análise sem Pydantic

Não é obrigatório usar Pydantic para analisar o resultado. O módulo padrão json também funciona:

import json

response = client.chat.completions.create(
    model="grok-4.20-0309-reasoning",
    messages=[{
        "role": "user",
        "content": "Analyze this text and extract entities"
    }],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "entities",
            "schema": {
                "type": "object",
                "properties": {
                    "people": {
                        "type": "array",
                        "items": { "type": "string" }
                    },
                    "places": {
                        "type": "array",
                        "items": { "type": "string" }
                    }
                }
            }
        }
    }
)

data = json.loads(response.choices[0].message.content)
print(data["people"])  # ["Marie Curie", "Pierre Curie"]
print(data["places"])      # ["Paris", "Warsaw"]

Quando escolher response_format

response_format destaca-se sempre que precisar de visualizar ou inspecionar o JSON antes de este se tornar um objeto. O caso mais comum é o registo (logging): em produção, manter o JSON bruto antes da transformação é frequentemente um requisito de auditoria ou depuração, e parse() não lhe fornece esse ponto de interceção. Segue-se a questão do esquema: se o seu contrato de interface for um esquema JSON bruto — partilhado com outras equipas, gerado por uma ferramenta, versionado independentemente do código Python — impor diretamente esse esquema é mais fiel do que reconstruí-lo como um modelo Pydantic. Por fim, nem todos os projetos operam dentro do ecossistema Pydantic: se a sua validação passar por outra estrutura, ou por uma etapa de processamento intermédia específica do seu pipeline, response_format entrega-lhe o JSON tal como está e deixa-o no controlo do que se segue.

Gestão de erros

Com o método manual, deve gerir os erros de análise por si próprio:

import json

try:
    data = json.loads(response.choices[0].message.content)
except json.JSONDecodeError as e:
    print(f"Parsing error: {e}")

Na prática, este erro nunca deverá ocorrer, uma vez que a API garante JSON válido. No entanto, a gestão defensiva permanece uma boa prática em produção.

Pontos-chave

  • response_format devolve uma cadeia JSON em response.choices[0].message.content
  • A análise é da sua responsabilidade: json.loads(), model_validate_json() ou outro método
  • Pode usar um esquema JSON bruto em vez de um modelo Pydantic
  • Mais flexibilidade que parse(), mas requer mais código
  • O JSON devolvido é garantido como válido — erros de análise não devem ocorrer