rocr: 离线中文 OCR CLI (RustO!/MNN, PP-OCRv6-Medium) 可分发包

- bin/rocr: 位置无关封装脚本, 带 daemon 常驻管理 (空闲 600s 自退)
- bin/rusto-rs: macOS x86_64 二进制 (含 --serve 常驻模式, 大输出不截断修复)
- install/uninstall 脚本 (含 macOS 双击 .command)
- models/ 与 *.zip 体积大, 由 .gitignore 排除, 需单独获取
This commit is contained in:
ssw committed 2026-09-11 18:07:56 +08:00
commit aa819b10c8
8 files changed
+338

No files matched your search

+9
View File
@@ -0,0 +1,9 @@
# 模型权重(约 132MB,体积大,单独分发,不进仓库)
models/
*.mnn
# 打包产物
*.zip
# macOS
.DS_Store
+106
View File
@@ -0,0 +1,106 @@
# 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 分钟)无请求自动退出释放内存**,下次调用再自动拉起。
性能实测(Intel Mac,无 SIMD 加速):
| 模式 | 单张耗时 | 说明 |
|------|---------|------|
| 一次性(旧版) | ~12s | 每次加载模型 + 推理 |
| 常驻 daemon 热态 | **~9.5s** | 省掉加载,剩余为纯推理 |
| 首次(拉起 daemon) | ~13s | 加载 + 首次推理 |
> ⚠️ 瓶颈说明:本机 MNN 设备探测 `i8sdot:0, fp16:0, i8mm:0`(无 SIMD 加速路径),推理走慢速标量内核,
> rec 模型按检测行数逐行推理,**每张 ~9s 是推理本身的成本**。要数量级提速需换有 NEON/fp16 的机器(如 Apple Silicon),
> 或在批量场景换小模型档(官方 release 另有 PPOCRv6-Tiny ~5.5MB,精度略降但快数倍)。
> 耗时随文本行数近似线性增长:约 1–2s/行,一页 40 行的图约 50s。
## 输出完整性(大 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——干净文本与各小模型持平,扫描件/小字/倾斜/噪点场景明显更稳。
Executable
+140
View File
@@ -0,0 +1,140 @@
#!/usr/bin/env bash
# rocr — 离线中文 OCR (rusto-rs + PP-OCRv6-Medium)
# 常驻模式: 首次调用自动拉起 daemon 加载模型(一次性 ~7-13s), 之后每次调用走 Unix socket,
# 亚秒级返回; 空闲 ROCR_IDLE 秒(默认 120)无请求后 daemon 自动退出释放内存。
set -euo pipefail
# 解析脚本真实路径(兼容 /usr/local/bin 软链与任意移动)
SOURCE="${BASH_SOURCE[0]}"
while [ -h "$SOURCE" ]; do
DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
SOURCE="$(readlink "$SOURCE")"
[[ "$SOURCE" != /* ]] && SOURCE="$DIR/$SOURCE"
done
SCRIPT_DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
BIN="${RUSTO_BIN:-$SCRIPT_DIR/rusto-rs}"
MODEL_DIR="${RUSTO_MODEL_DIR:-$SCRIPT_DIR/../models/PPOCRv6-Medium}"
SOCK_DIR="${ROCR_SOCK_DIR:-$HOME/.cache/rocr}"
SOCK="$SOCK_DIR/rocr.sock"
PIDF="$SOCK_DIR/rocr.pid"
LOG="$SOCK_DIR/daemon.log"
IDLE="${ROCR_IDLE:-600}"
usage() {
cat <<'EOF'
rocr — 离线中文 OCR (rusto-rs + PP-OCRv6-Medium, 约 94MB 高精度模型, 常驻加速)
用法:
rocr <图片路径> [text|json|tsv|markdown|textordered]
rocr # 显示本帮助
参数:
<图片路径> 待识别的图片 (png/jpg/...),必填
[格式] 输出格式,默认 text。可选: text | json | tsv | markdown | textordered
示例:
rocr scan.jpg # 文本输出 (默认)
rocr scan.jpg markdown # Markdown 输出 (直接进 文档→Markdown 流水线)
rocr scan.png json # JSON (含坐标框 + 置信度)
常驻加速:
首次调用会自动后台拉起 daemon 并加载模型(约 7-13 秒, 仅一次);
之后每次调用走本地 Unix socket, 亚秒级返回;
空闲 600 秒(10 分钟)无请求后 daemon 自动退出释放内存, 下次调用再自动拉起。
环境变量:
ROCR_IDLE=<秒> 空闲自退时间, 默认 600 (10 分钟)
ROCR_NO_DAEMON=1 禁用常驻, 每次一次性加载(慢但省内存)
ROCR_SOCK_DIR=<目录> socket/pid/日志目录, 默认 ~/.cache/rocr
RUSTO_BIN=<路径> 重定向二进制
RUSTO_MODEL_DIR=<目录> 重定向模型目录
说明:
- 纯本地推理, 无需联网 / API key, 不消耗 token
- 模型固定 PP-OCRv6-Medium (高精度档; 干净文本与 tiny 持平, 扫描件/小字/倾斜场景明显更准)
EOF
}
if [[ $# -eq 0 || "$1" == "-h" || "$1" == "--help" ]]; then
usage
exit 0
fi
IMG="$1"
FORMAT="${2:-text}"
if [[ ! -f "$IMG" ]]; then
echo "✗ 文件不存在: $IMG" >&2
exit 1
fi
if [[ ! -f "$MODEL_DIR/det.mnn" || ! -f "$MODEL_DIR/rec.mnn" || ! -f "$MODEL_DIR/dict.txt" ]]; then
echo "✗ 模型文件缺失: $MODEL_DIR/{det.mnn,rec.mnn,dict.txt} (可用 RUSTO_MODEL_DIR 覆盖)" >&2
exit 1
fi
one_shot() {
# 过滤 libMNN 直接打到 stdout 的设备探测行, 避免污染 json/tsv 输出
"$BIN" \
--det-model "$MODEL_DIR/det.mnn" \
--rec-model "$MODEL_DIR/rec.mnn" \
--dict "$MODEL_DIR/dict.txt" \
"$IMG" --format "$FORMAT" | awk '!/^The device supports: i8sdot:/'
}
# 无 python3、无二进制或显式禁用 → 一次性调用
# (不用 nc: macOS nc 在 stdin EOF 后立即断开, 等不到 daemon 响应)
if [[ "${ROCR_NO_DAEMON:-0}" == "1" || ! -x "$BIN" ]] || ! command -v python3 >/dev/null 2>&1; then
one_shot
exit 0
fi
mkdir -p "$SOCK_DIR"
daemon_alive() {
[[ -S "$SOCK" ]] && [[ -f "$PIDF" ]] && kill -0 "$(cat "$PIDF" 2>/dev/null)" 2>/dev/null
}
if ! daemon_alive; then
rm -f "$SOCK" "$PIDF"
# 简单锁避免并发重复拉起
if mkdir "$SOCK_DIR/lock" 2>/dev/null; then
nohup "$BIN" \
--det-model "$MODEL_DIR/det.mnn" \
--rec-model "$MODEL_DIR/rec.mnn" \
--dict "$MODEL_DIR/dict.txt" \
--serve --socket "$SOCK" --idle "$IDLE" >>"$LOG" 2>&1 &
echo $! > "$PIDF"
rmdir "$SOCK_DIR/lock" 2>/dev/null || true
fi
# 等 socket 出现; 模型加载期间连接会排队, 首次调用自动等到就绪
for _ in $(seq 1 60); do
[[ -S "$SOCK" ]] && break
sleep 0.5
done
fi
# 走 daemon: python 客户端连接 unix socket, 读到对端关闭为止
if command -v python3 >/dev/null 2>&1; then
if python3 - "$FORMAT" "$IMG" "$SOCK" <<'PY'
import socket, sys
fmt, img, sock = sys.argv[1], sys.argv[2], sys.argv[3]
s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
s.connect(sock)
s.sendall((fmt + "\n" + img + "\n").encode())
buf = b""
while True:
d = s.recv(65536)
if not d:
break
buf += d
sys.stdout.write(buf.decode())
PY
then
exit 0
fi
fi
# daemon 未就绪/失败 → 回退一次性调用
one_shot
Executable
BIN
View File
Binary file not shown.
+3
View File
@@ -0,0 +1,3 @@
#!/usr/bin/env bash
# macOS 双击入口: 直接运行同目录下的 install.sh
exec bash "$(dirname "$0")/install.sh" "$@"
Executable
+54
View File
@@ -0,0 +1,54 @@
#!/usr/bin/env bash
# rocr 安装脚本: 把本包复制到 ~/rocr 并将 rocr 注册到 /usr/local/bin
# 用法: bash install.sh (macOS 也可直接双击 install.command)
set -euo pipefail
# 解析本安装包所在目录(兼容被软链/移动)
SOURCE="${BASH_SOURCE[0]}"
while [ -h "$SOURCE" ]; do
DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
SOURCE="$(readlink "$SOURCE")"
[[ "$SOURCE" != /* ]] && SOURCE="$DIR/$SOURCE"
done
PKG_DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
TARGET="${ROCR_HOME:-$HOME/rocr}"
LINK="/usr/local/bin/rocr"
BIN="$TARGET/bin/rocr"
echo ">>> rocr 安装"
echo " 安装包: $PKG_DIR"
echo " 目标目录: $TARGET"
echo " 命令链接: $LINK"
# 平台提示(分发包内二进制为 macOS x86_64, 其它平台需自行编译)
OSARCH="$(uname -s) $(uname -m)"
if [ "$OSARCH" != "Darwin x86_64" ]; then
echo " ⚠ 当前平台 [$OSARCH] 与内置二进制(macOS x86_64)不符, 若运行失败请到 rusto-rs 源码目录执行 'cargo build --release' 覆盖 $TARGET/bin/rusto-rs"
fi
# 1) 复制包内容到目标目录
mkdir -p "$TARGET/bin" "$TARGET/models"
cp -R "$PKG_DIR/bin/." "$TARGET/bin/"
cp -R "$PKG_DIR/models/." "$TARGET/models/"
[ -f "$PKG_DIR/README.md" ] && cp "$PKG_DIR/README.md" "$TARGET/" || true
chmod +x "$TARGET/bin/rocr" "$TARGET/bin/rusto-rs"
# 2) 注册到 /usr/local/bin (无写权限时回退 sudo)
if [ -w "$(dirname "$LINK")" ]; then
ln -sf "$BIN" "$LINK"
else
echo " 需要管理员权限写入 $(dirname "$LINK") ..."
sudo ln -sf "$BIN" "$LINK"
fi
# 3) 自测
echo ">>> 验证命令可用性"
if command -v rocr >/dev/null 2>&1; then
echo "✓ rocr 已就绪, 直接运行:"
echo " rocr <图片> [text|json|tsv|markdown|textordered]"
echo " rocr # 查看帮助"
else
echo "⚠ 链接已建立, 但当前 shell 未刷新 PATH, 请重开终端或执行: export PATH=/usr/local/bin:\$PATH"
fi
echo ">>> 安装完成. 卸载: bash $PKG_DIR/uninstall.sh"
+3
View File
@@ -0,0 +1,3 @@
#!/usr/bin/env bash
# macOS 双击入口: 直接运行同目录下的 uninstall.sh
exec bash "$(dirname "$0")/uninstall.sh" "$@"
Executable
+23
View File
@@ -0,0 +1,23 @@
#!/usr/bin/env bash
# rocr 卸载脚本: 移除 ~/rocr 与 /usr/local/bin/rocr
# 用法: bash uninstall.sh (macOS 也可直接双击 uninstall.command)
set -euo pipefail
TARGET="${ROCR_HOME:-$HOME/rocr}"
LINK="/usr/local/bin/rocr"
echo ">>> rocr 卸载"
echo " 将移除: $LINK"
echo " $TARGET"
# 移除命令链接(无写权限时回退 sudo)
if [ -w "$(dirname "$LINK")" ]; then
rm -f "$LINK"
else
sudo rm -f "$LINK"
fi
# 移除安装目录
rm -rf "$TARGET"
echo "✓ rocr 已卸载"