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

Modo JSON e Aplicação de Esquema

Aula 10 de 16 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Modo JSON e Aplicação de Esquema
  2. Modo JSON vs. Saída Estruturada
  3. Saída Estruturada com Esquema JSON
  4. Regras para Saída Estruturada Estrita
  5. Auxiliar para Construção de Esquemas
  6. Exemplo: Extração de Dados Estruturados
  7. Medir o Que a Restrição Traz
  8. Pontos-chave

Lição atualizada em 3 de novembro de 2026 com base na documentação da OpenAI: temperature e top_p só são aceites com um esforço de raciocínio de none, enquanto os modelos GPT-5.6 raciocinam por padrão (medium). As chamadas que definem estes parâmetros devem, portanto, especificar reasoning={"effort": "none"} (API de Respostas) ou reasoning_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: true para máxima conformidade
  • Todos os campos devem ser required com additionalProperties: 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