- 源码 316 文件收编为 rusto-rs/ 文件夹,随本仓库管理 - 移除内部 .git(补丁已存档 docs/rusto-rs-metal-patch-20260912.patch,上游可随时 re-clone) - target/ 与 docs/.yarn 缓存不入库;本地改动:ROCR_* 环境变量调优 + Metal 链接修复 + 预处理测试脚本
153 lines
9.4 KiB
Markdown
153 lines
9.4 KiB
Markdown
# 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——干净文本与各小模型持平,扫描件/小字/倾斜/噪点场景明显更稳。
|