JSON confiável com LLMs: schemas, validação e retentativas
Obter JSON válido de um LLM exige mais que pedir com educação. Use schemas, saída estruturada, validação e retentativas e evite as falhas mais comuns.
Neste artigo
- Por que os modelos quebram o JSON, para começar?
- Passo 1: descreva a saída com precisão no prompt
- Passo 2: use o recurso de saída estruturada da API
- Passo 3: valide tudo, mesmo com a imposição
- Passo 4: tente de novo com o erro, não às cegas
- Onde colocar o raciocínio em uma resposta JSON?
- Erros comuns no desenho de schemas de saída
- Só o prompt basta alguma vez?
Para obter JSON confiável de um modelo de linguagem, defina a estrutura como um JSON Schema, use o recurso de saída estruturada do fornecedor quando houver, valide cada resposta no código e tente de novo com o erro de validação quando ela falhar. A redação do prompt sozinha leva você a boa parte do caminho; os últimos pontos percentuais de confiabilidade vêm da API e da sua própria validação.
A distinção importa porque "boa parte do caminho" não basta para código. Um parser que falha em 2% das respostas significa uma funcionalidade quebrada para alguém a cada poucos minutos em escala.
Por que os modelos quebram o JSON, para começar?
Antes de consertar, ajuda saber o que realmente dá errado. Mais ou menos na ordem em que você vai encontrar:
- Cercas de markdown. O modelo devolve
```json ... ```porque modelos de chat são treinados para apresentar código de forma agradável. - Introduções falantes. "Claro! Aqui está o JSON que você pediu:" seguido do objeto.
- Chaves erradas ou inventadas.
customerNameem vez decustomer_name, ou um camponotesextra que você nunca pediu. - Tipos errados.
"price": "19.99"como string,"count": "three", um objeto único onde você queria um array. - Truncamento. A resposta atinge o limite máximo de tokens e para no meio do objeto.
- Bobagem sintaticamente válida. JSON perfeito, conteúdo errado: uma data no formato errado, um telefone alucinado,
nullonde o valor estava ali na entrada.
Os recursos de saída estruturada eliminam as cinco primeiras, na maioria dos casos. Nada elimina a sexta, exceto bons prompts, grounding e verificações.
Passo 1: descreva a saída com precisão no prompt
Mesmo com o schema sendo imposto, é no prompt que você explica o que cada campo significa. Um schema diz que due_date é uma string; só o prompt pode dizer que deve ser ISO 8601 e que datas relativas devem ser resolvidas a partir da data de envio do e-mail.
Um prompt fraco:
Extraia os dados da fatura deste e-mail como JSON.
Um mais forte:
Extraia os dados da fatura do e-mail abaixo.
Devolva um único objeto JSON com exatamente estas chaves:
- "vendor": string, a empresa que emitiu a fatura
- "invoice_number": string, exatamente como escrito (mantenha os zeros à esquerda)
- "total": número, na moeda da fatura, sem símbolo de moeda
- "currency": string, código ISO 4217 como "USD" ou "EUR"
- "due_date": string no formato YYYY-MM-DD, ou null se não for informada
Se um valor não estiver no e-mail, use null. Não adivinhe.
Devolva somente o objeto JSON, sem markdown e sem explicação.
<email>
{{email_text}}
</email>
Dois detalhes pesam muito aqui. "Mantenha os zeros à esquerda" evita que o modelo, "prestativo", transforme 00417 em 417. E "use null, não adivinhe" dá ao modelo uma saída legítima. Sem uma opção explícita de null, um modelo sob a restrição de campo obrigatório inventa um valor plausível em vez de deixar vazio.
Passo 2: use o recurso de saída estruturada da API
A maioria dos grandes fornecedores hoje oferece alguma forma de restringir a saída a um schema. Os nomes e detalhes variam e mudam com o tempo, então confira a documentação atual, mas as principais opções são estas:
- OpenAI tem um JSON mode básico, que garante JSON sintaticamente válido, e o Structured Outputs, no qual você passa um JSON Schema com strict mode e a saída é restringida para corresponder a ele.
- Google Gemini permite definir o tipo MIME da resposta como JSON e fornecer um schema de resposta.
- Anthropic permite definir uma ferramenta com um schema de entrada e fazer o Claude chamá-la, o que gera argumentos no formato do schema; a documentação também descreve suporte nativo a saída estruturada.
A distinção importante é JSON mode vs imposição de schema. O JSON mode só promete que o texto é parseável. Suas chaves ainda podem estar erradas. A imposição de schema (muitas vezes feita com constrained decoding, que restringe quais tokens o modelo pode gerar em seguida) promete a forma.
Um schema para o exemplo da fatura:
{
"type": "object",
"properties": {
"vendor": { "type": ["string", "null"] },
"invoice_number": { "type": ["string", "null"] },
"total": { "type": ["number", "null"] },
"currency": { "type": ["string", "null"], "enum": ["USD", "EUR", "GBP", null] },
"due_date": { "type": ["string", "null"], "description": "YYYY-MM-DD" }
},
"required": ["vendor", "invoice_number", "total", "currency", "due_date"],
"additionalProperties": false
}
Repare nos tipos que aceitam null. Nos modos estritos, todo campo costuma ser obrigatório, então "opcional" precisa ser expresso como "obrigatório, mas pode ser null". Repare também em additionalProperties: false, que impede campos surpresa. Os modos estritos geralmente suportam só um subconjunto do JSON Schema, então veja quais palavras-chave são permitidas antes de montar algo elaborado.
Se você usa Python ou TypeScript, defina o schema como um modelo Pydantic ou um schema Zod e gere o JSON Schema a partir dele. Assim a mesma definição valida a resposta, e as duas coisas não se separam.
Passo 3: valide tudo, mesmo com a imposição
A imposição de schema garante a estrutura. Ela não garante:
- que
due_dateseja uma data real (30 de fevereiro é uma string válida), - que
totalbata com a soma dos itens, - que
vendorapareça em algum lugar do e-mail de origem, - que o modelo não tenha deixado de fora o terceiro de cinco itens.
Escreva as verificações que importam para o seu domínio. Faça o parse das datas. Verifique se os totais não são negativos. Em tarefas de extração, confira se as strings extraídas realmente aparecem na entrada; esse único teste pega uma quantidade surpreendente de alucinação.
Passo 4: tente de novo com o erro, não às cegas
Quando a validação falha, não reenvie a mesma requisição na esperança de que dê certo. Mande o erro de volta:
Sua resposta anterior falhou na validação:
- "due_date": "3 de março" não corresponde ao formato YYYY-MM-DD
- "currency": "dólares" não é um destes valores: USD, EUR, GBP
Devolva somente o objeto JSON corrigido.
Os modelos corrigem bem erros específicos e nomeados. Limite as retentativas a uma ou duas, registre cada falha em log e olhe os logs toda semana. Falhas repetidas no mesmo campo costumam indicar que o prompt ou o schema está confuso, não que o modelo é instável. Bibliotecas como o Instructor (Python) encapsulam esse ciclo de validar e tentar de novo, mas o padrão é simples o bastante para você mesmo escrever.
Para quebras só de sintaxe em fornecedores sem imposição, um parser tolerante que remove cercas e texto sobrando antes do JSON.parse resolve os casos mais comuns. Trate isso como contingência, não como estratégia.
Onde colocar o raciocínio em uma resposta JSON?
Se a tarefa exige julgamento (uma classificação com justificativa, uma pontuação de risco), coloque um campo de raciocínio antes do campo de decisão:
{
"evidence": "O cliente menciona uma cobrança duplicada na fatura de março.",
"category": "billing",
"confidence": "high"
}
Os modelos geram os campos em ordem. Uma decisão escrita primeiro é justificada depois, em vez de ser informada pelo raciocínio. Aprofundamos isso em chain-of-thought prompting explicado.
O outro lado: campos de raciocínio custam tokens a cada chamada. Em extrações simples, deixe-os de fora.
Erros comuns no desenho de schemas de saída
Aninhamento profundo sem motivo. Três níveis de objetos onde uma lista plana resolveria. Cada nível é mais um lugar onde o modelo pode colocar um valor no lugar errado.
Campos de texto livre que deveriam ser enums. Se o código a jusante se ramifica a partir de status, faça dele um enum. Do contrário, você vai receber "Pending", "pending", "In progress" e "awaiting review" para a mesma coisa.
Nomes de campo ambíguos. date em uma fatura pode ser a data de emissão, de vencimento ou de pagamento. Chame de due_date e descreva.
Pedir demais em uma só chamada. Um schema com quarenta campos extraídos de um contrato de vinte páginas convida a omissões. Divida: uma chamada por seção, ou uma chamada para localizar as passagens relevantes e outra para extrair delas.
Esquecer o caso vazio. O que a saída deve ser se o e-mail nem for uma fatura? Adicione um booleano is_invoice ou permita um resultado vazio, senão o modelo vai extrair uma fatura de um convite para almoço.
Só o prompt basta alguma vez?
Para protótipos, scripts que você roda manualmente ou modelos sem suporte a saída estruturada, sim. Uma descrição precisa do formato, um exemplo da saída exata e um parser defensivo levam você a uma confiabilidade alta. Para qualquer coisa voltada ao usuário, use a imposição de schema quando houver e a validação sempre.
A habilidade de fundo é a mesma em todos os casos: descrever a saída com tanta precisão que só exista uma forma razoável de preenchê-la. O tópico de saída estruturada treina essas decisões e, se o JSON que você produz é uma chamada de ferramenta e não uma resposta final, tool calling e agentes de IA continua daqui. Para extração baseada em documentos de origem, veja o que é RAG.
Perguntas frequentes
Como forço um LLM a devolver JSON válido?
Use o recurso de saída estruturada do fornecedor com um JSON Schema quando ele existir, porque ele restringe a geração ao schema. Depois, valide o resultado no código mesmo assim e tente de novo ou corrija quando a validação falhar.
Qual é a diferença entre JSON mode e structured outputs?
O JSON mode faz o modelo produzir JSON sintaticamente válido, mas não garante suas chaves nem seus tipos. Os structured outputs com um schema estrito restringem a saída para que ela siga o schema que você fornece.
Por que meu LLM envolve o JSON em blocos de código markdown?
Modelos ajustados para chat são treinados para formatar código de forma agradável para pessoas. Diga ao modelo que devolva apenas o objeto JSON puro ou use um modo de saída estruturada, e remova as cercas de forma defensiva no seu parser.
Devo validar o JSON de um LLM mesmo com schema?
Sim. Um schema garante a forma, não a verdade. O JSON pode ser perfeitamente válido e ainda conter uma data errada, um valor inventado ou um campo vazio onde havia dado.
- #saída estruturada
- #JSON
- #JSON schema
- #validação