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

Saída Estruturada: JSON Garantido

Aula 9 de 22 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Saída Estruturada: JSON Garantido
  2. O problema que isto resolve
  3. Pydantic em vez de JSON Schema escrito à mão
  4. Dois casos de uso comuns
  5. O que o modo estrito exige
  6. Pontos-chave

Saída Estruturada: JSON Garantido

A Saída Estruturada é uma das funcionalidades mais poderosas da API de Respostas. Em vez de esperar que o modelo devolva um JSON válido, garante-o ao fornecer um esquema. O modelo fica então estruturalmente constrangido a segui-lo. Isto transforma um modelo de linguagem, de um gerador de texto criativo, num componente fiável de um pipeline de processamento automatizado.

O problema que isto resolve

Pedir JSON no prompt funciona na maioria das vezes, o que é precisamente o que torna esta abordagem perigosa. Um dia em cada cem, o modelo prefixa a resposta com uma frase introdutória, envolve tudo num bloco de código Markdown ou renomeia um campo — e o seu json.loads() lança uma exceção em produção num pedido que não consegue reproduzir.

from openai import OpenAI
client = OpenAI()

# Sem estrutura — o modelo pode devolver qualquer formato
response = client.responses.create(
    model="gpt-5.6-terra",
    input="Give me info about Paris in JSON."
)
print(response.output_text)
# Resultado imprevisível:
# Por vezes JSON válido, por vezes texto contendo JSON,
# por vezes um formato inesperado...

O parâmetro text altera a natureza da garantia. Declara um formato json_schema juntamente com o esquema esperado, e a saída conforma-se a ele: a desserialização torna-se uma operação segura.

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Give me information about Paris.",
    text={
        "format": {
            "type": "json_schema",
            "name": "city_info",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "country": {"type": "string"},
                    "population": {"type": "integer"},
                    "official_language": {"type": "string"},
                    "landmarks": {
                        "type": "array",
                        "items": {"type": "string"}
                    }
                },
                "required": ["name", "country", "population", "official_language", "landmarks"],
                "additionalProperties": False
            }
        }
    }
)

import json
data = json.loads(response.output_text)
print(f"City: {data['name']}")
print(f"Population: {data['population']:,}")
print(f"Landmarks: {', '.join(data['landmarks'])}")

# Resultado GARANTIDO como JSON válido:
# City: Paris
# Population: 2,161,000
# Landmarks: Eiffel Tower, Louvre, Notre-Dame, Arc de Triomphe, Sacré-Cœur

Pydantic em vez de JSON Schema escrito à mão

Escrever esquemas à mão torna-se rapidamente tedioso e propenso a erros de digitação. O Pydantic permite descrevê-los como classes Python, gerar o JSON Schema com model_json_schema() e, em seguida, validar e tipar a resposta com model_validate_json(). No final da cadeia, obtém um objeto Python completo com autocompletamento no editor, em vez de um dicionário anónimo.

from pydantic import BaseModel
from typing import Optional
import json

class Product(BaseModel):
    name: str
    price: float
    category: str
    in_stock: bool
    description: Optional[str] = None

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Describe a high-end gaming laptop.",
    text={
        "format": {
            "type": "json_schema",
            "name": "product",
            "strict": True,
            "schema": Product.model_json_schema()
        }
    }
)

# Analisar e validar com Pydantic
product = Product.model_validate_json(response.output_text)
print(f"Product: {product.name}")
print(f"Price: {product.price} EUR")
print(f"In stock: {'Yes' if product.in_stock else 'No'}")

# Resultado:
# Product: ASUS ROG Strix G18
# Price: 2499.99 EUR
# In stock: Yes

Nada o limita a estruturas planas. Ao compor classes, descreve objetos aninhados e listas de objetos, algo de que necessitará assim que criar um perfil de cliente realista: uma empresa contém contactos, e cada contacto tem um endereço.

from pydantic import BaseModel

