Files
rocr/README.md
T
ssw c77a855eec rocr: 刷新 CPU 二进制并修正性能实测数据
- bin/rusto-rs: 换为支持调优环境变量的构建
  (ROCR_BACKEND / ROCR_NUM_THREADS / ROCR_PRECISION / ROCR_POWER)
  旧构建不认这些变量,会导致按线程调优时静默无效。
- README: 性能实测改为【机器静置】时的真实值
  · 常驻 daemon 热态 ~6s(旧值 9.6–10s 是在 cargo build 抢 CPU 时测得,偏高)
  · 一次性 ~10s,首次(拉起 daemon) ~8s
  · 新增"机器有负载时会退到 10–15s"的说明,提醒计时前先关掉重活
  · 补线程数结论:1 线程 ~9s / 2 线程 ~5.98s / 4 线程 ~6.06s,2 线程即接近饱和
- README: 补上核显(Metal)实测结论——本机 Intel HD 6000 不可用(一次性慢约 32x、
  换尺寸图骤增到 63s),要 GPU 提速需 Apple Silicon 或 N 卡;核显勿再尝试
- README: 澄清 i8sdot/fp16/i8mm 是 ARM 特性探测串,x86 恒为 0,不代表无 SIMD
2026-09-11 22:12:11 +08:00

117 lines
6.7 KiB
Markdown
Raw 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 源码目录 `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,精度略降但快数倍)。
## 输出完整性(大 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
└── 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 用)
```
daemon 日志:`~/.cache/rocr/daemon.log`。
## 在“文档→Markdown”流水线中的定位
扫描件 PDF / 图片缺 OCR 时,用 rocr 离线补齐:**扫描件 → 转图 → `rocr xxx.png markdown` → 回填 Markdown**。
批量场景 daemon 常驻只加载一次模型;模型选型:仅内置高精度档 PP-OCRv6-Medium——干净文本与各小模型持平,扫描件/小字/倾斜/噪点场景明显更稳。