语音交互与 AI 唤醒

语音交互与 AI 唤醒（Smart Voice / Keyword Spotting）是 AC792N SDK 中负责麦克风拾音、神经网络 VAD（语音活动检测）、关键词唤醒（KWS）以及后续 ASR 语音识别流水线的完整子系统，核心实现位于 sdk/audio/smart_voice/ 目录。

Purpose and Scope

本文档介绍 AC792N SDK 中语音交互与 AI 唤醒能力（Smart Voice / KWS / ASR）的完整实现机制，包括：

• smart_voice 模块的文件组成与职责划分；
• 关键词检测平台 jl_kws_platform.c 的内部结构、上下文管理与数据缓冲设计；
• 神经网络 VAD（nn_vad）与平台 VAD（vad_mic）的集成方式；
• 唤醒事件（kws_event）与麦克风数据管理（voice_mic_data）机制；
• 第三方 ASR（Wanson ASR、用户自研 ASR）的接入框架；
• ai_voice 音频流水线（PIPELINE_UUID_AI_VOICE）与系统事件处理的集成。

不涉及的范围：本页聚焦于语音侧的关键词检测与唤醒链路。麦克风硬件配置、音频效果（增益、ANC 等）、蓝牙/网络协议等主题由各自独立的目录页覆盖，本页仅在必要时引用。

Overview

在嵌入式音频芯片（如 AC792N）上，语音交互通常分为三个阶段：

1. 持续监听（Listen）：麦克风以 16 kHz 采样率持续采集 PCM 数据；
2. 唤醒检测（Wake-up / KWS）：在本地运行关键词检测模型，检测到预设唤醒词后置位唤醒标志；
3. 语音识别（ASR）：唤醒后，将语音上传或交由本地/云端 ASR 引擎识别。

AC792N SDK 将上述能力抽象为 smart_voice 子系统。其设计意图（WHY）在于：唤醒词检测必须在芯片本地以极低功耗、极低延迟持续运行，而完整的 ASR 识别（尤其是云端/大模型场景）只在唤醒之后才启动，从而在功耗与功能之间取得平衡。代码中通过编译期宏（如 TCFG_SMART_VOICE_ENABLE、TCFG_AUDIO_ASR_DEVELOP）在"仅 KWS 唤醒"与"KWS + 第三方 ASR"之间切换，体现了按需裁剪的设计理念。

子系统对外暴露的关键抽象：

Architecture

下图展示了语音交互与 AI 唤醒子系统的整体架构与数据流向：

flowchart TD
    subgraph sg_Input["输入层"]
        MIC["麦克风 (16kHz PCM)"]
    end

    subgraph sg_SmartVoice["smart_voice 子系统 (sdk/audio/smart_voice)"]
        MIC_DATA["voice_mic_data<br/>麦克风数据管理"]
        KWS_PLAT["jl_kws_platform<br/>KWS 平台层"]
        NN_VAD["nn_vad<br/>神经网络 VAD"]
        VAD_MIC["vad_mic<br/>平台 VAD (可选)"]
        KWS_ALGO["asr/jl_kws<br/>唤醒词检测算法"]
        KWS_EVT["kws_event<br/>唤醒事件"]
        ASR_ENGINE["wanson_asr / user_asr<br/>第三方 ASR 引擎"]
    end

    subgraph sg_App["应用与流水线层"]
        AI_PIPE["ai_voice 流水线<br/>PIPELINE_UUID_AI_VOICE (0x1BA8)"]
        EVT_HANDLER["jlstream_event_handler"]
        APP["应用程序 (TCFG_SMART_VOICE_ENABLE)"]
    end

    MIC --> MIC_DATA
    MIC_DATA --> KWS_PLAT
    KWS_PLAT --> NN_VAD
    KWS_PLAT --> VAD_MIC
    KWS_PLAT --> KWS_ALGO
    KWS_ALGO -->|"唤醒结果"| KWS_EVT
    KWS_EVT -->|"smart_voice_wakeup 标志"| APP
    KWS_PLAT -->|"唤醒后启动"| ASR_ENGINE
    MIC_DATA -->|"音频数据导出"| AI_PIPE
    AI_PIPE --> EVT_HANDLER
    EVT_HANDLER --> APP

