Saída Estruturada

Intenção

Exigir que o modelo responda num schema definido e validar a resposta no código antes de usar. Serve para qualquer saída que outro programa vai ler: extração, classificação, roteamento, chamada de API, dados que vão para o banco.

Problema

A Bianca automatizou a leitura de notas fiscais de fornecedores. O prompt pedia: “devolva um JSON com CNPJ do emitente, data de emissão e valor total”. Na primeira semana, deu certo em quase tudo.

Aí começaram os casos estranhos. Uma nota veio com o JSON embrulhado em três crases e a palavra json. Outra trouxe o valor como "R$ 1.234,56", em texto, quando o sistema esperava número. Uma terceira chamou o campo de cnpj_emissor em vez de cnpj_emitente. E numa delas o modelo respondeu “Claro! Aqui está o JSON:” antes das chaves.

Cada caso virou um try, um replace e uma expressão regular no código. O parser cresceu mais que a lógica de negócio, e mesmo assim falhava algumas vezes por dia.

A pergunta que este padrão responde: como fazer o modelo entregar dados que o seu código pode usar sem adivinhar?

Solução

Pare de pedir formato no texto do prompt e passe a declarar o formato como parte da chamada. As APIs atuais aceitam um schema JSON (ou uma classe Pydantic, ou um objeto Zod) e restringem a geração para que a saída siga esse schema: nomes de campo, tipos e valores permitidos.

O schema garante a forma, não a verdade. Um CNPJ pode ter 14 dígitos e mesmo assim estar errado. Por isso a segunda metade do padrão é validar regras de negócio no código: dígito verificador, data no passado, valor positivo. Forma garantida pela API, conteúdo conferido por você.

A refatoração que chega aqui é Trocar Texto Livre por Saída Estruturada. Use-a quando o parser de JSON já virou o produto.

Estrutura

flowchart LR
  IN(["1. Texto da nota"]):::io --> M(["2. Modelo com schema"]):::llm
  M --> P["3. Parse tipado"]:::tool
  P --> V{"4. Regras de negócio OK?"}
  V -->|"sim"| DB[("5. Sistema contábil")]:::store
  V -->|"não"| Q((("6. Fila de revisão"))):::human

1. A entrada é o texto que precisa virar dado.
2. A chamada leva o schema junto. O modelo só consegue gerar saídas nesse formato.
3. O SDK transforma a resposta num objeto tipado, sem expressão regular.
4. O código confere as regras que o schema não expressa.
5. Dado válido segue direto para o sistema.
6. Dado com forma certa e conteúdo suspeito vai para uma pessoa revisar.

Exemplo trabalhado

A Bianca recebe esta nota (trecho):

EMITENTE: Padaria São Jorge Ltda
CNPJ: 11.222.333/0001-81
Data de emissão: 14/08/2026
Total: R$ 1.234,56
Itens: Pão francês 800un  R$ 800,00 | Café 20kg  R$ 434,56

Com “devolva um JSON” no prompt, uma resposta realista era um parágrafo (“Claro! Segue o JSON:”), três crases, o campo cnpj_emissor no lugar de issuer_cnpj, e o total como a string "R$ 1.234,56".

Três falhas de forma numa resposta: texto em volta, nome de campo errado, número como string com R$. O parser da Bianca precisava das três correções, e na semana seguinte aparecia uma quarta.

Com schema nativo, a API só consegue emitir os campos issuer_cnpj, issue_date, total, items. O SDK entrega um objeto. Aí o código da Bianca ainda tem trabalho: o CNPJ 11222333000181 precisa passar no dígito verificador, a soma dos itens precisa bater com o total, a data não pode ser futura.

O CNPJ da Padaria São Jorge neste exemplo é ilustrativo. Em produção, use o validador de dígitos; 14 dígitos iguais (111…) já são inválidos pela regra.

Pseudocódigo

schema Invoice {
    issuer_cnpj: string        # 14 dígitos
    issue_date: date
    total: float
    items: list of { description: string, amount: float }
}

