real-offline-ocr

Offline OCR — Extração de Texto de Imagens Offline

Baseado em RapidOCR + PP-OCRv6 para extração de texto de imagens localmente, totalmente offline, suporta chinês e inglês. Não precisa de internet, registro de API ou GPU.

Quando usar

• O usuário fornece um arquivo de imagem (captura de tela, foto, recibo, documento escaneado, imagem de documento, CAPTCHA, etc.) e solicita a leitura do texto presente
• É necessário extrair conteúdo textual de imagens, como copiar informações de recibos, reconhecer código/texto em capturas de tela ou extrair texto de tabelas
• Quando o modelo atual não possui capacidade multimodal, serve como alternativa para 'ler imagens e reconhecer texto'
• Pode ser usado em conjunto com grandes modelos sem capacidade multimodal, como DeepSeek-V4: quando a interface conversacional do modelo não pode 'ver' imagens, este skill extrai primeiro o texto da imagem e depois o modelo o entende, responde e processa

Primeira instalação (apenas uma vez)

O script requer um ambiente virtual Python separado. Ao usar este skill pela primeira vez, verifique se o ambiente está pronto:

# Se <SKILL_DIR>/.venv não existir ou não for possível importar rapidocr, execute:
python <SKILL_DIR>/scripts/setup.py

# Usuários com CPU Intel que desejam maior desempenho (cerca de 1,8x) podem instalar o OpenVINO:
python <SKILL_DIR>/scripts/setup.py --with-openvino

O comando é multiplataforma (Windows/macOS/Linux, sem necessidade de bash). Se python não for encontrado, no Linux/macOS use python3.

setup.py é idempotente e pode ser executado repetidamente; se já instalado, ele ignora. Ele:

• Verifica se a versão do Python é >= 3.9 (caso contrário, fornece instruções de instalação para cada plataforma)
• Cria <SKILL_DIR>/.venv e instala rapidocr + onnxruntime (padrão) ou + openvino (opcional)
• Se detectar CPU Intel e OpenVINO não estiver instalado, sugere o método opcional de instalação para aceleração de 1,8x (não instala automaticamente)

<SKILL_DIR> é o diretório deste skill. Os modelos vêm embutidos no pacote rapidocr (det/rec de três níveis do PP-OCRv6), sem necessidade de download adicional.

Fluxo completo da primeira execução até o uso: python <SKILL_DIR>/scripts/setup.py → aguarde a instalação automática (cerca de 1-3 minutos) → use o comando abaixo para reconhecer imagens.

Modo de uso

# Imagem única
python <SKILL_DIR>/scripts/ocr.py <caminho_da_imagem>

# Múltiplas imagens
python <SKILL_DIR>/scripts/ocr.py <imagem1> <imagem2> ...

# Parâmetros comuns
--model tiny|small|medium        Nível do modelo (padrão: small)
--engine onnxruntime|openvino     Motor de inferência (padrão: onnxruntime)
--use_cls                        Ativa classificação de orientação de linhas de texto (útil para textos rotacionados/verticais, um pouco mais lento)
--save_vis                       Salva resultado visual em output/

Exemplo:

python <SKILL_DIR>/scripts/ocr.py /caminho/para/captura.png
python <SKILL_DIR>/scripts/ocr.py --model tiny --save_vis /caminho/para/fatura.jpg
python <SKILL_DIR>/scripts/ocr.py --engine openvino /caminho/para/foto.png

Nota: ocr.py usa automaticamente as dependências do .venv para executar (no Windows, .venv\Scripts\python.exe), sem necessidade de se preocupar com o caminho do interpretador.

Formato de saída

O script exibe o resultado no stdout, no seguinte formato:

===== nome_do_arquivo.png =====
Total de N caixas de texto reconhecidas:
[1] Primeira linha de texto reconhecida  (Confiança: 0.98)
[2] Segunda linha de texto reconhecida  (Confiança: 0.95)

Após o reconhecimento, organize o texto puro após [número] e retorne ao usuário, anexando um aviso para baixa confiança (por exemplo, reconhecimento com confiança < 0.6 pode ser impreciso).

Escolha do motor de inferência

Motor	Tamanho	Características
onnxruntime (padrão)	Pequeno (~52M)	Consistente entre plataformas, instalação limpa, recomendado universalmente
openvino	Grande (~+123M)	Apenas mais rápido em CPU Intel (cerca de 1,8x); sem vantagem em AMD/Apple Silicon

Escolha do nível do modelo

Nível	Tamanho dos modelos det/rec	Velocidade	Precisão	Cenário de uso
tiny	1.8M / 4.5M	Mais rápido	Menor	Cenários simples, pré-visualização rápida
small (padrão)	9.9M / 21M	Equilibrado	Boa	Cenários gerais
medium	62M / 77M	Mais lento	Maior	Texto complexo, desfocado, denso

Para imagens nítidas e texto bem formatado, use small; se o reconhecimento não for bom, mude para medium.

Observações

• Quanto mais nítida a imagem e mais regular o texto, melhor o reconhecimento; itálico, arte textual e fundo complexo reduzem a precisão
• Para textos invertidos ou verticais, use o parâmetro --use_cls
• O tempo para uma única imagem é de cerca de 0,1~1s (CPU), dependendo do tamanho da imagem, nível do modelo e motor
• Apenas Python 3.9+ é necessário; se não houver ambiente Python, o setup.py fornecerá instruções de instalação para cada plataforma