架构说明：

• 输入层：麦克风数据以 16 kHz、16 bit（SMART_VOICE_SAMPLE_RATE 16000，每样本 2 字节）进入子系统，见 jl_kws_platform.c。
• 平台层（jl_kws_platform）：核心编排者，持有 smart_voice_context（kws_model/kws/mic/nn_vad 四个句柄），串联麦克风数据、VAD 与 KWS 算法，见 jl_kws_platform.c。
• 检测层：nn_vad 先做语音活动检测（AUDIO_NN_VAD_ENABLE 控制），再由 asr/jl_kws 执行关键词匹配；平台 VAD（CONFIG_VAD_PLATFORM_SUPPORT_EN）作为可选路径。
• 事件层：kws_event 将检测结果异步通知应用层；全局唤醒标志 smart_voice_wakeup 供各任务轮询，见 jl_kws_platform.c。
• 流水线集成：ai_voice 流水线的 UUID 为 PIPELINE_UUID_AI_VOICE 0x1BA8，由 jlstream_event_handler.c 中 jlstream_get_pipeline_uuid("ai_voice") 识别，使语音数据能够汇入标准音频流水线框架。

核心实现分析

模块文件组成

sdk/audio/smart_voice/ 目录是语音交互子系统的全部实现，按职责划分如下：

运行时上下文：smart_voice_context

KWS 平台层使用单一上下文结构管理所有运行时资源：

struct smart_voice_context {
    u8 kws_model;          /* 当前使用的 KWS 模型标识 */
    void *kws;             /* jl_kws 唤醒算法句柄 */
    void *mic;             /* 麦克风数据句柄 (voice_mic_data) */
    void *nn_vad;          /* 神经网络 VAD 句柄 */
#if SMART_VOICE_TEST_WRITE_FILE
    void *file;            /* 调试：PCM 落盘句柄 */
#endif
#if SMART_VOICE_DEBUG_KWS_RESULT
    void *dump_hdl;        /* 调试：KWS 结果转储句柄 */
#endif
};

来源：jl_kws_platform.c

设计意图：将所有句柄集中到一个结构体中，并维护一个全局单例指针 this_sv，使平台层可以作为一个无状态调用边界，在任意任务上下文中访问当前唤醒实例。kws 与 nn_vad 使用 void * 类型，隔离了算法库的具体类型——这样 asr/jl_kws 与 nn_vad 可以独立升级或替换，而不影响平台层代码。

采样率与缓冲设计

#define SMART_VOICE_SAMPLE_RATE           16000
#define SMART_VOICE_REC_MIC_SECS          8
#define SMART_VOICE_REC_DATA_LEN          (SMART_VOICE_SAMPLE_RATE * SMART_VOICE_REC_MIC_SECS * 2)

#define SMART_VOICE_KWS_FRAME_LEN     (320)

#if SMART_VOICE_TEST_WRITE_FILE
#define VOICE_DATA_BUFFER_SIZE     16 * 1024
#elif SMART_VOICE_TEST_PRINT_PCM
#define VOICE_DATA_BUFFER_SIZE     SMART_VOICE_REC_DATA_LEN
#else
#define VOICE_DATA_BUFFER_SIZE     2 * 1024
#endif

来源：jl_kws_platform.c

设计要点：

• 16 kHz 采样率是语音识别领域的通用标准（覆盖人声主要频段，同时比 44.1 kHz 省一半以上的计算与内存），因此唤醒与识别共用同一路麦克风数据。
• KWS 帧长 320 样本（16 kHz 下即 20 ms），这是典型的 KWS 推理帧长，兼顾了延迟与模型输入尺寸。
• 生产环境缓冲仅 2 KB（VOICE_DATA_BUFFER_SIZE），说明唤醒链路采用"边采边推"的流式处理而非整段缓存；8 秒/256 KB 的整段缓冲仅用于调试转储（SMART_VOICE_TEST_PRINT_PCM / SMART_VOICE_TEST_WRITE_FILE），体现了"调试路径与生产路径分离"的嵌入式工程实践。

