dsh-handwritten-ocr

Readme

# 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](https://huggingface.co/breezedeus/pix2text-mfd-1.5) | 公式区检测（YOLO） | MIT |
| [RapidOCR](https://github.com/RapidAI/RapidOCR) | 中文文本行识别 | Apache-2.0 |
| [UniMERNet](https://github.com/dongzida/unimernet) | 公式 → LaTeX（手写优先） | MIT |
| Pix2Text MFR 1.5 | 公式 → LaTeX（兜底） | MIT |

## 安装

### 一键安装（Windows，推荐）

```powershell
powershell -ExecutionPolicy Bypass -File install.ps1
```

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

### 手动安装

```bash
# 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
```

## 使用

```bash
# 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` 会自动安装预设；手动安装：
```powershell
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](https://github.com/amd/RyzenAI-SW/issues/389) 阻塞**：
  Windows + RAI 1.8.0 下 DPU 分派报 ERT_CMD_STATE_ERROR（AMD open bug），建议用 GPU 或 CPU 模式。
- 手写矩阵的完整 `bmatrix` 输出仍在打磨（当前 MFD 会拆成多个公式框）。