class Address(BaseModel):
    street: str
    city: str
    postal_code: str
    country: str

class Contact(BaseModel):
    last_name: str
    first_name: str
    email: str
    phone: str
    address: Address

class Company(BaseModel):
    name: str
    sector: str
    employees: int
    contacts: list[Contact]

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Generate a fictional company profile in the tech sector "
          "with 2 contacts.",
    text={
        "format": {
            "type": "json_schema",
            "name": "company",
            "strict": True,
            "schema": Company.model_json_schema()
        }
    }
)

company = Company.model_validate_json(response.output_text)
print(f"Company: {company.name} ({company.sector})")
for c in company.contacts:
    print(f"  - {c.first_name} {c.last_name}: {c.email}")

Dois casos de uso comuns

O primeiro é a extração: transformar texto escrito num registo utilizável. Um anúncio de conferência escrito em linguagem natural torna-se uma linha de base de dados com título, data, localização e número de participantes — sem expressões regulares e sem falhar sempre que a redação muda.

class Event(BaseModel):
    title: str
    date: str
    location: str
    attendees: int

text = """
The PyCon France 2026 conference will be held on November 15 and 16
at the Palais des Congrès in Lyon. More than 800 Python developers
are expected for this edition.
"""

response = client.responses.create(
    model="gpt-5.6-terra",
    input=f"Extract the information from this event:\n{text}",
    text={
        "format": {
            "type": "json_schema",
            "name": "event",
            "strict": True,
            "schema": Event.model_json_schema()
        }
    }
)

evt = Event.model_validate_json(response.output_text)
print(f"{evt.title} - {evt.date} at {evt.location} ({evt.attendees} attendees)")
# Resultado: PyCon France 2026 - November 15-16, 2026 at Lyon (800 attendees)

O segundo é a classificação. Ao declarar uma enumeração, restringe o modelo a um vocabulário fechado: este não pode responder “bastante positivo” ou “positivo” quando o seu código espera positive. Esta é a diferença entre um valor que pode utilizar diretamente e um valor que deve normalizar posteriormente.

from enum import Enum

class Sentiment(str, Enum):
    positive = "positive"
    negative = "negative"
    neutral = "neutral"

class Analysis(BaseModel):
    sentiment: Sentiment
    confidence: float
    keywords: list[str]

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Analyze this comment: 'Great service, fast delivery!'",
    text={
        "format": {
            "type": "json_schema",
            "name": "sentiment_analysis",
            "strict": True,
            "schema": Analysis.model_json_schema()
        }
    }
)

analysis = Analysis.model_validate_json(response.output_text)
print(f"Sentiment: {analysis.sentiment.value} ({analysis.confidence:.0%})")
# Resultado: Sentiment: positive (95%)

O que o modo estrito exige

A garantia tem uma contrapartida: quando strict: True, o esquema deve aderir a um subconjunto específico de JSON Schema. Estas restrições são a principal causa de erros 400 para iniciantes, pelo que é melhor conhecê-las antes de as encontrar:

  • Todas as propriedades devem estar listadas em required
  • additionalProperties deve ser False
  • Tipos suportados: string, number, integer, boolean, array, object, null
  • Sem oneOf ou anyOf com tipos mistos
  • Utilize Optional[str], que se traduz em {"anyOf": [{"type": "string"}, {"type": "null"}]}

A regra sobre required surpreende frequentemente as pessoas: um campo opcional não é expresso removendo-o da lista, mas permitindo o valor null, exatamente o que Optional[str] produz no lado do Pydantic.

Pontos-chave

  • A Saída Estruturada garante que a resposta adere ao seu esquema JSON
  • Utilize text={"format": {"type": "json_schema", ...}} na API de Respostas
  • O Pydantic é a ferramenta ideal para definir e validar esquemas
  • Ative strict: True para garantir a conformidade com o esquema
  • Ideal para extração de dados, classificação e geração estruturada