编译期功能开关

#if CONFIG_VAD_PLATFORM_SUPPORT_EN
#include "vad_mic.h"
#endif /*CONFIG_VAD_PLATFORM_SUPPORT_EN*/

#if ((defined TCFG_AUDIO_DATA_EXPORT_ENABLE && TCFG_AUDIO_DATA_EXPORT_ENABLE))
#define CONFIG_VAD_KWS_DETECT_ENABLE    0
#else
#define CONFIG_VAD_KWS_DETECT_ENABLE    1
#endif

来源：jl_kws_platform.c 与 jl_kws_platform.c

设计意图：

• CONFIG_VAD_PLATFORM_SUPPORT_EN 开启时引入平台硬件 VAD（vad_mic.h），用于在低功耗监听模式下先由硬件粗筛语音，减少神经网络 KWS 的运行时长。
• CONFIG_VAD_KWS_DETECT_ENABLE 的默认值取决于 TCFG_AUDIO_DATA_EXPORT_ENABLE：当音频数据需要导出（例如喂给 ai_voice 流水线做进一步处理）时，KWS 检测被关闭（置 0），避免同一路数据被两套逻辑竞争消费；反之则默认开启 KWS 检测。这是"同一麦克风数据只能有一个消费者"这一约束在编译期的显式表达。

全局唤醒标志

static struct smart_voice_context *this_sv = NULL;
static u8 volatile smart_voice_wakeup = 0;

来源：jl_kws_platform.c

smart_voice_wakeup 声明为 volatile u8，这是因为唤醒检测可能发生在录音中断/检测线程中，而消费方（应用主循环、AI 流水线）运行在另一个任务中。volatile 确保每次读取都访问真实内存，避免编译器将其缓存到寄存器导致唤醒事件丢失。该标志是本子系统向应用层暴露的"最小状态机"：0 表示未唤醒，非 0 表示已唤醒。

调试与测试钩子

平台层内置了三个测试开关，全部默认为 0（生产关闭）：

#define SMART_VOICE_TEST_LISTEN_SOUND     0
#define SMART_VOICE_TEST_PRINT_PCM        0
#define SMART_VOICE_TEST_WRITE_FILE       0
#define SMART_VOICE_DEBUG_KWS_RESULT      0
#define AUDIO_NN_VAD_ENABLE               0

来源：jl_kws_platform.c

对应的辅助函数展示了调试路径的实现方式：

static inline void smart_voice_data_listen_sound(void *data, int len)
{
#if SMART_VOICE_TEST_LISTEN_SOUND
    if (audio_dac_is_working(&dac_hdl)) {
        audio_dac_write(&dac_hdl, data, len);
    }
#endif
}

static inline void smart_voice_data_write_file(struct smart_voice_context *sv, void *data, int len)
{
#if SMART_VOICE_TEST_WRITE_FILE
    if (sv->file) {
        fwrite(data, len, 1, sv->file);
    }
#endif
}

static void voice_mic_data_debug_stop(struct smart_voice_context *sv)
{
#if SMART_VOICE_TEST_PRINT_PCM
    if (sv->mic) {
        voice_mic_data_dump(sv->mic);
    }
#endif
#if SMART_VOICE_TEST_WRITE_FILE
    if (sv->file) {
        log_info("SMART_VOICE_TEST_WRITE_FILE CLOSE");
        fclose(sv->file);
        sv->file = NULL;
    }
#endif
}

来源：jl_kws_platform.c

