meida_backend/scripts/spikes/REPORT.md

# T9 · 视觉算法 SPIKE 报告（RTMPose 体型原型 + BiRefNet 抠图）

> 分支 `task/t9-vision-spike` ｜ 2026-08-14 ｜ 对应任务 T-P0-16 / T-P0-12 / TD-06 前置
> 测试机：Intel Core Ultra 7 265K（WSL 分配 16 vCPU、54GB 内存），onnxruntime 1.28.0（CPU 版）、opencv-python-headless 5.0.0、numpy 2.5.2
> 所有输入均为 OpenCV 合成人形图（`synthetic.py` 确定性生成），**未使用任何真实人脸/人体数据**（合规红线）。

---

## 一、三问三答（结论先行）

### Q1 RTMPose ONNX 在 CPU 上的单张推理耗时是多少？（T-P0-16）

**结论：通过。** RTMPose-s 单张纯推理 **2.2ms（P95 2.6ms / 最大 2.7ms）**，含预处理与解码的全链路 **2.8ms（P95 3.3ms / 最大 3.5ms）**；RTMPose-m 全链路 5.9ms。CPU 单张耗时对服务端批量/异步处理完全无压力，T-P0-16 验收口径（可接受即通过）满足。GPU 档未测：开发机有 RTX 5090（nvidia-smi 可见），但 venv 装的是 CPU 版 onnxruntime（无 CUDAExecutionProvider），按任务文档约定不装 GPU 版、只报 CPU 档。

### Q2 BiRefNet ONNX 抠图的质量与成本如何？（T-P0-12 初步）

**结论：有条件通过。** 管线成立：BiRefNet_lite fp32 在合成图上前景占比 24.4%（区间 15%~60% 内）、最大连通域占前景 1.0（单一主体）、边缘羽化带约 1px、纯色与渐变背景结果一致。**条件/风险有二**：① 单张全链路 **约 3.1s（CPU，1024×1024 输入）**，同步接口不可接受，必须走异步任务或降档（见 §四）；② 本 SPIKE 的指标是**代理口径**（合成图 + 几何指标），T-P0-12 的「质检通过率 ≥90%」必须用真实素材 + 人工标注验证，合成图结果不能外推到正式验收。

### Q3 「关键点定高 + 掩膜宽度剖面」体型测算原型是否成立？（TD-06 前置）

**结论：通过（原型口径）。** 管线端到端跑通：定高 → 掩膜剖面取宽 → 肩/腰/臀比值 → 规则初判。**真值定高路径 6/6 变体（H/A/V/O/X 全类别 + 中性 STD）分类硬断言全部通过**；掩膜测宽与几何真值偏差仅 ±1px（一个变体腰线 +3px）；关键点（RTMPose）定高路径参考一致率 6/6。两点保留：① COCO-17 无腰点，腰线取肩臀中点是代理，对真实人体（腰臀比例分布）是否成立待验证；② RTMPose 在合成剪影上置信度极低（见 §三），KP 路径在真实照片上的可用性未验证；≥80% 一致率的正式验证需要顾问轨人工标注（本任务不承诺）。

---

## 二、基准数字表

### 2.1 RTMPose CPU 单张耗时（预热 3 + 正式 20，`time.perf_counter`）

| 模型 | 链路 | 均值 | P95 | 单次最大 |
| --- | --- | ---: | ---: | ---: |
| rtmpose-s（20.9MB，输入 256×192） | 纯模型 `session.run` | 2.2ms | 2.6ms | 2.7ms |
| rtmpose-s | 全链路（resize+归一化+推理+SimCC 解码） | 2.8ms | 3.3ms | 3.5ms |
| rtmpose-m（51.8MB，输入 256×192） | 纯模型 | 5.2ms | 5.7ms | 5.8ms |
| rtmpose-m | 全链路 | 5.9ms | 6.2ms | 6.5ms |

- 预处理+解码开销约 0.6~0.7ms（全链路 − 纯模型），与模型规模无关。
- 耗时口径说明：RTMPose 是 top-down 模型，本基准以「合成图已知完美人体框、整图缩放」为输入，即纯姿态网络耗时；生产链路还需前置一个人体检测器（见 §四建议）。

