# 施工单 · Phase 11.18：发言人端上化（返工 Phase 10 发言人链路）

- 日期：2026-10-09
- 版本号：**0.11.18**（上一版 0.11.17 + 0.0.1，遵循 AGENTS.md 版本延续规则）
- 阶段：Phase 11.18（返工 Phase 10 的发言人链路）
- 前置：`docs/reports/phase-11-18-speaker-ondevice-feasibility.md`（可行性已验证）
- 状态：**待主人批准**（AGENTS.md §1「大改动先出方案等主人批准再动手」）

---

## 1. 目标

把**发言人声纹计算**从「租用的 AutoDL GPU」搬到**手机端**，恢复 Phase 10 的发言人功能，
并让整条链路**与 ASR 后端解耦**（MiMo 继续做转写，发言人不再需要 GPU）。

**验收目标（可量化）：**

1. 手机端能对每个 VAD 区间算出 192 维声纹 embedding；
2. 端上算出的 embedding 与 Python 参考实现（sherpa-onnx）在真实录音上**区分度相当**（margin ≥ 0.15）；
3. 上传后在服务端能自动聚类出说话人，并在 App 里看到「发言人 1 / 发言人 2」；
4. 全流程**不依赖 GPU**，`ASR_BACKEND=mimo` 下发言人照常工作；
5. 不碰录音热路径（AGENTS.md §5）。

---

## 2. 输入

- 已验证的模型：`campplus_zh_en_fp16.onnx`，14,695,579 字节，192 维，Apache-2.0
- 已验证的 fbank 参数（见 §6）
- 真实回归样本：`artifacts/phase-11/0.11.18-speaker-spike/audio/two-speaker-8min.wav`（531 秒双人对话）
  + `ground-truth.json`（78 句旧 GPU 发言人标签）
- 现有代码：`voice/VadSegmentAnalyzer.kt`（端上分析样板）、`upload/UploadWorker.kt`（上传样板）、
  `routers/speaker_embeddings.py`（服务端接口样板）

---

## 3. 允许修改的文件

### Android

| 文件 | 改动 |
| --- | --- |
| `android-app/app/src/main/assets/campplus_zh_en_fp16.onnx` | **新增**（14.7 MB 模型资产） |
| `android-app/app/src/main/assets/CAMPPUS-LICENSE.txt` | **新增**（Apache-2.0 署名，合规要求） |
| `.../voice/Fbank.kt` | **新增**：80 维 fbank 特征提取 |
| `.../voice/SpeakerEmbedder.kt` | **新增**：OrtSession 封装 + 区间切分 + embedding |
| `.../voice/SpeakerEmbeddingConfig.kt` | **新增**：参数集中处（对齐 `VadAnalysisConfig` 的风格） |
| `.../db/Entities.kt` | 新增 `SpeakerEmbeddingEntity` |
| `.../db/Daos.kt` | 新增 `SpeakerEmbeddingDao` |
| `.../db/VoiceMemoryDatabase.kt` | 注册实体与 DAO，**版本号 +1 并写 Migration** |
| `.../db/RecordingRepository.kt` | 新增 `analyzeSegmentSpeakers()` / `speakerEmbeddingsFor()` |
| `.../MicrophoneForegroundService.kt` | 扩展 `analyzeFinalizedSegment()`：VAD 之后加声纹 |
| `.../upload/UploadWorker.kt` | 注册请求带上 embedding |
| `.../upload/UploadApi.kt` | `registerSegment` 增加 `speakerEmbeddings` 字段 |
| `.../ui4/SettingsPage4.kt` | 显示「发言人分析」开关与状态 |
| `android-app/app/build.gradle.kts` | **显式声明** `onnxruntime-android`（已是传递依赖，见 §5） |
| `android-app/gradle/libs.versions.toml` | 同上，加版本目录条目 |
| `android-app/app/src/test/.../FbankTest.kt` | **新增**单测 |
| `android-app/app/src/test/.../SpeakerEmbedderTest.kt` | **新增**单测 |

