Files
ssw c303c315e5 rocr: rusto-rs 源码入库(上游 v0.2.5 基线 57609fc + 本地补丁)
- 源码 316 文件收编为 rusto-rs/ 文件夹,随本仓库管理
- 移除内部 .git(补丁已存档 docs/rusto-rs-metal-patch-20260912.patch,上游可随时 re-clone)
- target/ 与 docs/.yarn 缓存不入库;本地改动:ROCR_* 环境变量调优 + Metal 链接修复 + 预处理测试脚本
2026-09-12 17:30:04 +08:00

153 lines
9.4 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# rocr — 离线中文 OCR 工具(RustO! / rusto-rs 封装,常驻加速版)
纯 Rust OCR 引擎(RapidOCR + PaddleOCR 模型 + 阿里 MNN 推理后端,**零 OpenCV**),
内置 **PP-OCRv6-Medium(约 94MB 高精度模型)**。纯本地推理,无需联网 / API key / 不耗 token。
官方引擎:https://github.com/byrizki/rusto-rs (v0.2.5,本包在原版基础上新增 `--serve` 常驻模式)
## 安装(分发给别人也只需这两步)
1. 解压 `rocr-macos-x86_64.zip`,得到 `rocr/` 目录。
2. 运行安装脚本:
- **macOS**:双击 `install.command`(首次若被拦截,右键 → 打开;或在终端 `bash install.sh`)。
- **Linux / 终端**:`bash install.sh`
- 安装脚本会把 `rocr/` 复制到 `~/rocr`,并在 `/usr/local/bin` 建立 `rocr` 软链。
卸载:`bash uninstall.sh`(或双击 `uninstall.command`)。
> 内置二进制为 **macOS x86_64**。Apple Silicon / Linux x86_64 需自行编译:rusto-rs 源码随本仓库位于 `rusto-rs/`
> (基线:上游 https://github.com/byrizki/rusto-rs v0.2.5 = `57609fc`,本地已含 Metal/调优补丁,
> 补丁内容见 `docs/rusto-rs-metal-patch-20260912.patch`),在源码目录 `cargo build --release`,
> 把产物 `target/release/rusto-rs` 覆盖到 `~/rocr/bin/rusto-rs` 即可。
## 使用
```bash
rocr # 无参数 → 显示帮助与用法
rocr scan.jpg # 文本输出(默认)
rocr scan.jpg markdown # Markdown 输出(直接进 文档→Markdown 流水线)
rocr scan.png json # JSON(含坐标框 + 置信度)
```
输出格式:`text`(默认) | `json` | `tsv` | `markdown` | `textordered`。
## 常驻加速(daemon)
首次调用自动后台拉起 daemon:加载模型(一次,~2s)→ 监听 Unix socket(`~/.cache/rocr/rocr.sock`)。
之后每次调用走 socket,省去重复加载;**空闲 600 秒(10 分钟)无请求自动退出释放内存**,下次调用再自动拉起。
性能实测(2015 款 MacBook Air,i5-5250U 2C4T / 8GB,MNN 走 AVX2 CPU 内核,**机器静置**):
| 模式 | 单张耗时 | 说明 |
|------|---------|------|
| 常驻 daemon 热态 | **~6s** | 省掉加载,剩余为纯推理;与图片尺寸无关 |
| 一次性(未启用常驻) | ~10s | 每次加载模型 + 推理 |
| 首次(拉起 daemon) | ~8s | 模型加载约 2s + 首次推理 |
| 常驻 daemon 热态(**机器有负载时**) | 10–15s | 同时在编译 / Spotlight 索引 / 开浏览器时会明显变慢 |
> ⚠️ 瓶颈说明:每张 ~6s 是**推理本身**的成本(且与输入尺寸无关),rec 模型按检测到的文本行数逐行推理,
> 耗时随行数近似线性:约 1–2s/行,一页 40 行的图约 30–50s。
> 线程数实测(2 物理核 / 4 逻辑核):1 线程 ~9s,2 线程 ~5.98s,4 线程 ~6.06s —— 多线程有收益但 2 线程即接近饱和。
> **计时前请关掉重活**,否则数字会翻倍(本机在跑 `cargo build` 时曾测到 10.5s,同一配置静置仅 6.06s)。
> 注:日志里的 `The device supports: i8sdot:0, fp16:0, i8mm:0` 是 **ARM 特性探测串**,x86 上恒为 0,**不代表无 SIMD**(本机走 AVX2)。
>
> 🚫 **核显 GPU 已实测:不能提速(勿再尝试)**。用 MNN 官方 `mnn_3.6.1_macos_x64_arm82_cpu_opencl_metal`
> 重链出 Metal 后端实测(本机 Intel HD Graphics 6000,仅 `Metal GPUFamily macOS 1`):
> 一次性 **388–408s(慢约 32 倍)**;常驻下首次请求 394s(Metal 着色器运行时编译,本机无持久 shader 缓存),
> 热态同图 8.5s(仅比 CPU 快约 10%),但**换一张不同尺寸的图骤增到 63s**(按输入形状重编译流水线)。
> 对尺寸不一的真实文档完全不可用。要 GPU 提速需换 **Apple Silicon**(MNN Metal 对 M 系深度优化;源码 `cargo build --release --features metal`)
> 或带 N 卡的机器走 CUDA / onnxruntime-gpu。
> 批量提速的可行手段:换小模型档(官方 release 另有 PPOCRv6-Tiny ~5.5MB,精度略降但快数倍)。
### 2019 MBP / i7-9750H 实测(本机,2026-09-12)
| 场景 | 单张耗时 | 与 2015 Air 对比 |
|------|---------|------------------|
| 800×320 样本图 常驻热态(threads=6) | **~3.5 s** | 比 6.0s 快 1.7×(6C12T vs 2C4T) |
| 1721×1245 大图 常驻热态(threads=6) | **~12 s** | 像素量 8.37× → 实际每像素效率仍优 |
| INT8 量化 det(62MB→6.2MB) | ❌ **精度崩:检测 0 个文字框** | — |
**AVX2 路径已榨干**:MNN 官方说 AVX2 后端比 OpenVINO 快 20-440%、比 ONNX Runtime 快 18-60%。`ROCR_PRECISION=low` / `lowbf16` 在没 AVX-512 FP16/BF16 的本机(i7-9750H 没有 AVX-512 / VNNI)上**退化为 FP32 + 走 fallback,user CPU 时间反而高 14%**——保持默认 `high/high`。
**INT8 路线在本机不可行**(详见 `docs/int8-quantize-attempt-20260912.md`):
1. i7-9750H 是 Coffee Lake(2019 上半年),**没有 VNNI / AVX-512**,INT8 没有专用硬件加速
2. MNN 2.8.3 默认 PTQ 算法(KL + MAX_ABS)对 PP-OCRv6 det(DBNet)精度损失致命(sigmoid 输出对量化误差极敏感)
3. rec 模型是动态 shape,calibration 工具不支持
**推荐配置**:`ROCR_NUM_THREADS=6`(threads=12 也接近,无显著差异,threads=4 略慢)
## 输出完整性(大 JSON / TSV 不截断)
- daemon 传输已修复:早期版本大响应会在 **8192 字节**(macOS unix socket 默认发送缓冲 8KB)处被截断,
现强制阻塞写 + 客户端读到对端关闭,**任意大小输出完整**(已用 40 行图验证:19KB JSON 完整、合法)。
- `json` / `tsv` 输出同样完整;`json` 可被 `json.load` 直接解析。
- 已过滤 libMNN 直接打到 stdout 的设备探测行(`The device supports: ...`),one-shot 路径也不污染 payload。
## 模型文件与打包产物(不在本仓库内)
本仓库**只含脚本与二进制**,以下内容被 `.gitignore` 排除,需单独获取/生成:
- `models/`(`det.mnn` ~59MB + `rec.mnn` ~73MB + `dict.txt`)——模型权重,体积大,不进 Git。
获取方式:从官方 release 下载 `RustO-Models-PPOCRv6-Medium.zip` 并解压到 `models/PPOCRv6-Medium/`:
```bash
mkdir -p models/PPOCRv6-Medium
curl -L -o /tmp/m.zip https://github.com/byrizki/rusto-rs/releases/download/v0.2.5/RustO-Models-PPOCRv6-Medium.zip
unzip -o /tmp/m.zip -d models/PPOCRv6-Medium
```
- `rocr-*.zip` 分发包——由本仓库内容 + 模型打包生成,不进 Git。
> 因此 **直接 clone 本仓库得到的是「缺模型」的骨架**:`bin/` 与脚本齐备,补上 `models/PPOCRv6-Medium/` 即可运行;
> 或直接使用完整分发包 `rocr-macos-x86_64.zip`。
## 目录结构(安装后位于 ~/rocr)
```
~/rocr/
├── bin/
│ ├── rocr # 封装脚本(位置无关,可被软链,带 daemon 管理)
│ └── rusto-rs # OCR 二进制(含 --serve 常驻模式)
├── models/
│ └── PPOCRv6-Medium/
│ ├── det.mnn # 检测模型
│ ├── rec.mnn # 识别模型
│ └── dict.txt # 中文字典
├── install.sh / install.command
├── uninstall.sh / uninstall.command
├── docs/ # 验证与调研文档(随仓库分发)
│ ├── OCR性能验证说明.md # 总手册:验证方法 + 三条加速路径结论
│ ├── OCR性能验证-12png报告.html # 1721×1245 大图基准报告
│ ├── mac-gpu-acceleration-research.md # 独显/开源 GPU 加速方案调研
│ ├── int8-quantize-attempt-20260912.md # INT8 量化尝试与回滚复盘
│ ├── rocr-setup-20260912.md # 本机部署配置记录
│ ├── rusto-rs-metal-patch-20260912.patch # rusto-rs 本地补丁(后端/线程/精度环境变量 + Metal 链接修复)
│ └── bench/ # 基准脚本与原始计时记录
├── samples/ # 测试样本图 + 生成脚本
├── rusto-rs/ # OCR 引擎源码(上游 v0.2.5 基线 + 本地补丁,随本仓库管理;target/ 不入库)
└── README.md
```
## 高级:环境变量
```bash
export ROCR_IDLE=300 # 空闲自退时间(秒),默认 600(10 分钟)
export ROCR_NO_DAEMON=1 # 禁用常驻,每次一次性加载(省内存,慢)
export ROCR_SOCK_DIR=/tmp # socket/pid/日志目录,默认 ~/.cache/rocr
export RUSTO_BIN=/path/to/rusto-rs # 重定向二进制
export RUSTO_MODEL_DIR=/path/to/models # 重定向模型目录
export ROCR_HOME=/opt/rocr # 改变安装目标目录(install.sh 用)
# MNN 推理后端调优(rusto-rs 透传)
export ROCR_NUM_THREADS=6 # MNN 线程数(默认 4;本机最优 6)
export ROCR_PRECISION=high # high | normal | low (FP16, x86 没 AVX-512 退化) | lowbf16
export ROCR_POWER=high # high | normal | low
export ROCR_BACKEND=cpu # cpu | metal(x86 Mac 无效,见上节)
```
daemon 日志:`~/.cache/rocr/daemon.log`。
## 在“文档→Markdown”流水线中的定位
扫描件 PDF / 图片缺 OCR 时,用 rocr 离线补齐:**扫描件 → 转图 → `rocr xxx.png markdown` → 回填 Markdown**。
批量场景 daemon 常驻只加载一次模型;模型选型:仅内置高精度档 PP-OCRv6-Medium——干净文本与各小模型持平,扫描件/小字/倾斜/噪点场景明显更稳。