# 发言人端上化可行性验证报告（0.11.18 前置 spike）

- 日期：2026-10-09
- 触发：主人「发言人这一部分，我记得可以是部署到手机上的…如果可以部署到手机上的话，就部署到手机上吧」
- 工作区：`/vol1/ai/projects/voice-memory-card-dsh`
- **结论：技术上完全可行，且比预期容易。但发现一条需求文档冲突，需主人拍板后才能动手。**

---

## 阶段

Phase 10 返工前置验证（spike，**未改任何生产代码**）。

## 目标

回答一个问题：**发言人分离能不能放到手机端跑？** 并把技术风险在写代码之前验掉。

## 输入

- 真实 8.5 分钟双人对话录音（`ac12bde9-df5b-44bd-a889-63932cac3542`，531 秒 / 17 MB / 16 kHz 单声道 PCM）
- 该录音在旧 GPU 流水线上留下的发言人标签，作为**标准答案**（321 句去重后，78 句有标签且 ≥ 500ms：`018707d7` 54 句、`c53d0d4e` 24 句）
- 生产 APK `voice-memory-card-0.11.17-phase11.apk`

---

## 一、三个决定性的发现

### 发现 1：APK 里**已经**有 ONNX Runtime，且 Java API 已打进 dex

```
lib/arm64-v8a/libonnxruntime.so      17,571,160 字节
lib/arm64-v8a/libonnxruntime4j_jni.so   915,968 字节
assets/silero_vad.onnx                1,807,522 字节
```

Gradle 缓存里 `com.microsoft.onnxruntime:onnxruntime-android:1.20.0.aar` **已经是解析出来的依赖**
（Cloudflare 的 `android-vad:silero` 库带进来的）。APK 的 dex 里能直接搜到：

```
ai/onnxruntime/OrtEnvironment   OrtSession   OnnxTensor   OnnxValue   OnnxJavaType
```

**含义：跑我们自己的 ONNX 模型，不需要任何新的原生依赖，不增加一个字节的原生库体积。**
模型资产也可以照 `assets/silero_vad.onnx` 的现成模式放。

### 发现 2：CAM++ 的 ONNX 版本现成、体积小、速度够

| 模型 | 大小 | Pixel 6 每句耗时 | 区分度 |
| --- | --- | --- | --- |
| CAM++ fp32 | 27 MB | 102–120 ms | 0.814 |
| **CAM++ fp16** | **14 MB** | **70–78 ms** | 0.808 |
| CAM++ int8 | 8.2 MB | 287–330 ms | 0.738 |

（数据来源：模型页在 ARM64 CPU / 4 线程上的实测，见「参考来源」。）

选 **fp16**：体积和精度平衡最好；int8 反而更慢（动态量化在这个模型上不划算）。
授权是 **Apache-2.0**（3D-Speaker / ModelScope），满足 Phase 10 施工单「已准备经过许可的模型候选」。

### 发现 3（最关键）：**自己实现 fbank 就够，不必引入 sherpa-onnx**

手机上不会有 sherpa-onnx，必须「Kotlin 算 fbank + 已有的 OrtSession」。这是唯一的真风险点，
所以做了等价性验证。网格搜索 36 种参数组合后，最优配置为：

```
samp_freq=16000, frame_length=25ms, frame_shift=10ms
dither=0, preemph=0.97, remove_dc_offset=true
snip_edges=False, window=povey
num_bins=80, low_freq=20, high_freq=-400
use_energy=False
再做 CMN（逐维减整句均值）   ← 这一步不能省，省了相似度从 0.92 掉到 0.62
```

结果：

| 指标 | 自己实现 | sherpa-onnx 参考 |
| --- | --- | --- |
| 与参考 embedding 的余弦相似度 | 0.9225（最低 0.7498） | 1.0（自身） |
| 同人相似度均值 | 0.4088 | 0.3860 |
| 异人相似度均值 | 0.2241 | 0.2047 |
| **区分度 margin** | **0.1847** | 0.1813 |

**自己算的特征，区分度与 sherpa-onnx 持平（0.1847 vs 0.1813）。**
余弦相似度 0.92 而非 1.0 不影响结论 —— 真正要的是「分不分得开人」，而这一点是达标的。

---

## 二、端到端验证结果

用真实双人录音跑完整流程（`tools/speaker-ondevice-spike.py`）：

```
音频: 531.3 秒, 16000 Hz
标准答案: 321 句, 其中有标签且 >= 500ms 的 78 句
模型载入: 0.45 秒, embedding 维度 = 192
算出 78 条 embedding
每句耗时: 平均 17.0ms, 中位 14.5ms, 最慢 75.2ms

同一个人之间余弦相似度: 平均 0.3860 (最低 -0.1108)
不同人之间余弦相似度:   平均 0.2047 (最高 0.7040)
区分度 margin = 0.1813
最近邻判定准确率: 68/78 = 87.2%
```

