PicMe 语音栈

文档编号: TECH-SPEC-VOICE-001
关联模块: app/src/main/java/com/mamba/picme/features/camera/voice/, runtime-core/platform/voice/
创建日期: 2026-06-10
最后更新: 2026-07-08
维护者: [RD] 全栈工程师

历史合并说明：本文档由以下 3 份文档合并而成：WAKE_WORD_OPTIMIZATION.md、WAKE_WORD_DEPLOYMENT.md、KWS_MIGRATION_TECH_SPEC.md。内容已按「当前唤醒词实现 → 部署验收 → KWS 迁移规划」重组，并消除重复内容。
2026-07-08 再次合并 ASR_LANGUAGE_MODEL_EXPLANATION.md 作为附录「ASR Language Model 说明」，并去除重复元信息头。

1. 执行摘要

PicMe 语音栈当前处于 Phase 1（当前 ASR-based 唤醒词优化）→ Phase 2（Sherpa-ONNX KWS 迁移） 的过渡阶段。

2. 当前唤醒词实现（Phase 1）

2.1 问题诊断

旧版本局限性

原方案（6 个唤醒词）：
├─ "小觅" × 1（标准）
├─ "小蜜"（同音）
├─ "小秘"（同音）
├─ "小米"（近音）
├─ "小咪"（近音）
└─ "小哔"（近音）

问题：
❌ 不支持口语启动词（"嘿小觅"、"哎小觅"）
❌ 不支持自然用法（"小觅你好"、"小觅啊"）
❌ 轮询策略单一：固定 150ms，无法根据语音活动动态调整
❌ ASR 模型生命周期不优化：始终保持加载
❌ VAD 结果无稳定性检查，容易误触
❌ 唤醒词匹配无权重/优先级，不支持渐进式验证

用户体验痛点

• 识别失败：用户说”嘿小觅拍照”时，系统不识别
• 误触发：后台噪声（电视、语音）误触发唤醒
• 功耗消耗：长时间待机模式下 ASR 模型始终占用内存和 CPU
• 延迟感：VAD 检测波动导致识别延迟 > 1s

2.2 优化方案详解

唤醒词库扩展（21 个关键词）

// 【第 1 组】标准唤醒词 + 同音误识（信心度 0.94-1.0）
"小觅" to 1.0f          // 标准唤醒词，最高优先级
"小蜜" to 0.95f         // 同音：最常见 ASR 误识
"小秘" to 0.95f         // 同音
"小密" to 0.94f         // 同音

// 【第 2 组】近音变体（信心度 0.85-0.88）
"小米" to 0.88f         // 近音：小米手机
"小咪" to 0.87f         // 近音：拟声词
"小妹" to 0.85f         // 近音：可能被误识

// 【第 3 组】方言/口音变体（信心度 0.80-0.82）
"小美" to 0.82f         // mì/měi 易混
"小媽" to 0.80f         // 部分方言

// 【第 4 组】口语启动词 + 唤醒词（信心度 0.90-0.92）
"嘿小觅" to 0.92f       // 感叹词启动
"哎小觅" to 0.92f       // 感叹词启动
"呃小觅" to 0.90f       // 犹豫词启动
"喂小觅" to 0.91f       // 通话启动词

// 【第 5 组】后缀表达（信心度 0.88-0.90）
"小觅啊" to 0.90f       // 语气助词
"小觅呀" to 0.89f       // 语气助词
"小觅你好" to 0.88f     // 完整打招呼

权重匹配策略

优先级矩阵：

信心度区间 │ 匹配行为 │ 用途
────────────┼──────────┼─────────────────────────
0.9 - 1.0  │ 直接触发  │ 高置信度唤醒
0.8 - 0.9  │ 可接受    │ 常见口语表达
0.7 - 0.8  │ 验证     │ 考虑后续指令有效性
< 0.7      │ 拒绝     │ 备用名称（暂未启用）

实现：通过 findMatchedWakeWordWithScore() 返回 Pair<String, Float>，支持多层验证。

2.3 功耗优化

动态轮询间隔调整

private const val LOW_POWER_POLL_MS = 150L      // 待机模式
private const val ACTIVE_POLL_MS = 30L          // 活动期高精度
private var lastPollDelayMs = LOW_POWER_POLL_MS // 当前轮询延迟