### 服务端

| 文件 | 改动 |
| --- | --- |
| `server/src/app/schemas.py` | `RegisterSegmentRequest` 增加可选 `speakerEmbeddings` |
| `server/src/app/models.py` | 新增 `SpeakerEmbedding` 表 |
| `server/src/app/routers/upload.py` | 注册时落库 embedding |
| `server/src/app/asr/speaker_cluster.py` | **新增**：会话内聚类 + 对齐 utterance |
| `server/src/app/routers/speaker_embeddings.py` | 接入新的 embedding 来源 |
| `server/migrations/` 或等价迁移脚本 | 建新表 |
| `server/tests/test_speaker_cluster.py` | **新增**单测 |
| `server/tests/test_register_speaker_embeddings.py` | **新增**单测 |

### 文档

| 文件 | 改动 |
| --- | --- |
| `docs/00-product-requirements.md` | §12 措辞明确为「不在手机端运行**大型** ASR 模型；允许端上跑**轻量**说话人模型」 |
| `docs/adr/ADR-0006-on-device-speaker-embedding.md` | **新增** ADR |
| `docs/reports/phase-11-18-report.md` | **新增**阶段报告 |
| `docs/progress.md` | 更新 Phase 10/11 行 |
| `docs/08-requirements-traceability.md` | 更新追踪矩阵 |

---

## 4. 禁止修改的文件

- `server/src/app/asr/service.py`、`gpu/scheduler.py`（0.11.17 刚修好并验证过的转写认领逻辑）
- `server/src/app/routers/upload.py` 的**过期会话自愈**逻辑（0.11.17 成果）
- `android-app/.../upload/UploadPolicy.kt`（0.11.17 成果）
- `android-app/.../upload/UploadWorker.kt` 的 `ALREADY_DONE` / 未配对分支（0.11.17 成果）
- 任何 nginx 配置、`vmc-api` 的启动参数、其他业务服务
- `artifacts/phase-11/0.11.14`、`0.11.15`、`0.11.16`、`0.11.17`（既有产物只读）

---

## 5. 依赖变化

**新增显式依赖：`com.microsoft.onnxruntime:onnxruntime-android:1.20.0`**

- 它**已经是**当前 APK 的传递依赖（Cloudflare `android-vad:silero:2.0.9-cf.3` 带入），
  `libonnxruntime.so`（17.5 MB/ABI）与 `ai/onnxruntime/*` Java 类**已在 APK 内**；
- 显式声明只是把 API 变成一等依赖，**不增加原生体积**；
- AGENTS.md §2 要求新依赖须施工单明确允许 → **本施工单即该项授权请求**。

**权限变化：无。** 不申请任何新权限。

**APK 体积：** 103 MB → 约 **118 MB**（+14.7 MB 模型资产）。

---

## 6. 关键参数（已实测验证，不得擅自更改）

```
采样率        16000 Hz
帧长/帧移     25 ms / 10 ms
dither        0
preemph       0.97
remove_dc     true
snip_edges    false
window        povey
mel bins      80
low_freq      20
high_freq     -400
use_energy    false
后处理        CMN（逐维减整句均值）   ← 不可省，省了区分度从 0.18 掉到 0.10
模型输入      float32 [N, T, 80]，输入名 "x"
模型输出      "embedding"，192 维
最短片段      500 ms（与服务端 MIN_CLIP_MS 一致）
```

---

## 7. 数据结构变化

### Android（Room，版本 +1，必须写 Migration）

```kotlin
@Entity(tableName = "speaker_embedding")
data class SpeakerEmbeddingEntity(
    @PrimaryKey val id: String,
    val segmentId: String,
    val recordingSessionId: String,
    val sequenceNo: Int,          // 与 VAD 区间的 sequenceNo 对齐
    val startMs: Long,
    val endMs: Long,
    val embeddingJson: String,    // 192 个 float
    val modelVersion: String,     // "campplus_zh_en_fp16"
    val state: String,            // READY / UPLOADED
    val createdAtUtcMs: Long,
    val updatedAtUtcMs: Long
)
```

