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 会拆成多个公式框）。