Como escrever um bom schema de extração em linguagem natural

A primeira coisa que a maioria das pessoas faz no Ztract é criar um projeto. A segunda — a que de fato decide a qualidade dos seus resultados — é dizer o que você quer extrair dele. Essa descrição é o seu schema.

E aqui vem a parte que surpreende: você não escreve isso em código. Não há sintaxe para aprender, nenhum tipo de campo para declarar, nenhum modelo para desenhar na tela. Você descreve o que quer do mesmo jeito que explicaria para um colega novo: “Para cada nota fiscal, me traga o fornecedor, o total e cada item da lista.” O sistema cuida do resto.

Essa liberdade é justamente o objetivo — mas também significa que a qualidade do seu resultado acompanha a qualidade da sua descrição. Um pedido vago gera resultados vagos. Um pedido preciso gera dados limpos, em que você pode confiar logo na primeira passada. Este post é sobre o punhado de hábitos que deixam o seu schema em linguagem natural preciso, seja qual for o tipo de documento com que você está trabalhando.

Como é a cara de um bom schema

Antes das regras, veja o formato de uma descrição que funciona bem. Digamos que você esteja extraindo notas fiscais:

“Para cada nota fiscal, extraia o número da nota, a data de emissão, o nome do fornecedor e o valor total a pagar. Extraia também cada item da lista, com sua descrição, quantidade, preço unitário e total do item. Se um campo não estiver presente no documento, deixe em branco em vez de adivinhar.”

Repare no que isso faz. Ela nomeia campos específicos, e não “as coisas importantes”. Separa o que aparece uma vez por documento (número da nota, total) do que aparece várias vezes (os itens da lista). E diz o que fazer quando algo está faltando. Nada disso é técnico — é apenas preciso. Os cinco hábitos abaixo são como você chega lá.

Cinco hábitos que deixam um schema preciso

1. Seja específico sobre qual valor você quer

Documentos estão cheios de números e datas que se parecem. “O valor” de uma nota fiscal pode ser o subtotal, o imposto, o total antes do desconto ou o valor final a pagar. Se você escrever “extraia o valor”, está deixando a escolha por conta do acaso.

Nomeie exatamente qual:

• ❌ “a data” → ✅ “a data de emissão da nota fiscal (não a data de vencimento)”
• ❌ “o valor” → ✅ “o valor total a pagar, com impostos e descontos já incluídos”
• ❌ “o nome” → ✅ “a razão social do fornecedor (não a pessoa de contato)”

Quanto mais campos parecidos um documento tiver, mais isso importa.

2. Diga em que formato você quer

O sistema lê o que está na página, mas muitas vezes você quer aquilo padronizado em algo consistente — sobretudo datas, números e moeda. Se você se importa com o formato, peça por ele:

• “Formate todas as datas como YYYY-MM-DD.”
• “Apresente os valores como números simples, sem símbolos de moeda nem separadores de milhar.”
• “Registre os débitos como números negativos.”
• “Inclua o código da moeda (USD, EUR, etc.) como um campo separado.”

Sem isso, você recebe o que o documento mostra — $1,250.00, 1.250,00, (1,250.00) — e vai acabar arrumando tudo na planilha depois. Uma frase no começo poupa esse trabalho.

3. Separe “um por documento” de “um por linha”

Esse é o ponto que mais confunde as pessoas, e vale a pena ir devagar aqui. Alguns campos aparecem uma vez por documento — o número de uma nota fiscal, o período de um extrato bancário, o titular da conta. Outros se repetem — cada item da lista, cada transação, cada passageiro em uma passagem.

Se você não os distingue, pode acabar com um único valor onde queria uma lista, ou com uma bagunça achatada onde queria estrutura. A solução é dizer isso em voz alta:

“Extraia os campos no nível do extrato uma única vez: titular da conta, número da conta, saldo inicial, saldo final. Depois extraia cada transação como sua própria linha, com data, descrição e valor.”

As palavras “para cada” são suas aliadas. “Para cada item da lista…”, “para cada transação…” — elas dizem ao sistema para esperar uma lista e devolvem linhas limpas e repetidas em vez de uma confusão.

4. Acrescente uma palavra de desambiguação para campos que se confundem

Alguns campos são genuinamente ambíguos, e nenhuma leitura da página resolve isso — só a sua intenção resolve. Um documento aduaneiro pode trazer tanto um número de nota fiscal quanto um número de ordem de compra, tanto um endereço de entrega quanto um de cobrança, tanto um peso bruto quanto um peso líquido.

