ssw 98b9599ffd rocr: rusto-rs 源码仓收编至仓库目录 + 临时产物清理
- rusto-rs/ 移入仓库(独立 git、上游 GitHub,.gitignore 排除不入库)
- 本地 Metal/调优补丁导出存档 docs/rusto-rs-metal-patch-20260912.patch
- cargo 编译中间产物清理 1.0G→12M(保留 rusto-rs / rusto-rs-metal 最终二进制)
- /tmp 实验临时文件全清(mnn-build-001 216M、bench 脚本、GPU probe 等)
- README 同步源码位置与补丁说明
2026-09-12 17:23:47 +08:00

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/ (独立 git 仓库,上游 https://github.com/byrizki/rusto-rs ,不进本仓库;本地 Metal/调优补丁存档见 docs/rusto-rs-metal-patch-20260912.patch),在源码目录 cargo build --release, 把产物 target/release/rusto-rs 覆盖到 ~/rocr/bin/rusto-rs 即可。

使用

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/:
    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/             # 源码仓(独立 git,上游 GitHub,.gitignore 排除,仅保留最终二进制于 target/release/)
└── README.md

高级:环境变量

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——干净文本与各小模型持平,扫描件/小字/倾斜/噪点场景明显更稳。

S
Description
rocr - 离线中文 OCR CLI (RustO!/MNN, PP-OCRv6-Medium) 可分发包
Readme
2.9 MiB
0 Stars 1 Watchers 0 Forks
Languages
Rust 42.7%
C++ 23.5%
Python 9.9%
Swift 5.1%
Kotlin 4.5%
Other 14.3%