Lotook
Structured outputs é um recurso de LLM API que força a resposta de um modelo a seguir um JSON Schema fornecido por você. Usando decodificação restrita, a API compila seu esquema em uma gramática ou máquina de estados que limita a geração de tokens, evitando erros de sintaxe e campos ausentes nas APIs da OpenAI, Anthropic e Google.
O que são Structured Outputs em uma LLM API?
Structured outputs em uma LLM API restringe os tokens gerados pelo modelo para que a resposta completa corresponda a um JSON Schema fornecido pelo desenvolvedor. Tanto a Anthropic quanto o Google descrevem o mecanismo subjacente como decodificação restrita: antes do início da amostragem, a API compila seu esquema em uma gramática ou máquina de estados finitos que elimina qualquer próximo token que viole a estrutura, os nomes das chaves ou os tipos de valor do esquema.
Sem structured outputs, pedir em um prompt que um modelo de linguagem responda em JSON não funciona de forma consistente em produção. A documentação da Anthropic destaca quatro tipos comuns de falha ao depender apenas de instruções no prompt: erros de análise causados por sintaxe JSON inválida, campos obrigatórios ausentes, tipos de dados inconsistentes e violações de esquema que exigem tratamento de erros e novas tentativas. Na prática, essas falhas aparecem em exemplos gerais como estes:
- Erros de análise causados por sintaxe JSON inválida: Por exemplo, chaves não fechadas, vírgulas finais ou texto Markdown em torno dos dados podem interromper um analisador JSON.
- Campos obrigatórios ausentes: Por exemplo, um modelo pode omitir uma chave esperada pelo código posterior da aplicação.
- Tipos de dados inconsistentes: Por exemplo, um campo numérico pode chegar como string, ou um valor único pode chegar no lugar de um array.
- Violações de esquema que exigem tratamento de erros e novas tentativas: Por exemplo, chaves não solicitadas ou valores fora do intervalo exigem laços de repetição e código de validação defensiva.
A decodificação restrita elimina a necessidade de instruções enfáticas de formatação no prompt. Para manter os tipos da aplicação alinhados ao esquema enviado à API, OpenAI e Google fornecem auxiliares nativos do SDK que aceitam classes Pydantic BaseModel em Python e objetos Zod em JavaScript, enquanto o SDK Python da Anthropic aceita um modelo Pydantic via client.messages.parse() e analisa a resposta nesse tipo.
Como Structured Outputs difere de JSON mode e de JSON solicitado apenas por prompt?
Structured outputs garante a aderência exata ao seu JSON Schema, enquanto JSON mode e instruções apenas no prompt não conseguem impor nomes específicos de propriedades, estruturas aninhadas ou campos obrigatórios.
JSON mode foi a etapa intermediária antes das restrições completas de esquema. Na OpenAI, ativar JSON mode por meio de { "type": "json_object" } garante que o modelo produza JSON sintaticamente válido, desde que a solicitação não encontre um caso excepcional, como o esgotamento dos tokens de saída no meio de um objeto. Porém, a documentação da OpenAI traz ressalvas explícitas: é preciso incluir uma instrução para gerar JSON em algum ponto do contexto da conversa; caso contrário, a API lança um erro quando a palavra JSON está ausente e o modelo pode, de outra forma, gerar um fluxo interminável de espaços em branco até atingir o limite de tokens.
A OpenAI apresenta structured outputs como a evolução de JSON mode e recomenda usar structured outputs sempre que houver suporte, reservando JSON mode para modelos antigos como gpt-4-turbo e anteriores.
| Recurso | JSON apenas por prompt | JSON mode | Structured Outputs |
|---|---|---|---|
| Sintaxe JSON válida garantida | Não | Sim, salvo truncamento | Sim, salvo recusa ou truncamento |
| Impõe esquema e tipos exatos | Não | Não | Sim |
| Exige instrução JSON no prompt | Sim | Sim, exigida pela OpenAI | Não |
| Elimina novas tentativas de formatação | Não | Parcialmente | Sim, para a estrutura do esquema |
| Análise nativa com Pydantic e Zod | Manual | Manual | Compatível com SDKs dos fornecedores |
Structured Outputs versus Function Calling: quando usar cada um?
Structured outputs formata a resposta final do modelo para sua aplicação ou para o usuário final, enquanto function calling conecta o modelo a ferramentas, APIs e fontes de dados externas durante a execução.
Desenvolvedores frequentemente confundem os dois recursos porque ambos dependem de definições JSON Schema. OpenAI e Google estabelecem a mesma fronteira arquitetural:
- Use structured outputs quando quiser formatar claramente a mensagem final do assistente para sua interface, banco de dados ou pipeline posterior, como na extração de dados ou classificação estruturada.
- Use function calling (tool use) quando o modelo precisar solicitar uma ação, consultar registros em tempo real ou invocar uma rotina de backend antes de terminar a resposta. Para entender melhor como as definições de ferramentas se encaixam nos protocolos modernos, consulte nosso guia de tool calling e MCP.
A OpenAI oferece esquemas rigorosos de duas formas distintas: function calling com esquemas rigorosos ao conectar o modelo a ferramentas ou dados e um formato de resposta json_schema ao estruturar a resposta ao usuário. A Anthropic separa seus dois recursos em output_config.format para a resposta final do Claude e strict: true em ferramentas individuais para garantir nomes de ferramentas e argumentos de entrada válidos, além de permitir explicitamente o uso de ambos em uma única solicitação. Combinar os dois é especialmente prático em fluxos de trabalho com agentes de IA, nos quais as chamadas intermediárias de ferramentas e o resumo final precisam seguir contratos rigorosos.
Como OpenAI, Anthropic e Google implementam Structured Outputs
Em novembro de 2026, OpenAI, Anthropic e Google implementam structured outputs por meio da compilação de esquemas, embora seus parâmetros de solicitação, palavras-chave JSON Schema aceitas e limites de complexidade sejam diferentes.
| Fornecedor | Como ativar | Auxiliares de esquema do SDK | Regras importantes de esquema | Limites importantes |
|---|---|---|---|---|
| OpenAI | Responses API text.format ou Chat Completions response_format com type: "json_schema" e strict: true |
Pydantic BaseModel (Python), Zod (JS) |
A raiz deve ser um objeto, não anyOf; todos os campos em required; additionalProperties: false obrigatório; chaves emitidas na ordem do esquema |
Até 5.000 propriedades, 10 níveis de aninhamento, 120.000 caracteres entre nomes/enums, 1.000 valores enum |
| Anthropic Claude | output_config.format com type: "json_schema", mais strict: true nas ferramentas |
client.messages.parse() com Pydantic (Python) |
Aceita $ref/$defs, anyOf e allOf (com limites); additionalProperties: false obrigatório; sem limites numéricos ou de comprimento de string |
Máximo de 20 ferramentas rigorosas, 24 parâmetros opcionais, 16 parâmetros de união, tempo limite de compilação de 180s; cache de gramática de 24 horas |
| Google Gemini API | Configuração de resposta com tipo de texto, mime_type: "application/json" e esquema |
Pydantic (Python), Zod (JS) | Aceita minimum/maximum, minItems/maxItems, prefixItems; remove silenciosamente limites sem suporte |
Esquemas grandes ou muito aninhados falham com 400 INVALID_ARGUMENT |
OpenAI
A OpenAI oferece suporte a structured outputs a partir do GPT-4o e recomenda gpt-6-astra para novos projetos. Chamar a API com strict: true e uma palavra-chave sem suporte, como allOf, not, if/then/else, dependentRequired ou dependentSchemas, retorna um erro em vez de falhar silenciosamente. A OpenAI aceita formatos de string como date-time, time, date, duration, email, hostname, ipv4, ipv6 e uuid, além de limites numéricos (minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf) e limites de arrays (minItems, maxItems).
Anthropic Claude
A Anthropic oferece suporte a structured outputs em todos os modelos da Messages API, mas não dentro de Managed Agents. Ao usar client.messages.parse() no SDK Python, restrições sem suporte, como minimum, maximum, minLength e maxLength, são movidas automaticamente para as descrições dos campos para que Claude entenda a intenção, e o SDK valida localmente os dados retornados em relação ao modelo Pydantic original.
Claude armazena gramáticas compiladas em cache por 24 horas a partir do último uso; alterar a estrutura do esquema ou o conjunto de ferramentas invalida esse cache de gramática, enquanto editar nomes ou descrições de campos não o invalida. Como Claude também recebe um prompt de sistema automático que explica o formato JSON, a contagem de tokens de entrada aumenta ligeiramente, e alterar output_config.format invalida o cache de prompt da conversa. As propriedades obrigatórias são emitidas primeiro, seguidas das opcionais. Structured outputs funciona com streaming, contagem de tokens e Batch processing (com desconto de 50 por cento da Anthropic). Porém, combinar saídas JSON com Citations retorna um erro 400, e structured outputs é incompatível com o preenchimento prévio de mensagens.
Google Gemini API
O Google destaca extração de dados, classificação estruturada e fluxos de trabalho com agentes como principais casos de uso de structured outputs do Gemini. Diferentemente da OpenAI e da Anthropic, Gemini remove e ignora silenciosamente várias palavras-chave sem gerar erro, incluindo minLength, maxLength, minProperties, maxProperties, uniqueItems, contains, minContains e maxContains. Você deve sempre executar Pydantic model_validate_json() ou Zod .parse() nas respostas do Gemini para aplicar essas restrições no código da aplicação. Se Gemini retornar 400 INVALID_ARGUMENT para um esquema complexo demais, o Google recomenda achatar aninhamentos, reduzir campos opcionais ou enums, encurtar nomes de propriedades e mover regras não estruturais para as descrições dos campos.
Como criar um JSON Schema confiável para LLMs
Um JSON Schema confiável para structured outputs de LLMs mantém uma estrutura plana, marca campos como obrigatórios e usa tipos que aceitam null em vez de chaves opcionais. Criar esquemas com base em regras comuns entre fornecedores ajuda a evitar erros de compilação e rejeições inesperadas em tempo de execução.
Use esta lista antes de disponibilizar um esquema para OpenAI, Claude ou Gemini:
- Mantenha o aninhamento raso: Achate objetos profundamente aninhados quando possível para ficar bem abaixo do limite de 10 níveis da OpenAI e evitar rejeições de compilação do Gemini ou Claude.
- Torne cada campo obrigatório: Liste cada chave de objeto em
required, pois a OpenAI aplica essa regra rigorosamente e Claude limita o total de parâmetros opcionais por solicitação a 24. - Use uniões que aceitam null para dados ausentes: Represente valores opcionais com
"type": ["string", "null"]em vez de omitir chaves derequired. - Restrinja objetos: Defina
"additionalProperties": falseem cada definição de objeto, conforme exigido pela OpenAI e pela Anthropic. - Restrinja opções fixas com enums: Substitua categorias de strings livres por arrays
enumexplícitos quando apenas um conjunto conhecido de rótulos for válido. - Escreva descrições claras: Coloque regras de domínio e restrições ignoradas, como metas de comprimento de caracteres ou instruções alternativas, na
descriptionde cada propriedade.
A seguir está um esquema ilustrativo para classificar um chamado de atendimento ao cliente. Ele segue as regras comuns aos fornecedores acima: uma raiz de objeto, todos os campos obrigatórios, um campo que aceita null para metadados opcionais, additionalProperties: false e um enum para roteamento.
{
"type": "object",
"additionalProperties": false,
"required": ["category", "urgency", "summary", "order_id"],
"properties": {
"category": {
"type": "string",
"enum": ["billing", "bug_report", "account_access", "other"],
"description": "Primary topic of the support message."
},
"urgency": {
"type": "string",
"enum": ["low", "normal", "high"],
"description": "Escalation priority based on user impact."
},
"summary": {
"type": "string",
"description": "One-sentence summary of the issue in 25 words or fewer."
},
"order_id": {
"type": ["string", "null"],
"description": "Order identifier if present in the message, otherwise null."
}
}
}O que ainda pode dar errado com Structured Outputs?
Structured outputs garante sintaxe válida em relação ao esquema, mas aplicações em produção ainda encontram recusas, truncamento de tokens, valores alucinados, variações de maiúsculas e minúsculas em enums, latência na primeira solicitação e entradas de usuário não confiáveis. Tratar a conformidade com o esquema como verificação de sintaxe, e não como verificação de verdade ou segurança, evita falhas silenciosas em produção.
Recusas de segurança e truncamento no limite de tokens
Modelos ainda podem recusar solicitações inseguras feitas por usuários ou parar no meio da geração ao atingir o limite de tokens de saída. Na OpenAI, uma recusa de segurança preenche um campo separado refusal que não segue seu JSON Schema. Na Anthropic Claude, uma recusa retorna HTTP 200 com stop_reason definido como "refusal" (que ainda é cobrado) e prevalece sobre o esquema; da mesma forma, atingir o limite de saída retorna stop_reason "max_tokens" com JSON incompleto. Verifique sempre indicadores de recusa e motivos de parada antes de chamar JSON.parse() ou um validador.
Valores válidos no esquema, mas incorretos factualmente
A decodificação restrita força o modelo a preencher o esquema mesmo quando o texto de origem não contém uma resposta ou contradiz as premissas do esquema. Uma resposta pode passar por todas as verificações de tipo e enum e ainda conter datas inventadas, categorias erradas ou suposições plausíveis. A OpenAI recomenda instruir o modelo no prompt sobre o que retornar quando a entrada for incompatível com o esquema, como null ou campos vazios, e o Google alerta desenvolvedores a validar valores no código conforme as regras de negócio. Para entender por que respostas confiantes ainda podem estar erradas, leia nosso guia sobre taxas de alucinação de IA.
Maiúsculas e minúsculas em enums no Claude e latência de compilação
Duas particularidades operacionais pegam equipes de surpresa durante a implantação:
- Maiúsculas e minúsculas em enums no Claude: A Anthropic observa que o uso de maiúsculas e minúsculas em enums não é garantido durante a decodificação restrita; portanto, compare as strings enum retornadas sem diferenciar maiúsculas de minúsculas na lógica da aplicação.
- Atraso de compilação na primeira solicitação: Claude adiciona latência extra na primeira vez que um novo esquema é compilado em uma gramática antes de armazená-la em cache por 24 horas, e a OpenAI relata atraso semelhante no processamento do esquema na primeira solicitação para modelos ajustados.
Prompt Injection em valores de campos
Restringir a estrutura de saída não neutraliza instruções maliciosas escondidas em texto não confiável que é resumido ou extraído para um campo de string JSON. Um modelo pode retornar corretamente JSON válido cujo campo summary ou notes contém instruções injetadas ou conteúdo enganoso direcionado a ferramentas posteriores ou revisores humanos. Trate cada valor de campo analisado como entrada não confiável e consulte nossa introdução sobre o que é prompt injection antes de passar campos extraídos para ações automatizadas.
Perguntas frequentes
Structured outputs deixa as respostas dos LLMs mais lentas?
Structured outputs pode adicionar latência na primeira solicitação com um novo esquema, enquanto solicitações posteriores em cache são executadas sem o custo de compilação. A Anthropic armazena gramáticas compiladas do Claude por 24 horas a partir do último uso, a menos que você altere a estrutura do esquema ou as definições de ferramentas. A OpenAI relata latência adicional no processamento do esquema na primeira solicitação apenas ao usar modelos ajustados.
Um LLM ainda pode alucinar ao usar structured outputs?
Sim, um LLM ainda pode alucinar valores enquanto retorna JSON 100 por cento válido segundo o esquema. A decodificação restrita limita a sintaxe dos tokens e os tipos de campos, não a precisão factual. Se a entrada não tiver informações obrigatórias, o modelo poderá inventar valores para preencher chaves necessárias, a menos que você permita campos que aceitam null e instrua quando retornar null.
Devo usar Pydantic ou Zod com APIs de structured output?
Auxiliares nativos de esquema do SDK ajudam a manter os tipos da aplicação e os esquemas da API alinhados. OpenAI e Google oferecem suporte tanto a Pydantic em Python quanto a Zod em JavaScript, enquanto o SDK Python da Anthropic oferece suporte a Pydantic via client.messages.parse(). Esses auxiliares convertem seus modelos em JSON Schema, analisam respostas em objetos tipados e validam restrições como comprimentos de string que Gemini remove ou Anthropic move para as descrições dos campos.
O que acontece se um modelo recusar uma solicitação com structured outputs ativado?
Quando um modelo recusa uma solicitação por motivos de segurança, a recusa prevalece sobre seu JSON Schema. A OpenAI coloca a explicação em um campo refusal específico em vez de seguir o esquema, enquanto a Anthropic retorna HTTP 200 com stop_reason definido como "refusal". Sua aplicação precisa examinar esses campos antes de tentar analisar o JSON.
Por que Claude ou Gemini rejeita meu JSON Schema com um erro 400?
Tanto Claude quanto Gemini rejeitam com um erro 400 esquemas que excedem os limites internos de complexidade da gramática ou da máquina de estados. Claude também retorna um erro 400 se você incluir recursos de esquema sem suporte, como esquemas recursivos ou limites numéricos, ou se combinar saídas JSON com Citations. Achatar objetos aninhados, encurtar nomes e reduzir parâmetros opcionais ou de união geralmente resolve rejeições de compilação.
