BroadRouter

Extrair dados de faturas, recibos e formulários com LLM de visão

Pela equipe da BroadNet Inference · 4 min de leitura · Publicado em

Converta cada página em imagem, envie a um modelo de visão com um prompt que nomeie cada campo e seu formato, e peça só JSON. Depois valide no código: faça o parsing, confira o esquema, verifique se os itens somam o total e repita uma vez com o erro. Falhas repetidas vão para uma pessoa.

A paper invoice headed "فاتورة" (invoice) with tabs labelled Vendor, Date and Total, and the text "Turn documents into useful data."
Illustrative example.

Faturas, recibos e formulários têm o mesmo problema: os dados estão numa imagem, e você precisa deles num banco de dados. OCR baseado em templates quebra a cada novo layout de fornecedor. Um modelo de visão e linguagem lê a página e devolve os campos diretamente. O porém é que ele pode errar com toda a confiança, então o trabalho está no pipeline em volta dele. Este post cobre o pipeline geral, para qualquer idioma. Para documentos em árabe, veja ler faturas em árabe com visão para a configuração e OCR em árabe versus LLMs de visão para saber quando o OCR clássico é a melhor ferramenta.

Como é o pipeline?

  1. Prepare cada página: converta PDFs em imagens, corrija a rotação, redimensione.
  2. Extraia: uma requisição por documento, com um prompt campo a campo, só JSON.
  3. Valide: parsing, checagem de esquema, checagem aritmética.
  4. Repita uma vez com a mensagem de erro se a validação falhar.
  5. Revise: o que continuar falhando vai para uma pessoa, com a imagem e o rascunho.
  6. Meça a precisão por campo em uma amostra rotulada e rode de novo sempre que trocar de modelo ou de prompt.

Como preparar as imagens dos documentos?

Converta PDFs em imagens com o PyMuPDF e mantenha o menor texto nítido sem enviar mais pixels do que o necessário:

# pip install pymupdf pillow
import base64, io
import pymupdf  # older code imports it as fitz
from PIL import Image

def pdf_pages_as_data_urls(path, long_edge=1800):
    urls = []
    for page in pymupdf.open(path):
        pix = page.get_pixmap(dpi=200)
        img = Image.open(io.BytesIO(pix.tobytes("png"))).convert("RGB")
        img.thumbnail((long_edge, long_edge))
        buf = io.BytesIO()
        img.save(buf, format="JPEG", quality=90)
        urls.append("data:image/jpeg;base64," + base64.b64encode(buf.getvalue()).decode())
    return urls

Na BroadNet Inference, as imagens vão na mensagem como URLs data: com o tipo MIME correto e, no pagamento por uso, são cobradas como tokens de entrada; imagens maiores usam mais. Meça uma vez os tokens por página com o bloco usage e dimensione os lotes a partir disso; contar tokens antes de enviar mostra como, e custo por imagem em LLMs de visão transforma tokens em custo por página. Para estimar os tokens por página antes de enviar qualquer coisa, jogue uma digitalização de exemplo na calculadora de tokens de imagem.

Como escrever o prompt de extração?

Seja exato sobre chaves, tipos, formatos e valores ausentes. Se você também quiser um JSON Schema para validação ou para provedores que o exigem, o gerador gratuito de JSON Schema monta um a partir de uma fatura de exemplo:

PROMPT = """Extract this invoice. Reply with one JSON object only, no prose.
Keys:
- vendor_name: string, as printed
- vendor_tax_id: string or null
- invoice_number: string
- invoice_date: string, YYYY-MM-DD
- currency: ISO 4217 code, e.g. USD, EUR, SAR
- line_items: list of {description: string, quantity: number, unit_price: number, line_total: number}
- subtotal: number
- tax: number or null
- total: number
Rules: numbers without currency symbols or thousands separators. If a field is not on the page, use null. Never guess."""

“Never guess” (nunca chute) junto com um null explícito é o que mais importa. Sem isso, os modelos preenchem lacunas com valores plausíveis, o que é pior do que um campo vazio, porque passa numa checagem ingênua.

Como obter saída estruturada e validá-la?

A saída estruturada tem dois níveis. O modo JSON garante um JSON válido. A saída restrita a um esquema garante também o formato. O guia da OpenAI diz isso com clareza: os dois produzem JSON válido, mas só os Structured Outputs garantem a aderência ao esquema. O suporte a cada um varia por provedor e modelo, então valide no código, não importa o que a API prometa:

import json, os
from decimal import Decimal
from pydantic import BaseModel, ValidationError, model_validator
from openai import OpenAI

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])

class Line(BaseModel):
    description: str
    quantity: Decimal
    unit_price: Decimal
    line_total: Decimal

class Invoice(BaseModel):
    vendor_name: str
    vendor_tax_id: str | None = None
    invoice_number: str
    invoice_date: str
    currency: str
    line_items: list[Line]
    subtotal: Decimal
    tax: Decimal | None = None
    total: Decimal

    @model_validator(mode="after")
    def sums(self):
        tol = Decimal("0.02")
        if abs(sum(l.line_total for l in self.line_items) - self.subtotal) > tol:
            raise ValueError("line_totals do not sum to subtotal")
        if abs(self.subtotal + (self.tax or 0) - self.total) > tol:
            raise ValueError("subtotal + tax != total")
        return self