Quando dois campos podem ser confundidos, acrescente um esclarecimento curto:

• “o número da nota fiscal (o do vendedor, marcado como ‘INV’ — não o número da PO)”
• “o endereço de entrega (para onde a mercadoria vai, não o endereço de cobrança)”

Você sabe qual deles realmente precisa. Dizer isso elimina a adivinhação.

5. Decida o que acontece quando um campo está faltando

Documentos reais são inconsistentes. Uma nota fiscal tem número de PO, a seguinte não tem. Se você não diz o que fazer, deixa a coisa em aberto — e, na extração, o padrão seguro que você quase sempre quer é não inventar nada:

“Se um campo não estiver presente no documento, deixe em branco. Nunca adivinhe nem preencha com algo provisório.”

Essa única linha vale especialmente a pena para documentos financeiros, jurídicos e médicos, onde um valor errado, mas convicto, é muito mais perigoso do que uma célula vazia que você consegue ver e investigar depois.

Três formas de criar um schema — e quando usar cada uma

O Ztract te dá três pontos de partida. Os hábitos acima valem para todos eles; a questão é só por onde você começa.

• Comece a partir de um schema pronto. Para documentos comuns — notas fiscais, recibos, extratos bancários, documentos de identidade, currículos, contratos, laudos laboratoriais, papelada aduaneira — já existe um modelo que conhece os campos de sempre. Melhor quando o seu documento é de um tipo padrão e você quer começar rápido, e depois ajustar.
• Descreva os campos você mesmo. Escreva a descrição em linguagem natural do zero. Melhor quando o seu documento é incomum, ou quando você quer exatamente estes campos e nada mais. É aqui que os cinco hábitos provam seu valor.
• Deduza a partir de uma amostra. Envie um documento representativo e deixe o sistema propor um schema a partir do que ele vê. Melhor quando você ainda não sabe quais campos um documento contém até olhar um — depois é só refinar a proposta em linguagem natural.

A maioria das pessoas acaba combinando as três: começa por um modelo ou uma amostra e depois afia a descrição na mão, usando os hábitos acima.

Você pode conferir nossa página de documentação criando o seu schema para mais informações.

Uma tabela rápida de solução de problemas

Quando o resultado não é o que você esperava, a causa costuma estar na descrição. As mais comuns:

O que você vê	Causa provável	A solução
Número errado extraído para o “valor”	O campo não era específico	Nomeie o valor exato: “total a pagar com impostos”
Datas em formatos misturados	Nenhum formato foi pedido	Acrescente “formate todas as datas como YYYY-MM-DD”
Um valor único onde você queria uma lista	Campo repetido não foi marcado	Use “para cada … extraia …”
Lista achatada em uma única célula	O mesmo de cima	O mesmo — nomeie explicitamente os campos por linha
Um campo inventado do nada	Nenhuma regra para campo faltante	Acrescente “deixe em branco se não estiver presente, nunca adivinhe”
Dois campos parecidos trocados	Nenhuma desambiguação	Acrescente um esclarecimento: “o número da PO, não o número da nota fiscal”

O schema é só metade do ciclo

Mesmo um schema bem escrito se beneficia de uma segunda olhada, e o Ztract foi construído em torno disso. Cada valor extraído fica ancorado à sua posição no documento de origem — clique em um valor e você vê exatamente de onde ele veio. Você procura os que parecem errados, corrige em um clique, e pronto. As correções não custam nada; só a extração conta na sua cota de páginas, e não a edição feita depois.

Então o objetivo de um bom schema não é a perfeição na primeira tentativa — é chegar perto o suficiente para que a etapa de revisão seja uma conferida rápida, e não um refazer tudo. Os cinco hábitos acima são o que te levam até lá.

Experimente em um documento de verdade

A forma mais rápida de pegar o jeito disso é escrever uma descrição para um documento com que você realmente trabalha e ver o que volta. Contas novas ganham 30 páginas grátis, sem cartão de crédito — mais que suficiente para rascunhar um schema, refiná-lo e ver o resultado ficar mais preciso conforme você faz isso.

E se algum tipo de documento ou um schema que você tentou descrever te deixou na mão — se você não encontrou as palavras para obter o resultado que queria — é exatamente esse o feedback que buscamos. Fale conosco; fazer com que o design de schema pareça óbvio para quem não é engenheiro é a parte do produto que mais nos importa acertar.