docTR: guia completo para criar um pipeline de OCR e inteligência de documentos

Extrair informação útil de documentos escaneados — notas fiscais, contratos, laudos, formulários — sempre foi um dos trabalhos mais manuais (e caros) em qualquer empresa. O que mudou é que, hoje, uma biblioteca open source consegue fazer reconhecimento de texto (OCR), análise de layout e extração estruturada de campos em um único pipeline, rodando até na sua máquina. Este guia mostra como montar esse fluxo com o docTR, do zero até a exportação de PDFs pesquisáveis.

Prós e contras do docTR

✅ O que você ganha

• Pipeline completo em uma única biblioteca: detecção, reconhecimento, layout e KIE (extração de informação-chave).
• Modelos pré-treinados com pesos prontos para download, sem treinar nada do zero.
• Geometria em coordenadas relativas (0–1), o que facilita reconstruir ordem de leitura e tabelas.
• Exportação em vários formatos: texto, JSON, hOCR, imagem sintetizada e PDF pesquisável.
• Suporte a GPU com ganhos de 5–10x trocando apenas a arquitetura.
• Código aberto (Apache 2.0), com integração ao Hugging Face Hub.

⚠️ O que você NÃO ganha

• O vocabulário padrão dos checkpoints é francês/latim — para acentos e caracteres específicos do português, pode ser preciso fine-tuning.
• Não faz “entendimento” semântico: ele devolve texto fiel + geometria, não o significado. A extração de campos ainda depende de regex ou de um LLM.
• Documentos manuscritos ou com texto curvo exigem modelos mais pesados (PARSeq) e mais cuidado.
• Detecção de layout e KIE exigem versões específicas e, para uso real, treino com classes próprias.

Requisitos

Passo a passo

1. Instalar e preparar o ambiente

Comece instalando a biblioteca principal. Se estiver no Google Colab, o próprio script resolve as dependências na primeira execução:

pip install "python-doctr[viz]" reportlab

Depois, confira se há GPU disponível — o docTR usa PyTorch e se beneficia bastante dela:

import torch, doctr
DEVICE = "cuda" if torch.cuda.is_available() else "cpu"
print(doctr.__version__, DEVICE)

2. Carregar imagens e PDFs

O ponto de entrada é o DocumentFile, que normaliza qualquer fonte para uma lista de arrays NumPy:

from doctr.io import DocumentFile
imgs = DocumentFile.from_images(["pag1.png", "pag2.png"])
pdf  = DocumentFile.from_pdf("doc.pdf", scale=3)  # scale maior = texto pequeno

A regra prática do scale: o texto do corpo deve ter pelo menos ~10 pixels de altura para o reconhecedor funcionar bem. Para scans de 150–300 dpi, o padrão (2) serve; para texto denso de 8pt, suba para 3 ou 4.

3. Construir o preditor de OCR

from doctr.models import ocr_predictor
model = ocr_predictor(det_arch="db_resnet50", reco_arch="crnn_vgg16_bn", pretrained=True)
if DEVICE == "cuda":
    model = model.cuda()
result = model(imgs)

O ocr_predictor une dois modelos: o detector (que encontra as caixas de texto) e o reconhecedor (que transcreve o que há dentro de cada caixa). O resultado é uma hierarquia de pages → blocks → lines → words, onde cada palavra carrega valor, confiança e geometria.

4. Benchmark de arquiteturas

Nem sempre o modelo mais pesado é o melhor. O tutorial compara combinações de detector + reconhecedor medindo tempo e acurácia de palavras:

5. Reconhecimento em duas passadas

Uma técnica poderosa para melhorar a precisão sem encarecer todo o fluxo: rode um modelo rápido, identifique as palavras com confiança abaixo de um limiar (ex.: 0,85) e reprocesse somente esses recortes com um modelo mais forte (PARSeq).

# palavras fracas recebem uma segunda leitura com um modelo melhor
weak = [w for w in words if w.confidence < 0.85]
strong = recognition_predictor("parseq", pretrained=True)
redo = strong(crop_words(weak))

6. Lidar com documentos rotacionados

Há três estratégias para páginas tortas:

• assume_straight_pages=True — mais rápido, mas quebra com inclinação acima de ~5 graus.
• assume_straight_pages=False — devolve polígonos de 4 pontos, mais robusto.
• straighten_pages=True — "desentorta" a página antes de processar.

7. Exportar resultados (inclusive PDF pesquisável)

O docTR exporta em vários formatos. O mais útil para o mundo real é o PDF pesquisável: uma camada de texto invisível é sobreposta à imagem original, então você pode usar Ctrl+F no documento escaneado — o visual não muda, mas o texto fica selecionável.

txt  = result.render()          # texto puro
data = result.export()          # JSON com geometria
xml  = result.export_as_xml()   # hOCR
synth = result.synthesize()     # re-renderiza o texto nas caixas

Casos de uso reais

• Financeiro: extrair número da nota fiscal, data e valor total de milhares de documentos automaticamente.
• Jurídico: transformar contratos escaneados em PDFs pesquisáveis para consulta rápida.
• Saúde: digitalizar laudos e prontuários preservando a estrutura de tabelas.
• Logística: ler conhecimentos de embarque e etiquetas com texto inclinado ou ruidoso.
• RAG corporativo: alimentar um assistente de IA com o texto fiel extraído de documentos internos.

Custo: local vs cloud

Troubleshooting

• ❌ "ImportError: python-doctr" → Causa: dependência não instalada. Solução: pip install "python-doctr[viz]" e reinicie o runtime no Colab.
• ❌ Erro de vocabulário (caracteres ignorados) → Causa: o checkpoint padrão usa vocabulário francês/latim. Solução: faça fine-tuning com um vocab mais amplo (doctr.datasets.VOCABS).
• ❌ Baixa acurácia em texto pequeno → Causa: scale do PDF baixo. Solução: aumente scale=3 ou scale=4.
• ❌ Muitas caixas falsas (ruído) → Causa: thresholds de detecção baixos. Solução: suba bin_thresh/box_thresh e filtre por objectness_score.
• ❌ Texto torto não é reconhecido → Causa: assume_straight_pages=True. Solução: use polígonos ou straighten_pages=True.
• ❌ Estouro de memória na GPU → Causa: det_bs alto (detecção é memory-bound). Solução: comece com det_bs=2 e aumente só reco_bs.

FAQ

• O docTR funciona sem GPU? Sim, mas fica bem mais lento. Para volume baixo ou provas de conceito, CPU é suficiente.
• Preciso treinar um modelo do zero? Não. Os checkpoints pré-treinados já resolvem a maioria dos documentos impressos limpos.
• Consigo extrair campos de uma nota fiscal? Sim — combinando o texto renderizado com expressões regulares, ou treinando um detector multi-classe para o KIE.
• Ele lê texto em português? Lê caracteres latinos, mas acentos específicos podem exigir fine-tuning do vocabulário.
• Como coloco isso em produção? Há template FastAPI, imagem Docker (ghcr.io/mindee/doctr) e demo Streamlit prontos.

O que vem pela frente

O OCR deixou de ser um produto isolado e virou um módulo dentro de pipelines de inteligência de documentos. A tendência é clara: o docTR cuida do "texto fiel + geometria", enquanto LLMs e modelos de layout cuidam do entendimento e da estrutura. Quem domina essa divisão de responsabilidades hoje — extração barata na borda, semântica na camada de IA — estará à frente quando a automação de documentos se tornar padrão no back-office brasileiro.