def extract(image_urls, model="broadnet/qwen3.8-27b"):
    content = [{"type": "text", "text": PROMPT}] + [
        {"type": "image_url", "image_url": {"url": u}} for u in image_urls]
    messages = [{"role": "user", "content": content}]
    for attempt in range(2):
        r = client.chat.completions.create(model=model, messages=messages, max_tokens=4000, temperature=0)
        raw = (r.choices[0].message.content or "").strip().removeprefix("```json").removesuffix("```")
        try:
            return Invoice.model_validate(json.loads(raw)), r.usage
        except (json.JSONDecodeError, ValidationError, ValueError) as e:
            messages += [{"role": "assistant", "content": raw},
                         {"role": "user", "content": f"That failed validation: {e}. Re-read the image and reply with corrected JSON only."}]
    return None, r.usage  # send to human review

Use Decimal, não float, para valores monetários. Mantenha max_tokens generoso: o Qwen3.8 27B raciocina antes de responder, e o raciocínio conta no limite; um teto baixo devolve uma string vazia. Veja por que modelos de raciocínio devolvem respostas vazias.

Quais checagens pegam mais erros?

Checagem O que pega Custo
O JSON faz parsing Texto em volta do JSON, truncamento Grátis
O esquema valida Chaves ausentes, tipos errados Grátis
As linhas somam o subtotal Dígitos lidos errado, linhas puladas Grátis
Subtotal + imposto = total Total ou imposto lidos errado Grátis
A data faz parsing e não está no futuro Dia e mês trocados, ruído de OCR Grátis
O CNPJ do fornecedor bate com o seu cadastro Fornecedor errado, fraude Uma consulta
Número de fatura duplicado por fornecedor Pagamento em dobro Uma query

As checagens aritméticas são as que mais compensam: um único dígito lido errado quase sempre quebra uma soma. Recibos muitas vezes não têm detalhe por linha, então confira o que existe e aceite menos checagens para eles.

Como medir a precisão antes de colocar em produção?

Rotule à mão de 50 a 100 documentos reais, rode o pipeline e avalie por campo, não por documento. Totais e datas merecem um critério mais rígido do que descrições. Acompanhe três números: a precisão por campo, a fração de documentos que passam na validação sem retentativa e a fração enviada para revisão. Como desenhar essa etapa de revisão, incluindo auditorias aleatórias de documentos que passaram, está em tornar a revisão humana parte do seu fluxo de IA para documentos. Quando testar outro modelo, use o mesmo conjunto; avaliar um LLM antes de trocar explica o método.

Quais modelos de visão servem na BroadNet Inference?

Modelo Imagens Contexto Observações
Qwen3.8 27B Sim 262.144 Ferramentas, saída estruturada e raciocínio listados; testado em árabe pela BroadNet
Gemma 4 VL 26B Sim 32.768 Menor preço da BroadNet; funciona com o crédito gratuito e com a chave por hora
DeepSeek V4.1 Flash Sim 1.048.576 Imagens incluídas nos planos ilimitados

Os preços por 1M de tokens estão na página de preços; multiplique os tokens por página que você mediu pelo volume mensal na calculadora de custo de API de LLM.

Onde a BroadNet Inference se encaixa

A BroadNet Inference aceita imagens em três modelos de chat pelo formato padrão de mensagens da OpenAI e não retém prompts, imagens nem respostas após a requisição, o que importa em faturas cheias de nomes, números de identificação fiscal e dados bancários (retenção zero de dados). A documentação lista saída estruturada para o Qwen3.8 27B, mas não documenta parâmetros de esquema, então confie na camada de validação acima, e não na API, para impor o seu esquema. A BroadNet não publica um limite de tamanho de imagem nem um produto dedicado de IA para documentos, e a documentação descreve entrada de imagens, não upload de PDF, então converta as páginas em imagens antes. Para execuções de alto volume com orçamento fixo, um plano ilimitado do DeepSeek V4.1 Flash inclui imagens.

Perguntas frequentes

Um LLM de visão pode substituir o OCR em faturas?

Em muitos layouts, sim. Um modelo de visão lê a imagem e associa o texto aos campos em uma só etapa, sem templates por fornecedor. Mas às vezes ele ainda lê dígitos errado, então mantenha a validação e uma fila de revisão.

Como obter um JSON confiável de um modelo de visão?

Liste no prompt as chaves, os tipos e os formatos exatos, peça só JSON e faça o parsing no código. Se o modelo suporta saída restrita a um esquema, use. De qualquer forma, valide com uma biblioteca de esquemas e repita uma vez com o erro.

Como extrair dados de uma fatura em PDF com várias páginas?

Converta cada página em imagem e envie todas as páginas de uma mesma fatura em uma única requisição, se couberem no contexto do modelo, para que os totais da última página possam ser conferidos com as linhas da primeira.

Qual resolução as imagens das faturas devem ter?

Alta o suficiente para que os menores dígitos fiquem nítidos, e não mais que isso. Imagens maiores usam mais tokens de entrada. Um lado maior de cerca de 1.500 a 2.000 pixels é um bom ponto de partida para uma página A4; teste com os seus documentos.

Como medir a precisão da extração?

Rotule à mão de 50 a 100 documentos reais e avalie campo a campo. Acompanhe totais e datas separados de campos de texto livre, como nomes de fornecedores, porque o custo dos erros é diferente.

Ler em MarkdownPerguntar ao ChatGPTPerguntar ao ClaudePerguntar ao Perplexity