手写公式 OCR KL3jd/handwritten-ocr

OCR 本地插件 — 手写中文 + 数学公式 → Markdown

本地 OCR 插件：识别手写中文笔记与数学公式图片，输出 Markdown（中文纯文本 + 公式 LaTeX）。
全程本地推理、不联网，图片与数据不出本机。可作为 DSH（或其他 LLM 工具框架）的插件调用。

功能

- 整页手写笔记识别：中文 → 纯文本、公式 → LaTeX
- 三模式后端：GPU（DirectML，推荐）/ CPU / NPU（实验性，见下）
- 可调参数集中在 settings.json，无需改代码
- FastAPI 服务（ocr_server.py，POST /ocr）+ CLI（ocr_cli.py）
- DSH 工具预设（dsh-assets/）：LLM 可直接调用 ocr_image 识别图片

组件

| 组件 | 用途 | 许可 |
| Pix2Text MFD 1.5 | 公式区检测（YOLO） | MIT |
| RapidOCR | 中文文本行识别 | Apache-2.0 |
| UniMERNet | 公式 → LaTeX（手写优先） | MIT |
| Pix2Text MFR 1.5 | 公式 → LaTeX（兜底） | MIT |

安装

一键安装（Windows，推荐）

powershell -ExecutionPolicy Bypass -File install.ps1

自动完成：建 .venv + 装依赖（清华源优先、失败退官方源）→ 下载模型（hf-mirror）→ 装 DSH 预设。
模型已有可加 -SkipModels。

手动安装

1. Python 3.10 环境
python -m venv .venv
Windows: .venv\Scripts\activate

2. 依赖
pip install -r requirements-gpu.txt

3. 下载模型（自动走 hf-mirror 国内镜像，落 models/ocr/）
python scripts/download_models.py

使用

CLI（每次新进程，模型重新加载，慢）
python ocr_cli.py 笔记照片.jpg --mode gpu

HTTP 常驻服务（推荐，默认 8765 端口）——模型只加载一次，后续秒回
python ocr_server.py
或 python -m uvicorn ocr_server:app --port 8765 POST /ocr (multipart: file=图片, mode=gpu) -> {markdown, timing}

🖥️ 管理面板（服务模式用）

启动服务后浏览器打开 http://127.0.0.1:8765/：

- 服务状态：运行中/已停止、PID、引擎加载状态、启动时间
- 停止服务按钮（服务停止后由 DSH 工具自动拉起，或重新运行 python ocr_server.py）
- 参数编辑：每个参数带「用途 / 优点 / 注意 / 建议值」，修改后保存即热加载，下次识别生效
- DSH 的 ocr_image 工具首次调用会自动拉起服务（约 25s 加载模型），之后每次识别约 2~3s 返回

设置（settings.json）

| 键 | 默认 | 说明 |
| mode | auto | gpu / npu / cpu / auto |
| formula_backend | auto | unimernet / mfr / auto |
| formula_iou | 0.3 | 文本与公式框去重 IoU |
| mfd_conf | 0.25 | 公式检测置信度 |
| mfd_resized_shape | 768 | 检测输入尺寸 |
| merge_x_iou / merge_y_gap | 0.3 / 24 | 公式碎片合并 |
| crop_pad_ratio | 0.08 | 公式裁剪外扩 |
| crop_min_width / height | 24 / 18 | 裁剪最小尺寸 |
| crop_upscale | 256 | 小图放大阈值 |

环境变量：OCR_PY / OCR_CLI / OCR_MODEL_DIR / OCR_SETTINGS 可覆盖默认路径。

DSH 集成

install.ps1 会自动安装预设；手动安装： Copy-Item dsh-assets\preset-ocr-assistant "C:\Users\$env:USERNAME\.dsh\.agent-presets\ocr-assistant" -Recurse -Force 刷新后出现「OCR 助手」预设，LLM 拥有 ocr_image 工具（识别本地图片 → Markdown）。
若报 python 找不到，设 OCR_PY / OCR_CLI 环境变量后重启 DSH。

已知限制

- NPU 模式（AMD XDNA1）受 amd/RyzenAI-SW#389 阻塞： Windows + RAI 1.8.0 下 DPU 分派报 ERT_CMD_STATE_ERROR（AMD open bug），建议用 GPU 或 CPU 模式。
- 手写矩阵的完整 bmatrix 输出仍在打磨（当前 MFD 会拆成多个公式框）。