Saídas estruturadas de LLMs: JSON confiável em produção

Saídas estruturadas de LLMs parecem triviais até o pipeline quebrar silenciosamente porque o modelo decidiu omitir o campo status numa terça à noite.

O problema não é que o modelo seja incapaz. É que JSON livre, sem enforcement de schema, é uma promessa verbal. O modelo geralmente entrega. Mas "geralmente" não entra no SLA.

Então: o que muda quando você configura saídas estruturadas de LLMs de verdade, como validar isso em produção e como medir se está funcionando.

O que são saídas estruturadas (e o que não são)

Saída estruturada é quando o modelo retorna dados num formato definido com antecedência: campos específicos, tipos determinados, sem surpresas.

Isso não é a mesma coisa que escrever "responda em JSON" no prompt. Existem três abordagens com garantias bem diferentes:

• Instrução no prompt: você pede JSON e o modelo tenta. Sem garantia.
• Modo JSON: a API garante que a saída é JSON parseável. Não garante os campos certos.
• Schema enforcement: você define um schema e o processo de geração é constrangido a obedecê-lo. Campo ausente não existe como possibilidade.

A terceira opção é a única que muda o contrato. As duas primeiras aumentam a probabilidade, não a confiabilidade.

Quando saídas estruturadas fazem diferença real

Não é toda tarefa de LLM que precisa disso. Geração de texto para exibir ao usuário, resumo, explicação: formato livre funciona bem.

Structured output importa quando:

• A resposta do modelo alimenta outro sistema (banco de dados, fila de eventos, outro agente).
• Um campo ausente ou mal tipado quebra o processo downstream.
• Você precisa auditar o que o modelo extraiu campo a campo.
• A saída é processada por lógica, não lida por humano.

Qualquer pipeline de extração de informação, classificação com categorias fixas ou geração de dados para inserção estruturada entra nessa lista. Spoiler: se o próximo passo depois do LLM é um parse, você precisa de schema enforcement.

Como descrever o schema para o modelo

Aqui está o ponto onde a maioria das implementações erra: a descrição do schema precisa ser precisa o suficiente para que o modelo entenda as restrições, sem ser verbosa a ponto de consumir tokens que fariam falta para a tarefa em si.

Quando for pedir para uma IA ajudar a montar isso, descreva o schema em termos de negócio, não técnicos. Em vez de listar tipos e formatos em notação especializada, explique o que cada campo significa e quais valores são válidos. "O campo status aceita apenas ativo, inativo ou pendente" é mais eficiente para o modelo do que uma nota sobre enum em formato de especificação.

Outro ponto: quanto mais campos obrigatórios, maior a chance de falha. Um schema com 15 campos obrigatórios exige muito mais do modelo do que um com 4. Se você pode tornar alguns opcionais sem comprometer o sistema downstream, faça isso. O ganho em taxa de conformidade é mensurável.

A documentação do Pydantic é a referência que a maioria das implementações Python usa para definir e validar schemas de saída. Vale entender a lógica, mesmo que você não vá implementar diretamente.

Modo nativo vs instrução no prompt

Alguns providers oferecem schema enforcement nativo: você passa o schema na chamada de API e o processo de geração é constrangido a obedecer. Outros dependem de instrução no prompt com validação posterior.

A diferença em taxa de conformidade é real. Em extrações de dados com schemas moderados, modo nativo chega perto de 99% de conformidade. Instrução no prompt fica entre 85% e 95% dependendo da complexidade do schema e do modelo.

Em 10.000 requisições, 5% de falha são 500 registros que precisam de tratamento manual ou que criam inconsistências no sistema. Essa conta muda o cálculo de qual abordagem escolher.

Se o provider oferece enforcement nativo, use. Se não oferece, coloque isso como variável explícita na escolha do provider quando structured output for central no seu produto.

Como validar a saída antes de usar

Mesmo com schema enforcement, validação downstream ainda faz sentido. Não por desconfiança do modelo, mas porque schemas capturam estrutura, não lógica de negócio.

O que verificar além do formato:

• Campos obrigatórios presentes.
• Valores de lista são os válidos, não apenas que o campo existe.
• Relações entre campos são coerentes (data de fim não é anterior a data de início).
• Strings não estão vazias quando o contexto exige conteúdo.