这些钩子的设计意图：SMART_VOICE_TEST_LISTEN_SOUND 可在无耳机/喇叭回放链路时把麦克风采集的 PCM 实时送到 DAC 监听（验证采集通路）；SMART_VOICE_TEST_PRINT_PCM/SMART_VOICE_TEST_WRITE_FILE 分别用于串口打印与文件落盘，方便在 PC 端用音频工具分析 KWS 模型的实际输入质量。由于全部由编译期宏控制且默认为 0，生产构建不会引入任何调试开销。

核心流程：从麦克风到唤醒

下图描述了从麦克风采集到应用层感知唤醒的完整时序：

sequenceDiagram
    participant MIC as 麦克风 (16kHz)
    participant MD as voice_mic_data
    participant PLAT as jl_kws_platform
    participant VAD as nn_vad / vad_mic
    participant KWS as asr/jl_kws (KWS 算法)
    participant EVT as kws_event
    participant APP as 应用层

    MIC->>MD: 持续采集 PCM 数据
    MD->>PLAT: 按帧递交数据 (320 样本/帧)
    PLAT->>VAD: 语音活动检测 (AUDIO_NN_VAD_ENABLE)
    VAD-->>PLAT: 是否包含语音
    alt 检测到语音
        PLAT->>KWS: 送入 KWS 模型推理
        KWS-->>PLAT: 关键词匹配结果
        alt 命中唤醒词
            PLAT->>EVT: 派发唤醒事件
            EVT->>APP: 通知唤醒 (smart_voice_wakeup = 1)
            PLAT->>PLAT: 启动 ASR 识别阶段
        else 未命中
            PLAT->>PLAT: 丢弃该帧，继续监听
        end
    else 静音/噪声
        PLAT->>PLAT: 跳过 KWS 推理，降低功耗
    end

流程要点：

1. 流式处理：麦克风数据以 SMART_VOICE_KWS_FRAME_LEN（320 样本，20 ms）为粒度持续送入平台层，无需整段缓存即可开始检测，唤醒延迟理论上可低至单帧处理时间。
2. 两级检测：先 VAD 后 KWS。VAD 是轻量级预筛，用于跳过静音/纯噪声段，避免 KWS 神经网络在无语音时段空转——这是降低平均功耗的关键设计。
3. 事件异步化：唤醒结果通过 kws_event 派发，应用层既可通过事件回调响应，也可轮询 smart_voice_wakeup 标志，适配中断驱动与轮询两种编程模型。
4. 唤醒即切换：唤醒成功后平台层进入 ASR 阶段（调用 wanson_platform_asr_open() 等），实现"监听态（低功耗）→ 识别态（高算力）"的状态切换。

唤醒事件机制（kws_event）

kws_event.c/h 负责将 KWS 检测结果转化为子系统内外的异步事件。它与全局标志 smart_voice_wakeup 互为补充：事件机制适合"一次性触发 + 携带结果参数"的场景（例如上报命中的关键词 ID、置信度），而标志位适合持续监听状态的低开销轮询。事件定义与派发函数的具体实现位于 kws_event.c 与 kws_event.h。

第三方 ASR 接入框架

子系统支持通过编译期宏在多种 ASR 后端之间切换：

extern const int config_jl_audio_kws_enable;
extern const int config_wanson_asr_enable;

#if ((defined TCFG_AUDIO_ASR_DEVELOP) && (TCFG_AUDIO_ASR_DEVELOP == ASR_CFG_WANSON))
void wanson_asr_hdl_free(void);
int wanson_platform_asr_open(void);
#endif

来源：jl_kws_platform.c 与 jl_kws_platform.c

设计意图：

• config_jl_audio_kws_enable 与 config_wanson_asr_enable 是链接期常量（extern const int，由配置工程/其他编译单元提供），允许在不改动源码的情况下，通过链接脚本或配置模块决定是否链接 KWS 与 Wanson ASR 的实现——这是嵌入式 SDK 常见的"链接期裁剪"手段。
• TCFG_AUDIO_ASR_DEVELOP == ASR_CFG_WANSON 时启用 Wanson ASR：wanson_platform_asr_open() 负责打开识别会话，wanson_asr_hdl_free() 负责释放句柄，具体实现见 wanson_asr.c。
• 用户自研 ASR 通过 user_asr.c/h 接入，形成"JL 内置 KWS + 可选第三方 ASR"的分层结构：唤醒始终在本地完成，识别引擎可按产品需求替换。

