Tutorial: Como construir um pipeline de OCR completo com Unlimited-OCR do Baidu — processamento de documentos, tabelas e PDFs de múltiplas páginas

Por que o Unlimited-OCR do Baidu importa agora

Em julho de 2026, o OCR (Optical Character Recognition) vive uma transformação profunda. O modelo Unlimited-OCR do Baidu — um modelo de visão-linguagem de 3 bilhões de parâmetros disponível como open source no Hugging Face — elimina a necessidade de pipelines tradicionais de OCR com etapas separadas de detecção de layout, segmentação e reconhecimento. Em vez disso, ele processa a página inteira em uma única passada de decodificação, entregando texto estruturado com parágrafos, tabelas e formatação preservada.

Este tutorial prático mostra como rodar o Unlimited-OCR no Google Colab (GPU gratuita), processando desde imagens de documentos simples até PDFs de múltiplas páginas com tabelas e layouts complexos.

✅ O que você ganha

• OCR de uma passada: sem pipeline separado de layout, segmentação e reconhecimento — o modelo lê a página inteira de uma vez
• Suporte a múltiplas páginas: processamento de PDFs com coerência entre páginas via infer_multi()
• Dois modos de inferência: Gundam (alta precisão para documentos densos, usa tiles) e Base (mais rápido, visão única)
• Open source e gratuito: modelo disponível no Hugging Face, roda em GPUs consumer com 6 GB de VRAM
• Saída estruturada: texto, Markdown, MMD e JSON com preservação de tabelas e formatação

⚠️ Limitações

• Requer GPU com pelo menos 6 GB de VRAM — não funciona em CPU
• O download do modelo (6 GB em BF16) é demorado na primeira execução
• Documentos com caligrafia manual ou fontes muito estilizadas podem ter precisão reduzida
• O modo Gundam é mais lento que o Base (mas mais preciso para layouts densos)

Passo a passo: construindo o pipeline

1. Configuração do ambiente e instalação das dependências

O primeiro passo é preparar o ambiente Google Colab com GPU. Instalamos as bibliotecas necessárias e verificamos a disponibilidade da GPU:

import subprocess, sys
def pip_install(*pkgs):
    subprocess.check_call([sys.executable, "-m", "pip", "install", "-q", *pkgs])

# Instalar dependências (~1-2 minutos)
pip_install(
    "transformers==4.57.1", "Pillow", "matplotlib",
    "einops", "addict", "easydict", "pymupdf",
    "psutil", "accelerate"
)

import torch
assert torch.cuda.is_available(), "GPU não detectada! Runtime → Change runtime type → GPU"

# Seleção automática de precisão
use_bf16 = torch.cuda.is_bf16_supported()
DTYPE = torch.bfloat16 if use_bf16 else torch.float16

Por que isso importa: a seleção automática entre bfloat16 e float16 garante que o modelo use a precisão ideal para sua GPU. GPUs mais antigas (T4, V100) usam float16; GPUs modernas (A100, H100) usam bfloat16 com maior estabilidade numérica.

2. Carregamento do modelo Unlimited-OCR

Carregamos o tokenizer e o modelo de 3B parâmetros diretamente do Hugging Face:

from transformers import AutoModel, AutoTokenizer

MODEL_NAME = "baidu/Unlimited-OCR"
tokenizer = AutoTokenizer.from_pretrained(MODEL_NAME, trust_remote_code=True)
model = AutoModel.from_pretrained(
    MODEL_NAME, trust_remote_code=True,
    use_safetensors=True, torch_dtype=DTYPE
)
model = model.eval().cuda()

Por que trust_remote_code=True: o Unlimited-OCR inclui código de inferência personalizado (modos Gundam/Base) que não está na biblioteca transformers padrão. Sem esta flag, o carregamento falha.

3. Geração de documentos de teste

Criamos documentos sintéticos com títulos, parágrafos, tabelas e notas de rodapé para testar o pipeline:

from PIL import Image, ImageDraw, ImageFont
import textwrap, os

os.makedirs("inputs", exist_ok=True)
os.makedirs("outputs/single_gundam", exist_ok=True)
os.makedirs("outputs/single_base", exist_ok=True)
os.makedirs("outputs/multi_page", exist_ok=True)

def make_sample_page(path, page_no):
    W, H = 1240, 1754
    img = Image.new("RGB", (W, H), "white")
    d = ImageDraw.Draw(img)
    # Adiciona título, parágrafo e tabela com dados de receita regional
    # ... (código completo no repositório oficial)
    img.save(path)
    return path

4. OCR de página única — Modo Gundam (alta precisão)

O modo Gundam combina visão global do documento com tiles de imagem recortados para preservar texto fino:

model.infer(
    tokenizer,
    prompt="<image>document parsing.",
    image_file=IMAGE_PATH,
    output_path="outputs/single_gundam",
    base_size=1024,
    image_size=640,       # tile menor = mais detalhe
    crop_mode=True,        # ativa recorte em tiles
    max_length=32768,
    no_repeat_ngram_size=35,
    ngram_window=128,
    save_results=True,
)

Quando usar Gundam: documentos digitalizados com texto pequeno, layouts densos, múltiplas colunas, ou quando a precisão do texto é crítica. O trade-off é velocidade — Gundam é mais lento que o Base.