### 2.2 BiRefNet_lite 抠图代理质检指标（预热 3 + 正式 10，单张 >3s 自适应降档并注明）

| 输入 | 前景占比 | 最大连通域/前景 | 连通域数 | 边缘羽化带 | 均值耗时 | P95 | 最大 |
| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
| 纯色背景 | 0.2444 | 1.0000 | 1 | 0.97px | 3097ms | 3128ms | 3131ms |
| 渐变背景 | 0.2443 | 1.0000 | 1 | 1.02px | 3097ms | 3131ms | 3139ms |

- 前景占比处于 15%~60% 合理区间，主体单一完整（>0.9 阈值达成，实际 1.0）。
- 羽化带 ≈1px：对高对比合成图边缘干净利落，真实照片（毛发/半透明）会显著变宽，该值应作为正式质检的分档特征而非固定阈值。
- 两背景变体指标几乎一致 → 对背景明暗变化不敏感（该结论仅限合成域）。

### 2.3 体型测算原型（合成图，掩膜 = BiRefNet_lite）

| 变体 | 期望 | 真值定高（硬断言） | 关键点定高（参考） | 掩膜测宽 肩/腰/臀(px) | 保真度偏差(px) |
| --- | --- | --- | --- | --- | --- |
| STD（中性） | H | **H ✓** | H ✓ | 131/111/131 | +1/+1/+1 |
| H | H | **H ✓** | H ✓ | 127/121/125 | +1/+1/+1 |
| A | A | **A ✓** | A ✓ | 99/103/147 | +1/+1/+1 |
| V | V | **V ✓** | V ✓ | 155/107/119 | +1/+1/+1 |
| X | X | **X ✓** | X ✓ | 131/81/135 | +1/+3/+1 |
| O | O | **O ✓** | O ✓ | 115/143/123 | +1/+1/+1 |

- 真值定高 **6/6 断言通过**；关键点定高一致率 **6/6（100%）**（参考值，样本为合成图）。
- 阈值（首版经验值，**待顾问校准**）：肩/臀 >1.05 → V；<0.95 → A；腰 <0.80×min(肩,臀) → X；腰 >1.02×max(肩,臀) → O；否则 H。判定顺序 O → X → V → A → H。

---

## 三、RTMPose 在合成剪影上的关键点质量（重要发现）

RTMPose 关键点在合成剪影上**定位偏差可用但置信度极低**：rtmpose-s 肩线偏差 +12px、臀线偏差 −28.5px（画布高 512px），但平均置信度仅 0.003（SimCC 分布近乎平坦）。已排除预处理口径因素（RGB/BGR、0-255/0-1 归一化四种组合结果几乎一致），结论是**域差异**：模型在真实人像上训练，对无纹理几何剪影没有信心。对本 SPIKE 的处理：

- 断言路径用「真值定高」（任务文档明确允许：*"用 3.2 的关键点（或合成图直接已知的真值框）定肩线/腰线/臀线高度"*），KP 路径仅统计参考一致率；
- 对 Sprint 1 的含义：**RTMPose 的关键点质量必须在真实照片上重新验证**，合成图不能作为其可用性依据；体型管线的关键点依赖是当前最大不确定性。

---

## 四、对 Sprint 1 正式验证的建议

1. **T-P0-16（RTMPose 耗时）**：CPU 数字已可决策（s 档 3ms 级全链路）。还需要补两件事：① 生产链路要前置**人体检测器**（RTMPose 是 top-down），建议补测 YOLOv8n-ONNX 或 RTMO 一体化模型的 CPU 耗时；② 若上传链路要同步姿态，当前 CPU 数字已够；无需 GPU。
2. **T-P0-12（抠图质检 ≥90%）**：需要 **200~500 张真实全身照**（覆盖多背景/光线/姿态），人工标注粗前景 GT，指标建议 IoU ≥0.90 或边界 F-measure，先定义「单张通过」标准再统计通过率。成本决策点：若 CPU 3.1s/张不可接受，候选降档（按优先级）——任务异步化（现有 task 架构，零成本）→ BiRefNet fp16 / 512×512 变体（候选已在 download_models.py 链里）→ GPU EP。
3. **TD-06（体型测算 ≥80% 一致率）**：需要顾问轨 **≥100 人体型标注**（H/A/V/O/X 五类尽量均衡）+ 每人至少一张标准站姿全身照；阈值校准建议用分位数/ROC 而非拍脑袋值；**前置依赖**是 RTMPose 在真实照片上的关键点质量验证（§三）。腰线代理（肩臀中点）需在标注数据上复核落点。
4. **数据合规**：真实人体照片进入验证集前需走用户授权/合成替代评估；本 SPIKE 已验证「合成图 + 真值」开发范式可行，阈值调参阶段可继续用合成图，终验必须真实分布。

