diff --git a/README.md b/README.md
index aac15d5..ab595c6 100644
--- a/README.md
+++ b/README.md
@@ -66,7 +66,7 @@ rocr scan.png json # JSON(含坐标框 + 置信度)
**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`):
+**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 工具不支持
@@ -111,6 +111,14 @@ rocr scan.png json # JSON(含坐标框 + 置信度)
│ └── 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 # 本机部署配置记录
+│ └── bench/ # 基准脚本与原始计时记录
+├── samples/ # 测试样本图 + 生成脚本
└── README.md
```
diff --git a/docs/OCR性能验证-12png报告.html b/docs/OCR性能验证-12png报告.html
new file mode 100644
index 0000000..a0f883e
--- /dev/null
+++ b/docs/OCR性能验证-12png报告.html
@@ -0,0 +1,223 @@
+
+
+
+
+
+
+ OCR 性能验证 · 实测报告
+ 12.png 大图:CPU vs 独显(Radeon Pro 5300M)
+ 结论:独显没有加速。大图 1721×1245 下 CPU 与独显同为 12–15 s/张;硬证据显示 Metal 后端并未把计算交给 GPU。
+
+ 机型 MacBook Pro 2019
+ CPU i7-9750H(6核12线程)
+ GPU Radeon Pro 5300M + UHD 630
+ 系统 macOS 26.6.2 (x86_64)
+ 测试时间 2026-09-12 12:15–12:41
+
+
+
+
+ 0测试对象
+ 你提供的 12.png —— 比原有样本图大一个量级,更能反映真实文档/截图批量场景
+
+
+
像素量(相对样本图 A 800×320)
8.37倍
+
+ 图为 WorkBuddy 界面截图,共识别出 1422 字符,CPU 与独显两条路径的输出 sha256 完全一致 → 都真实跑通、结果正确,不存在空跑或短路。
+
+
+
+ 1三组独立测量:结果一致,独显无优势
+ 为排除后台负载干扰,用三种不同编排各测一轮,互相印证
+
+ A. 三臂交错(CPU-6 / CPU-12 / 独显 同时待命,交替请求,10 轮)
+
+ | 后端 | 最小 | 中位 | 最大 |
+
+ | CPU(6 线程) | 11.60 s | 12.46 s | 15.22 s |
+ | CPU(12 线程) | 11.62 s | 12.06 s | 15.61 s |
+ | 独显 Radeon 5300M | 11.56 s | 12.32 s | 15.83 s |
+
+
+
+ B. 单 daemon 串行(同一时刻只有一个在跑,各预热 1 次 + 热态 6 次)
+
+ | 后端 | 最小 | 中位 | 最大 | 输出 sha256 |
+
+ | 独显 Radeon 5300M | 13.83 s | 13.90 s | 15.71 s | 98831d2e… |
+ | CPU(6 线程) | 13.25 s | 14.72 s | 15.83 s | 98831d2e… |
+ | CPU(12 线程) | 11.99 s | 12.91 s | 16.18 s | 98831d2e… |
+
+
+ 两轮编排的数据高度吻合:三者全部落在 12–15 s 区间,差异小于测量波动本身——独显没有带来任何可观测的加速。
+
+ 耗时对比(中位数)
+
+ 0 s8 s16 s
+
+
+
+ 2决定性证据:GPU 根本没干活
+ 只看耗时容易误判,于是直接比对「CPU 干了多少活」——用 /usr/bin/time -l 一次性调用
+
+ | 指标(一次性调用,12.png) | CPU(6 线程) | 独显(metal) | 差异 |
+
+ | 墙钟 real | 12.13 s | 12.57 s | +3.6% |
+ | 用户态 CPU user | 59.62 s | 60.49 s | +1.5% |
+ | 系统态 CPU sys | 3.39 s | 3.50 s | +3.2% |
+ | 执行指令数 | 288.22 G | 287.99 G | −0.08% |
+ | 峰值内存 | 2226 MB | 2258 MB | +1.4% |
+
+
+ 关键判读:如果独显真的在算,CPU 的 user 时间和指令数应当大幅下降。实测两者几乎完全一样(指令数仅差 0.08%)——说明该构建下 ROCR_BACKEND=metal 并没有把计算卸载到 GPU,CPU 承担了完全相同的计算量。这就是「两者性能持平」的根本原因,而不是巧合。
+ 补充:该二进制确实链接了 Metal 并能返回正确结果(设备探针也确认系统默认设备为 Radeon 5300M),所以这不是报错或回退失败,而是 MNN 的 Metal 后端在这套 x86 macOS 构建 + 这两个模型上没有产生实际加速。
+
+
+
+ 3尺寸切换:没有「重编译爆炸」
+ 2015 基线曾记录「换尺寸图暴涨到 63 s」,本机复测该现象不存在
+
+ | 步骤(同一个 GPU daemon 内) | 耗时 | 说明 |
+
+ | 小图 800×320 预热 | 2.91 s | 常驻预热 |
+ | 小图 800×320 #1 | 2.75 s | 热态 |
+ | 切大图 1721×1245(首次新尺寸) | 17.23 s | ×6.3(纯像素量) |
+ | 大图 1721×1245 #2 | 14.62 s | 热态 |
+ | 切回小图 800×320 | 2.54 s | 无爆炸 |
+ | 再切大图 1721×1245 | 15.70 s | 无爆炸 |
+
+
+ 切回小图立刻回到 2.5 s,说明没有按尺寸重编译流水线;大图变慢只是像素量翻了 8.37 倍带来的正常计算增长(首次略高属预热效应)。
+
+
+
+ 4结论与建议
+
+ - 用 CPU,不用独显。12.png 大图上 CPU 与独显同为 12–15 s/张,独显零收益。
+ - 线程数取 6–12 都行。本次 12 线程中位略优(12.06 s vs 12.46 s),差异在噪声范围内;6 线程已足够。
+ - 不必为独显做任何适配工作。根因是 Metal 后端未真正卸载计算,不是配置问题。
+ - 尺寸不再是隐患。本机无「换尺寸重编译」问题,批量混合尺寸文档可放心用常驻 daemon。
+ - 横向参考:样本图 800×320 下本机 CPU 热态 2.14–2.33 s,相比 2015 款 Air(6.0 s 基线)快约 2.6–2.8 倍,符合「6 核 12 线程 vs 2 核 4 线程」的预期。
+
+ 数据可信度说明:历史档案 bench-result-xsMBP-20260912-1026.txt 中记录的「Metal 热态 9.61 s / 换尺寸 59.33 s」与本轮干净复测严重不符(本轮样本图 800×320 下 Metal 仅 2.07–2.31 s、换尺寸 2.46 s)。该段为早期二进制版本或当时环境干扰所致,建议作废,不采信。
+ 环境干扰提醒:本机存在间歇性后台负载(iCloud/群盘同步、Spotlight 索引,负载 5–16 波动)。本报告已用「多轮交错 + 单 daemon 串行 + 输出哈希校验」三重手段交叉验证,确保结论不依赖单次采样。测试时请尽量关闭同步与索引。
+
+
+
+ 5附录:复现命令与设备信息
+ 设备探针输出
+ # gpu_probe(枚举全部 Metal 设备)
+设备: AMD Radeon Pro 5300M lowPower=0 headless=0
+设备: Intel(R) UHD Graphics 630 lowPower=1 headless=0
+# 系统默认设备(MTLCreateSystemDefaultDevice)
+ROCR_METAL_DEVICE=(未设置=系统默认) -> 选中: AMD Radeon Pro 5300M (lowPower=0)
+
+ 核心复现命令
+ # 单次耗时(CPU / 独显)
+ROCR_BACKEND=cpu ROCR_NUM_THREADS=6 \
+ rocr/bin/rusto-rs --det-model rocr/models/PPOCRv6-Medium/det.mnn \
+ --rec-model rocr/models/PPOCRv6-Medium/rec.mnn \
+ --dict rocr/models/PPOCRv6-Medium/dict.txt \
+ /Users/xs/Desktop/12.png -f text
+
+ROCR_BACKEND=metal ROCR_NUM_THREADS=6 \
+ rusto-rs/target/release/rusto-rs-metal # 参数同上
+
+# 关键:比对 CPU 干了多少活(判定 GPU 是否真的参与)
+/usr/bin/time -l env ROCR_BACKEND=metal rusto-rs/target/release/rusto-rs-metal \
+ ... /Users/xs/Desktop/12.png -f text | grep -E "real|user|instructions"
+
+ 原始数据存档
+ bench-12png-20260912-1241.txt(本目录)——含全部轮次原始计时、sha256 校验、CPU 时间/指令数明细。
+
+
+
+
+
+
+
diff --git a/docs/OCR性能验证说明.md b/docs/OCR性能验证说明.md
new file mode 100644
index 0000000..e46ae17
--- /dev/null
+++ b/docs/OCR性能验证说明.md
@@ -0,0 +1,388 @@
+# OCR 性能验证说明(rocr / RustO! + MNN)
+
+**目的**:在另一台 Mac(如 2019 款 MBP i7 + 独显)上复现同一套 OCR 性能实验,用数据回答
+**「这台机器会不会好一点?独显到底值不值得用?」**
+
+**做法**:把整个工作空间文件夹(本目录)复制过去,cd 进来,粘一段命令,等结果。
+本文件就是全部说明,不需要额外的临时文件夹——所需的二进制、模型、样本图都已在工作空间里。
+
+---
+
+## 0. 会用到的东西(都在本目录,无需再下载)
+
+| 路径 | 说明 |
+|------|------|
+| `rocr/bin/rusto-rs` | **CPU 版** OCR 二进制,3.7 MB。纯 CPU 后端(已确认未链接 MetalKit/MPS),支持下面的 `ROCR_*` 调优变量 |
+| `rusto-rs/target/release/rusto-rs-metal` | **Metal 版**二进制(约 3.8 MB)。已链接 Metal 后端,跑的是**系统默认 GPU**(本机默认=独显,2015 Air 默认=核显) |
+| `rocr/models/PPOCRv6-Medium/` | 模型权重:`det.mnn`(62 MB) + `rec.mnn`(76 MB) + `dict.txt`,约 138 MB |
+| `samples/lt-a-800x320.png` | 测试图 A(800×320,5 行中文) |
+| `samples/lt-b-1000x400.png` | 测试图 B(**尺寸不同**,专门用来测 Metal 的流水线重编译) |
+| `samples/gen-sample.py` | 样本图生成脚本(需 Pillow,一般用不到) |
+| `rocr-macos-x86_64.zip` | 正式安装包(只想装来用、不做性能测试的话用它) |
+
+> `rusto-rs/` 是源码目录(736 MB,含 `target/` 构建产物)。**如果只想要上面两样东西**,
+> 复制时可以只带 `rocr/`、`samples/`、本文件和 `rusto-rs/target/release/rusto-rs-metal`,
+> 合计约 150 MB。缺了金属版二进制也可以跳过独显测试(脚本会自己提示)。
+
+---
+
+## 1. 三步跑起来
+
+**① 拷过去,进入目录**(换成你实际放的位置)
+
+```bash
+cd ~/Desktop/ro
+```
+
+**② 解除 macOS 隔离属性**(AirDrop / 网盘 / 浏览器下载过来的文件会被 Gatekeeper 拦住,做一次即可)
+
+```bash
+xattr -dr com.apple.quarantine .
+```
+
+**③ 把下面整段复制到终端执行**(先改 `FULL`,再用鼠标选中整段一次粘进去)
+
+```bash
+FULL=0 # ← 想连独立显卡(Metal)一起测,把 0 改成 1
+RESULT="$PWD/bench-result-$(hostname -s)-$(date +%Y%m%d-%H%M).txt"
+
+bench() {
+ local ROOT="$PWD"
+ local CPU="$ROOT/rocr/bin/rusto-rs"
+ local MODEL="$ROOT/rocr/models/PPOCRv6-Medium"
+ local METAL="$ROOT/rusto-rs/target/release/rusto-rs-metal"
+ local IMG_A="$ROOT/samples/lt-a-800x320.png"
+ local IMG_B="$ROOT/samples/lt-b-1000x400.png"
+ local SOCK_BASE="/tmp/rocr-bench-$$"
+ local BASE_CPU_WARM=6.00 # 2015 Air 静置实测基线,用于换算"快了几倍"
+ local PHY LOG DAEMON_PID LAST
+
+ [ -x "$CPU" ] || { echo "✗ 找不到 $CPU"; echo " 请先 cd 到工作空间根目录(含 rocr/ rusto-rs/ samples/ 的那层)再贴这段"; return 1; }
+ [ -f "$MODEL/det.mnn" ] || { echo "✗ 找不到模型 $MODEL"; return 1; }
+ [ -f "$IMG_A" ] || { echo "✗ 找不到样本图 $IMG_A"; return 1; }
+
+ if xattr -p com.apple.quarantine "$CPU" >/dev/null 2>&1; then
+ echo "· 检测到 quarantine 属性,正在解除…"; xattr -dr com.apple.quarantine "$ROOT" >/dev/null 2>&1
+ fi
+ chmod +x "$CPU" "$METAL" 2>/dev/null
+
+ _now() { perl -MTime::HiRes=time -e 'printf "%.2f", time'; }
+ _dt() { awk -v a="$1" -v b="$2" 'BEGIN{printf "%.2f", b-a}'; }
+ _line() { printf '%s\n' "-------------------------------------------------------------------------------"; }
+ _head() { echo; _line; printf ' %s\n' "$1"; _line; }
+ row() { printf ' %-30s %10s s\n' "$1" "$2"; }
+
+ # 往 daemon 发一次请求(协议:第一行格式,第二行图片路径)
+ sock_req() {
+ perl -e '
+ use strict; use warnings; use IO::Socket::UNIX;
+ my ($sock,$img,$fmt)=@ARGV;
+ my $s=IO::Socket::UNIX->new(Peer=>$sock) or die "connect failed: $!\n";
+ $s->autoflush(1); print $s "$fmt\n$img\n";
+ my $out=do{ local $/; <$s> }; print defined $out ? $out : ""; close $s;
+ ' "$1" "$2" "${3:-text}"
+ }
+
+ stop_daemon() { [ -n "${DAEMON_PID:-}" ] && kill "$DAEMON_PID" 2>/dev/null; DAEMON_PID=""; sleep 1; }
+
+ start_daemon() { # $1=bin $2=backend $3=threads $4=sock
+ local bin="$1" be="$2" th="$3" sock="$4" n=0
+ stop_daemon
+ rm -f "$sock" "$sock.log"
+ ROCR_BACKEND="$be" ROCR_NUM_THREADS="$th" "$bin" --serve --socket "$sock" --idle 3600 \
+ --det-model "$MODEL/det.mnn" --rec-model "$MODEL/rec.mnn" --dict "$MODEL/dict.txt" >"$sock.log" 2>&1 &
+ DAEMON_PID=$!
+ while [ "$n" -lt 900 ]; do
+ grep -qi ready "$sock.log" 2>/dev/null && return 0
+ kill -0 "$DAEMON_PID" 2>/dev/null || { echo " ✗ daemon 启动失败:"; sed 's/^/ /' "$sock.log"; return 1; }
+ sleep 1; n=$((n+1))
+ done
+ echo " ✗ daemon 启动超时"; return 1
+ }
+
+ cleanup() { stop_daemon; rm -f /tmp/rocr-bench-*.sock /tmp/rocr-bench-*.sock.log 2>/dev/null; }
+ trap cleanup EXIT INT TERM
+
+ timed_req() { # $1=sock $2=img $3=标签
+ local t0 t1; t0=$(_now); sock_req "$1" "$2" text >/dev/null 2>&1; t1=$(_now)
+ LAST="$(_dt "$t0" "$t1")"; row "$3" "$LAST"
+ }
+ timed_oneshot() { # $1=bin $2=backend $3=threads $4=img $5=标签
+ local t0 t1; t0=$(_now)
+ ROCR_BACKEND="$2" ROCR_NUM_THREADS="$3" "$1" \
+ --det-model "$MODEL/det.mnn" --rec-model "$MODEL/rec.mnn" --dict "$MODEL/dict.txt" \
+ "$4" --format text >/dev/null 2>&1
+ t1=$(_now); LAST="$(_dt "$t0" "$t1")"; row "$5" "$LAST"
+ }
+
+ # ---------------- 硬件信息 ----------------
+ echo "==============================================================================="
+ echo " rocr OCR 性能验证 —— $(date '+%Y-%m-%d %H:%M:%S')"
+ echo "==============================================================================="
+ echo " CPU : $(sysctl -n machdep.cpu.brand_string 2>/dev/null || echo '?')"
+ echo " 核心 : $(sysctl -n hw.physicalcpu) 物理 / $(sysctl -n hw.logicalcpu) 逻辑"
+ echo " 内存 : $(sysctl -n hw.memsize | awk '{printf "%.0f GB", $1/1073741824}')"
+ echo " 系统 : macOS $(sw_vers -productVersion 2>/dev/null) ($(uname -m))"
+ echo " 模式 : $( [ "$FULL" = "1" ] && echo '完整(CPU+Metal)' || echo '快速(仅CPU)' )"
+ echo " GPU :"
+ system_profiler SPDisplaysDataType 2>/dev/null \
+ | grep -E "^\s+(Chipset Model|Vendor|Metal)" | sed 's/^[[:space:]]*/ /' \
+ || echo " (读取失败)"
+ echo " 模型 : $MODEL"
+ echo
+
+ PHY="$(sysctl -n hw.physicalcpu 2>/dev/null || echo 4)"
+ LOG="$(sysctl -n hw.logicalcpu 2>/dev/null || echo 4)"
+
+ # ---------------- 1. CPU 一次性 ----------------
+ _head "1) CPU —— 一次性调用(未启用常驻)"
+ timed_oneshot "$CPU" cpu 4 "$IMG_A" "一次性 (默认4线程)"
+ CPU_ONESHOT="$LAST"
+
+ # ---------------- 2. CPU 常驻 ----------------
+ _head "2) CPU —— 常驻 daemon(threads=4,默认档)"
+ CPU_COLD=""; CPU_WARM=""; CPU_SHAPE=""
+ sock="$SOCK_BASE-cpu4.sock"
+ if start_daemon "$CPU" cpu 4 "$sock"; then
+ t0=$(_now); sock_req "$sock" "$IMG_A" text >/dev/null 2>&1; CPU_COLD="$(_dt "$t0" "$(_now)")"
+ row "首次请求(含模型加载)" "$CPU_COLD"
+ timed_req "$sock" "$IMG_A" "热态 #1"; CPU_WARM="$LAST"
+ timed_req "$sock" "$IMG_A" "热态 #2"
+ timed_req "$sock" "$IMG_B" "热态(换尺寸图)"; CPU_SHAPE="$LAST"
+ else
+ echo " (跳过)"
+ fi
+ stop_daemon
+
+ # ---------------- 3. 线程数扫描 ----------------
+ _head "3) CPU —— 线程数扫描(常驻热态,看多核能否再提速)"
+ CPU_WARM_PHY=""; CPU_WARM_LOG=""; CPU_WARM_T1=""
+ DONE=" 4 "
+ for t in 1 "$PHY" "$LOG"; do
+ case "$DONE" in *" $t "*) continue ;; esac
+ DONE="$DONE$t "
+ sock="$SOCK_BASE-cput$t.sock"
+ if start_daemon "$CPU" cpu "$t" "$sock"; then
+ timed_req "$sock" "$IMG_A" "threads=$t 热态 #1"
+ timed_req "$sock" "$IMG_A" "threads=$t 热态 #2"
+ case "$t" in
+ 1) CPU_WARM_T1="$LAST" ;;
+ "$PHY") CPU_WARM_PHY="$LAST" ;;
+ "$LOG") CPU_WARM_LOG="$LAST" ;;
+ esac
+ else
+ echo " (threads=$t 跳过)"
+ fi
+ stop_daemon
+ done
+
+ # ---------------- 3b. 对照复测(抓"越跑越快"的漂移)----------------
+ CPU_WARM_CTRL=""
+ sock="$SOCK_BASE-cpuctrl.sock"
+ if start_daemon "$CPU" cpu 4 "$sock"; then
+ timed_req "$sock" "$IMG_A" "对照复测 threads=4"
+ CPU_WARM_CTRL="$LAST"
+ fi
+ stop_daemon
+
+ # ---------------- 4/5. Metal ----------------
+ METAL_ONESHOT=""; METAL_COLD=""; METAL_WARM=""; METAL_SHAPE=""
+ if [ "$FULL" = "1" ]; then
+ if [ -x "$METAL" ]; then
+ _head "4) Metal(系统默认 GPU)—— 一次性调用"
+ echo " ⏳ 首次要做 Metal 着色器运行时编译,可能非常慢(2015 核显实测约 390 s),耐心等…"
+ timed_oneshot "$METAL" metal "$PHY" "$IMG_A" "一次性 (含编译)"
+ METAL_ONESHOT="$LAST"
+
+ _head "5) Metal —— 常驻 daemon(编译一次,后续热态)"
+ sock="$SOCK_BASE-metal.sock"
+ if start_daemon "$METAL" metal "$PHY" "$sock"; then
+ echo " ⏳ 首次请求含着色器编译,可能很慢…"
+ t0=$(_now); sock_req "$sock" "$IMG_A" text >/dev/null 2>&1
+ METAL_COLD="$(_dt "$t0" "$(_now)")"; row "首次请求(含着色器编译)" "$METAL_COLD"
+ timed_req "$sock" "$IMG_A" "热态 #1"; METAL_WARM="$LAST"
+ timed_req "$sock" "$IMG_A" "热态 #2"
+ timed_req "$sock" "$IMG_B" "热态(换尺寸图)"; METAL_SHAPE="$LAST"
+ else
+ echo " (跳过: Metal daemon 未启动)"
+ fi
+ stop_daemon
+ else
+ echo; echo "⚠️ 未找到 Metal 版二进制 $METAL,跳过独显阶段。"
+ echo " (重建见文末「Metal 二进制丢了怎么办」)"
+ fi
+ fi
+
+ # ---------------- 汇总 ----------------
+ _head "汇总对比"
+ printf ' %-30s %10s s %s\n' "项目" "耗时" "vs 2015 i5-5250U"
+ printf ' %-30s %10s\n' "2015 基线 CPU 常驻(静置)" "$BASE_CPU_WARM"
+ [ -n "$CPU_WARM" ] && printf ' %-30s %10s s 快 %.1f 倍\n' "本机 CPU 常驻 (threads=4)" "$CPU_WARM" \
+ "$(awk -v a="$BASE_CPU_WARM" -v b="$CPU_WARM" 'BEGIN{printf "%.2f", a/b}')"
+ [ -n "$CPU_WARM_PHY" ] && printf ' %-30s %10s s\n' "本机 CPU 常驻 (threads=$PHY)" "$CPU_WARM_PHY"
+ [ -n "$CPU_WARM_LOG" ] && printf ' %-30s %10s s\n' "本机 CPU 常驻 (threads=$LOG)" "$CPU_WARM_LOG"
+ [ -n "$CPU_WARM_T1" ] && printf ' %-30s %10s s\n' "本机 CPU 常驻 (threads=1)" "$CPU_WARM_T1"
+ [ -n "$CPU_ONESHOT" ] && printf ' %-30s %10s s\n' "本机 CPU 一次性" "$CPU_ONESHOT"
+ [ -n "$CPU_WARM_CTRL" ] && printf ' %-30s %10s s 对照\n' "本机 CPU 复测 (threads=4)" "$CPU_WARM_CTRL"
+ if [ -n "$METAL_WARM" ]; then
+ printf ' %-30s %10s s\n' "本机 Metal 常驻 热态" "$METAL_WARM"
+ printf ' %-30s %10s s\n' "本机 Metal 冷启动(含编译)" "$METAL_COLD"
+ printf ' %-30s %10s s\n' "本机 Metal 换尺寸图" "$METAL_SHAPE"
+ fi
+ _line
+
+ # 漂移检测
+ if [ -n "$CPU_WARM" ] && [ -n "$CPU_WARM_CTRL" ]; then
+ DRIFT="$(awk -v a="$CPU_WARM" -v b="$CPU_WARM_CTRL" 'BEGIN{
+ if (a<=0) { print "0"; exit } d=(b-a)/a; if (d<0) d=-d; printf "%.0f", d*100 }')"
+ if [ "$DRIFT" -ge 25 ]; then
+ echo
+ echo " ⚠️ 结果漂移较大:threads=4 首测 $CPU_WARM s,末尾复测 $CPU_WARM_CTRL s(相差 ${DRIFT}%)。"
+ echo " 多半是测量期间机器在后台干活(Spotlight 索引、iCloud/网盘同步、杀毒、Chrome)。"
+ echo " 建议关掉它们再跑一遍取稳定值。"
+ fi
+ fi
+
+ echo
+ echo " 判读要点:"
+ echo " · 看「本机 CPU 常驻」,这就是批量任务的真实速度(每张)。"
+ echo " · Metal 值不值得用,看两点:热态是否明显快于 CPU;"
+ echo " 以及「换尺寸图」是否暴涨(暴涨=每个新尺寸都要重编译流水线,批量场景不可用)。"
+ echo " · 若 Metal 热态 ≈ CPU(±20% 内)→ 别折腾独显,用 CPU。"
+ [ "$FULL" != "1" ] && echo " · 想连独显一起验,把本段开头的 FULL=0 改成 FULL=1 再跑一次。"
+ echo
+}
+bench | tee "$RESULT"
+echo "结果已存档: $RESULT"
+```
+
+跑完把 `bench-result-<主机名>-<时间>.txt` 发回来即可。
+
+---
+
+## 2. 它测什么
+
+**CPU 阶段**(默认,约 1–2 分钟)
+- 一次性调用(没启用常驻时的体验)
+- 常驻 daemon:首次请求(含模型加载)/ 热态 ×2 / **换尺寸图**
+- 线程数扫描:`1` / 物理核 / 逻辑核(看多核还能不能再提速)
+- **对照复测**:把 `threads=4` 放在最后再测一次。与首测偏差 ≥25% 就说明本次测量被后台任务污染了,脚本会自动打 ⚠️ 警告。
+
+**Metal 阶段**(`FULL=1`,首次含着色器编译,可能十几分钟)
+- 一次性调用(含编译)
+- 常驻 daemon:首次请求(含编译)/ 热态 ×2 / **换尺寸图**
+
+> ⚠️ 注意:Metal 阶段跑的是 `MTLCreateSystemDefaultDevice()` 返回的**系统默认 GPU**,不一定是独立显卡。
+> 双显卡机器上 macOS 可能返回核显也可能返回独显(本机实测返回独显 Radeon)。
+> 所以脚本里旧称「Metal(独立显卡)」已更正为「Metal(系统默认 GPU)」。
+> 想显式指定,需要打补丁让 MNN 按环境变量选设备并**从源码重编**(见文末附注)。
+
+---
+
+## 3. 怎么判读
+
+1. **「本机 CPU 常驻」就是批量任务的真实速度**(每张图)。
+2. **Metal 值不值得用**,看两点:
+ - 热态是否**明显**快于 CPU(不是 ±10% 这种量级);
+ - **「换尺寸图」是否暴涨**。暴涨 = 每个新输入尺寸都要重编译 Metal 流水线且不缓存 → 批量场景(每份文档尺寸都可能不同)不可用。
+3. Metal 热态 ≈ CPU(±20% 内)→ 别折腾独显,用 CPU。
+4. 脚本末尾会自动换算 **「比 2015 基线快几倍」**。
+
+---
+
+## 4. 已知基线:2015 款 MacBook Air(i5-5250U / Intel HD 6000)
+
+| 场景 | 耗时 | 备注 |
+|------|------|------|
+| CPU 一次性 | ~10.1 s | 每次重新加载模型(比常驻慢约 4 s) |
+| CPU 常驻热态 | **~6.0–6.4 s** | 与图片尺寸无关,稳定 |
+| CPU 常驻 threads=1 | ~8.9 s | 多线程确实有效 |
+| CPU 常驻 threads=2 | ~6.0 s | 与 4 线程基本等同(只有 2 个物理核) |
+| Metal 一次性 | **~390–408 s** | 几乎全是 Metal 着色器运行时编译 |
+| Metal 常驻·热态 | ~8.55 s | 编译一次后只快约 10%(且该值在有负载时测得,偏高) |
+| Metal 常驻·换尺寸 | **~63 s** | 新形状触发流水线重编译,不缓存 |
+
+**结论(2015 机器):核显不可用**——最好情况也就与 CPU 持平甚至更慢,常态慢 6–32 倍。
+「换尺寸暴涨到 63 s」这个致命点与机器负载无关,换成独显也不会消失。
+
+> **本脚本已在这台 2015 Air 上完整跑通验证**(`zsh` 粘贴执行,1 分 42 秒,结果无漂移):
+> 一次性 10.09 s → 4 线程 6.06 s → 1 线程 8.88 s → 2 线程 5.98 s,末尾对照复测 4 线程 6.36 s(漂移 5%,通过)。
+>
+> 有意思的是:再早一次测量得到的是 4 线程 10.48 s、2 线程 5.93 s,**同一配置差了一倍**。
+> 那次恰好和 `cargo build` 同时跑,被抢了 CPU。这正是第 3b 步「对照复测」要抓的东西——
+> **测之前请关掉重活(编译、索引、同步、Chrome),否则数字没意义。**
+
+### 为什么值得在 2019 款 Pro 上重跑
+
+- **CPU 侧大概率是真提升**:i5-5250U 是 2 核 4 线程 15 W 低压(1.6 GHz);i7-9750H 是
+ 6 核 12 线程 45 W(2.6–4.5 GHz),单核约 2 倍、多核约 3–4 倍。
+ **CPU 路径零改动、自带二进制直接跑**,按 6 s 基线预计能到 1.5–2 s/张。
+- **GPU 侧仍待验证**:Intel HD 6000 只有 `Metal GPUFamily macOS 1`(最低档);
+ Radeon Pro 5300M/5500M(RDNA)强得多,但 **MNN 的 Metal 后端是按 Apple Silicon 优化的**,
+ 且「按输入形状重编译、不缓存」这个致命点与 GPU 强弱无关。所以只有实测才知道。
+
+---
+
+## 5. 环境变量(进阶调优)
+
+脚本内部用到,也可以手动调:
+
+| 变量 | 取值 | 默认 |
+|------|------|------|
+| `ROCR_BACKEND` | `cpu` / `metal` / `opencl` / `vulkan` / 空 = Auto | Auto |
+| `ROCR_NUM_THREADS` | 整数,MNN 线程数 | 4 |
+| `ROCR_PRECISION` | `high` / `normal` / `low` / `lowbf16` | high |
+| `ROCR_POWER` | `high` / `normal` / `low` | high |
+
+---
+
+## 6. 附注
+
+- **跑之前把重活关掉**:Chrome / 网盘同步 / 杀毒 / 大文件拷贝都会明显污染计时。
+- 两个二进制都是 **macOS x86_64**。2019 款 Pro 是 Intel,原生可跑;Apple Silicon 上会走
+ Rosetta,性能不代表原生。
+- Metal 阶段慢是**正常的**——不是卡死,是在运行时编译着色器,耐心等。
+- 只想**正式安装** `rocr`(当命令行 OCR 工具用),用 `rocr-macos-x86_64.zip`:
+ 解压后 `bash install.sh`(或双击 `install.command`),之后任意目录直接 `rocr 图片.png`。
+- **Metal 二进制丢了怎么办**:源码在 `rusto-rs/`,执行
+ ```bash
+ cd rusto-rs && cargo build --release --features metal
+ cp target/release/rusto-rs target/release/rusto-rs-metal
+ ```
+ 注意这一步会把 `target/release/rusto-rs` 也覆盖成 Metal 版;
+ 纯 CPU 版请用 `rocr/bin/rusto-rs`,别用 `target/` 里的。
+
+---
+
+## 7. 本机实测结论(2019 MBP / i7-9750H / Radeon Pro 5300M,2026-09-12)
+
+用**用户提供的大图 `12.png`(1721×1245,像素量为样本图 A 的 8.37 倍)**实测,结论:
+
+| 后端 | 12.png 热态(中位) | 800×320 热态 |
+|------|------|------|
+| CPU(6 线程) | 12.46 s | 2.14–2.33 s |
+| CPU(12 线程) | 12.06 s | 2.47–2.74 s |
+| 独显 Radeon 5300M | 12.32 s | 2.07–2.31 s |
+
+**结论:CPU ≈ 独显,独显零收益。**
+
+**硬证据**(`/usr/bin/time -l` 一次性调用,12.png):
+
+| 指标 | CPU-6 | 独显 metal |
+|------|------|------|
+| 用户态 CPU 时间 | 59.62 s | 60.49 s |
+| 执行指令数 | 288.22 G | 287.99 G |
+
+两者**几乎完全相同** → `ROCR_BACKEND=metal` **并未把计算卸载到 GPU**,CPU 承担了同等计算量。
+这是性能持平的根因(不是配置问题,二进制能正确出结果、设备探针也确认默认设备是 Radeon)。
+
+**其他发现**:
+- **无「换尺寸重编译爆炸」**:12.png 与样本图之间反复切换,秒级回落到 2.5 s,未见 2015 基线所述的 63 s 暴涨。
+- **设备默认值**:本机 `MTLCreateSystemDefaultDevice()` 返回 **AMD Radeon Pro 5300M(独显)**,不是核显(探针实测)。
+- **两条弯路(勿重复踩)**:
+ 1. 用 `DYLD_INSERT_LIBRARIES` 劫持 `MTLCreateSystemDefaultDevice` 强制选 GPU —— **在 macOS 26 上对 framework 懒加载符号无效**(libc 的 `getpid` 能拦,Metal 的拦不到)。
+ 2. 打补丁让 MNN 按 `ROCR_METAL_DEVICE` 选设备并**从源码重编** —— cmake 4.x 需加 `CMAKE_POLICY_VERSION_MINIMUM=3.5` 才能 configure,且重编出的 Metal 版在 macOS 26 上**推理时报 `Failed to copy tensor data` / 空返回(不可用)**。建议直接用 GitHub 预编译 `libMNN.a` 重链。
+- **横向对比**:样本图 800×320 下本机 CPU 热态 2.14–2.33 s,比 2015 Air 基线(6.0 s)快 **2.6–2.8 倍**,符合硬件预期。
+
+> 完整数据与图表见同目录 **`OCR性能验证-12png报告.html`**;原始计时存档 **`bench-12png-20260912-1241.txt`**。
+> 早期档案 `bench-result-xsMBP-20260912-1026.txt` 中的「Metal 热态 9.61 s / 换尺寸 59.33 s」与上述干净复测严重不符,**已作废**。
diff --git a/docs/bench/bench-12png-20260912-1241.txt b/docs/bench/bench-12png-20260912-1241.txt
new file mode 100644
index 0000000..c680854
--- /dev/null
+++ b/docs/bench/bench-12png-20260912-1241.txt
@@ -0,0 +1,102 @@
+===============================================================================
+ rocr OCR 性能验证 —— 用户提供图 12.png 实测
+ 时间: 2026-09-12 12:15–12:41 机型: MacBook Pro 2019 / i7-9750H / macOS 26.6.2
+ 测试图: /Users/xs/Desktop/12.png 1721x1245 (2,142,645 px, 为样本图 A 的 8.37 倍)
+ 背景: 已废弃核显方案, 本轮只测 CPU vs 独显(Radeon Pro 5300M)
+===============================================================================
+
+【设备探针】(gpu_probe)
+ 设备: AMD Radeon Pro 5300M lowPower=0 headless=0
+ 设备: Intel(R) UHD Graphics 630 lowPower=1 headless=0
+ 系统默认(MTLCreateSystemDefaultDevice) -> AMD Radeon Pro 5300M (lowPower=0)
+
+-------------------------------------------------------------------------------
+ [A] 三臂交错 (CPU-6 / CPU-12 / 独显 三 daemon 并行, 各预热1次后交替请求)
+ 负载: 起始 10.70 / 结束 10.43
+-------------------------------------------------------------------------------
+轮次 | CPU-6线程 | CPU-12线程 | 独显Radeon
+1 | 13.01 | 12.88 | 12.13
+2 | 11.88 | 12.06 | 11.56
+3 | 12.15 | 11.83 | 12.38
+4 | 11.60 | 11.62 | 12.56
+5 | 11.61 | 11.84 | 11.76
+6 | 12.46 | 11.71 | 11.82
+7 | 15.22 | 15.61 | 15.83
+8 | 12.65 | 12.25 | 12.32
+9 | 12.82 | 12.86 | 12.41
+10 | 12.59 | 12.89 | 12.75
+-------------------------------------------------------------------------------
+CPU-6 : min=11.60 med=12.46 max=15.22
+CPU-12 : min=11.62 med=12.06 max=15.61
+独显 : min=11.56 med=12.32 max=15.83
+-------------------------------------------------------------------------------
+
+-------------------------------------------------------------------------------
+ [B] 单 daemon 串行 (各预热1次 + 热态6次, 同一时刻只有一个 daemon 在跑)
+ 负载: 起始 9.45 (mdworker=0)
+-------------------------------------------------------------------------------
+GPU-Radeon : 13.90 13.83 14.74 13.86 15.71 14.32 -> min=13.83 med=13.90 max=15.71
+CPU-6 : 15.41 15.83 15.33 14.72 13.77 13.25 -> min=13.25 med=14.72 max=15.83
+CPU-12 : 15.05 16.18 13.70 11.99 12.35 12.91 -> min=11.99 med=12.91 max=16.18
+-------------------------------------------------------------------------------
+输出一致性 (三组 OCR 文本 sha256 前16位):
+ GPU : 98831d2e3f06c681
+ CPU6: 98831d2e3f06c681
+ CPU12: 98831d2e3f06c681 <- 三者完全相同, 结果一致且非空跑
+-------------------------------------------------------------------------------
+
+-------------------------------------------------------------------------------
+ [C] 决定性证据: 一次性调用的 CPU 时间 / 指令数 (/usr/bin/time -l)
+ (若独显真在算, user 时间与指令数应远低于纯 CPU 路径)
+-------------------------------------------------------------------------------
+CPU-6 (ROCR_BACKEND=cpu, threads=6):
+ 12.13 real 59.62 user 3.39 sys
+ 2,226,331,648 maximum resident set size
+ 288,219,953,545 instructions retired
+
+独显 (ROCR_BACKEND=metal, threads=6):
+ 12.57 real 60.49 user 3.50 sys
+ 2,258,702,336 maximum resident set size
+ 287,993,541,359 instructions retired
+-------------------------------------------------------------------------------
+判读: user 时间 60.49 vs 59.62 (GPU 反而高 1.5%)
+ 指令数 287.99G vs 288.22G (差 0.08%)
+ => Metal 后端并未把计算卸载到 GPU, CPU 承担了完全相同的计算量。
+ => 这就是两者性能持平的根因。
+
+-------------------------------------------------------------------------------
+ [D] 尺寸切换 (单 GPU daemon 内混跑两种尺寸, 负载≈5)
+-------------------------------------------------------------------------------
+ 预热 小图800x320 2.91 s
+ 小图800x320 #1 2.75 s
+ 切大图1721x1245(首次新尺寸) 17.23 s
+ 大图1721x1245 #2 14.62 s
+ 切回小图800x320 2.54 s
+ 再切大图1721x1245 15.70 s
+-------------------------------------------------------------------------------
+判读: 无"换尺寸重编译爆炸"。耗时差异纯粹来自像素量(8.37倍)。
+ (对比: 样本图 A 800x320 与 B 1000x400 之间切换同样无爆炸)
+
+-------------------------------------------------------------------------------
+ [E] 12.png OCR 输出片段 (GPU 路径, 与 CPU 路径 sha256 相同)
+-------------------------------------------------------------------------------
+Q @"OCR性能验证说明.md"你在本机metal打包验证一下,用独显/不用独显性能 Q. ① □
+WorkBuddy 发现应用
+5.5.6 换尺寸图 59.33s 0.61s
+新建任务
+这只能说明一件事:之前那次「默认 Metal」其实跑在核显(Intel)上(系统自动切卡,默认设备会变),而 Radeon 独显是 0.61s,两者差 15 倍,且...
+(共 1422 字符, 识别正确)
+
+===============================================================================
+ 结论
+===============================================================================
+1. 12.png(1721x1245 大图)上: CPU-6 ≈ CPU-12 ≈ 独显 ≈ 12–15 s/张, 三者无显著差异。
+ 独显不提供任何加速。
+2. 根因(硬证据): metal 路径的 user CPU 时间与指令数同纯 CPU 路径完全一致,
+ 说明该构建下 MNN 的 Metal 后端未真正把负载交给 GPU。
+3. 尺寸切换无流水线重编译爆炸(推翻了 2015 基线「换尺寸暴涨 63s」在本机的复现)。
+4. 建议: 用 CPU 即可, threads=6~12 差异不显著(12 线程中位略优)。
+5. 历史档案 bench-result-xsMBP-20260912-1026.txt 中
+ "Metal 热态 9.61s / 换尺寸 59.33s" 与本轮干净复测(800x320 下 2.07–2.31s、
+ 2.46s)严重不符, 判定为当时的二进制版本差异或环境干扰, 该段数据存疑, 不应采信。
+===============================================================================
diff --git a/docs/bench/bench-radeon-clean-20260912-1200.txt b/docs/bench/bench-radeon-clean-20260912-1200.txt
new file mode 100644
index 0000000..530c0da
--- /dev/null
+++ b/docs/bench/bench-radeon-clean-20260912-1200.txt
@@ -0,0 +1,23 @@
+############################################################
+ 独显(Radeon Pro 5300M) Metal —— 干净基准 Sat Sep 12 12:00:15 CST 2026
+ 二进制: 预编译 libMNN.a 重链 (Metal 正常, 非源码重编坏版)
+ 机型: MacBook Pro 2019 / i7-9750H / macOS 26.6.2
+############################################################
+--- 设备确认 (系统默认) ---
+2026-09-12 12:00:16.058 gpu_probe[27690:1948280] ROCR_METAL_DEVICE=(未设置=系统默认) -> 选中: AMD Radeon Pro 5300M (lowPower=0)
+--- 启动 Metal daemon (系统默认=Radeon) ---
+daemon ready after 0s
+--- 冷启动 (首请求含着色器编译) ---
+ 冷启动: 2.50 s
+--- 热态 (A图 800x320, 连续 6 次) ---
+ 热态 #1 2.25 s
+ 热态 #2 2.07 s
+ 热态 #3 2.14 s
+ 热态 #4 2.08 s
+ 热态 #5 2.12 s
+ 热态 #6 2.31 s
+--- 换尺寸图 (B图 1000x400) ---
+ 换尺寸图: 2.46 s
+--- 回 A 图 (确认无重编译爆炸) ---
+ 回A图: 2.32 s
+--- 完成 ---
diff --git a/docs/bench/bench-run.sh b/docs/bench/bench-run.sh
new file mode 100644
index 0000000..b0c8278
--- /dev/null
+++ b/docs/bench/bench-run.sh
@@ -0,0 +1,219 @@
+#!/usr/bin/env bash
+# 改编自 OCR性能验证说明.md 的基准脚本
+# 适配点:
+# 1) FULL 从环境变量读取 (FULL=0 仅CPU; FULL=1 含 Metal)
+# 2) 透传 ROCR_METAL_DEVICE 让 patched 的 MNN 选择 GPU
+# (discrete=独显 Radeon 5300M / integrated=核显 Intel UHD630 / 不设=系统默认=核显)
+set -u
+FULL="${FULL:-0}"
+RESULT="$PWD/bench-result-$(hostname -s)-$(date +%Y%m%d-%H%M).txt"
+
+bench() {
+ local ROOT="$PWD"
+ local CPU="$ROOT/rocr/bin/rusto-rs"
+ local MODEL="$ROOT/rocr/models/PPOCRv6-Medium"
+ local METAL="$ROOT/rusto-rs/target/release/rusto-rs-metal"
+ local IMG_A="$ROOT/samples/lt-a-800x320.png"
+ local IMG_B="$ROOT/samples/lt-b-1000x400.png"
+ local SOCK_BASE="/tmp/rocr-bench-$$"
+ local BASE_CPU_WARM=6.00 # 2015 Air 静置实测基线,用于换算"快了几倍"
+ local PHY LOG DAEMON_PID LAST
+
+ [ -x "$CPU" ] || { echo "✗ 找不到 $CPU"; echo " 请先 cd 到工作空间根目录(含 rocr/ rusto-rs/ samples/ 的那层)再贴这段"; return 1; }
+ [ -f "$MODEL/det.mnn" ] || { echo "✗ 找不到模型 $MODEL"; return 1; }
+ [ -f "$IMG_A" ] || { echo "✗ 找不到样本图 $IMG_A"; return 1; }
+
+ if xattr -p com.apple.quarantine "$CPU" >/dev/null 2>&1; then
+ echo "· 检测到 quarantine 属性,正在解除…"; xattr -dr com.apple.quarantine "$ROOT" >/dev/null 2>&1
+ fi
+ chmod +x "$CPU" "$METAL" 2>/dev/null
+
+ _now() { perl -MTime::HiRes=time -e 'printf "%.2f", time'; }
+ _dt() { awk -v a="$1" -v b="$2" 'BEGIN{printf "%.2f", b-a}'; }
+ _line() { printf '%s\n' "-------------------------------------------------------------------------------"; }
+ _head() { echo; _line; printf ' %s\n' "$1"; _line; }
+ row() { printf ' %-30s %10s s\n' "$1" "$2"; }
+
+ # 往 daemon 发一次请求(协议:第一行格式,第二行图片路径)
+ sock_req() {
+ perl -e '
+ use strict; use warnings; use IO::Socket::UNIX;
+ my ($sock,$img,$fmt)=@ARGV;
+ my $s=IO::Socket::UNIX->new(Peer=>$sock) or die "connect failed: $!\n";
+ $s->autoflush(1); print $s "$fmt\n$img\n";
+ my $out=do{ local $/; <$s> }; print defined $out ? $out : ""; close $s;
+ ' "$1" "$2" "${3:-text}"
+ }
+
+ stop_daemon() { [ -n "${DAEMON_PID:-}" ] && kill "$DAEMON_PID" 2>/dev/null; DAEMON_PID=""; sleep 1; }
+
+ start_daemon() { # $1=bin $2=backend $3=threads $4=sock
+ local bin="$1" be="$2" th="$3" sock="$4" n=0
+ stop_daemon
+ rm -f "$sock" "$sock.log"
+ ROCR_BACKEND="$be" ROCR_NUM_THREADS="$th" ROCR_METAL_DEVICE="${ROCR_METAL_DEVICE:-}" "$bin" --serve --socket "$sock" --idle 3600 \
+ --det-model "$MODEL/det.mnn" --rec-model "$MODEL/rec.mnn" --dict "$MODEL/dict.txt" >"$sock.log" 2>&1 &
+ DAEMON_PID=$!
+ while [ "$n" -lt 900 ]; do
+ grep -qi ready "$sock.log" 2>/dev/null && return 0
+ kill -0 "$DAEMON_PID" 2>/dev/null || { echo " ✗ daemon 启动失败:"; sed 's/^/ /' "$sock.log"; return 1; }
+ sleep 1; n=$((n+1))
+ done
+ echo " ✗ daemon 启动超时"; return 1
+ }
+
+ cleanup() { stop_daemon; rm -f /tmp/rocr-bench-*.sock /tmp/rocr-bench-*.sock.log 2>/dev/null; }
+ trap cleanup EXIT INT TERM
+
+ timed_req() { # $1=sock $2=img $3=标签
+ local t0 t1; t0=$(_now); sock_req "$1" "$2" text >/dev/null 2>&1; t1=$(_now)
+ LAST="$(_dt "$t0" "$t1")"; row "$3" "$LAST"
+ }
+ timed_oneshot() { # $1=bin $2=backend $3=threads $4=img $5=标签
+ local t0 t1; t0=$(_now)
+ ROCR_BACKEND="$2" ROCR_NUM_THREADS="$3" ROCR_METAL_DEVICE="${ROCR_METAL_DEVICE:-}" "$1" \
+ --det-model "$MODEL/det.mnn" --rec-model "$MODEL/rec.mnn" --dict "$MODEL/dict.txt" \
+ "$4" --format text >/dev/null 2>&1
+ t1=$(_now); LAST="$(_dt "$t0" "$t1")"; row "$5" "$LAST"
+ }
+
+ # ---------------- 硬件信息 ----------------
+ echo "==============================================================================="
+ echo " rocr OCR 性能验证 —— $(date '+%Y-%m-%d %H:%M:%S')"
+ echo "==============================================================================="
+ echo " CPU : $(sysctl -n machdep.cpu.brand_string 2>/dev/null || echo '?')"
+ echo " 核心 : $(sysctl -n hw.physicalcpu) 物理 / $(sysctl -n hw.logicalcpu) 逻辑"
+ echo " 内存 : $(sysctl -n hw.memsize | awk '{printf "%.0f GB", $1/1073741824}')"
+ echo " 系统 : macOS $(sw_vers -productVersion 2>/dev/null) ($(uname -m))"
+ echo " 模式 : $( [ "$FULL" = "1" ] && echo '完整(CPU+Metal)' || echo '快速(仅CPU)' )"
+ echo " MetalGPU: ${ROCR_METAL_DEVICE:-<系统默认=核显>}"
+ echo " GPU :"
+ system_profiler SPDisplaysDataType 2>/dev/null \
+ | grep -E "^\s+(Chipset Model|Vendor|Metal)" | sed 's/^[[:space:]]*/ /' \
+ || echo " (读取失败)"
+ echo " 模型 : $MODEL"
+ echo
+
+ PHY="$(sysctl -n hw.physicalcpu 2>/dev/null || echo 4)"
+ LOG="$(sysctl -n hw.logicalcpu 2>/dev/null || echo 4)"
+
+ # ---------------- 1. CPU 一次性 ----------------
+ _head "1) CPU —— 一次性调用(未启用常驻)"
+ timed_oneshot "$CPU" cpu 4 "$IMG_A" "一次性 (默认4线程)"
+ CPU_ONESHOT="$LAST"
+
+ # ---------------- 2. CPU 常驻 ----------------
+ _head "2) CPU —— 常驻 daemon(threads=4,默认档)"
+ CPU_COLD=""; CPU_WARM=""; CPU_SHAPE=""
+ sock="$SOCK_BASE-cpu4.sock"
+ if start_daemon "$CPU" cpu 4 "$sock"; then
+ t0=$(_now); sock_req "$sock" "$IMG_A" text >/dev/null 2>&1; CPU_COLD="$(_dt "$t0" "$(_now)")"
+ row "首次请求(含模型加载)" "$CPU_COLD"
+ timed_req "$sock" "$IMG_A" "热态 #1"; CPU_WARM="$LAST"
+ timed_req "$sock" "$IMG_A" "热态 #2"
+ timed_req "$sock" "$IMG_B" "热态(换尺寸图)"; CPU_SHAPE="$LAST"
+ else
+ echo " (跳过)"
+ fi
+ stop_daemon
+
+ # ---------------- 3. 线程数扫描 ----------------
+ _head "3) CPU —— 线程数扫描(常驻热态,看多核能否再提速)"
+ CPU_WARM_PHY=""; CPU_WARM_LOG=""; CPU_WARM_T1=""
+ DONE=" 4 "
+ for t in 1 "$PHY" "$LOG"; do
+ case "$DONE" in *" $t "*) continue ;; esac
+ DONE="$DONE$t "
+ sock="$SOCK_BASE-cput$t.sock"
+ if start_daemon "$CPU" cpu "$t" "$sock"; then
+ timed_req "$sock" "$IMG_A" "threads=$t 热态 #1"
+ timed_req "$sock" "$IMG_A" "threads=$t 热态 #2"
+ case "$t" in
+ 1) CPU_WARM_T1="$LAST" ;;
+ "$PHY") CPU_WARM_PHY="$LAST" ;;
+ "$LOG") CPU_WARM_LOG="$LAST" ;;
+ esac
+ else
+ echo " (threads=$t 跳过)"
+ fi
+ stop_daemon
+ done
+
+ # ---------------- 3b. 对照复测(抓"越跑越快"的漂移)----------------
+ CPU_WARM_CTRL=""
+ sock="$SOCK_BASE-cpuctrl.sock"
+ if start_daemon "$CPU" cpu 4 "$sock"; then
+ timed_req "$sock" "$IMG_A" "对照复测 threads=4"
+ CPU_WARM_CTRL="$LAST"
+ fi
+ stop_daemon
+
+ # ---------------- 4/5. Metal ----------------
+ METAL_ONESHOT=""; METAL_COLD=""; METAL_WARM=""; METAL_SHAPE=""
+ if [ "$FULL" = "1" ]; then
+ if [ -x "$METAL" ]; then
+ _head "4) Metal(${ROCR_METAL_DEVICE:-系统默认=核显})—— 一次性调用"
+ echo " ⏳ 首次要做 Metal 着色器运行时编译,可能非常慢(2015 核显实测约 390 s),耐心等…"
+ timed_oneshot "$METAL" metal "$PHY" "$IMG_A" "一次性 (含编译)"
+ METAL_ONESHOT="$LAST"
+
+ _head "5) Metal(${ROCR_METAL_DEVICE:-系统默认=核显})—— 常驻 daemon(编译一次,后续热态)"
+ sock="$SOCK_BASE-metal.sock"
+ if start_daemon "$METAL" metal "$PHY" "$sock"; then
+ echo " ⏳ 首次请求含着色器编译,可能很慢…"
+ t0=$(_now); sock_req "$sock" "$IMG_A" text >/dev/null 2>&1
+ METAL_COLD="$(_dt "$t0" "$(_now)")"; row "首次请求(含着色器编译)" "$METAL_COLD"
+ timed_req "$sock" "$IMG_A" "热态 #1"; METAL_WARM="$LAST"
+ timed_req "$sock" "$IMG_A" "热态 #2"
+ timed_req "$sock" "$IMG_B" "热态(换尺寸图)"; METAL_SHAPE="$LAST"
+ else
+ echo " (跳过: Metal daemon 未启动)"
+ fi
+ stop_daemon
+ else
+ echo; echo "⚠️ 未找到 Metal 版二进制 $METAL,跳过独显阶段。"
+ echo " (重建见文末「Metal 二进制丢了怎么办」)"
+ fi
+ fi
+
+ # ---------------- 汇总 ----------------
+ _head "汇总对比"
+ printf ' %-30s %10s s %s\n' "项目" "耗时" "vs 2015 i5-5250U"
+ printf ' %-30s %10s\n' "2015 基线 CPU 常驻(静置)" "$BASE_CPU_WARM"
+ [ -n "$CPU_WARM" ] && printf ' %-30s %10s s 快 %.1f 倍\n' "本机 CPU 常驻 (threads=4)" "$CPU_WARM" \
+ "$(awk -v a="$BASE_CPU_WARM" -v b="$CPU_WARM" 'BEGIN{printf "%.2f", a/b}')"
+ [ -n "$CPU_WARM_PHY" ] && printf ' %-30s %10s s\n' "本机 CPU 常驻 (threads=$PHY)" "$CPU_WARM_PHY"
+ [ -n "$CPU_WARM_LOG" ] && printf ' %-30s %10s s\n' "本机 CPU 常驻 (threads=$LOG)" "$CPU_WARM_LOG"
+ [ -n "$CPU_WARM_T1" ] && printf ' %-30s %10s s\n' "本机 CPU 常驻 (threads=1)" "$CPU_WARM_T1"
+ [ -n "$CPU_ONESHOT" ] && printf ' %-30s %10s s\n' "本机 CPU 一次性" "$CPU_ONESHOT"
+ [ -n "$CPU_WARM_CTRL" ] && printf ' %-30s %10s s 对照\n' "本机 CPU 复测 (threads=4)" "$CPU_WARM_CTRL"
+ if [ -n "$METAL_WARM" ]; then
+ printf ' %-30s %10s s\n' "本机 Metal(${ROCR_METAL_DEVICE:-默认}) 常驻 热态" "$METAL_WARM"
+ printf ' %-30s %10s s\n' "本机 Metal(${ROCR_METAL_DEVICE:-默认}) 冷启动(含编译)" "$METAL_COLD"
+ printf ' %-30s %10s s\n' "本机 Metal(${ROCR_METAL_DEVICE:-默认}) 换尺寸图" "$METAL_SHAPE"
+ fi
+ _line
+
+ # 漂移检测
+ if [ -n "$CPU_WARM" ] && [ -n "$CPU_WARM_CTRL" ]; then
+ DRIFT="$(awk -v a="$CPU_WARM" -v b="$CPU_WARM_CTRL" 'BEGIN{
+ if (a<=0) { print "0"; exit } d=(b-a)/a; if (d<0) d=-d; printf "%.0f", d*100 }')"
+ if [ "$DRIFT" -ge 25 ]; then
+ echo
+ echo " ⚠️ 结果漂移较大:threads=4 首测 $CPU_WARM s,末尾复测 $CPU_WARM_CTRL s(相差 ${DRIFT}%)。"
+ echo " 多半是测量期间机器在后台干活(Spotlight 索引、iCloud/网盘同步、杀毒、Chrome)。"
+ echo " 建议关掉它们再跑一遍取稳定值。"
+ fi
+ fi
+
+ echo
+ echo " 判读要点:"
+ echo " · 看「本机 CPU 常驻」,这就是批量任务的真实速度(每张)。"
+ echo " · Metal 值不值得用,看两点:热态是否明显快于 CPU;"
+ echo " 以及「换尺寸图」是否暴涨(暴涨=每个新尺寸都要重编译流水线,批量场景不可用)。"
+ echo " · 若 Metal 热态 ≈ CPU(±20% 内)→ 别折腾独显,用 CPU。"
+ [ "$FULL" != "1" ] && echo " · 想连独显一起验,把本段开头的 FULL=0 改成 FULL=1 再跑一次。"
+ echo
+}
+bench | tee "$RESULT"
+echo "结果已存档: $RESULT"
diff --git a/docs/int8-quantize-attempt-20260912.md b/docs/int8-quantize-attempt-20260912.md
new file mode 100644
index 0000000..bb4f920
--- /dev/null
+++ b/docs/int8-quantize-attempt-20260912.md
@@ -0,0 +1,116 @@
+# INT8 量化尝试(2026-09-12)- 失败回滚
+
+**任务**:苏苏「去更新本机的 rocr,用 ax2 方案(AVX2 + INT8 量化)」
+
+**结论一句话**:**本机 INT8 量化精度崩了**(det 模型量化后检测 0 个文字框),回滚到 FP32。这是硬件 + 模型 + 工具链三重限制的结果。
+
+---
+
+## 一、本机硬件能力(决定 INT8 上限)
+
+| 项目 | 状态 |
+|---|---|
+| CPU | i7-9750H(Coffee Lake 2019 上半年) |
+| AVX2 / FMA / ADX / BMI1/2 | ✅ 全在 |
+| VNNI(INT8 专用硬件指令) | ❌ **没有** |
+| AVX-512 | ❌ **没有** |
+
+**关键限制**:VNNI 是 Cascade Lake(2019 下半年服务器)/ Ice Lake(10 代笔记本)才有的。**本机没有 INT8 硬件加速**,只能走 AVX2 通用整数指令(vpmaddubsw + vpmaddwd),AVX2 上 INT8 收益有限。
+
+---
+
+## 二、实际执行步骤
+
+### 1. 备份已装 FP32 模型 ✅
+- 路径:`/Users/xs/Desktop/know/ro/rocr/models/PPOCRv6-Medium/`
+- 备份:`/tmp/rocr-fp32-backup-20260912-1444/`
+- 备份前/后 md5 校验:`det.mnn=b96dabccd7bdc1a905a155548049ff85`,`rec.mnn=3d79ab0053cfe14f3e9ecb2cd9bcd24b`
+
+### 2. 工具链折腾 ✅
+
+| 步骤 | 结果 |
+|---|---|
+| `pip install MNN` 装到本机 Python 3.13 | ❌ wheel 只有 macOS 14+ ARM64,本机 x86 + macOS 26 符号不匹配 |
+| `pip install MNN --target --platform macosx_11_0_x86_64` | ⚠️ 装上 x86 wheel,但 `_mnncengine.so` 缺 `__ZN3MNN10getVersionEv` 等所有主运行时符号,wheel 本身不完整 |
+| `brew install python@3.10` | ✅ 26 分钟装好 |
+| 用 Python 3.10 + x86 wheel 装 MNN | ❌ 同样符号缺失(wheel 本身问题,与 Python 版本无关) |
+| `brew install cmake` | ✅(之前已装 cmake 4.4.3) |
+| 从源码编译 MNN 完整工程 | ⚠️ 10 分钟 / 30% + MNN 缺 `