Isso é diferente de guardrails de conteúdo, que verificam o que o modelo disse. Aqui você está verificando se os valores são operacionalmente válidos. As duas camadas existem por razões diferentes e resolvem problemas distintos, como detalhamos no artigo sobre guardrails para LLMs em validação em tempo real.

O que fazer quando a conformidade quebra

Ter um plano de fallback não é pessimismo, é arquitetura. Quando a saída não conforma com o schema, você precisa de uma política definida antes do incidente:

• Retry com prompt ajustado: funciona para falhas esporádicas, mas custa tokens e latência.
• Fallback para valor padrão: viável quando o campo é opcional e o default é seguro para o downstream.
• Fila de revisão humana: necessário quando o dado é crítico e não tem default seguro.
• Rejeição com log: quando a entrada que gerou a falha precisa ser investigada.

O que você não quer é silenciar o erro e deixar um JSON incompleto alimentar o sistema. Isso cria inconsistências que aparecem semanas depois, quando o dado já se propagou por outros lugares.

Como medir a taxa de conformidade das saídas estruturadas

Essa é a métrica que define se a sua implementação está saudável.

Taxa de conformidade = respostas válidas dividido pelo total de requisições no período.

Você quer isso quebrado por:

• Schema, se você tem mais de um em uso.
• Modelo ou versão, especialmente durante rollout.
• Tipo de entrada, porque alguns inputs são mais difíceis de estruturar que outros.

Se você não rastreia isso, não tem como saber se uma mudança de modelo ou de prompt melhorou ou piorou a confiabilidade. Integramos essa métrica num contexto mais amplo no artigo sobre avaliação de LLM em produção.

Threshold mínimo aceitável depende do contexto. Para pipeline de dados críticos, eu não colocaria em produção com menos de 98%. Para classificação de baixo risco com revisão humana ativa, 92% pode ser defensável desde que o fallback esteja operando.

Custo e latência: o que muda com structured output

Detalhe que aparece depois do deploy: saídas estruturadas não são gratuitas em latência. Schema enforcement nativo adiciona processamento na geração. Prompts com instruções de schema são maiores e custam mais tokens por requisição.

Acontece que, se você usa prompt caching, um schema que muda com frequência derruba o hit rate do cache. Um schema estável amortiza o custo ao longo das requisições. Há mais sobre essa interação no artigo sobre prompt caching para LLMs.

O ponto aqui não é que structured output seja caro. É que você precisa incluir latência e custo por requisição na equação ao comparar abordagens, não só a taxa de conformidade.

Perguntas frequentes

Modo JSON garante structured output?

Não. Modo JSON garante que a saída é JSON parseável. Não garante campos corretos, tipos certos ou presença dos campos obrigatórios. Para isso você precisa de schema enforcement ou validação posterior obrigatória.

O modelo pode gerar campos extras além do schema?

Com enforcement nativo, geralmente não. Com instrução no prompt, sim. Uma falha frequente é o modelo adicionar campos "explicativos" fora do schema, o que quebra o parse mesmo quando os campos corretos estão presentes.

Structured output funciona com modelos menores?

Modelos menores tendem a ter taxa de conformidade menor com instrução no prompt. Isso torna o enforcement nativo ainda mais importante quando você usa um modelo menor para reduzir custo. A escolha do provider importa tanto quanto a escolha do modelo nesse caso.

Como lidar com campos que dependem do contexto?

Marque como opcionais no schema e documente a lógica de presença no prompt de sistema. Não tente replicar lógica de negócio complexa só nas restrições do schema: você vai criar um schema frágil e difícil de manter ao longo do tempo.

Saídas estruturadas de LLMs como contrato, não sugestão

O que separa um pipeline de LLM monitorável de um que você reza para funcionar é a taxa de conformidade das saídas estruturadas.

Antes do próximo deploy que dependa de campos específicos na resposta do modelo: define o schema, configura enforcement quando disponível, implementa validação downstream e estabelece um threshold mínimo. Depois mede. Não inverta essa ordem.

O que fazer agora:

• Identifique os pipelines que dependem de saída de LLM sem schema enforcement hoje.
• Para cada um, defina o schema mínimo e o threshold de conformidade aceitável.
• Configure rastreamento antes do próximo deploy, não depois.
• Leia sobre como estruturar avaliação de LLM em produção para integrar essa métrica ao restante do monitoramento.