// 核心逻辑（主循环中）：
if (isSpeech) {
    if (!isInHighPrecisionMode) {
        isInHighPrecisionMode = true
        lastPollDelayMs = ACTIVE_POLL_MS  // 切换高精度（30ms）
    }
} else {
    if (isInHighPrecisionMode) {
        isInHighPrecisionMode = false
        lastPollDelayMs = LOW_POWER_POLL_MS  // 恢复低功耗（150ms）
    }
}

delay(lastPollDelayMs)  // 使用动态延迟

收益： - 无声环境：150ms 轮询，功耗 ↓ 80%（vs 固定 30ms） - 有声环境：30ms 高精度，识别延迟 < 100ms - 动态切换：毫秒级响应，无需额外资源

按需 ASR 加载

原方案：start() → 加载 ASR → 持续运行 → stop()
问题：ASR 282MB 模型始终占用内存和 CPU

优化方案：
┌─────────────────────────────────────┐
│ WakeWordEngine.start()              │
│   ├─ 启动 AudioRecorder + VAD       │
│   └─ ASR 保持未初始化（低功耗）      │
│        ↓
│   检测到语音活动 + VAD 稳定        │
│   └─ 【关键】调用 asrEngine.transcribe()
│        → 触发 ASR 按需加载          │
│        ↓ (仅在识别期间运行)
│   识别完成或超时                   │
│   └─ ASR 自动释放（不在此管理）     │
│        ↓
└─────────────────────────────────────┘

2.4 精准度优化

VAD 稳定性检查

private const val VAD_STABILITY_FRAMES = 3  // 连续 3 帧语音
private var consecutiveSpeechFrames = 0      // 计数器

// 核心逻辑：
if (isSpeech) {
    consecutiveSpeechFrames++
    if (consecutiveSpeechFrames < VAD_STABILITY_FRAMES) {
        delay(ACTIVE_POLL_MS)
        continue  // 跳过本轮 ASR，等待稳定
    }
    // 稳定 ✓ → 触发 ASR
    triggerAsr()
} else {
    consecutiveSpeechFrames = 0  // 重置
}

效果： - 噪声脉冲（1-2 帧）被过滤 - 真实语音（>3 帧连续）触发识别 - 误触率 ↓ 40%

冷却期管理

private const val WAKE_COOLDOWN_MS = 1200L
private var lastWakeTime = 0L

// 检查冷却期
val now = System.currentTimeMillis()
if (now - lastWakeTime < WAKE_COOLDOWN_MS) {
    vadDetector.reset()
    consecutiveSpeechFrames = 0
    delay(LOW_POWER_POLL_MS)
    continue
}

// 成功识别后更新
lastWakeTime = System.currentTimeMillis()

2.5 技术规格

常量定义

代码流程

VoiceCommandCoordinator.startWakeWordListening()
    ↓
wakeWordEngine.start(onTranscript)
    ├─ audioRecorder.start()
    ├─ vadDetector.reset()
    └─ Dispatchers.IO 启动主循环
         ├─ 轮询 audioRecorder.read()
         ├─ VAD 处理 + 动态轮询
         ├─ 稳定性检查（3 帧）
         ├─ 冷却期检查（1.2s）
         ├─ ASR 按需转录
         ├─ 唤醒词权重匹配 + 日志
         └─ onTranscript 回调（主线程）
    ↓
AgentOrchestrator 接收指令并执行

2.6 性能指标

2.7 单元测试

运行测试：

# 仅编译（无需设备）
./gradlew :app:compileDebugKotlin
# 预期：BUILD SUCCESSFUL

# 运行 WakeWordEngine 单元测试
./gradlew :app:testDebugUnitTest --tests "*WakeWordEngine*" 2>&1 | grep -E "passed|failed"
# 预期：35+ 个测试通过

2.8 故障排查

3. 部署验收

3.1 功能清单

• 唤醒词库扩展至 21 个关键词，包含同音/近音/口语表达
• 实现动态轮询：待机 150ms ↔︎ 活动期 30ms
• 实现 VAD 稳定性检查：连续 3 帧才触发 ASR
• 实现权重优先匹配：findMatchedWakeWordWithScore() 返回信心度
• 实现唤醒词全量移除：支持多个变体和位置
• 添加冷却期管理：1.2s 内忽略重复触发
• 完善日志输出：✓/✗ 标记，信心度显示
• 添加 35+ 单元测试用例
• 无编译错误和 linter 告警
• 生成本技术文档