function read_invoice(text):
    # 2 e 3. forma garantida pela API
    invoice = llm(EXTRACT_PROMPT, text) -> Invoice

    # 4. conteúdo conferido no código
    errors = []
    if not valid_cnpj(invoice.issuer_cnpj): errors.add("cnpj")
    if invoice.issue_date > today(): errors.add("data futura")
    if abs(sum(invoice.items.amount) - invoice.total) > 0.01: errors.add("soma")

    if errors: return human.review(invoice, errors)   # 6
    return accounting.save(invoice)                    # 5

Cenários reais

• Extração de NF-e e contratos. Cada documento vira um objeto com campos fiscais. O schema acaba com o parser frágil, e a validação de CNPJ e de soma pega o que o modelo leu errado.
• Triagem automática de tickets. Fila, prioridade e produto vêm como enums. O código nunca recebe uma prioridade “urgentíssima” que não existe na lista.
• Triagem de currículos com controle de viés. Cada critério de avaliação vira um campo com nota e justificativa. A estrutura permite auditar a decisão campo por campo e checar viés por grupo.

Aplicabilidade

• Outro programa vai ler a saída do modelo.
• A resposta tem campos que você precisa acessar por nome.
• Os valores possíveis de um campo são uma lista fechada.
• Você vai gravar o resultado num banco ou mandar para uma API.
• Etapas de uma cadeia passam dados entre si.

Quando não usar

• A saída é texto para uma pessoa ler, como uma resposta de chat. Forçar schema ali só atrapalha a escrita.
• O formato é um texto curto e livre, e o código só exibe o que veio.
• O schema seria tão aberto (um campo resposta: string) que não garante nada. Aí ele só adiciona cerimônia.

Erro comum: campo obrigatório que a fonte não tem

Toda NF-e tem emitente. Nem todo contrato de prestação tem multa. Se penalty é obrigatório, o modelo inventa “10% padrão” para não quebrar o schema. No eval, isso aparece como taxa de invenção: documentos sem o campo deveriam devolver null.

Marque como opcional o que pode faltar. Use enum para prioridade, produto, tipo de nota. string aberto é o schema largo que deixa "urgentíssima" passar.

Saída estruturada também não é para a resposta de chat que uma pessoa lê. Forçar JSON ali deixa o texto engessado e não ajuda o código, porque ninguém vai parsear.

Como implementar

1. Escreva o schema antes do prompt. Use os tipos mais estreitos possíveis: enum no lugar de string, número no lugar de texto.
2. Marque como opcional o que pode realmente faltar no documento. Campo obrigatório que não existe na fonte leva o modelo a inventar.
3. Use o recurso nativo de saída estruturada do SDK (messages.parse com Pydantic ou Zod).
4. Mantenha no prompt só a explicação de cada campo, com exemplos de casos difíceis. O formato já está no schema.
5. Escreva no código as validações de negócio que o schema não cobre.
6. Decida o que acontece com dados inválidos: reparo automático, revisão humana ou descarte com log.
7. Monte um eval com valores esperados por campo.

Não avalie “JSON válido”. Com schema nativo isso quase sempre passa e esconde o erro de conteúdo. Avalie issuer_cnpj, total, issue_date contra o rótulo, depois da normalização (só dígitos no CNPJ, data em ISO).

Variações

• Saída estruturada nativa. A API restringe a geração ao schema. É a opção padrão hoje.
• Ferramenta como schema. Você define uma ferramenta com strict: true e o modelo “chama” essa ferramenta com os dados. Útil quando a mesma chamada também usa outras ferramentas.
• Validar e reparar. Sem suporte nativo, você valida a saída e, se falhar, manda o erro de volta para o modelo corrigir. Tem página própria em Validação e Reparo de Saída.

Versione o schema como versiona o prompt. Um campo novo obrigatório empurra invenção nos documentos antigos do eval. Um campo removido quebra o código que ainda lê o nome velho. Guarde schema_version no span junto com a versão do prompt, para um pico de “cnpj inválido” apontar para o deploy certo.

Quando o provedor ainda não restringe a geração, não finja que pediu JSON no texto. Valide, e se falhar, entre no reparo com a mensagem de erro do parser. Isso é outro padrão, e o teto de tentativas dele é o mesmo teto de qualquer laço.

