前言¶
DeepSeek Harness（DSH）的理念是“一切皆插件”，社區通過獨立站點（如 skillhub.cn）提供各類工具。在構建本地化智能體時，識別手寫內容（如筆記、草稿）是一個常見需求。傳統方案往往依賴雲端 API，存在隱私泄露風險且依賴網絡。下面介紹一款本地 OCR 插件，它能在不聯網的情況下，將手寫中文與數學公式圖片轉換爲 Markdown 文本和 LaTeX 公式。
這是什麼¶
kl3jd/handwritten-ocr 是由維護者 KL3jd 開發的一個本地 OCR 插件。它的核心功能是整頁手寫筆記識別：將圖片中的中文純文本提取出來，並將數學公式轉換爲 LaTeX 格式。插件全程在本地運行，數據不出本機，可作爲 DSH（或其他 LLM 工具框架）的插件調用。
核心功能¶
- 整頁識別：支持將整頁手寫筆記轉換爲 Markdown，包含中文純文本和公式 LaTeX。
- 多後端支持：支持 GPU（DirectML，推薦）、CPU 和 NPU 三種推理模式。
- 多種接口：提供 FastAPI HTTP 服務和 CLI 命令行工具，方便集成。
- DSH 工具集成：內置 DSH 工具，LLM 可直接調用
ocr_image工具識別本地圖片。
安裝¶
插件提供了 Windows 的一鍵安裝腳本，會自動完成虛擬環境搭建、依賴安裝、模型下載和 DSH 預設配置。
powershell -ExecutionPolicy Bypass -File install.ps1
安裝腳本會自動執行以下步驟：
1. 創建 Python 虛擬環境。
2. 安裝依賴包（優先使用清華源，失敗則回退官方源）。
3. 下載 OCR 模型（使用 hf-mirror 國內鏡像）。
4. 安裝 DSH 預設文件。
如果本地已有模型，可以在安裝命令中添加 -SkipModels 參數跳過下載。
使用¶
安裝完成後，可以通過 CLI、HTTP 服務或 DSH 工具進行調用。
CLI 調用¶
使用命令行工具直接識別圖片。由於是每次啓動新進程，模型會重新加載，速度較慢。
python ocr_cli.py 筆記照片.jpg --mode gpu
HTTP 服務¶
推薦啓動常駐 HTTP 服務。模型只需加載一次，後續請求響應極快。
# 啓動服務（默認端口 8765）
python ocr_server.py
服務啓動後，可以通過瀏覽器訪問 http://127.0.0.1:8765/ 查看管理面板，實時監控服務狀態、PID、引擎加載情況，並修改配置參數（支持熱加載）。
DSH 工具調用¶
安裝腳本會自動將預設文件複製到 DSH 的 preset-ocr-assistant 目錄。刷新後，LLM 即可擁有 ocr_image 工具。
- 首次調用：DSH 調用工具時會自動拉起 OCR 服務（約 25 秒加載模型）。
- 後續調用：識別速度約 2~3 秒返回結果。
- 環境變量：如果系統找不到 Python，可通過設置
OCR_PY或OCR_CLI環境變量指定路徑。
設置¶
插件的核心配置集中在 settings.json 文件中，無需修改代碼即可調整行爲。
主要配置項包括：
* mode：推理模式（gpu / npu / cpu / auto）。
* formula_backend：公式後端（unimernet / mfr / auto）。
* formula_iou、mfd_conf：用於控制公式檢測的閾值和合並邏輯。
* merge_x_iou、merge_y_gap：用於合併被拆分的公式碎片。
此外，可通過環境變量 OCR_SETTINGS 覆蓋默認配置路徑。
已知限制¶
- NPU 模式問題：AMD RyzenAI-SW#389 問題會阻塞 NPU 模式（Windows + RAI 1.8.0 下 DPU 分派報錯）。建議在 AMD 硬件上使用 GPU 或 CPU 模式。
- 矩陣輸出：手寫矩陣的完整
bmatrix輸出仍在打磨中，當前可能會被拆成多個公式框。 - 隱私：全程本地推理，圖片與數據不會離開本機。
總結¶
該插件通過本地化方案解決了手寫內容數字化的問題，適合需要在本地處理敏感數據或離線使用的場景。配合 DSH 的插件化生態，可以輕鬆將其集成到智能體工作流中。
- 插件目錄：https://www.skillhub.cn/plugins/KL3jd/handwritten-ocr
- GitHub 倉庫：https://github.com/KL3jd/handwritten-ocr
