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?
- Prepare cada página: converta PDFs em imagens, corrija a rotação, redimensione.
- Extraia: uma requisição por documento, com um prompt campo a campo, só JSON.
- Valide: parsing, checagem de esquema, checagem aritmética.
- Repita uma vez com a mensagem de erro se a validação falhar.
- Revise: o que continuar falhando vai para uma pessoa, com a imagem e o rascunho.
- 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.