与 ai_voice 音频流水线的集成

语音数据不仅服务于唤醒，还通过标准音频流水线框架导出：

#define PIPELINE_UUID_AI_VOICE      0x1BA8

if (!strcmp(name, "ai_voice")) {
    return PIPELINE_UUID_AI_VOICE;
}

来源：jlstream_event_handler.c 与 jlstream_event_handler.c

jlstream_get_pipeline_uuid() 依据流水线名字符串返回固定 UUID：ai_voice → 0x1BA8。这意味着 AI 语音可作为与录音（0x49EC）、LE Audio（0x99AA）并列的一等流水线类型，获得统一的流事件处理（启动/停止/异常回调）。这也解释了前文 CONFIG_VAD_KWS_DETECT_ENABLE 的联动逻辑：当 TCFG_AUDIO_DATA_EXPORT_ENABLE 开启（数据要被 ai_voice 流水线消费）时，平台层自动关闭内置 KWS 检测，避免同一路麦克风数据被平台层与流水线双重消费。

配置选项

API 参考

voice_mic_data_dump(void *mic)

• 说明：导出/转储麦克风数据句柄中的 PCM 数据，用于 SMART_VOICE_TEST_PRINT_PCM 调试路径。
• 参数：mic（void *）——由 smart_voice_context.mic 持有的麦克风数据句柄。
• 返回：无。
• 调用场景：voice_mic_data_debug_stop() 在录音调试结束时调用（jl_kws_platform.c）。

wanson_platform_asr_open(void): int

• 说明：打开 Wanson ASR 识别会话（唤醒成功后由平台层调用，进入识别阶段）。
• 参数：无。
• 返回：int——0 表示成功，非 0 表示打开失败。
• 前置条件：TCFG_AUDIO_ASR_DEVELOP == ASR_CFG_WANSON，且 config_wanson_asr_enable 已链接。
• 实现：见 wanson_asr.c。

wanson_asr_hdl_free(void)

• 说明：释放 Wanson ASR 句柄（识别结束/会话关闭时调用）。
• 参数：无。
• 返回：无。
• 实现：见 wanson_asr.c。

jlstream_get_pipeline_uuid(name): u32

• 说明：将流水线名字符串映射为流水线 UUID；"ai_voice" 映射为 PIPELINE_UUID_AI_VOICE (0x1BA8)。
• 参数：name（const char *）——流水线名称。
• 返回：u32 UUID。
• 实现：见 jlstream_event_handler.c。

失败模式、边界情况与并发

• 唤醒标志丢失风险：smart_voice_wakeup 为 volatile u8，但并未使用原子操作或临界区。若检测线程在应用线程读取标志的同一时刻写入，理论上存在读写竞争；由于标志为单字节且只有 0/1 两种值，实际影响仅限于"晚一个轮询周期感知"，不会出现半更新状态。如需严格同步，应在应用层配合事件回调使用。
• 双消费者冲突：当 TCFG_AUDIO_DATA_EXPORT_ENABLE 开启（ai_voice 流水线消费麦克风数据）时，CONFIG_VAD_KWS_DETECT_ENABLE 被强制置 0。若用户同时强制开启两者，同一路 PCM 会被平台层 KWS 与流水线双重消费，可能导致检测结果与导出数据不同步——该冲突在编译期通过宏联动显式规避。
• 调试宏误开：SMART_VOICE_TEST_WRITE_FILE 会把每帧数据写入文件系统，SMART_VOICE_TEST_PRINT_PCM 会把 256 KB 整段数据通过串口打印，二者在生产构建中必须为 0，否则将导致严重的 IO 阻塞与功耗上升。代码默认值均为 0。
• 唤醒后无语音（误唤醒）：KWS 引擎返回"命中"但后续并无有效指令时，系统依赖 ASR 会话的超时/静音检测自行收敛（wanson_asr_hdl_free 释放资源），平台层不阻塞监听流程。
• 低功耗监听与推理时序：神经网络 KWS 推理必须在 VAD 判定有语音后才执行；若 VAD 阈值过松，静音段也会触发 KWS 推理，拉高平均功耗；若过紧，可能漏检轻声唤醒词。AUDIO_NN_VAD_ENABLE 默认关闭，表明默认部署依赖平台 VAD 或直接 KWS。