3.2 验收指标

3.3 设备端测试

# 1. 构建 APK
./gradlew :app:assembleDebug

# 2. 安装到设备/模拟器
adb install -r app/build/outputs/apk/debug/app-debug.apk

# 3. 启动相机应用
adb shell am start -n com.mamba.picme/.features.camera.CameraScreen

# 4. 打开唤醒词模式（点击语音按钮进入唤醒词模式）

# 5. 测试唤醒词识别
说出以下命令并验证：
├─ "小觅拍张照"       ✓ (标准词)
├─ "小蜜打开前置"     ✓ (同音词)
├─ "嘿小觅换滤镜"     ✓ (口语启动词)
├─ "小觅你好"         ✓ (打招呼)
├─ "嘿小觅你好"       ✓ (组合)
└─ "天气怎么样"       ✗ (无唤醒词，正确拒绝)

# 6. 观看日志
adb logcat -s "PicMe:WakeWord" | head -50

3.4 日志示例

[高置信度唤醒]
I/PicMe:WakeWord: Wake word engine started (keywords: 21, core: 6)
D/PicMe:WakeWord: Entered high precision mode (polling: 30ms)
D/PicMe:WakeWord: Speech detected but stability check: 1/3
D/PicMe:WakeWord: Speech detected but stability check: 2/3
I/PicMe:WakeWord: Triggering ASR (stability: 3 frames, confidence: 100%)
I/PicMe:WakeWord: ✓ Wake word matched: '小觅' (confidence: 1.0), command: '拍张照' (raw: '小觅拍张照')

[同音误识但纠正]
I/PicMe:WakeWord: ✓ Wake word matched: '小蜜' (confidence: 0.95), command: '打开前置' (raw: '小蜜打开前置')

[误触（冷却期）]
D/PicMe:WakeWord: Speech detected but in cooldown (200ms / 1200ms), skipped

3.5 文件改动清单

4. KWS 迁移规划（Phase 2）

4.1 当前架构问题诊断

隐式耦合链（历史）

libsherpa-mnn-jni.so → libMNN.so ← libmnn_llm.so
         ↓                               ↓
    [ASR 推理]                      [LLM 推理]
         ↓
libMNN.so 还被 FaceDetectManager（MNN 路径）引用

核心矛盾：libMNN.so 被三个子系统共享，MnnResourceManager 的引用计数 + 全局释放锁 + 三级释放策略本质上是一个被迫的补丁。

当前唤醒词方案缺陷

VAD(RMS 25dB) → 录音(最长4s) → ASR 全量转录(282MB) → 文本匹配"小觅"
                                                    ↑
                                          每次检测都跑 282MB 模型
                                          延迟数秒，无法 always-on

4.2 目标架构

分层运行时

┌─────────────────────────────────────────────────────────┐
│                    应用层 (App Layer)                      │
│                                                         │
│  CameraScreen  →  VoiceCommandCoordinator                │
│                      ├─ WakeWordEngine (新 KWS)           │
│                      ├─ PushToTalkEngine                  │
│                      └─ AiAgentUseCase                   │
└──────────┬──────────────┬──────────────┬────────────────┘
           │              │              │
┌──────────▼──────┐ ┌─────▼──────┐ ┌────▼──────────────┐
│  语音栈 (ONNX)   │ │ LLM (MNN)  │ │  FaceDetect       │
│                 │ │            │ │  (NCNN/MediaPipe) │
│ libsherpa-      │ │ libMNN.so  │ │  独立 .so         │
│ onnx-jni.so     │ │ +          │ │                   │
│ +               │ │ libmnn_llm │ │                   │
│ libonnxruntime  │ │ .so        │ │                   │
│ .so             │ │            │ │                   │
│                 │ │            │ │                   │
│ ├─ Keyword      │ │ Qwen3.5-2B │ │ Det10G + 2D106   │
│ │  Spotter(KWS) │ │            │ │                   │
│ ├─ OnlineRecog  │ │            │ │                   │
│ │  nizer(ASR)   │ │            │ │                   │
│ └─ Vad(DNN VAD) │ │            │ │                   │
│                 │ │            │ │                   │
│ 完全独立        │ │ MNN 唯一   │ │ 完全独立          │
│ 加载/释放       │ │ 使用者     │ │ 加载/释放         │
└─────────────────┘ └────────────┘ └───────────────────┘