5. OCR de página única — Modo Base (mais rápido)

Para documentos limpos e bem impressos, o modo Base processa a imagem com uma única visão de 1024px:

model.infer(
    tokenizer,
    prompt="<image>document parsing.",
    image_file=IMAGE_PATH,
    output_path="outputs/single_base",
    base_size=1024,
    image_size=1024,       # visão única
    crop_mode=False,        # sem recorte
    max_length=32768,
    no_repeat_ngram_size=35,
    ngram_window=128,
    save_results=True,
)

Quando usar Base: documentos modernos com texto claro, relatórios gerados digitalmente (não digitalizados), ou quando a velocidade é prioridade.

6. Processamento de PDFs de múltiplas páginas

Para processar um PDF completo, usamos PyMuPDF para rasterizar cada página e infer_multi() para manter coerência entre páginas:

import fitz

def pdf_to_images(pdf_path, dpi=300):
    # Rasteriza cada página do PDF para PNG
    doc = fitz.open(pdf_path)
    mat = fitz.Matrix(dpi / 72, dpi / 72)
    paths = []
    for page in doc:
        out = f"page_{page.number + 1:04d}.png"
        page.get_pixmap(matrix=mat).save(out)
        paths.append(out)
    doc.close()
    return paths

# Processar múltiplas páginas
page_images = pdf_to_images("documento.pdf", dpi=300)
model.infer_multi(
    tokenizer,
    prompt="<image>Multi page parsing.",
    image_files=page_images,
    output_path="outputs/multi_page",
    image_size=1024,
    max_length=32768,
    no_repeat_ngram_size=35,
    ngram_window=1024,  # janela maior para coerência entre páginas
    save_results=True,
)

Por que ngram_window=1024: a janela de repetição mais ampla evita que o modelo repita texto ao transitar entre páginas, mantendo a coerência do documento como um todo.

Tabela comparativa: Gundam vs Base

Casos de uso reais

• Digitalização de contratos jurídicos: processe documentos escaneados de múltiplas páginas extraindo cláusulas e tabelas de valores automaticamente com preservação da estrutura
• Extração de dados de notas fiscais: automatize a leitura de notas fiscais brasileiras (NF-e) digitalizadas, extraindo CNPJ, valores e descrições de produtos em lote
• Processamento de relatórios financeiros: converta PDFs de balanços trimestrais em dados estruturados (Markdown/JSON) para análise automatizada
• Arquivamento digital de documentos históricos: digitalize acervos de jornais e documentos antigos, preservando a estrutura de colunas e artigos
• Extração de dados de prontuários médicos: processe formulários e laudos digitalizados para alimentar sistemas de gestão hospitalar

Troubleshooting: erros comuns e soluções

❌ CUDA out of memory
Causa: GPU com menos de 6 GB de VRAM ou modo Gundam consumindo memória excessiva.
Solução: use o modo Base com image_size=640 ou faça upgrade para runtime T4 no Colab.

❌ trust_remote_code=True is required
Causa: o Unlimited-OCR tem código de inferência customizado não incluído no transformers.
Solução: adicione trust_remote_code=True tanto no AutoTokenizer quanto no AutoModel.

❌ Texto truncado em documentos longos
Causa: max_length insuficiente para o tamanho do documento.
Solução: aumente max_length para 32768 ou mais, dependendo do documento.

❌ Repetição de texto no modo multi-página
Causa: ngram_window muito pequeno para transições entre páginas.
Solução: aumente ngram_window para 1024 em chamadas infer_multi().

❌ Tabelas não são reconhecidas corretamente
Causa: modo Base com crop_mode=False perdendo detalhes das células.
Solução: use modo Gundam com crop_mode=True e image_size=640 para documentos com tabelas.

FAQ

O Unlimited-OCR funciona em português?
Sim. O modelo é multilíngue e reconhece texto em português, incluindo caracteres acentuados (ç, ã, õ). A qualidade depende da clareza do documento original.

Preciso pagar para usar o Unlimited-OCR?
Não. O modelo é open source e está disponível gratuitamente no Hugging Face. Você só precisa de uma GPU (gratuita no Google Colab).

Qual a diferença entre Unlimited-OCR e Tesseract?
O Tesseract é um OCR tradicional que requer pipeline separado de layout analysis. O Unlimited-OCR é um modelo de visão-linguagem que processa a página inteira em uma passada, preservando estrutura de tabelas e formatação.

Posso rodar em CPU?
Não. O modelo de 3B parâmetros requer GPU. Em CPU o processamento seria extremamente lento (horas por página).

Funciona com PDFs protegidos por senha?
Não diretamente. Você precisa remover a proteção do PDF antes de processar com PyMuPDF. Use qpdf --decrypt ou equivalente.

O futuro do OCR é de uma passada

O Unlimited-OCR do Baidu representa uma mudança de paradigma no processamento de documentos. Em vez de encadear múltiplos modelos especializados (detecção de layout, segmentação de texto, reconhecimento de caracteres), um único modelo de visão-linguagem lê a página inteira e produz texto estruturado. Em 2027, é provável que este padrão se torne dominante, com modelos ainda mais leves rodando diretamente em dispositivos móveis para digitalização de documentos em tempo real.