Saída Estruturada: JSON Garantido
Nesta página
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 additionalPropertiesdeve serFalse- Tipos suportados:
string,number,integer,boolean,array,object,null - Sem
oneOfouanyOfcom 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: Truepara garantir a conformidade com o esquema - Ideal para extração de dados, classificação e geração estruturada