**17 ms/句是在 16 线程 i5-14400 桌面上；手机预期 70–100 ms/句**（按 Pixel 6 基准）。
按每天 300 句估算，手机上总共约 30 秒 CPU，且是在**封口后异步**跑，不碰录音热路径。

---

## 三、建议的架构（聚类留在服务端）

```
手机端（复用现有的封口后异步 pass，不碰热路径）
  读 PCM ──► Silero VAD 区间          ← 已有，0.11.15 就在跑
         └─► 每个区间切片段 ──► 80 维 fbank ──► CAM++ ──► 192 维 embedding
                                                          │
                                            存 Room，随片段注册一起上传
                                                          ▼
服务端
  收 embedding ──► 按会话聚类（余弦 + 阈值）──► speaker_cluster
              ──► 按 VAD 区间对齐到 utterance        ← 已有逻辑
              ──► 与 speaker_profile 做身份匹配      ← 已有 _cosine / _suggestions_for
              ──► App 显示与纠正                     ← 已有 UI，不用动
```

**为什么聚类放服务端而不是手机：**

1. 聚类阈值/参数可随时调整，**不用发新版 APK**；
2. 身份匹配（跨会话认人）本来就需要全局 `speaker_profile` 库，绕不开服务端；
3. embedding 极小（192 × float32 ≈ 768 字节/句），上传成本可忽略；
4. 现有 `routers/speaker_embeddings.py` 的接口形态（收 embedding → 聚类 → 给建议）**几乎不用改**，只是把「谁算 embedding」从 GPU worker 换成手机。

**另一个好处：这条路与 ASR 后端解耦。** MiMo 继续做转写（今天实测 1.1–3.0 秒、质量好、¥0.5/小时），
发言人单独走这条链路，不再需要租 GPU。

---

## 四、⚠️ 发现一条需求文档冲突（按 AGENTS.md §8 停止并报告）

`docs/00-product-requirements.md` 第 213 行，在「12. 明确不承诺」里写着：

> **不在手机端运行大型 ASR 或说话人模型。**

这句话当初是按「发言人全在服务端/GPU」的设计写的。现在主人要求端上化，需要确认口径：

- **解读 A**：字面执行 —— 禁的是**大型**模型。CAM++ fp16 是 **14 MB**，不属于大型，**不冲突，可以动手**。
- **解读 B**：按当初的意图 —— 发言人模型一律不上手机，**那就冲突**，需要先改需求文档再实施。

按 AGENTS.md §1.5「发现需求冲突时停止，不得自行选择更方便的解释」，**我不自行选 A**，请主人拍板。

补充：Phase 10 施工单（`docs/phases/phase-10-speakers.md`）**没有规定模型跑在哪**，
只要求「已准备经过许可的说话人分离/嵌入模型候选」和「低置信度保持 UNKNOWN」，所以施工单本身不阻碍端上化。

---

## 五、改动面预估（待批准后执行）

| 层 | 改动 | 规模 |
| --- | --- | --- |
| Android | 新增 `SpeakerEmbedder`（fbank + OrtSession 封装） | 中，~300 行 + 单测 |
| Android | 扩展封口后 pass：VAD 区间后加 embedding 计算 | 小 |
| Android | Room 新增 embedding 存储 + 上传字段 | 小 |
| Android | 显式声明 `onnxruntime-android` 依赖；模型放 `assets/` | 小（**不增原生体积**） |
| Android | 设置页显示「发言人分析」开关与状态 | 小 |
| 服务端 | 注册接口接收 embedding；会话内聚类；对齐；喂身份匹配 | 中 |
| 服务端 | 单测 + 真实数据回归 | 中 |
| 文档 | 视主人选择更新 §12；新增 ADR | 小 |

**APK 体积**：+14 MB（fp16），从 103 MB → 约 117 MB。

---

## 六、风险与未验证项

1. **手机真实耗时未实测**。AGENTS.md §5 禁止连接主人手机，我无法测。有 Pixel 6 的 70–78 ms 基准兜底，
   且可在模拟器上验证**正确性**（时序不代表真机）。
2. **区分度 87.2% 是下界**。标准答案本身来自旧 GPU 流水线，未必全对；且这批句子普遍偏短
   （中位 1440 ms，最短 70 ms），短句声纹质量天然差。
3. **同人最低相似度 -0.1108**（有少数同人句对完全不像）—— 短句/噪声导致，需要靠 Phase 10 既有的
   「低质量片段不自动加入声纹」规则兜住。
4. **模型选型未横向对比**。只验了 CAM++；eres2net_base（37.8 MB）和 NeMo TitaNet 未测。
   若 CAM++ 精度不够，TitaNet 在 sherpa-onnx 基准里更快（RTF 0.110 vs 0.241）。
5. **未验证多 ABI**。APK 含 arm64-v8a / armeabi-v7a / x86 / x86_64 四套 onnxruntime；
   主人的 Mate 60 Pro+ 是 arm64-v8a，已在 APK 内。