Custo, latência e falhas

Como avaliar

Avalie campo por campo. “O JSON era válido” deixou de ser métrica: com saída estruturada nativa, ele quase sempre é.

• Acerto por campo: o valor bate com o rótulo? Normalize antes de comparar (datas, maiúsculas).
• Taxa de invenção: em documentos onde o campo não existe, o modelo devolve null ou inventa?
• Taxa de barrados pela validação: quanto vai para revisão humana, e quantos desses eram de fato erros.

Um caso de eval:

O rótulo precisa do valor canônico, não do texto da nota. R$ 1.234,56 no PDF vira 1234.56 no expected. Se você comparar string com string, o eval pune formatação e deixa passar CNPJ errado com a pontuação certa.

Inclua documentos ruins de propósito: escaneados tortos, campos faltando, dois valores parecidos na mesma página. O caso fácil não ensina o schema. O caso com dois totais (o da capa e o da última página) ensina se o modelo chuta o maior.

Separe no eval os documentos onde o campo existe dos onde ele não existe. Acurácia geral mistura acerto em campo presente com invenção em campo ausente. São dois erros diferentes, com dois consertos: prompt e exemplos para o primeiro, opcionalidade para o segundo.

{ "input": "notas/fornecedor-118.txt", "expected": { "issuer_cnpj": "11222333000181", "issue_date": "2026-08-14", "total": 1234.56 } }

Em produção

• Log da versão do schema junto com a versão do prompt em cada span.
• Métrica de quantos documentos falham em cada regra de validação. Uma regra que dispara de repente costuma indicar um fornecedor com layout novo.
• Tamanho da fila de revisão humana e tempo até alguém olhar.
• Amostra periódica de documentos aprovados automaticamente, para achar erros que passaram em todas as regras.

Segurança

Saída estruturada reduz uma classe de risco: o código para de interpretar texto livre que pode conter qualquer coisa. Mas o conteúdo dos campos ainda vem do modelo, que leu um documento externo. Trate os valores como entrada não confiável: escape antes de exibir, use parâmetros em consultas SQL e nunca execute um campo como código.

O OWASP Top 10 for LLM Applications trata isso como handling inseguro de saída: o modelo não é uma fonte confiável, mesmo quando a forma está certa. Um campo description copiado para HTML é XSS. Um campo query interpolado em SQL é injeção. Schema não sanitiza.

Prós e contras

Código

As abas extraem a mesma nota com schema e validam CNPJ e soma no código. Python e TypeScript usam o SDK da Anthropic. A aba OpenAI é a mesma chamada em outro provedor. LangChain esconde o envelope para os dois.

from datetime import date

import anthropic
from pydantic import BaseModel

client = anthropic.Anthropic()


class Item(BaseModel):
    description: str
    amount: float


class Invoice(BaseModel):
    issuer_cnpj: str
    issue_date: date
    total: float
    items: list[Item]


def valid_cnpj(cnpj: str) -> bool:
    digits = [int(c) for c in cnpj if c.isdigit()]
    if len(digits) != 14 or len(set(digits)) == 1:
        return False
    for size in (12, 13):
        weights = [6, 5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2][-size:]
        check = sum(d * w for d, w in zip(digits, weights)) % 11
        if digits[size] != (0 if check < 2 else 11 - check):
            return False
    return True


def read_invoice(text: str) -> Invoice | list[str]:
    # 2 e 3. forma garantida pela API
    invoice = client.messages.parse(
        model="claude-opus-5-5",
        max_tokens=4096,
        system="Extraia os dados da nota fiscal. CNPJ só com dígitos. Valores em reais, como número.",
        messages=[{"role": "user", "content": text}],
        output_format=Invoice,
    ).parsed_output

    # 4. conteúdo conferido no código
    errors = []
    if not valid_cnpj(invoice.issuer_cnpj):
        errors.append("cnpj")
    if invoice.issue_date > date.today():
        errors.append("data futura")
    if abs(sum(i.amount for i in invoice.items) - invoice.total) > 0.01:
        errors.append("soma")
    return errors or invoice

