杰里AC79N模组
百度 AI 模组(AC79N)集成开发指南
目录
1 概述
1.1 方案简介
百度 AI 语音模组基于百度 RTC 大模型互动平台,面向智能家电、AI 玩具等场景。AC791N 端侧固件负责麦克风采集、回声消除、离线唤醒、音频编解码、Wi-Fi 联网和对话协议,语音识别、大模型对话、语音合成和设备控制指令由百度云端完成。
以往方案商接入 AI 语音能力,需要自行完成硬件选型、音频调测和云端对接,开发周期较长。本方案把这些工作提前做完:语音唤醒、降噪与回声消除、配网、联网对话的整条链路已在模组与开发套件中集成并完成调优,端云协同的语音增强让低配置硬件也能获得稳定的识别与交互效果,大幅缩短产品从对接到量产的周期。
交付形态:硬件模组(或开发板)+ RTOS 端侧开发套件(全套端侧源码)。
适用场景
| 类别 | 示例 |
|---|---|
| 智能家电 | 中控、厨具、小家电、智能照明 |
| AI 玩具 | 故事机、AI 闹钟、毛绒玩具、AI 挂件、桌面机器人 |
集成步骤
| 步骤 | 内容 | 对应章节 |
|---|---|---|
| 1 | 开通云端应用与 License,配置智能体 | 第 5 章 |
| 2 | 把应用凭据填入源码 | 6.1 |
| 3 | 选择板型和连接方式,编译并烧录 | 第 4 章 |
| 4 | 通过 BLE 完成 Wi-Fi 配网,验证一轮完整对话 | 4.5 |
| 5 | 按产品需要调整交互、会话参数、设备控制和提示音 | 6.3 到 6.6 |
| 6 | 样机验证后进入量产烧录 | 第 8 章 |
1.2 模组与板型
本方案为单芯片方案:AC791N 同时负责音频、联网和业务逻辑。联网方式为 Wi-Fi,配网入口为 BLE。
| 类别 | 参数 |
|---|---|
| 主控 | 杰理 AC791N |
| 片内 Flash | 8 MB |
| SDRAM | 2 MB |
| 联网 | Wi-Fi,BLE 仅用于配网 |
| 音频编码 | G.722,16 kHz、单声道、16 bit,每帧 20 ms(640 字节) |
| 回声消除 | 本地 AEC,参考信号默认走硬件回采 |
| 离线唤醒 | 默认开启,唤醒词「小维小维」 |
型号、电气特性、引脚定义等详细参数见模组硬件技术规格书,请联系百度获取。
板级配置由构建变量 BOARD 选择:默认板型已内置板级脚位、按键、调试口、功放 MUTE 等完整配置;BOARD=NONE 为通用板,不指定板级脚位,需自行补充板级配置(参考 board/wl82/board.c 与 app_config.h)。
1.3 软件能力
云端能力(详见 大模型实时互动功能特性)
| 能力 | 说明 |
|---|---|
| 语音识别(ASR) | 流式识别,支持普通话、中英混合,以及广东话、四川话等 8 种方言和英语、日语等 16 种外语;VAD 由云端判断;支持关键词增强(见 关键词增强最佳实践) |
| 大模型对话(LLM) | 角色人设、开场白、多轮对话 |
| 语音合成(TTS) | 流式合成,多音色可选 |
| Function Call | 按业务自定义设备控制指令,设备执行后回执,云端播报结果;支持执行器,可在 Function 描述中调用 HTTP 接口或检索知识库,把结果用于参数提取(撰写方法见 Function 撰写最佳实践,见 执行器最佳实践) |
| MCP Server 接入 | 通过 MCP Server 扩展云端工具能力(见 MCP Server 接入指南) |
| 知识库 | 在控制台「知识库」上传文档并在「意图设置」配置意图路由,问题命中意图后检索知识库(见 知识库使用最佳实践) |
| 多意图识别 | 一句话里的多个诉求自动拆分,按顺序执行(见 多意图使用最佳实践) |
| 云端音频 3A | 云端回声消除、噪声抑制、自动增益(见 云端音频 3A 最佳实践) |
| 云端音乐 | 点播、暂停、续播,由云端推流,端上解码播放 |
| 多语言 | 支持 8 种方言与 16 种外语,可在控制台开启多语言并按语种配置角色与音色(见 多语言接入) |
| 对话记录与语音调测 | 按用户、实例回溯历史对话;联调时可下载原声及 3A 处理后的音频(见 互动记录) |
设备端能力
| 能力 | 说明 |
|---|---|
| 联网 | Wi-Fi;首次通过 BLE 小程序配网,凭证保存后开机自动连接 |
| 离线唤醒 | 唤醒词「小维小维」 |
| 本地回声消除 | 本地 AEC,播报期间仍可识别人声 |
| 三种交互模式 | 按键说话、唤醒词、连续对话,见 6.3 |
| 实时语音对话 | 流式上行与播放,支持播报中打断 |
| 设备控制 | 基于 Function Call,已内置音量调节和退出对话,可自行扩展 |
| 角色与音色 | 端侧场景内置多个角色和音色(如角色「北极熊」,音色「可爱童音」),可通过语音切换,见 6.4 |
| 本地提示音 | 联网、配网、唤醒应答、异常提示等,见 6.6 |
| 会话管理 | 断网自动重连;无人交互 30 秒(AIAGENT_IDLE_STANDBY_MS)后播报提示并回到待机 |
| 固件升级 | 支持网络 OTA,见 6.8 |
1.4 交付物
| 交付物 | 获取方式 |
|---|---|
| 模组与开发板 | 随货 |
| RTOS 端侧开发套件(全套端侧源码) | 联系百度商务获取,见 3.1 |
杰理 AC791N SDK(子模块 project/jieli/rtos_jieli_ac79) |
随源码提供 |
| 杰理 pi32 编译工具链 | 随杰理 SDK 环境安装 |
| 本文档 | — |
1.5 系统架构
上图是百度 AI 模组(AC79N)系统架构。图中色块对应图例:黄色为百度云端、绿色为 AC791N 端侧主控、蓝色为片内音频链路、灰色为外部设备。
模组内部分工如下:
| 部分 | 负责内容 |
|---|---|
| 音频链路(片内) | 麦克风采集、降噪、本地 AEC、离线唤醒、G.722 编解码,驱动功放输出(图中蓝色子框) |
| 主控 AC791N | Wi-Fi 联网、BLE 配网、对话协议、设备控制、提示音调度;承载数据面/控制面两个 SDK 与一层应用桥(图中绿色盒子) |
| 百度云端 | 语音识别、大模型对话、语音合成、Function Call 下发、云端音乐(图中黄色、粉色盒子) |
AC791N 为单芯片方案:音频处理与联网业务在同一颗芯片上完成,不依赖第二颗语音芯片。端侧没有外部音频通路,音频帧在片内由音频链路编解码后直接送入数据面 SDK;主控 CPU 和内存同时负责语音与联网业务。BLE 仅用于配网,手机配网小程序(图左侧灰色盒子)完成 Wi-Fi 信息注入,配网后 BLE 不再参与对话。
端侧模块与代码对应关系
| 端侧模块 | 代码位置 | 说明 |
|---|---|---|
| 应用层 | project/jieli/aiagent_app/ |
应用桥:唯一同时感知两个 SDK 的文件层,负责配网、联网、按键、场景启停、提示音、OTA |
| AI 交互 SDK(数据面) | aiagent_sdk/ |
WebSocket 实时语音对话:ASR、LLM、TTS、Function Call;core/ 为状态机与协议,platform/jieli/ 为 AC791N 平台 HAL |
| 设备接入 SDK(控制面) | iot_sdk/ |
MQTT 接入设备管理平台:上下线、心跳、互动实例凭据、点播指令;与应用桥 iot_device.c 对接,与数据面 SDK 互不引用 |
| 平台适配层 | aiagent_sdk/platform/jieli/ + 杰理 SDK |
杰理 RTOS(wl82)、Wi-Fi、BLE、录放音等平台能力 |
| 音频链路(片内) | 杰理 SDK 音频服务 + 数据面 SDK 唤醒/录放音 | 麦克风采集、降噪、本地 AEC、离线唤醒,G.722 编解码后送入数据面 SDK |
图中连线说明
| 连线 | 含义 |
|---|---|
| WebSocket 双向语音 / 指令 | 数据面 SDK ↔ 大模型互动服务:实时语音对话与 Function Call 下发(绿色实线) |
| 事件 / FC 回调 | 应用层 ↔ 数据面 SDK:应用层实施设备控制并回执,SDK 下发事件与 Function Call |
| 网络 / 线程 | 数据面 SDK ↔ 平台适配层:经平台完成 WebSocket、Wi-Fi 等底层通信(绿色双向箭头) |
| G.722 帧 | 音频编解码 ↔ 平台适配层:上行编码帧、下行解码帧双向传输,片内直通(单芯片无外部音频通路,蓝色双向箭头) |
| 唤醒事件 | 语音前端 → 应用层:本地唤醒命中后由应用层拉起对话 |
| 增强后语音 | 语音前端 ↔ 音频编解码:降噪、AEC 后的增强语音送入编解码,编解码回送播放参考用于 AEC(蓝色双向箭头) |
| HTTP 鉴权 | 端侧 → 业务服务:设备鉴权、获取互动实例凭据(图中红色虚线) |
| 配网 / 设备管理 / OTA | 小程序(BLE 配网)与客户 IoT / OTA 平台 → 应用层 |
| 云端接入 / 智能体配置 | 客户平台与控制台 → 智能云控制台 / 大模型互动服务:角色音色、FC 模板等云端配置同步 |
2 开发环境搭建
推荐在 Windows 10/11 上开发,也可在 Linux/WSL 下编译。
2.1 安装工具链
| 序号 | 工具 | 用途 | 说明 |
|---|---|---|---|
| 1 | 杰理 pi32 工具链 | 编译 | Windows 默认 C:/JL/pi32,Makefile 使用 C:/JL/pi32/bin;Linux 默认 /opt/jieli/pi32v2/bin |
| 2 | msys64 | 命令行 make |
Windows 下使用 |
| 3 | Code::Blocks(杰理定制版) | 图形化编译 | 加载 SPEED_AGENT.cbp |
| 4 | 杰理下载工具 | 烧录 | make 的 POST-BUILD 也会调用下载脚本 |
Linux/WSL 下链接前先执行 ulimit -n 8096,链接阶段会打开大量文件,句柄不足会导致链接失败。杰理 SDK 的完整说明见杰理文档系统。
2.2 串口日志
| 项 | 说明 |
|---|---|
| 调试口 | PA05(TCFG_DEBUG_PORT) |
| 波特率 | 115200 |
波特率设置不对会显示乱码。
3 获取源码与目录结构
3.1 获取源码
源码由百度提供,包含两部分:
| 部分 | 内容 |
|---|---|
| 本仓库 | 百度端侧 AI 交互 SDK、设备接入 SDK、AC791N 应用代码 |
| 杰理 AC791N SDK | 子模块 project/jieli/rtos_jieli_ac79,提供芯片驱动、RTOS、音频服务和工程文件 |
拿到源码后按下表确认环境:
| 检查项 | 要求 |
|---|---|
| 子模块 | project/jieli/rtos_jieli_ac79 下有完整的杰理 SDK 文件 |
| 仓库位置 | 编译通过 ROOT_PREFIX 回到杰理 SDK 根目录,所以本仓库必须位于杰理 SDK 的 apps/<任意名>/ 下 |
| 软链接 | 杰理 SDK 的 apps/<名>/ 下有 aiagent_sdk、iot_sdk、project/jieli/aiagent_app 三条软链接,指回本仓库 |
| Windows 开发 | 仓库需设置 core.symlinks=true;压缩包解压或直接拷贝后软链接可能失效,需重新创建 |
3.2 目录结构
<仓库根目录>/
├── aiagent_sdk/ # 百度数据面 SDK
│ ├── include/ # 对外头文件:aiagent_engine.h、aiagent_scene.h、aiagent_config.h、aiagent_types.h
│ ├── config/aiagent_credentials.h # 应用凭据(需要修改)
│ ├── core/ # 平台无关内核:状态机、协议、交互模式(一般不改)
│ ├── scenes/scene_ai_toy/ # AC791N 使用的场景:会话参数、Function Call、角色音色
│ ├── platform/jieli/ # AC791N 平台 HAL:WebSocket、录放音、唤醒、设备信息等
│ └── third_party/ # G.722、Mongoose 等第三方库
├── iot_sdk/ # 百度设备接入 SDK
│ └── config/iot_credentials.h # 设备接入凭据(需要修改)
└── project/jieli/
├── aiagent_app/ # AC791N 应用层(二次开发主要改这里)
│ ├── app_main.c # 启动入口
│ ├── aiagent_app.c # 应用桥:联网、按键、场景启停、提示音
│ ├── iot_device.c # 设备接入桥:IoT 上线、指令、点播
│ ├── wakeword_app.c # 离线唤醒应用侧
│ ├── wifi_app_task.c # Wi-Fi 任务
│ ├── hrd_key.c # 按键处理
│ ├── bt_ble/ # BLE 配网服务
│ ├── include/app_config.h # 编译期配置:板级、唤醒、AEC、音量、提示音路径
│ └── board/wl82/ # 构建目录:Makefile、SPEED_AGENT.cbp、board.c
└── rtos_jieli_ac79/ # 杰理 AC791N SDK 子模块
3.3 改哪里、不改哪里
| 需求 | 改动位置 |
|---|---|
| 应用凭据 | aiagent_sdk/config/aiagent_credentials.h、iot_sdk/config/iot_credentials.h |
| 连接方式 | 构建变量 CONN_MODE,见 6.2 |
| 板型 | 构建变量 BOARD,见 1.2 |
| 离线唤醒开关 | 构建变量 WAKEWORD_IMPL |
| 会话参数(招呼语、语种、TTS) | aiagent_sdk/scenes/scene_ai_toy/scene_ai_toy.c、scene_ai_toy_config.h |
| 自定义设备控制(Function Call) | scene_ai_toy.c 的 toy_on_function_call() |
| 角色与音色列表 | scene_ai_toy_config.h |
| 按键、提示音、待机超时 | app_config.h、aiagent_app.c、hrd_key.c |
| AEC、唤醒库参数 | app_config.h 中 CONFIG_HUWEN_* 等宏 |
| 板级引脚、串口 | board/wl82/board.c、app_config.h |
| 固件版本号 | 构建变量 FW_VERSION |
| 平台无关内核、HAL | 一般不改。更换外设或移植时才动 aiagent_sdk/platform/jieli/ |
aiagent_sdk/core/ 不允许 include platform/ 下的任何文件,平台相关类型和 RTOS 接口只能出现在 platform/ 中。
4 编译与烧录
4.1 编译选项
所有选项都是构建变量,写在 make 命令行上。
| 变量 | 可选值 | 默认 | 说明 |
|---|---|---|---|
BOARD |
默认板型 / NONE |
默认板型 | 板级脚位、功放 MUTE、ADC 通道、AEC 回采通道 |
CONN_MODE |
IOT / AKSK / USERSERVER / TEST |
IOT |
连接方式,见 6.2 |
WAKEWORD_IMPL |
HUWEN / NONE |
HUWEN |
离线唤醒;NONE 时不编入唤醒源文件和库 |
FW_VERSION |
如 1.0.1 |
无 | 注入 FIRMWARE_VERSION,随设备上报 |
LINK_AT |
1 / 0 |
1 |
旧版 make 不支持 $(file ...) 时设为 0 |
VERBOSE |
1 |
无 | 回显完整编译命令 |
Makefile 中固定的基线宏,一般不要改:
| 宏 | 作用 |
|---|---|
CONFIG_CPU_WL82 |
选择 AC791N 的 CPU 目录 |
CONFIG_NET_ENABLE=1、CONFIG_BT_ENABLE=1 |
Wi-Fi 与 BLE |
AIAGENT_UPLINK_MUTE_WHILE_TTS=0 |
播报期间上行不静音(全双工) |
AIAGENT_USERSERVER_CFG_IN_URL=0 |
USERSERVER 模式下配置不拼进 URL |
AIAGENT_USERSERVER_DOWNLINK_CBR=1 |
USERSERVER 模式下行使用 CBR |
4.2 编译命令
cd project/jieli/aiagent_app/board/wl82/ ulimit -n 8096 # Linux / WSL 下先执行 make # IOT 模式,带离线唤醒 make CONN_MODE=AKSK # AKSK 联调 make WAKEWORD_IMPL=NONE # 关闭离线唤醒 make FW_VERSION=1.0.1 # 指定固件版本 make clean # 清理
产物与注意事项:
| 项 | 说明 |
|---|---|
| 产物 | cpu/wl82/tools/sdk.elf,符号表在同目录 sdk.map;中间文件在 board/wl82/objs/ |
| 切换配置 | 切换 BOARD、CONN_MODE、WAKEWORD_IMPL 前先 make clean,否则会混入旧宏编出的目标文件 |
| 修改宏 | 只改 -D 宏不会触发增量重编,需先 make clean |
| 自动烧录 | make 的 all 目标在链接后固定执行 POST-BUILD(download.sh),连接的开发板会被直接写入 |
| 生成文件 | pre_build 生成 sdk.ld、sdk_used_list.used、section.txt、download.sh、isd_config.ini。要改链接或下载配置,请改对应 .c 源文件,不要改生成物 |
| 库路径 | 链接库用短路径 SDK_LINK_ROOT(../../../../../aiagent_sdk),不要改成 $(SDK_ROOT);链接器遇到超过 260 字符的路径会报找不到文件 |
| 新增源文件 | 必须同时修改 Makefile 和 SPEED_AGENT.cbp |
4.3 Code::Blocks
打开 project/jieli/aiagent_app/board/wl82/SPEED_AGENT.cbp,选择 Release 后 Build。
| 对比项 | Makefile | SPEED_AGENT.cbp |
|---|---|---|
AIAGENT_CONN_MODE、MG_ARCH 等宏 |
有 | 缺少 |
USE_RTOS、USE_MBEDTLS |
无 | 多出 |
| 板型切换 | BOARD 变量 |
需手工加对应板级宏 |
两条路径的宏集合不一致,编出的固件可能不同。发版请使用命令行编译。
4.4 烧录
| 方式 | 说明 |
|---|---|
make 自动烧录 |
编译完成后由 POST-BUILD 调用下载脚本,开发板需已连接并处于下载模式 |
| 手动烧录 | 使用杰理下载工具,烧录编译生成的固件镜像(文件名见附录 A) |
烧录前建议整片擦除,否则残留的 Wi-Fi 凭证、音量等配置会带到下一台样机。烧录后按 2.2 打开串口,看到启动日志即正常。
4.5 首次上电与配网
设备默认不预置 Wi-Fi。首次使用需通过手机 BLE 小程序写入 Wi-Fi 名称和密码,成功后凭证保存,下次开机自动连接。
| 步骤 | 操作 | 结果 |
|---|---|---|
| 1 | 设备上电,手机打开蓝牙 | — |
| 2 | 双击 KEY_OK | 设备进入配网模式并开始 BLE 广播,播放 NetCfgEnter.mp3 |
| 3 | 微信扫描配网小程序二维码,进入小程序 | — |
| 4 | 在小程序中填写 Wi-Fi 名称和密码,点击「搜索蓝牙设备」,连接后点击「蓝牙设备配网」 | 设备获取 Wi-Fi 信息并自动连接 |
| 5 | 设备拿到 IP 并连上云端 | 联网成功播放 NetCfgSucc.mp3,招呼语「联网成功啦,喊一声“小维小维”就能唤醒我哦。」 |
| 6 | 说「小维小维」唤醒,开始对话 | — |
异常处理:
| 现象 | 提示音 | 处理 |
|---|---|---|
| 配网失败 | NetCfgFail.mp3 |
检查 Wi-Fi 名称和密码后重试 |
| 配网超时 | NetCfgTo.mp3 |
重新双击进入配网 |
| 主动退出 | 再次双击 KEY_OK | 退出配网模式 |
BLE 设备名的 JL 前缀不可修改,否则小程序搜索不到设备;设备名后缀可在 le_net_cfg.c 中调整。配网小程序二维码由百度提供,不在仓库内。
5 云端开通与配置
设备端的对话能力由百度智能云提供。账户和应用在控制台自行创建,License 资源由百度线下下发。
5.1 开通应用与 License
| 步骤 | 操作 | 产出 |
|---|---|---|
| 1 | 注册并登录百度智能云控制台,进入「实时音视频 RTC」 | — |
| 2 | 把账户的用户 ID(控制台右上角头像菜单中查看)提供给百度产品接口人,同时确认采购的模组型号和需要开通的能力 | 百度按「一批一码」下发 License 资源 |
| 3 | 在「大模型实时互动 → 资源列表」确认已收到 License | — |
| 4 | 在「互动应用」中创建应用 | 应用 ID(AppID) |
| 5 | 回到资源列表,点「绑定应用」,填写分给该应用的 License 数量。绑定后不可撤回,按实际需要填写 | — |
| 6 | 点「下载 License」 | License Key |
5.2 配置智能体
在互动应用详情的「智能体配置」和「TTS 文字转语音」中配置:
| 配置项 | 说明 |
|---|---|
| 角色 | 人设、开场白、知识范围;可配置多个,标「默认」的角色生效 |
| 音色 | 播报所用的合成音色 |
| Function Call 模板 | 声明设备支持的控制函数(函数名、参数说明) |
AC791N 端侧场景另有一套本地配置(招呼语、TTS 音色、角色和音色列表),优先级和用法见 6.4。人设和函数描述的质量直接影响对话效果和指令识别率,撰写参考:
6 端侧配置与二次开发
6.1 填写应用凭据
默认 IOT 接入方式:设备经 MQTT 登录百度设备管理平台,由平台下发互动会话凭据。下表各项必须属于同一个应用。
| 项 | 位置 | 来源 |
|---|---|---|
| 应用 ID | iot_sdk/config/iot_credentials.h 的 IOT_APPID |
5.1 步骤 4 |
| MQTT 实例 | 同文件 IOT_MQTT_INSTANCE |
百度下发 |
| MQTT 密码 | 同文件 IOT_MQTT_PASSWORD,与用户名成套下发,必须同步更新 |
百度下发 |
| License Key | aiagent_sdk/config/aiagent_credentials.h 的 AIAGENT_LICENSE_KEY |
5.1 步骤 6 |
| AK / SK | 同文件 AIAGENT_ACCESS_KEY、AIAGENT_SECRET_KEY(仅 CONN_MODE=AKSK 使用) |
控制台 |
/* iot_sdk/config/iot_credentials.h */ #define IOT_APPID "<您的 AppID>" #define IOT_MQTT_INSTANCE "<您的 MQTT 实例>" #define IOT_MQTT_PASSWORD "<您的 MQTT 密码>" /* aiagent_sdk/config/aiagent_credentials.h */ #define AIAGENT_LICENSE_KEY "<您的 License Key>"
| 常见错误 | 现象 |
|---|---|
| AppID 与 MQTT 密码不配套 | MQTT 能连上,但会话对不上 |
| License 未绑定到当前应用 | License 鉴权失败 |
同一款产品的所有设备共用一组凭据,烧录时不需要逐台区分。设备 ID 由固件读取 MAC 生成(12 位大写十六进制,不带冒号),无需在控制台登记;移植时 hal_device_get_device_id() 不要加冒号,否则平台按设备 ID 路由的下发会匹配不到。不要把真实凭据提交到公共仓库。
6.2 连接方式
CONN_MODE |
适用场景 | 会话凭据来源 | 配置位置 |
|---|---|---|---|
IOT(默认) |
量产 | MQTT 登录后由平台下发 | 随 eventAgentCreate 下发,不进 WebSocket URL |
AKSK |
联调 | 设备使用 AK/SK 直接访问 WebSocket | 拼进 WebSocket 请求行 |
USERSERVER |
经用户服务取会话地址 | 用户服务返回 | 拼进请求行(AIAGENT_USERSERVER_CFG_IN_URL=0 时不拼) |
TEST |
内部测试 | 内部测试配置 | 拼进请求行 |
拼进请求行的模式,路径上限约 1023 字节。新增字段前先确认长度,超长时日志只会出现 ws init fail。
6.3 交互模式与唤醒
AC791N 场景默认交互模式为连续对话(AI_TOY_DEFAULT_MODE = AIAGENT_INTERACT_CONTINUOUS)。SDK 支持三种模式:
| 模式 | 枚举 | 端上行为 |
|---|---|---|
| 按键说话 | AIAGENT_INTERACT_PRESS |
按住按键说话,松开发送 |
| 唤醒词 | AIAGENT_INTERACT_WAKEUP |
待机时由唤醒词进入对话 |
| 连续对话(默认) | AIAGENT_INTERACT_CONTINUOUS |
麦克风持续上行,由云端判断开口,播报中可说话打断 |
离线唤醒与待机相关配置:
| 配置 | 位置 | 当前值 | 说明 |
|---|---|---|---|
| 唤醒词 | 唤醒库内置 | 「小维小维」 | — |
| 唤醒应答音 | AIAGENT_WAKE_PROMPT_FILE |
WakeupAck.mp3 |
唤醒后播放 |
| 待机超时 | AIAGENT_IDLE_STANDBY_MS |
30000(30 秒) | 连续对话中无人说话的时长,播报期间不计时;超时后播报告别语并回到静默待机 |
| 待机告别语 | AIAGENT_IDLE_STANDBY_TTS |
我先休息一下,想聊天就喊我小维小维。 | 由云端合成下发,置空串则不播直接收回 |
| 仅唤醒词打断 | AIAGENT_ONLY_WAKEWORD_BREAK |
0 | 1 时在线对话中忽略按键单击打断;0 时按键和说话(云端自动打断)都可打断 |
| 播报期间上行 | AIAGENT_UPLINK_MUTE_WHILE_TTS(Makefile) |
0 | 0 为全双工 |
| 关闭离线唤醒 | make WAKEWORD_IMPL=NONE |
— | 关闭后只能按键或连续对话 |
6.4 调整会话参数
会话参数集中在 aiagent_sdk/scenes/scene_ai_toy/scene_ai_toy.c 的 s_toy_config,默认值定义在 scene_ai_toy_config.h。设备每次建会话时上报云端。
| 字段 | 当前值 | 说明 |
|---|---|---|
tts_sayhi |
「联网成功啦,喊一声“小维小维”就能唤醒我哦。」 | 联网成功后的招呼语(AI_TOY_SAYHI_TEXT) |
lang |
NULL |
识别语种,不填由云端决定;需固定语种时填 zh、en、ja、zh_yue 等 |
| TTS 音色 | AI_TOY_TTS_VOICE_ID |
音色由端侧选择,当前为 1000960;备选「可爱童音」1000382 已注释 |
| TTS 语速、音量 | AI_TOY_TTS_SPEED、AI_TOY_TTS_VOLUME |
均为 1 |
| 音频格式 | 16 kHz、1 声道、16 bit、20 ms | AI_TOY_SAMPLE_RATE 等 |
| 角色 | scene_role |
端侧通过该字段切换,值须与控制台角色名一致 |
端侧内置的角色与音色(可通过语音「切换角色/音色」):
| 类型 | 名称(scene_ai_toy_config.h) |
|---|---|
| 角色 | 北极熊、情感陪伴老师、猪八戒、哪吒 |
| 音色 | 可爱学妹(1000002)、星梦倾诉者(1000201)、苏菲(1000224)、温润女声(1000374)、可爱童音(1000382)、直率少年(1000385)、风铃声线等 |
以下与音频链路配套的字段已调优,改动前必须同时确认云端与解码链路:audiocodec、audio_bitrate、aopt、aoco、cloud_3a_url、tts_enable_fast_send 相关字段、dfda。会话参数写在源码里,修改后需重新编译、烧录。
6.5 实现自定义设备控制
设备控制走 Function Call:云端根据控制台的函数模板识别出函数名和参数,下发给设备;设备执行后回执结果,云端再生成一句话播报。
场景已实现的函数(自定义函数不要与它们重名)
| 函数 | 作用 | 说明 |
|---|---|---|
adjust_volume |
调节音量 | 步长 10,范围 0 到 100,设置值下限 10;回执文案见 AI_TOY_FC_VOLUME_MSG_* |
conversation_exit |
退出对话 | 回执「好的,那我先休息啦,想聊天就喊我小维小维。」,之后回到待机 |
| 角色、音色切换 | 语音切换角色或音色 | 由 function_call_menu 模块处理,列表见 6.4 |
开发步骤
| 步骤 | 操作 | 位置 |
|---|---|---|
| 1 | 在控制台 Function Call 模板中声明函数和参数,例如 set_fan_speed(level),level 为 1 到 3 |
控制台 |
| 2 | 在场景回调中增加分支,按函数名解析参数 | scene_ai_toy.c 的 toy_on_function_call() |
| 3 | 执行业务动作 | 您的业务代码 |
| 4 | 回执结果 | aiagent_engine_send_fc_result() |
/* scene_ai_toy.c:toy_on_function_call() 中增加分支 */
if (strcmp(name, "set_fan_speed") == 0) {
scene_fc_set_fan_speed(session_id, params);
return 1; /* 1 = 已处理 */
}
...
return 0; /* 0 = 交给引擎内置 FC 注册表 */
static void scene_fc_set_fan_speed(const char *session_id, const char *params)
{
hal_json_t json = (params != NULL) ? hal_json_parse(params) : NULL;
int level = 0;
bool ok = false;
if ((json != NULL) && (hal_json_get_int(json, "level", &level) == 0)
&& (level >= 1) && (level <= 3)) {
ok = (my_fan_set_level(level) == 0); /* 您的业务实现 */
}
if (json != NULL) {
hal_json_destroy(json);
}
aiagent_engine_send_fc_result(s_engine, session_id,
ok ? "ok" : "error",
ok ? "档位设置成功" : "档位设置失败");
}
注意事项
| 要点 | 说明 |
|---|---|
| 参数格式 | params 是云端下发的 JSON 字符串,字段名与控制台模板一致 |
| 返回值 | 返回 1 表示已处理;返回 0 交给 SDK 内置逻辑 |
| 回执 | 每次调用都要回执(conversation_exit 除外),否则云端一直等待结果 |
| 线程 | 回调运行在网络接收线程,不能阻塞。串口通信等耗时操作要投递到应用自己的任务,完成后再回执 |
6.6 按键与提示音
按键
默认板型的按键为 KEY_OK(PA0):
| 按键 | 操作 | 行为 |
|---|---|---|
| KEY_OK(PA0) | 双击 | 进入或退出配网模式 |
| KEY_OK(PA0) | 单击 | 待机时唤醒;在线对话中可打断播报(AIAGENT_ONLY_WAKEWORD_BREAK=0 时) |
提示音
提示音文件通过 CONFIG_VOICE_PROMPT_FILE_PATH 指向的资源目录读取,随 -res 打包进固件,源文件在 cpu/wl82/tools/audlogo。缺文件时只降级,不阻断联网或唤醒。
| 文件 | 宏 | 场景 |
|---|---|---|
WakeupAck.mp3 |
AIAGENT_WAKE_PROMPT_FILE |
离线唤醒应答(「我在」) |
NetCfgEnter.mp3 |
AIAGENT_NET_CFG_ENTER_FILE |
进入配网 |
NetCfgSucc.mp3 |
AIAGENT_NET_CFG_SUCC_FILE |
配网成功 |
NetCfgFail.mp3 |
AIAGENT_NET_CFG_FAIL_FILE |
配网失败 |
NetCfgTo.mp3 |
AIAGENT_NET_CFG_TO_FILE |
配网超时 |
NetDisc.mp3 |
AIAGENT_NET_DISC_FILE |
网络断开 |
NetEmpty.mp3 |
AIAGENT_NET_EMPTY_FILE |
未联网时单击或唤醒的应答(「未配网」) |
AgentFailed.mp3 |
AIAGENT_AGENT_FAIL_FILE |
已联网但申请不到对话实例 |
Restart.mp3 |
AIAGENT_WAKEWORD_EXPIRE_FILE |
调试唤醒库到期、重启前的提示 |
替换提示音:用同名文件替换后重新编译、整包烧录,格式保持与原文件一致。
6.7 音频链路与回声消除
| 项 | 说明 |
|---|---|
| 音频格式 | 16 kHz、单声道、16 bit,20 ms 一帧(640 字节) |
| 编码 | 上下行 G.722(当前提交为对照实验配置) |
| AEC | 本地 AEC;云端 3A 可配合使用 |
| 唤醒与上行共用采集 | 上行 PCM 取自唤醒前端,唤醒与上行共享一份数据 |
app_config.h 中的关键宏:
| 宏 | 默认值 | 作用 |
|---|---|---|
CONFIG_HUWEN_LIB_SEL |
HUWEN_LIB_V11 |
唤醒库版本,可选 HUWEN_LIB_RELEASE / HUWEN_LIB_DEMO30 / HUWEN_LIB_V11 |
HUWEN_AEC_ENABLE |
0 | 0 表示库内不做 AEC,近端使用本地 AEC 输出,CPU 上只跑一次 AEC |
CONFIG_UPLINK_PCM_FROM_WAKEWORD |
1 | 1 表示上行 PCM 取自唤醒前端 |
CONFIG_REC_AEC_HW_REF |
1 | 本地 AEC 参考信号走硬件回采(喇叭经 ADC 采回) |
CONFIG_HUWEN_MIC_CHANNEL_MAP、CONFIG_HUWEN_REC_CHANNEL_MAP |
按板型 | 麦克风与回采通道映射;回采通道是交错缓冲中的某一路,不一定是最后一路 |
调试库 HUWEN_LIB_DEMO30 约 30 到 40 分钟后会停止回调,唤醒静默失效。固件内置到期看护,到期前播报提示并自动重启;换正式库后看护自动关闭。
6.8 固件升级
| 项 | 说明 |
|---|---|
| 升级方式 | 网络 OTA,由设备管理平台下发 |
| OTA 包文件 | 必须使用 db_update_files_data.bin,上传前改名为 update-ota.ufw |
| 禁止使用 | jl_isd.ufw,用它升级会失败 |
| 版本号 | make FW_VERSION=x.y.z 注入,随设备上报 |
6.9 进阶使用
切换交互模式:设备支持按键说话、唤醒词、连续对话三种交互模式,默认连续对话,端侧切换方式见 6.3;三种模式的原理与选择方法见 语音对话模式最佳实践。
接入知识库:在控制台「知识库」上传文档,再到「意图设置」配置意图路由,问题命中意图后才会检索知识库。详见 知识库使用最佳实践。
多语言接入:支持广东话、四川话等 8 种方言和英语、日语等 16 种外语。端侧在 6.4 的 lang 字段中指定语种(如广东话 zh_yue、日语 ja),并在控制台开启多语言、按语种配置角色与音色。详见 多语言接入。
互动记录及语音调测:「互动记录 → 对话记录」保存每轮交互的上下行文本与语音,可按用户、实例 ID 回溯试听;产品的喇叭、麦克风和腔体与开发板不同时,可在「互动记录 → 语音调测」中新增调测设备,对话一轮后下载原声及 3A 处理后的音频,对比定位问题环节。详见 互动记录。端侧效果欠佳时,也可以配合开启云端 3A 做回归验证,见 6.7。
更多场景实现:
| 场景 | 说明 | 参考 |
|---|---|---|
| 实时语音翻译 | 音频实时识别并翻译,支持智能断句和译文播报 | 实时语音翻译最佳实践 |
| 会议纪要 | 通话中实时收集识别文本,结束后生成全文摘要、分段摘要、发言人观点和待办事项 | 在线会议纪要最佳实践 |
更多功能和场景的进阶用法,参考官网 最佳实践。
7 调试
7.1 查看日志
日志从调试口输出,参数见 2.2。排查时先按 TAG 过滤到对应模块。
| TAG | 模块 |
|---|---|
[AIAGENT_APP] |
应用桥:联网、配网、按键、唤醒、场景启停 |
WW_APP |
离线唤醒应用侧 |
IOT_DEVICE、IOT_CLIENT、IOT_LINK、IOT_AGENT、IOT_HB |
设备接入:MQTT 上线、互动实例、心跳、点播 |
LIC |
License 鉴权 |
CONN、HAL_WS |
WebSocket 建连与收发 |
SM、DISP |
对话状态机、下行消息分发 |
推荐排查顺序
| 顺序 | 检查项 | 看什么 |
|---|---|---|
| 1 | 启动 | 串口是否有启动日志,板型和串口是否冲突 |
| 2 | 联网 | Wi-Fi 是否连上、是否获取 IP |
| 3 | 接入 | IOT 模式看 MQTT 是否上线;AKSK 模式看签名参数 |
| 4 | 鉴权 | LIC 是否通过 |
| 5 | 对话 | WebSocket 是否建立,ASR、LLM、TTS 下行是否到达 |
| 6 | 音频 | 上行有无数据,下行播放有无欠载 |
| 7 | 业务 | Function Call、音乐、音量 |
7.2 常见问题
| 现象 | 关键日志(TAG) | 排查方向 |
|---|---|---|
| 设备一直连不上云端 | IOT_DEVICE、LIC |
Wi-Fi 是否连上;CONN_MODE 与凭据是否匹配;IOT_APPID、MQTT 密码、License 是否属于同一应用 |
| MQTT 连上但没有对话 | IOT_DEVICE、IOT_AGENT、LIC |
appid 与 MQTT 密码是否配套;IOT_DEVICE、LIC 日志是否异常 |
| License 鉴权失败 | LIC |
License 未下发、未绑定当前应用,或该应用分到的 License 已用完 |
| 配网后不能联网 | AIAGENT_APP |
确认 Wi-Fi 名称与密码无误;必要时再次进入配网覆盖凭证 |
| 小程序搜不到设备 | AIAGENT_APP |
先双击 KEY_OK 进入配网模式;BLE 设备名的 JL 前缀不能改 |
| 未联网时唤醒只听到「未配网」 | AIAGENT_APP |
设备没有 Wi-Fi 凭证,先配网 |
| 联网后唤醒只听到对话实例申请失败提示 | IOT_AGENT |
已联网但申请不到互动实例,检查凭据与云端应用状态(AgentFailed.mp3) |
| 唤醒没反应 | WW_APP |
确认编译时未关闭 WAKEWORD_IMPL;确认调试唤醒库是否已到期 |
| 唤醒突然失效,唤醒库 CPU 占用骤降 | WW_APP |
调试库 HUWEN_LIB_DEMO30 到期停止回调,换正式库 |
| 播报中说话没有打断 | — | 确认 AIAGENT_UPLINK_MUTE_WHILE_TTS 为 0;AIAGENT_ONLY_WAKEWORD_BREAK 是否为 1 |
| 自说自话(播报被自己识别) | — | 核对 AEC 回采通道配置;CONFIG_REC_AEC_HW_REF 与板型是否匹配 |
| 上行有杂音或卡顿 | — | 用 CONFIG_UPLINK_PCM_FROM_WAKEWORD 做 A/B;唤醒前端出数率曾测得仅约 80%(25.6 KB/s) |
| 对话中突然断开,日志出现 ping_timeout | CONN、HAL_WS |
Wi-Fi 接收卡死:设备只发不收超过 96 秒,日志出现 No BEACON,CPU 空闲率低于 10%。同时核对 WS_DEAD_RECOVER_MS(20 秒)小于 DNS 最坏耗时(34 秒)导致的重建连接相撞 |
| WebSocket 被 RST | CONN、HAL_WS |
TLS nonce 复用会导致 RST;FIN 之后的迟到写入也会批量 RST。先区分是 TLS Alert 还是 EOF |
| Function 调用无回应 | SM、DISP |
是否已回执;回调是否阻塞了网络接收线程 |
ws init fail |
CONN、HAL_WS |
AKSK、USERSERVER、TEST 模式下 URL 超过约 1023 字节,检查新增字段长度 |
| 改宏后行为不变 | — | -D 宏改动不会触发增量重编,先 make clean |
| IDE 中改动编译后不生效 | — | 打开的文件可能未保存,编译前在磁盘上核对改动是否落盘 |
snprintf 格式报错 |
— | 该库不支持 %.*s,改用其他写法 |
8 出厂烧录
不同阶段用不同的烧录方式,写入的都是同一份编译产物。
| 阶段 | 烧录方式 |
|---|---|
| 开发板调试 | make 自动下载,或杰理下载工具,见 4.4 |
| 小批量试产 | 自行烧录,见 8.2 |
| 大批量量产 | 交工厂自动化产线代烧,见 8.3 |
8.1 量产镜像
| 文件 | 说明 |
|---|---|
cpu/wl82/tools/sdk.elf |
带符号的链接产物,用于定位问题 |
| 下载脚本生成的整机镜像 | 用于整片烧录(文件名见附录 A) |
发版前必须完成:
| 检查项 | 要求 |
|---|---|
| 唤醒库 | 切换为正式库。需同时修改三处:CONFIG_HUWEN_LIB_SEL、构建侧链接的正式库 .a、HAL 中的双回调 API;缺一处则到期看护仍生效或链接失败 |
| 连接方式 | 保持默认 IOT |
| 版本号 | make FW_VERSION=x.y.z,并记录对应源码提交 |
| 凭据 | 确认真实凭据已按产品配置,且未提交到公共仓库 |
| 留档 | 每个发布版本保留一份整机镜像、sdk.elf 和源码版本记录 |
8.2 小批量自行烧录
模组贴到产品板后,用杰理下载工具烧录整机镜像。接线和下载模式对应的管脚见硬件技术规格书,产品板上建议预留测试点。
| 要求 | 说明 |
|---|---|
| 先整片擦除 | 否则残留的 Wi-Fi 凭证、音量等设置会带到成品里 |
| 写后校验 | — |
| 成功判据 | 重新上电后能看到启动日志,并播放开机或未配网提示音 |
8.3 大批量工厂代烧
交给工厂的材料
| 材料 | 说明 |
|---|---|
| 整机镜像 | 及对应的版本记录 |
| 烧录参数 | 芯片 AC791N,使用杰理下载工具,先整片擦除,写后校验 |
| 判定标准 | 烧录后逐台产测,下表全部通过 |
产测项
| 产测项 | 操作 | 通过标准 |
|---|---|---|
| 供电 | 按规格书接电源,测输入电压 | 电压在规格范围内 |
| 喇叭 | 重新上电,听提示音 | 正常启动,声音清晰,没有破音、杂音 |
| 麦克风 | 配网后说「小维小维」 | 有应答提示音,能正常对话 |
| 按键 | 按 6.6 按键说明操作(单击、双击 KEY_OK) | 按键有对应响应 |
附录 A 参考资料
| 资料 | 链接 | |
|---|---|---|
| 百度智能云控制台 | https://console.bce.baidu.com/ | |
| 大模型实时互动官方文档 | https://cloud.baidu.com/doc/RTC/s/cmadw0u0z | |
| 大模型实时互动功能特性 | https://cloud.baidu.com/doc/RTC/s/Am919xgbc | |
| 最佳实践总览 | https://cloud.baidu.com/doc/RTC/s/zmok257u5 | |
| 语音对话模式最佳实践 | https://cloud.baidu.com/doc/RTC/s/9mj8k5zat | |
| 人设 Prompt 撰写最佳实践 | https://cloud.baidu.com/doc/RTC/s/jmhcsb8te | |
| Function 撰写最佳实践 | https://cloud.baidu.com/doc/RTC/s/Jmowue620 | |
| 关键词增强最佳实践 | https://cloud.baidu.com/doc/RTC/s/Gmvhj8ls7 | |
| 执行器最佳实践 | https://cloud.baidu.com/doc/RTC/s/tmtmptm7y | |
| MCP Server 接入指南 | https://cloud.baidu.com/doc/RTC/s/Emmd44mbi | |
| 知识库使用最佳实践 | https://cloud.baidu.com/doc/RTC/s/Fmnraroa4 | |
| 多意图使用最佳实践 | https://cloud.baidu.com/doc/RTC/s/3mv4uppzm | |
| 多语言接入 | https://cloud.baidu.com/doc/RTC/s/Kmg4p7vii | |
| 云端音频 3A 最佳实践 | https://cloud.baidu.com/doc/RTC/s/jmipg7gxi | |
| 互动记录 | https://cloud.baidu.com/doc/RTC/s/rmnicssqd | |
| 实时语音翻译最佳实践 | https://cloud.baidu.com/doc/RTC/s/Lmn32ptkj | |
| 在线会议纪要最佳实践 | https://cloud.baidu.com/doc/RTC/s/mmpcad1mm | |
| 杰理文档系统 | https://doc.zh-jieli.com/ |
评价此篇文章
