Ir para o conteúdo
TokIQ
Saída

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.

TokIQ Editorial6 min de leitura
Neste artigo
  1. Por que os modelos quebram o JSON, para começar?
  2. Passo 1: descreva a saída com precisão no prompt
  3. Passo 2: use o recurso de saída estruturada da API
  4. Passo 3: valide tudo, mesmo com a imposição
  5. Passo 4: tente de novo com o erro, não às cegas
  6. Onde colocar o raciocínio em uma resposta JSON?
  7. Erros comuns no desenho de schemas de saída
  8. 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:

  1. Cercas de markdown. O modelo devolve ```json ... ``` porque modelos de chat são treinados para apresentar código de forma agradável.
  2. Introduções falantes. "Claro! Aqui está o JSON que você pediu:" seguido do objeto.
  3. Chaves erradas ou inventadas. customerName em vez de customer_name, ou um campo notes extra que você nunca pediu.
  4. Tipos errados. "price": "19.99" como string, "count": "three", um objeto único onde você queria um array.
  5. Truncamento. A resposta atinge o limite máximo de tokens e para no meio do objeto.
  6. Bobagem sintaticamente válida. JSON perfeito, conteúdo errado: uma data no formato errado, um telefone alucinado, null onde 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_date seja uma data real (30 de fevereiro é uma string válida),
  • que total bata com a soma dos itens,
  • que vendor apareç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

Agora pratique

O TokIQ transforma prompt engineering em quizzes curtos, com uma explicação para cada resposta.

Em breve naApp StoreDisponível noGoogle Play

Escreva prompts melhores, com algumas questões por dia.

Quizzes curtos sobre decisões reais de prompting, com uma explicação para cada resposta. Grátis para começar no iPhone e no Android.

Em breve naApp StoreDisponível noGoogle Play