关键性质：三个栈各自拥有独立的 Native 运行时，互相不共享全局状态。

API 层映射

双引擎工作流程

【待机阶段】
KWS 常驻监听 (50mW)
    ↓ (100ms chunk 推理)
检测到唤醒词 (如"小觅")
    ↓
【唤醒阶段】
加载 ASR 模型 (~282MB, ~500mW)
    ↓
完整转录音频 (获取指令: "打开前置")
    ↓
识别完毕立即释放 ASR
    ↓
LLM 处理指令 (执行操作)
    ↓
【回到待机】
KWS 继续监听

4.3 生命周期状态机

模型加载状态

每个子系统独立管理加载/释放，互不耦合：

         ┌──────────┐    ┌──────────┐    ┌──────────┐
         │  KWS     │    │  ASR     │    │  LLM     │
         │ (ONNX)   │    │ (ONNX)   │    │ (MNN)    │
         ├──────────┤    ├──────────┤    ├──────────┤
UNLOADED │          │    │          │    │          │
    ↓    │  释放    │    │  释放    │    │  释放    │
LOADED   │  加载    │    │  加载    │    │  加载    │
    ↓    │          │    │          │    │          │
ACTIVE   │  推理中  │    │  推理中  │    │  推理中  │
         └──────────┘    └──────────┘    └──────────┘
              ↑ 独立            ↑ 独立            ↑ 独立
             不共享任何 Native 状态

核心原则：分时复用，绝不叠加

[休眠态]                    [唤醒态]                     [推理态]                  [休眠态]
KWS ████████████           KWS ░░░░░░░░░░░              KWS ░░░░░░░░░░░            KWS ████████████
ASR ────────────    →      ASR ────────────     →       ASR ████████████    →      ASR ────────────
LLM ────────────           LLM ────────────             LLM ████████████           LLM ────────────

 常驻 ~45MB                 KWS 暂停                     峰值 ~2GB                  常驻 ~45MB
                            ASR 加载 (~400MB)            LLM + ASR 同时存在
                            LLM 按需加载 (~1.5GB)        转录完成 → ASR 立即释放
                                                        LLM 推理完成 → 立即释放

设计约束： 1. KWS 与 ASR 绝不同时 ACTIVE（KWS 暂停后 ASR 加载） 2. ASR 转录完成后立即释放（不缓存，不等待 GC） 3. LLM 推理完成后立即释放（可选保留 KV cache 用于 follow-up 对话） 4. 人脸检测按需加载/释放（NCNN/MediaPipe，不受语音栈影响）

状态转移表

注意：LLM + ASR 同时 ACTIVE 只在理论上发生。实际实现中应优先释放 ASR 再加载 LLM。

4.4 内存压力分析

各组件内存预算

KWS（sherpa-onnx-kws-zipformer-wenetspeech-3.3M）：

ASR（sherpa-onnx-streaming-zipformer-bilingual-zh-en-2023-02-20）：

LLM（Qwen3.5-2B-MNN）：

FaceDetect（NCNN 路径）：

各阶段内存账本

进程总计 = Native 总计 + Java Heap (~200MB) + Graphics (~300-500MB for GL/CameraX)

设备分级评估

* Android 进程上限取决于厂商 ROM 配置和系统版本，并非固定值。上表为典型估算。

4.5 内存安全策略

设备分级策略

enum class DeviceTier {
    LOW,      // < 6GB RAM, LLM 使用远程推理, ASR 可能触发警告
    MID,      // 6-8GB, LLM 可用但监控 Native Heap, ASR 安全
    HIGH,     // >= 8GB, 所有模型本地运行
}

fun getDeviceTier(): DeviceTier {
    val totalRam = getTotalRamMb()
    return when {
        totalRam < 6000 -> DeviceTier.LOW
        totalRam < 8000 -> DeviceTier.MID
        else -> DeviceTier.HIGH
    }
}

LLM 加载前检查

