uglymie/real-offline-ocr

Offline OCR — 離線圖像文字提取

基於 RapidOCR + PP-OCRv6 的本地圖像文字提取能力，完全離線運行，支援中文和英文。無需聯網、無需註冊 API、無需 GPU。

何時使用

• 使用者提供圖像檔案（螢幕截圖、照片、票據、掃描件、文件圖片、驗證碼等），要求讀取圖中文字
• 需要從圖像中提取文字內容，如複製票據資訊、辨識截圖中的程式碼/文字、提取表格裡的文字
• 當前模型不具備多模態能力時，作為「看圖識字」的替代方案
• 可搭配 DeepSeek-V4 等無多模態能力的大模型使用：當模型的對話介面本身「看不了圖」時，由此 skill 先從圖像中提取文字，再交由模型理解、回答、處理

首次安裝（只需一次）

運行腳本需要獨立的 Python 虛擬環境。首次使用此 skill 時，先確認環境是否已就緒：

# 若 <SKILL_DIR>/.venv 不存在或無法 import rapidocr，執行：
python <SKILL_DIR>/scripts/setup.py

# Intel CPU 使用者想要更高效能（約 1.8x），可額外安裝 OpenVINO：
python <SKILL_DIR>/scripts/setup.py --with-openvino

命令跨平台一致（Windows/macOS/Linux 均可使用，無需 bash）。若提示找不到 python，Linux/macOS 可改用 python3 代替。

setup.py 是冪等的，可重複執行；已安裝會跳過。它會：

• 檢測 Python 版本是否 >= 3.9（不足則給出各平台安裝指引）
• 建立 <SKILL_DIR>/.venv 並安裝 rapidocr + onnxruntime（預設）或 + openvino（可選）
• 若檢測到 Intel CPU 且未裝 OpenVINO，會提示可選的 1.8x 加速安裝方式（不會自動安裝）

<SKILL_DIR> 指此 skill 所在目錄。模型隨 rapidocr 套件內建（PP-OCRv6 三檔 det/rec），無需額外下載。

首次執行到可用的完整流程：python <SKILL_DIR>/scripts/setup.py → 等待自動安裝（約 1-3 分鐘）→ 即可用下方指令辨識圖片。

使用方法

# 單張圖片
python <SKILL_DIR>/scripts/ocr.py <圖像路徑>

# 多張圖片
python <SKILL_DIR>/scripts/ocr.py <圖像1> <圖像2> ...

# 常用參數
--model tiny|small|medium      模型檔位（預設 small）
--engine onnxruntime|openvino  推理引擎（預設 onnxruntime）
--use_clr                      啟用文字行方向分類（對旋轉/豎排文字有用，略慢）
--save_vis                     儲存可視化結果到 output/

範例：

python <SKILL_DIR>/scripts/ocr.py /path/to/screenshot.png
python <SKILL_DIR>/scripts/ocr.py --model tiny --save_vis /path/to/invoice.jpg
python <SKILL_DIR>/scripts/ocr.py --engine openvino /path/to/photo.png

說明：ocr.py 會自動使用 .venv 中的相依套件執行（Windows 下為 .venv\Scripts\python.exe），無需關心解譯器路徑。

輸出格式

腳本在 stdout 輸出辨識結果，格式如下：

===== 檔案名.png =====
共辨識 N 個文字框：
[1] 辨識到的第一行文字  （置信度：0.98）
[2] 辨識到的第二行文字  （置信度：0.95）

辨識結束後，將 [序號] 後的純文字內容整理後回傳給使用者，並附上置信度低的提醒（如 <0.6 的辨識可能不準）。

推理引擎選擇

引擎	體積	特點
onnxruntime（預設）	小（~52M）	跨平台一致、安裝乾淨，普適推薦
openvino	大（~+123M）	僅 Intel CPU 更快（約 1.8x）；AMD/Apple Silicon 無優勢

模型檔位選擇

檔位	det/rec 模型大小	速度	精度	適用場景
tiny	1.8M / 4.5M	最快	較低	簡單場景、快速預覽
small（預設）	9.9M / 21M	均衡	良好	一般場景
medium	62M / 77M	最慢	最高	複雜、模糊、密集文字

圖片清晰、文字規整時優先使用 small；遇到辨識不準再升級到 medium。

注意事項

• 圖片越清晰、文字越規整，辨識效果越好；斜體、藝術字、背景複雜會降低準確率
• 對於方向顛倒或豎排的文字，可加上 --us_cls 參數
• 單張圖片耗時約 0.1~1s（CPU），視圖片大小、檔位和引擎而定
• 僅需 Python 3.9+；無 Python 環境時 setup.py 會給出各平台安裝指引