Resposta manual com response_format
Nesta página
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:
- A API devolve o JSON como uma cadeia em
response.choices[0].message.content - 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()
| Aspeto | parse() | response_format |
|---|---|---|
| Retorno | (Response, ParsedModel) | Apenas Response |
| Análise | Automática | Manual |
| Acesso aos dados | parsed.field | json.loads() ou model_validate_json() |
| Flexibilidade | Padrão | Máxima |
| Gestão de erros | Integrada | Da 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_formatdevolve uma cadeia JSON emresponse.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