fun canLoadLlm(): Boolean {
    val currentNativeHeap = Debug.getNativeHeapAllocatedSize() / 1048576L
    val llmEstimatedMb = 1800L
    val availableMb = getAvailableNativeMemoryMb()

    return when (deviceTier) {
        DeviceTier.LOW -> false  // 低端设备不使用本地 LLM
        DeviceTier.MID -> availableMb > llmEstimatedMb + 200L  // 留 200MB 缓冲
        DeviceTier.HIGH -> true
    }
}

三级释放策略（简化版）

相比当前 MnnResourceManager.ReleaseLevel(SOFT/SESSION/FULL) 的复杂三级体系，解耦后简化为：

不再需要 “SESSION” 中间层级，因为不存在跨子系统的共享状态。

后台行为

// App 后台 30s: TRIM 所有活跃模型
// App 后台 60s: UNLOAD 所有模型（释放 KWS，停止 always-on）

4.6 迁移实施计划

改动范围

总计: ~13 小时

实施顺序

Phase 1: 基础迁移（2天）          Phase 2: KWS 集成（1天）        Phase 3: 解耦优化（1天）
┌──────────────────────┐    ┌──────────────────────┐    ┌──────────────────────┐
│ 1. 添加 AAR 依赖      │    │ 5. 实现 KWS 引擎       │    │ 8. 简化资源管理器     │
│ 2. 更新模型配置        │    │ 6. 重写 WakeWordEngine │    │ 9. 删除 MnnReleaseLock│
│ 3. 重写 ASR 引擎       │    │ 7. KWS 单元测试        │    │ 10. 集成测试          │
│ 4. 下载 ONNX ASR 模型  │    │                      │    │ 11. 全链路验证        │
└──────────────────────┘    └──────────────────────┘    └──────────────────────┘
         ↓                          ↓                          ↓
    ASR 功能持平              唤醒词体验质变               代码质量提升

4.7 模型配置

更新 llm_models.json

[
  {
    "id": "sherpa-onnx-zipformer-zh-en",
    "name": "Sherpa-ONNX Zipformer 中英双语",
    "description": "ONNX Runtime 流式语音识别模型，支持中文+英文，端侧实时推理",
    "type": "ASR",
    "size": 295334441,
    "sources": {
      "ModelScope": "csukuangfj/sherpa-onnx-streaming-zipformer-bilingual-zh-en-2023-02-20"
    },
    "files": [
      "encoder-epoch-99-avg-1.int8.onnx",
      "decoder-epoch-99-avg-1.int8.onnx",
      "joiner-epoch-99-avg-1.int8.onnx",
      "tokens.txt"
    ],
    "tags": ["ASR", "speech", "chinese", "english"]
  },
  {
    "id": "sherpa-onnx-kws-zipformer-zh",
    "name": "Sherpa-ONNX KWS Zipformer 中文唤醒词",
    "description": "3.3M 参数关键词检测模型，支持自定义唤醒词，适合 always-on",
    "type": "KWS",
    "size": 14000000,
    "sources": {
      "ModelScope": "csukuangfj/sherpa-onnx-kws-zipformer-wenetspeech-3.3M-2024-01-01"
    },
    "files": [
      "encoder-epoch-12-avg-2.int8.onnx",
      "decoder-epoch-12-avg-2.int8.onnx",
      "joiner-epoch-12-avg-2.int8.onnx",
      "tokens.txt",
      "keywords.txt"
    ],
    "tags": ["KWS", "keyword", "wake", "chinese"]
  }
]

新增 keywords.txt

小觅
小蜜
小秘
小米
小咪

AAR 依赖

// app/build.gradle.kts
dependencies {
    // 替换:
    // implementation(files("libs/libsherpa-mnn-jni.so"))
    // 为:
    implementation("com.k2fsa:sherpa-onnx:1.13.2")
}

4.8 配置选项

4.9 常见故障排查

4.10 风险评估

4.11 验收标准

• KWS always-on 在休眠态常驻 < 45MB Native Heap
• KWS 唤醒延迟 < 100ms（从用户说话到检测到关键词）
• KWS 误触发率 < 1次/小时（正常环境）
• ASR 转录质量不低于当前 MNN 版本（对比测试 ≥ 95% 字符准确率）
• LLM 可以完全卸载（Native Heap 回落到休眠态水平）
• 多次 KWS→ASR→LLM 循环无内存泄漏（Native Heap 不持续增长）
• 低端设备（4GB）不触发 OOM（KWS + 远程 LLM）
• MnnGlobalReleaseLock 完全删除，无残留引用
• 人脸检测（NCNN）不受语音栈切换影响