### 服务端（新表）

```
speaker_embedding
  id, device_id, segment_id, start_ms, end_ms,
  embedding_json, model_version, created_at
  UNIQUE(segment_id, start_ms, end_ms, model_version)
```

**embedding 版本隔离**（Phase 10 施工单硬要求）：不同 `model_version` 的向量**不得混比**。

---

## 8. 分步执行计划（一次只做一个 phase，但内部分步验收）

| 步骤 | 内容 | 验收方式 |
| --- | --- | --- |
| **1** | Android：`Fbank.kt` + `SpeakerEmbedder.kt` + 单测 | 单测里用固定 WAV 算出 embedding，与 Python 参考结果比对余弦 ≥ 0.9 |
| **2** | Android：Room + 集成到封口后 pass | 模拟器上录一段，检查 Room 里有 embedding 行 |
| **3** | Android：上传 | 模拟器上跑通，服务端能收到 |
| **4** | 服务端：落库 + 聚类 + 对齐 utterance | pytest + 真实数据回归（用 `two-speaker-8min.wav` 的标签当标准答案） |
| **5** | 端到端 + 出包 + 报告 | `lintDebug assembleDebug`、真机清单交主人 |

**每个步骤完成即跑一次完整测试套件**，不允许累积到最后。

---

## 9. 验收命令

```bash
# Android
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export GRADLE_USER_HOME=/vol1/ai/projects/voice-memory-card-dsh/.gradle-vmc
export ANDROID_USER_HOME=/vol1/ai/projects/voice-memory-card-dsh/.android
cd android-app
./gradlew testDebugUnitTest          # 基线 185 个，预期新增若干
./gradlew lintDebug                  # 必须 0 error
./gradlew assembleDebug              # 必须 BUILD SUCCESSFUL

# 服务端
cd server
.venv/bin/python -m pytest -q        # 基线 186 个，预期新增若干

# 端上 embedding 与 Python 参考的一致性（新增）
.venv-asr/bin/python tools/speaker-ondevice-spike.py     # 参考基准
```

---

## 10. 风险与对策

| 风险 | 对策 |
| --- | --- |
| Kotlin fbank 与 Python 实现有数值差异 | 单测直接对比同一段音频的 embedding 余弦相似度，阈值 ≥ 0.9 |
| 手机 CPU 耗时超预期 | 只在封口后异步跑；如过慢，可只对 ≥ 1000ms 的区间算，或降低采样密度 |
| 声纹准确率不足 | 已有备选 TitaNet（基准里更快）；先按 Phase 10 既有规则「低置信度保持 UNKNOWN」 |
| Room 迁移出错 | 写 Migration 并加迁移测试；旧数据不受影响 |
| 模型资产进仓库体积大 | 与既有 `artifacts/` 大文件一致；同时在报告里记录 SHA-256 |
| 服务端聚类参数需要调 | 参数放服务端，可调不用发版 |

---

## 11. 明确不做（避免范围蔓延）

- **不改** `UploadConfig.APP_VERSION` 硬编码（那是独立问题 P0-2，本阶段不顺手改）
- **不改** deviceId 分裂（主人已明确说旧录音界面不需要）
- **不做**保留策略清理（主人已明确说先不调）
- **不做**时间戳小修（独立问题，另开）
- **不引入** sherpa-onnx（已验证不需要）
- **不做**模型横向对比（TitaNet 等留作备选）

---

## 12. 需要主人确认的事项

1. **批准本施工单** → 我按 §8 分步开工
2. 确认 §11「明确不做」的四项确实本阶段不做
3. 确认 APK 体积增加到约 118 MB 可接受

---

## 参考来源

- [CAM++ ONNX 模型与端上基准](https://huggingface.co/ldov/campplus-zh-en-onnx)
- [sherpa-onnx 说话人分离文档](https://k2-fsa.github.io/sherpa/onnx/speaker-diarization/index.html)