---

## 执行命令与退出码

```bash
# 拉取真实双人录音（17 MB）
$ ssh … 'sudo cat …/ac12bde9-….wav' > artifacts/…/audio/two-speaker-8min.wav     # 退出码 0

# 下载 CAM++ fp16 ONNX（14,695,579 字节）
$ HF_ENDPOINT=https://hf-mirror.com HF_HUB_DISABLE_XET=1 \
  .venv-asr/bin/python -c "hf_hub_download('ldov/campplus-zh-en-onnx','campplus_zh_en_fp16.onnx', …)"
                                                                                 # 退出码 0

# 端到端 spike（模型载入 + 逐句 embedding + 区分度）
$ .venv-asr/bin/python tools/speaker-ondevice-spike.py                           # 退出码 0

# fbank 等价性 + 参数网格搜索（36 组）
$ .venv-asr/bin/python tools/speaker-fbank-parity.py                             # 退出码 0
$ .venv-asr/bin/python tools/speaker-fbank-grid.py                               # 退出码 0
```

## 测试数量与结果

本轮为**可行性 spike**，未改动生产代码，故未跑服务端/Android 测试套件。
沿用 10-08 基线：服务端 pytest **186 passed**、App 单测 **185/185**、lint 0 error。
spike 自身：78 条 embedding 全部算出（跳过 0 条）；fbank 网格 36 组全部跑完。

## 产物路径、大小、SHA-256

```
tools/speaker-ondevice-spike.py          # 端到端 spike
tools/speaker-fbank-parity.py            # fbank 等价性
tools/speaker-fbank-grid.py              # 参数网格搜索
artifacts/phase-11/0.11.18-speaker-spike/
  audio/two-speaker-8min.wav             17,000,492 字节
  models/campplus_zh_en_fp16.onnx        14,695,579 字节
  ground-truth.json                      （321 句，含旧流水线发言人标签）
  result.json                            （端到端结果）
  fbank-grid.json                        （网格搜索结果）
```

## 已知限制

见第六节。

## 失败与重试记录

| 问题 | 处理 |
| --- | --- |
| spike 脚本 `ROOT` 多退了两级，音频路径解析成 `/vol1/ai/artifacts/…` | 改为只退一级 |
| `ground-truth.json` 首次导出为空（psql 输出混入 stderr） | 加 `grep '^\['` 过滤后正常 |
| fbank 网格里 `use_energy=True` 导致输入变成 81 维，模型报 `Got: 81 Expected: 80` | 从网格中去掉该维度 |
| 不带 CMN 时与参考相似度只有 0.6178 | 加 CMN 后升到 0.9099 → 0.9225 |

## 是否满足每一条验收标准

| # | 验收标准 | 结论 | 依据 |
| --- | --- | --- | --- |
| 1 | 回答「能不能部署到手机」 | ✅ | 能。ONNX Runtime 已在 APK，模型 14 MB，自己实现 fbank 即可 |
| 2 | 验证模型可用 | ✅ | 192 维 embedding，载入 0.45 s，78/78 句全部算出 |
| 3 | 验证能区分发言人 | ✅ | margin 0.1813，最近邻准确率 87.2% |
| 4 | 验证速度可接受 | ✅ | 桌面 17.0 ms/句；手机按 Pixel 6 基准 70–78 ms/句 |
| 5 | 验证不引入新原生依赖 | ✅ | `libonnxruntime.so` 与 `ai/onnxruntime/*` 已在 APK 内 |
| 6 | 验证 fbank 可自行实现 | ✅ | 自实现 margin 0.1847 ≥ sherpa-onnx 0.1813 |
| 7 | 检查需求文档是否冲突 | ✅ | **发现 §12 冲突，已停止并上报** |
| 8 | 未改生产代码 | ✅ | 本轮只读排查 + 独立 spike |

---

## 结论

**技术可行性已充分验证，可以动手。** 但在动手前需要主人回答一个问题：

> `docs/00-product-requirements.md` §12 写的「不在手机端运行**大型** ASR 或说话人模型」——
> 14 MB 的 CAM++ 算不算「大型」？是维持原意，还是把 §12 更新为「允许端上跑轻量说话人模型」？

主人确认口径后，我会出正式施工单，按 AGENTS.md「一次只做一个 phase」执行。

## 参考来源

- [CAM++ ONNX（fp32/fp16/int8）与 Pixel 6 端上基准](https://huggingface.co/ldov/campplus-zh-en-onnx)
- [CAM++ 3D-Speaker 200k ONNX 导出规格（192 维、27 MB、Apache-2.0）](https://huggingface.co/welcomyou/campplus-3dspeaker-200k-onnx)
- [sherpa-onnx 说话人分离文档](https://k2-fsa.github.io/sherpa/onnx/speaker-diarization/index.html)
- [sherpa-onnx HarmonyOS 端上说话人识别示例](https://k2-fsa.github.io/sherpa/onnx)