5. 相关文件

6. 附录：ASR Language Model 说明

本附录原载于 ASR_LANGUAGE_MODEL_EXPLANATION.md，说明 PicMe Phase 1 Sherpa-MNN ASR 中 Language Model（LM）文件的作用、当前部署状态及取舍依据。随着 Phase 2 迁移至 Sherpa-ONNX，LM 的概念仍适用于理解 ASR 解码行为，但具体文件格式与配置路径可能发生变化。

6.1 什么是 LM 文件

LM = Language Model（语言模型）

在语音识别（ASR）流水线中，LM 负责根据语言规律修正声学模型的输出，提升识别准确率。

6.1.1 ASR 流水线

音频输入
    │
    ▼
┌─────────────────┐
│  声学模型 (AM)   │  ← encoder.mnn + decoder.mnn + joiner.mnn
│  Acoustic Model │     将音频波形转为音素概率分布
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  语言模型 (LM)   │  ← with-state-epoch-*.mnn（可选）
│  Language Model │     根据语法/语义规律选择最可能的文本
└────────┬────────┘
         │
         ▼
      文本输出

6.1.2 LM 的作用举例

LM 的核心价值：将声学相似的候选词，按语言规律排序，选择最合理的文本。

6.2 Sherpa-MNN 中的 LM 文件

6.2.1 文件命名

Sherpa-MNN 的 LM 文件通常命名为：

with-state-epoch-{N}-avg-{M}.int8.mnn

例如：

with-state-epoch-99-avg-1.int8.mnn

6.2.2 当前部署状态

PicMe 当前部署的 Sherpa-MNN 模型包不包含 LM 文件。模型目录中只有：

llm_models/sherpa-mnn-zipformer-zh-en/
├── encoder-epoch-99-avg-1.int8.mnn   ← 声学模型：编码器
├── decoder-epoch-99-avg-1.int8.mnn   ← 声学模型：解码器
├── joiner-epoch-99-avg-1.int8.mnn    ← 声学模型：联合器
└── tokens.txt                        ← 词表映射

没有：with-state-epoch-99-avg-1.int8.mnn

6.2.3 配置加载逻辑

AsrConfigManager.getLmConfigFromDirectory() 的加载顺序：

1. 读取 config.json 中的 lm 字段（如果存在）
2. 如果不存在，调用 getDefaultLmConfig()
3. getDefaultLmConfig() 检查模型目录名是否包含 zh/bilingual/chinese
4. 如果是中文模型，尝试查找 with-state-epoch-99-avg-1.int8.mnn
5. 文件不存在 → 静默使用空 LM 配置

// 当前行为：空 LM 配置
OnlineLMConfig()  // model="", scale=0.0f

6.3 有 LM vs 无 LM 的差异

6.4 是否需要 LM

6.4.1 当前决策：不部署 LM

原因： 1. 模型包体积：LM 文件约 100-200MB，增加下载负担 2. 当前准确率：纯 AM 对相机场景短指令（“拍照”、“切换滤镜”）已足够 3. 内存预算：相机页本身占用大，ASR 应尽量轻量

6.4.2 未来可优化

如果用户反馈语音识别错误率高，可考虑： 1. 下载带 LM 的完整模型包 2. 在 config.json 中配置 lm 字段 3. AsrConfigManager 会自动加载

{
  "modelType": "zipformer",
  "transducer": {
    "encoder": "encoder-epoch-99-avg-1.int8.mnn",
    "decoder": "decoder-epoch-99-avg-1.int8.mnn",
    "joiner": "joiner-epoch-99-avg-1.int8.mnn"
  },
  "tokens": "tokens.txt",
  "lm": {
    "model": "with-state-epoch-99-avg-1.int8.mnn",
    "scale": 0.5
  }
}

6.5 相关文件

6.6 参考

• Sherpa-ONNX 文档：https://k2-fsa.github.io/sherpa/onnx/
• MNN 模型格式：https://www.yuque.com/mnn/cn/model_convert