Modo JSON e Aplicação de Esquema
Nesta página
Lição atualizada em 3 de novembro de 2026 com base na documentação da OpenAI:
temperatureetop_psó são aceites com um esforço de raciocínio denone, enquanto os modelos GPT-5.6 raciocinam por padrão (medium). As chamadas que definem estes parâmetros devem, portanto, especificarreasoning={"effort": "none"}(API de Respostas) oureasoning_effort="none"(Chat Completions). Fontes: Using GPT-6 · GPT-5.6 Terra.
Modo JSON e Aplicação de Esquema
A Saída Estruturada da OpenAI garante que a resposta do modelo é um JSON válido que cumpre um esquema definido por si. Adeus à análise frágil com expressões regulares ou erros de formatação; a restrição é aplicada ao próprio nível de geração.
Esta nuance é crítica e muda tudo para um programador. Pedir «responda em JSON» no prompt é um apelo: o modelo obedece na maioria das vezes, mas um dia prefixa a resposta com «Eis o JSON solicitado:», adiciona crases de Markdown ou esquece uma vírgula, e o seu json.loads lança uma exceção em produção às 3 da manhã, no lote mais importante da semana. Com a Saída Estruturada, a restrição aplica-se durante a descodificação: tokens que produziriam um JSON inválido ou não conforme simplesmente não podem ser escolhidos. Deixa de implorar e passa a impor.
Modo JSON vs. Saída Estruturada
A OpenAI oferece dois níveis de restrição, e a distinção resume-se a uma única palavra. O Modo JSON garante um JSON válido sem restrições estruturais; a Saída Estruturada garante um JSON conforme a um Esquema JSON que escreveu.
O Modo JSON resolve metade do problema. Tem a certeza de que consegue analisar a resposta, mas não sabe o que ela contém: o modelo pode nomear um campo annee num pedido e year no seguinte, ou envolver a sua lista num objeto resultats que não usou no dia anterior. Para um protótipo ou uma visualização bruta destinada a um humano, isto basta; assim que a saída alimenta código que acede a campos pelo nome, precisa do segundo nível.
from openai import OpenAI
client = OpenAI()
# Modo JSON simples (JSON válido, estrutura livre)
response = client.responses.create(
model="gpt-5.6-terra",
instructions="Always respond in JSON.",
input="List 3 programming languages with their year of creation.",
text={"format": {"type": "json_object"}}
)
import json
data = json.loads(response.output_text)
print(data)
Saída Estruturada com Esquema JSON
Esta é a funcionalidade mais poderosa. Define um esquema JSON e a API garante que a saída lhe obedece. O exemplo abaixo analisa o sentimento de uma avaliação de cliente e ilustra três utilizações complementares do esquema.
O enum em sentiment impede o modelo de inventar uma categoria intermédia como «bastante positivo»: tem de escolher entre os quatro valores fornecidos, tornando a saída diretamente utilizável num filtro ou painel. A description do campo score atua como um miniprompt local, indicando a escala esperada sem que precise de a explicar nas instruções gerais, e permanece associada ao campo mesmo que o prompt evolua. Por fim, o array aspects permite decompor uma avaliação contraditória — aqui, um produto apreciado mas uma entrega falhada — em vez de esmagar essa nuance numa única pontuação que não ajuda ninguém.
response = client.responses.create(
model="gpt-5.6-terra",
input="Analyze the sentiment of: 'The product is excellent "
"but the delivery was catastrophic.'",
text={
"format": {
"type": "json_schema",
"name": "sentiment_analysis",
"schema": {
"type": "object",
"properties": {
"sentiment": {
"type": "string",
"enum": ["positive", "negative", "mixed", "neutral"]
},
"score": {
"type": "number",
"description": "Score from -1.0 (very negative) to 1.0 (very positive)"
},
"aspects": {
"type": "array",
"items": {
"type": "object",
"properties": {
"aspect": {"type": "string"},
"sentiment": {
"type": "string",
"enum": ["positive", "negative", "neutral"]
}
},
"required": ["aspect", "sentiment"],
"additionalProperties": False
}
},
"summary": {"type": "string"}
},
"required": ["sentiment", "score", "aspects", "summary"],
"additionalProperties": False
},
"strict": True
}
}
)
result = json.loads(response.output_text)
# Garantido: result tem exatamente os campos definidos
print(f"Sentiment: {result['sentiment']}")
print(f"Score: {result['score']}")
for aspect in result["aspects"]:
print(f" - {aspect['aspect']}: {aspect['sentiment']}")
Regras para Saída Estruturada Estrita
O modo strict: true impõe as suas próprias restrições ao esquema. Todos os campos devem aparecer em required e additionalProperties deve ser false em cada objeto. Os tipos permitidos são string, number, integer, boolean, array, object e null, além de enum para restringir valores. No entanto, nem pattern nem minLength/maxLength são aceites: a validação de granularidade fina ocorre do lado do cliente.
Estas regras podem surpreender na primeira tentativa, pois proíbem o campo opcional tal como habitualmente escrito em Esquema JSON. A contrapartida é confortável: o seu código nunca tem de testar se uma chave existe; ela está sempre lá. Para um campo que pode legitimamente estar vazio — um número de telefone em falta num documento, uma data de fim para um contrato em curso —, a resposta não é removê-lo de required, mas permitir que seja null. Quanto à ausência de pattern e limites de comprimento, sinaliza a próxima lição: o esquema garante a forma, mas a validação comercial permanece da sua responsabilidade assim que a resposta é recebida.
Auxiliar para Construção de Esquemas
Escrever manualmente o bloco text.format para cada chamada torna-se rapidamente tedioso e propenso a erros de digitação — falta uma chave name, um strict deslocado, e o erro volta da API sem indicar onde procurar. Algumas linhas de código wrapper centralizam a estrutura, aplicam uma temperatura baixa por padrão (já que a variabilidade nada acrescenta à extração) e tornam o local da chamada legível.
def structured_query(prompt: str, schema: dict,
schema_name: str = "response",
model: str = "gpt-5.6-terra",
system: str = "") -> dict:
"""Wrapper para pedidos de Saída Estruturada."""
response = client.responses.create(
model=model,
reasoning={"effort": "none"}, # temperature requer effort none
instructions=system or "Respond in JSON according to the provided schema.",
input=prompt,
text={
"format": {
"type": "json_schema",
"name": schema_name,
"schema": schema,
"strict": True
}
},
temperature=0.1
)
return json.loads(response.output_text)
Exemplo: Extração de Dados Estruturados
Eis o caso de uso que, por si só, justifica aprender esta técnica: transformar uma fatura recebida como texto simples num objeto utilizável pelo seu sistema de contabilidade. O esquema descreve três níveis — o cabeçalho da fatura, um objeto aninhado vendor e um array lines onde cada elemento tem a mesma forma. O modelo deve, portanto, localizar informações dispersas pelo documento e colocá-las no sítio certo, inclusive para uma linha expressa em horas em vez de unidades, onde o preço unitário é entendido como uma taxa horária.
Note que os totais aparecem no esquema como campos a extrair, não a recalcular. Pedimos ao modelo que leia; o controlo aritmético ocorre depois no seu código, onde uma simples comparação entre a soma das linhas e o total_ht extraído assinalará documentos para revisão humana.
invoice_schema = {
"type": "object",
"properties": {
"invoice_number": {"type": "string"},
"date": {"type": "string"},
"vendor": {
"type": "object",
"properties": {
"name": {"type": "string"},
"siret": {"type": "string"},
"address": {"type": "string"}
},
"required": ["name", "siret", "address"],
"additionalProperties": False
},
"lines": {
"type": "array",
"items": {
"type": "object",
"properties": {
"description": {"type": "string"},
"quantity": {"type": "integer"},
"unit_price_excl_tax": {"type": "number"},
"vat_percent": {"type": "number"}
},
"required": ["description", "quantity",
"unit_price_excl_tax", "vat_percent"],
"additionalProperties": False
}
},
"total_excl_tax": {"type": "number"},
"total_incl_tax": {"type": "number"}
},
"required": ["invoice_number", "date", "vendor",
"lines", "total_excl_tax", "total_incl_tax"],
"additionalProperties": False
}
invoice_text = """
Invoice No. 2026-0042
Date: 15/03/2026
Vendor: TechServ SARL, SIRET 123 456 789 00012
12 rue de la Paix, 75002 Paris
- REST API Development x1: 3500.00 EUR excl. tax (VAT 20%)
- Cloud hosting (3 months) x1: 450.00 EUR excl. tax (VAT 20%)
- Technical support x10h: 150.00 EUR excl. tax/h (VAT 20%)
Total excl. tax: 5450.00 EUR
Total incl. tax: 6540.00 EUR
"""
result = structured_query(
invoice_text,
invoice_schema,
schema_name="invoice",
system="Extract the data from this invoice."
)
Medir o Que a Restrição Traz
Aplique este princípio a um documento que conheça bem: defina um esquema JSON para extrair informações-chave de um currículo — nome, experiência, competências, formação — e teste-o em três currículos em texto simples, escolhidos deliberadamente pelas suas disposições heterogéneas. Verifique se a saída respeita o esquema mesmo quando uma secção está completamente em falta.
Depois, repita a mesma extração sem Saída Estruturada, pedindo simplesmente JSON no prompt, e mantenha as seis saídas lado a lado. Comparar as duas séries mostra o que a restrição traz: a diferença raramente reside no conteúdo extraído, quase sempre na estabilidade dos nomes dos campos e na presença das chaves esperadas.
Pontos-chave
- A Saída Estruturada garante um JSON conforme ao esquema ao nível da geração
- Utilize
strict: truepara máxima conformidade - Todos os campos devem ser
requiredcomadditionalProperties: false - Ideal para extração de dados, classificação e pipelines de processamento
- A validação de granularidade fina (comprimento, padrão) ocorre do lado do cliente após receção