---

## 五、使用的模型与版本（models/manifest.json）

| 用途 | 模型 | 仓库 @ revision | 变体 | 大小 |
| --- | --- | --- | --- | ---: |
| 姿态（基准主档） | rtmpose-s.onnx | `bukuroo/RTMPose-ONNX` @ `a6e9fb8a` | RTMPose-s body COCO-17 SimCC，输入 256×192 | 20.9MB |
| 姿态（对比档） | rtmpose-m.onnx | `bukuroo/RTMPose-ONNX` @ `a6e9fb8a` | RTMPose-m 同上 | 51.8MB |
| 抠图 | birefnet_lite.onnx | `onnx-community/BiRefNet_lite-ONNX` @ `de15b22b` | fp32，输入 1024×1024，ImageNet 归一化 | 213.6MB |

下载通道：`https://hf-mirror.com`（国内镜像优先，实测 4~12MB/s，总 ~290MB，未触发 10 分钟超时纪律）。

## 六、降级路径与偏差说明

- **实现并验证的降级链**（本次全部未触发，代码路径已在脚本中就位）：姿态 `bukuroo rtmpose-s` → （失败）`cv2.HOG` 关键点占位；抠图 `BiRefNet_lite fp32` → `fp16` → `briaai/RMBG-1.4` → （仍失败）Otsu 二值化占位。脚本对每级失败均打印 `[降级]` 日志并在输出 JSON 记 `model_source`。
- **偏差 1（依赖）**：任务文档建议用 `huggingface_hub.snapshot_download`，但该包不在 spike extra 且本批禁止新增依赖（协作规程 §4.2），改用 stdlib `urllib` 直连 `{endpoint}/{repo}/resolve/main/{file}`（同一 HTTP 语义，支持 30x 与 Range 断点续传）。已在脚本 docstring 声明。
- **偏差 2（模型选型）**：文档首选 `PINTO0309/PINTO_model_zoo` 的 rtmpose，但该仓库为巨型混合仓库（API 兄弟列表无法按"body 17/26 keypoint 小模型"脚本化定位）；`dhkim0115/rtmpose-onnx` 经 API 探查不存在；最终选社区导出 `bukuroo/RTMPose-ONNX`（17 点 COCO、SimCC、256×192，符合文档"body 小模型"要求）。BiRefNet 官方仓 `ZhengPeng7/BiRefNet` 只有 safetensors 无 ONNX，采用 `onnx-community` 的 ONNX 导出（文档列举的备选之一）。
- **偏差 3（GPU 档）**：nvidia-smi 可见 RTX 5090，但 venv 的 onnxruntime 为 CPU 构建（providers 无 CUDA），按任务文档「不装 GPU 版 ORT、探测失败不折腾」只报 CPU 档。
- **口径调整**：BiRefNet 单张 >3s，正式次数由 20 自适应降为 10（脚本内 `adaptive_note` 字段注明）；RTMPose 基准严格按预热 3 + 正式 20。

## 七、复现方式（worktree 根目录）

```bash
.venv/bin/python scripts/spikes/download_models.py      # 联网下载（已缓存则秒过，唯一联网环节）
.venv/bin/python scripts/spikes/rtmpose_benchmark.py    # Q1：耗时基准 + 关键点
.venv/bin/python scripts/spikes/birefnet_matting.py     # Q2：代理质检指标
.venv/bin/python scripts/spikes/body_measure_prototype.py  # Q3：体型分类硬断言
```

输出：数字与 JSON 落在 `scripts/spikes/out/`（已 gitignore），掩膜/抠图预览同目录可人工核验。