Dicklesworthstone/franken_ocr

Pure-Rust, CPU-only OCR engine for Baidu Unlimited-OCR (a DeepSeek-OCR-derived 3B MoE VLM). Five-model zoo, custom int8 kernels, no ML framework, no Python, no GPU.

franken_ocr – Baidu 的 Unlimited-OCR 及相關模型用純 Rust CPU 僅 OCR

是什麼 – franken_ocr（二進位檔 focr）是一套 Rust 庫 + CLI，可在 CPU 上完全運行少量手動移植的視覺-語言模型。預設模型是 Baidu 的 Unlimited-OCR，一個強大的文件解析模型；其他模型涵蓋表格（GOT-OCR2）、圖像描述/VQA（SmolVLM2）、圖表提取（OneChart）和光學音樂辨識（Polyphonic-TrOMR）。無需 Python、CUDA、FFI 或 GPU——整個推論堆疊皆包含於單一、記憶體安全的 Rust 二進位檔中。

核心功能

特性	為何重要
單一可移植二進位檔	適用於 macOS（Intel/Apple-Silicon）、Linux（x86-64/ARM64）和 Windows（x86-64/ARM64）的 13–17 MiB 可執行檔。無需外部執行時，易於部署至 CI 執行器、邊緣裝置或嵌入式代理。
離線推論	在 `focr pull` 下載模型資產（儲存在 `~/.cache/franken_ocr/models` 下）後，所有 OCR 運作均完全本地化——無需網路流量。
Rust API	庫公開一個 `OcrEngine`，支援同步、阻塞呼叫，開發者可直接在 Rust 程式中嵌入 OCR，無需處理非同步或 FFI。
原生 PDF 處理	PDF 透過純 Rust 程式碼在程序中光柵化，支援頁面旋轉並可拆分雙頁版面。
多頁與結構化輸出	`--multi-page` 產生帶 `<PAGE>` 分隔符的單一文件；`--json` 回傳帶邊界框的 JSON；`--extract-figures` 將圖表/照片與 Markdown 一同儲存。
模型庫	`focr models` 列出五個即用型模型；每個模型都有自訂、形狀最佳化的內核，消除通用 ML 框架的開銷。
Int8 加速內核	手寫 SIMD 內核（AVX-512-VNNI、AVX-VNNI、AVX2、Apple SDOT/SMMLA 等）使 int8 量化資產的處理速度比標量參考快約 3 倍。
決定性、代理就緒輸出	「機器人」模式以 NDJSON 事件流（含音樂專用 `staff` 事件）輸出，具穩定退出碼，適合自主代理使用。
自檢與可追溯性	`focr robot selftest` 驗證 int8 內核在主機 CPU 上與標量 Oracle 產生位元級相同結果；倉儲包含大量發布就緒腳本和效能日誌。
記憶體安全的 Rust	除極小的經審核 SIMD 島外，全範圍禁止 `unsafe`；支援大資產的可選 mmap 加載。

快速入門（來自 README）

# 安裝二進位檔（偵測 OS，驗證 SHA-256）
curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/franken_ocr/main/install.sh | bash
# 拉取預設 Unlimited-OCR 權重（約 4 GB）
focr pull
# 將單張影像 OCR 為 Markdown
focr ocr page.png
# 或取得帶邊界框的結構化 JSON
focr ocr page.png --json -o page.json
# 使用專用模型（例如表格）
focr pull got-ocr2
focr ocr --model got-ocr2.int8.focrq --task tables table.png

模型快取後，所有命令均可離線運行。

架構概覽

輸入層 – 接收 PNG/JPG、光柵化 PDF 頁面、影像批次或樂譜掃描。
模型路由 – 根據 --task 標誌或顯式 --model 路徑，將請求分派至相應手動移植的模型。
執行時核心（OcrEngine） – 持有一個模型實例，僅載入一次權重，並透過微型 SQLite 類儲存（fsqlite）記錄遙測資料。
CPU 執行 – 為每個模型撰寫固定形狀的 Rust 內核；SIMD 調度選擇最佳 ISA（x86 上為 AVX-512-VNNI、AVX-VNNI、AVX2、標量；ARM 上為 LLVM autovec 或 Apple SDOT/SMMLA）。Int8 內核採用保守配方，保持大部分層在高精度 BF16 以確保精度，同時加速前饋網路。
輸出層 – 產生 Markdown、帶佈局框的 JSON、MusicXML（用於 OMR）或 NDJSON 機器人事件。

項目健康與授權

版本 – v0.8.0（支援所有主要 OS/架構組合的二進位發布）。預設 Unlimited-OCR 資產固定於 v0.7.0 int8 檢查點，通過 20 頁語料 CER 預算 0.193（平均）和硬頁終止測試。
安全性 – 除經審核的 SIMD 內核外，禁止使用 unsafe；程式碼庫旨在實現完全記憶體安全。
授權 – MIT（參見 LICENSE）。
發布證據 – 倉儲包含效能日誌、一致性門測試、模糊測試語料庫，以及生成「試煉卡」評分表以認證每次發布。

誰可能使用它？

需要輕量級、無 GPU 的 OCR 組件，可嵌入 Rust 服務或編譯為單一二進位檔的 開發者。
安裝 Python + CUDA 不切實際的 CI / 自動化流程。
必須在無網際網路環境下運行文件 OCR 的 邊緣或離線裝置（如筆電、CI 執行器、IoT 裝置）。
透過機器人 NDJSON 流消費結構化 OCR 輸出的代理。
尋找純 Rust OMR 解決方案的 音樂科技愛好者。

總結

franken_ocr 為一組精選的 Baidu 視覺-語言模型提供生產級、CPU 僅 OCR 堆疊，以記憶體安全的 Rust 實作封裝。其對決定性內核、離線運作和廣泛發布就緒工具鏈的關注，使其成為任何希望在無重型 Python/CUDA 生態系統下獲得可靠 OCR 的人的堅實選擇。