commit aa819b10c8ca95a90e061c6d112d162bef346184 Author: ssw Date: Fri Sep 11 18:07:56 2026 +0800 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 排除, 需单独获取 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..c68b583 --- /dev/null +++ b/.gitignore @@ -0,0 +1,9 @@ +# 模型权重(约 132MB,体积大,单独分发,不进仓库) +models/ +*.mnn + +# 打包产物 +*.zip + +# macOS +.DS_Store diff --git a/README.md b/README.md new file mode 100644 index 0000000..dce3f8e --- /dev/null +++ b/README.md @@ -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——干净文本与各小模型持平,扫描件/小字/倾斜/噪点场景明显更稳。 diff --git a/bin/rocr b/bin/rocr new file mode 100755 index 0000000..abb7dc5 --- /dev/null +++ b/bin/rocr @@ -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 diff --git a/bin/rusto-rs b/bin/rusto-rs new file mode 100755 index 0000000..be0bfbc Binary files /dev/null and b/bin/rusto-rs differ diff --git a/install.command b/install.command new file mode 100755 index 0000000..9574279 --- /dev/null +++ b/install.command @@ -0,0 +1,3 @@ +#!/usr/bin/env bash +# macOS 双击入口: 直接运行同目录下的 install.sh +exec bash "$(dirname "$0")/install.sh" "$@" diff --git a/install.sh b/install.sh new file mode 100755 index 0000000..7ca9e91 --- /dev/null +++ b/install.sh @@ -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" diff --git a/uninstall.command b/uninstall.command new file mode 100755 index 0000000..d5ed3d4 --- /dev/null +++ b/uninstall.command @@ -0,0 +1,3 @@ +#!/usr/bin/env bash +# macOS 双击入口: 直接运行同目录下的 uninstall.sh +exec bash "$(dirname "$0")/uninstall.sh" "$@" diff --git a/uninstall.sh b/uninstall.sh new file mode 100755 index 0000000..f42cc9b --- /dev/null +++ b/uninstall.sh @@ -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 已卸载"