tecjustica-ocr 0.1.1

Extração OCR de processos judiciais — PDF para Markdown

tecjustica-ocr

Extração OCR de processos judiciais — transforma PDFs em Markdown legível.

Usa PaddleOCR 3.x (PP-OCRv5 / PP-StructureV3) com auto-detecção GPU/CPU.

Requisitos

Requisito	Mínimo	Recomendado
Python	3.10+	3.12
RAM	4 GB	8 GB+
Disco	2 GB livres	5 GB+
GPU (opcional)	NVIDIA com CUDA 11.8	RTX 3050+
Sistema	Linux, Windows	Linux (melhor suporte GPU)

GPU não é obrigatório. O tecjustica-ocr funciona em CPU, porém fica mais lento (~5x). Com GPU, processa ~312 páginas em ~7 minutos. Em CPU, o mesmo leva ~35 minutos.

Instalação

Passo 1: Criar ambiente virtual

O tecjustica-ocr tem dependências pesadas (PaddlePaddle, modelos de IA). Use sempre um ambiente virtual.

# Opção A: com uv (recomendado, mais rápido)
uv venv ocr-env --python 3.12
source ocr-env/bin/activate     # Linux/Mac
# ocr-env\Scripts\activate      # Windows

# Opção B: com python padrão
python3 -m venv ocr-env
source ocr-env/bin/activate     # Linux/Mac
# ocr-env\Scripts\activate      # Windows

Passo 2: Instalar PaddlePaddle

O PaddlePaddle (motor de IA) precisa ser instalado separadamente porque a versão GPU vem de um repositório especial.

Se você tem GPU NVIDIA (CUDA 11.8):

pip install paddlepaddle-gpu==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu118/

Se você NÃO tem GPU (somente CPU):

pip install paddlepaddle==3.2.0

Como saber se tenho GPU compatível? Execute nvidia-smi no terminal. Se aparecer uma tabela com o nome da sua placa, você tem GPU. Se der erro "comando não encontrado", use a versão CPU.

Passo 3: Instalar tecjustica-ocr

pip install tecjustica-ocr

Passo 4: Verificar instalação

tecjustica-ocr init

Este comando verifica tudo automaticamente:

• Versão do Python
• RAM e espaço em disco
• Se PaddlePaddle está instalado
• Se tem GPU e qual modelo
• Se os modelos OCR estão baixados

Na primeira execução, ele baixa os modelos automaticamente (~500 MB). Depois disso, ficam em cache.

Exemplo de saída:

╭──────────────────────────────────────────────────────────────────╮
│ tecjustica-ocr 0.1.0 — Diagnóstico do sistema                   │
╰──────────────────────────────────────────────────────────────────╯

1. Verificando sistema...

┌────────────────────────────┬────────┬──────────────────────────────────────┐
│ Verificação                │ Status │ Detalhe                              │
├────────────────────────────┼────────┼──────────────────────────────────────┤
│ Python                     │   OK   │ 3.12.3                               │
│ Sistema                    │   OK   │ Linux x86_64                         │
│ RAM                        │   OK   │ 7.6 GB total                         │
│ Espaço em disco            │   OK   │ 901.9 GB livres                      │
│ PaddlePaddle               │   OK   │ v3.2.0                               │
│ PaddleOCR                  │   OK   │ v3.4.0                               │
│ pypdfium2                  │   OK   │ v4.x                                 │
│ GPU CUDA                   │   OK   │ 1 GPU(s) — NVIDIA GeForce RTX 3050   │
│ Modelo PP-OCRv5_mobile_det │   OK   │ em cache                             │
│ Modelo PP-OCRv5_mobile_rec │   OK   │ em cache                             │
│ Modelo PP-OCRv5_server_det │   OK   │ em cache                             │
│ Modelo PP-OCRv5_server_rec │   OK   │ em cache                             │
└────────────────────────────┴────────┴──────────────────────────────────────┘

2. Baixando modelos OCR...

  OK Modelo mobile pronto
  OK Modelo server pronto

╭────────────────────────────── Pronto para usar ──────────────────────────────╮
│ Sistema compatível!                                                          │
│                                                                              │
│   Dispositivo: GPU                                                           │
│   Comando: tecjustica-ocr run <pdf>                                          │
╰──────────────────────────────────────────────────────────────────────────────╯