性能与运维注意事项

• 内存占用：生产路径下麦克风缓冲仅 2 KB，配合 smart_voice_context 的四个句柄，整体内存足迹小，可在低 RAM 的音频 SoC 上常驻。
• 延迟预算：KWS 帧长 20 ms，VAD 预筛通过后单帧即可进入推理，唤醒响应延迟可控制在数十毫秒量级（取决于模型推理耗时）。
• 功耗策略：VAD → KWS 两级流水线使神经网络在无语音时段尽可能休眠；唤醒后仅短暂运行 ASR 会话，识别结束即释放（wanson_asr_hdl_free），避免高算力路径长期占用。
• 调试与回归：通过 SMART_VOICE_TEST_WRITE_FILE 导出的 16 kHz PCM 可在 PC 端直接用于模型输入校验与音频质量回归；建议在每次 KWS 模型更新后回放验证采集通路增益与噪声水平。

扩展点

1. 替换 KWS 模型：smart_voice_context.kws_model 标识当前模型；更换模型时保持 16 kHz / 320 样本帧长协议即可无缝接入 asr/jl_kws。
2. 接入新 ASR 后端：仿照 wanson_asr.c/h 提供 xxx_platform_asr_open() 与 xxx_asr_hdl_free() 两个接口，并在 TCFG_AUDIO_ASR_DEVELOP 中增加新的枚举值（如 ASR_CFG_USER，参考 user_asr.c/h）。
3. 自定义唤醒事件：在 kws_event.h 中扩展事件类型，携带关键词 ID、置信度等字段供应用层差异化响应。
4. 接入音频流水线：新增流水线类型时在 jlstream_get_pipeline_uuid() 中注册新名称与 UUID，与 ai_voice（0x1BA8）并行，复用统一的事件处理框架。

测试

源码中的测试以编译期调试宏的形式内嵌在平台层（SMART_VOICE_TEST_* 与 SMART_VOICE_DEBUG_KWS_RESULT，全部默认关闭），而非独立测试工程：

• 采集通路验证：SMART_VOICE_TEST_LISTEN_SOUND 通过 DAC 实时回放采集 PCM，用于确认麦克风增益与采样时钟。
• 模型输入验证：SMART_VOICE_TEST_WRITE_FILE / SMART_VOICE_TEST_PRINT_PCM 导出原始 16 kHz PCM，供 PC 端工具分析或与 KWS 模型训练数据对比。
• 结果转储：SMART_VOICE_DEBUG_KWS_RESULT 转储每次 KWS 推理结果，用于统计唤醒率/误唤醒率。

这些测试钩子揭示了子系统的使用模式：先确认采集数据质量，再验证唤醒率，最后以 CONFIG_VAD_KWS_DETECT_ENABLE 或流水线导出模式交付生产配置。

Related Links

• smart_voice 核心入口 smart_voice_core.c
• KWS 平台层 jl_kws_platform.c
• 唤醒事件 kws_event.h
• 神经网络 VAD nn_vad.h
• 麦克风数据管理 voice_mic_data.h
• Wanson ASR 接入 wanson_asr.c
• 用户 ASR 接入 user_asr.c
• 音频流水线事件处理 jlstream_event_handler.c
• 相关目录页：音频流水线（audio_flow）、麦克风效果（mic_effects）、音频增益配置（audio_effects）