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 识别图片
组件
安装
一键安装（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 -m uvicorn ocr_server:app --port 8765
# POST /ocr (multipart: file=图片, mode=gpu)
设置（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 会拆成多个公式框）。