Se algum item aparecer como FALHA, o init explica o que corrigir.

Uso

Processar um PDF

tecjustica-ocr run processo.pdf

Gera output/processo.md com todo o texto extraído.

Processar uma pasta inteira

tecjustica-ocr run pasta-com-pdfs/ -o resultado/

Gera um .md para cada PDF encontrado na pasta.

Escolher modelo

# Mobile (default) — rápido, bom para maioria dos casos
tecjustica-ocr run processo.pdf -m mobile

# Server — maior qualidade, ~2.5x mais lento
tecjustica-ocr run processo.pdf -m server

Modelo	Velocidade	Textos	Quando usar
mobile	~1.3s/pág	~86 por pág	Processos longos, leitura rápida
server	~3.2s/pág	~93 por pág	Documentos difíceis, qualidade máxima

Modo estrutural (tabelas e layout)

tecjustica-ocr run processo.pdf --mode structure

Usa PP-StructureV3 para preservar tabelas, cabeçalhos e layout do documento.

Forçar CPU ou GPU

tecjustica-ocr run processo.pdf -d cpu    # Forçar CPU
tecjustica-ocr run processo.pdf -d gpu    # Forçar GPU

Por padrão, detecta automaticamente (-d auto).

Todas as opções

tecjustica-ocr run [CAMINHO] [OPÇÕES]

Argumentos:
  CAMINHO              Arquivo PDF ou pasta com PDFs (obrigatório)

Opções:
  -o, --output DIR     Diretório de saída (default: ./output)
  -m, --model TEXT     mobile (default) ou server
  -d, --device TEXT    auto (default), gpu ou cpu
  -s, --scale INT      Escala de render: 1, 2 ou 3 (default: 2)
  -w, --workers INT    Workers paralelos (default: auto)
  --mode TEXT          text (default) ou structure
  --min-score FLOAT    Score mínimo de confiança (default: 0.5)
  -v, --verbose        Output detalhado

tecjustica-ocr init [OPÇÕES]

Opções:
  --download/--no-download   Baixar modelos (default: sim)
  -m, --model TEXT           Modelo para baixar: mobile, server ou all (default: all)

Formato de saída

O markdown gerado tem a seguinte estrutura:

# nome-do-arquivo.pdf

- **Data de extração**: 2025-03-17 15:44
- **Páginas**: 312
- **Textos extraídos**: 26706

## Página 1

Tribunal de Justiça do Estado do Ceará - 1° Grau
PJe - Processo Judicial Eletrônico
Número: 3000066-83.2025.8.06.0203
...

---

## Página 2

...

API Python

Para usar dentro de scripts ou outros programas:

from tecjustica_ocr import extract_text, extract_structure, OcrConfig

# Extrair texto simples
texto = extract_text("processo.pdf")
print(texto)

# Extrair com configurações customizadas
config = OcrConfig(model="server", device="gpu", scale=3)
texto = extract_text("processo.pdf", config)

# Extrair estrutura (tabelas, layout) como markdown
markdown = extract_structure("processo.pdf")

Resolução de problemas

"comando não encontrado" após instalar

O ambiente virtual precisa estar ativado:

source ocr-env/bin/activate
tecjustica-ocr --version

Ou execute via Python:

python -m tecjustica_ocr --help

Erro de CUDA / GPU não detectada

1. Verifique se nvidia-smi funciona
2. Verifique se instalou paddlepaddle-gpu (não paddlepaddle)
3. Execute tecjustica-ocr init para diagnóstico completo
4. Se não tiver GPU, o sistema funciona em CPU automaticamente

Modelos não baixam

Execute o init com download explícito:

tecjustica-ocr init --download -m all

Os modelos ficam em ~/.paddlex/official_models/. Se precisar limpar, delete essa pasta e rode o init novamente.

Processo muito lento

• Use modelo mobile (default): -m mobile
• Escala 2 é suficiente: -s 2
• Se tiver GPU, confirme que está sendo usada: olhe "Dispositivo: gpu:0" no início

Benchmarks

Testado em RTX 3050 6GB, 312 páginas de processo judicial:

Modelo	Tempo total	Por página	Textos
mobile + GPU	6.8 min	1.310 ms	26.706
server + GPU	16.5 min	3.181 ms	29.005