import Anthropic from "@anthropic-ai/sdk";
import { zodOutputFormat } from "@anthropic-ai/sdk/helpers/zod";
import { z } from "zod";

const client = new Anthropic();

const Invoice = z.object({
  issuer_cnpj: z.string(),
  issue_date: z.string(), // AAAA-MM-DD
  total: z.number(),
  items: z.array(z.object({ description: z.string(), amount: z.number() })),
});
type Invoice = z.infer<typeof Invoice>;

function validCnpj(cnpj: string): boolean {
  const d = cnpj.replace(/\D/g, "").split("").map(Number);
  if (d.length !== 14 || new Set(d).size === 1) return false;
  for (const size of [12, 13]) {
    const weights = [6, 5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2].slice(-size);
    const check = weights.reduce((acc, w, i) => acc + w * d[i], 0) % 11;
    if (d[size] !== (check < 2 ? 0 : 11 - check)) return false;
  }
  return true;
}

export async function readInvoice(text: string): Promise<Invoice | string[]> {
  // 2 e 3. forma garantida pela API
  const { parsed_output: invoice } = await client.messages.parse({
    model: "claude-opus-5-5",
    max_tokens: 4096,
    system: "Extraia os dados da nota fiscal. CNPJ só com dígitos. Valores em reais, como número. Data em AAAA-MM-DD.",
    messages: [{ role: "user", content: text }],
    output_config: { format: zodOutputFormat(Invoice) },
  });
  if (!invoice) return ["schema"];

  // 4. conteúdo conferido no código
  const errors: string[] = [];
  if (!validCnpj(invoice.issuer_cnpj)) errors.push("cnpj");
  if (new Date(invoice.issue_date) > new Date()) errors.push("data futura");
  const sum = invoice.items.reduce((acc, i) => acc + i.amount, 0);
  if (Math.abs(sum - invoice.total) > 0.01) errors.push("soma");
  return errors.length ? errors : invoice;
}

from datetime import date

from openai import OpenAI

client = OpenAI()  # lê OPENAI_API_KEY do ambiente


def read_invoice(text: str) -> Invoice | list[str]:
    # 2 e 3. forma garantida pela API. Invoice é a classe da aba Python.
    invoice = client.chat.completions.parse(
        model="gpt-4o-mini",
        messages=[
            {"role": "system", "content": "Extraia os dados da nota fiscal. CNPJ só com dígitos. Valores em reais, como número."},
            {"role": "user", "content": text},
        ],
        response_format=Invoice,
    ).choices[0].message.parsed
    if invoice is None:
        return ["schema"]

    # 4. conteúdo conferido no código
    errors = []
    if not valid_cnpj(invoice.issuer_cnpj):
        errors.append("cnpj")
    if invoice.issue_date > date.today():
        errors.append("data futura")
    if abs(sum(i.amount for i in invoice.items) - invoice.total) > 0.01:
        errors.append("soma")
    return errors or invoice

from datetime import date

from langchain.chat_models import init_chat_model

MODEL = "openai:gpt-4o-mini"  # ou "anthropic:claude-opus-5-5"
reader = init_chat_model(MODEL, temperature=0).with_structured_output(Invoice)


def read_invoice(text: str) -> Invoice | list[str]:
    # 2 e 3. o schema é o mesmo objeto Pydantic da aba Python
    invoice = reader.invoke([
        ("system", "Extraia os dados da nota fiscal. CNPJ só com dígitos. Valores em reais, como número."),
        ("human", text),
    ])

    # 4. conteúdo conferido no código
    errors = []
    if not valid_cnpj(invoice.issuer_cnpj):
        errors.append("cnpj")
    if invoice.issue_date > date.today():
        errors.append("data futura")
    if abs(sum(i.amount for i in invoice.items) - invoice.total) > 0.01:
        errors.append("soma")
    return errors or invoice

Suporte por framework

Conferido nas documentações da OpenAI e do LangChain 1.x em outubro de 2026.

Teste seu entendimento