kwsModelAutoDeploy 工具使用指南*
📌 基本信息
- SDK 仓库: http://gitlab.nationalchip.com/nationalchip/voice-wifi-solution/ovp_aiot/
- 工具路径:
tools/kws_model_auto_deploy/- 适用芯片: GX8005 / GX8006
- ⚠️ 访问权限: 内部仓库，请联系国芯微申请权限
1. 工具简介*
kwsModelAutoDeploy 模型自动部署工具，可将训练生成的模型一键部署至 ovp_aiot SDK。
⚠️ 注意事项
当遇到下面情况时需要自行配置，可参考章节 5.2 手动配置模型
-b参数失效- 默认配置不符合自己的硬件配置或实际需求
2. 部署模式选择*
根据模型类型和业务需求，选择对应的部署模式：
| 部署模式 | 适用场景 |
|---|---|
BunKws-DeploymentMode |
纯分类唤醒方案 |
BunKws+CTC-DeploymentMode |
WIFI 大模型方案 |
BunKws+CTC+MP-DeploymentMode |
可配置 + 分类唤醒方案 |
3. 命令参数详解*
3.1 通用参数（所有模式共用）*
./kwsModelAutoDeploy <MODE> [OPTIONS]
| 参数 | 简写 | 说明 | 示例/要求 |
|---|---|---|---|
--inputPath |
-i |
BunKws 输出的模型目录路径 | 目录需包含：keyword.txt, mean_std.txt, model_fornax.h, cmd_id.txt |
--sdkRootPath |
-r |
SDK 根路径（以 ovp_aiot 结尾） |
~/work/ovp/ovp_aiot |
--customerName |
-c |
客户标识 | 仅支持字母/下划线，如 nationalchip |
--projectName |
-p |
项目名称（模型部署子目录） | 仅支持字母/下划线，如 xiaoshu_ai |
--deployVersion |
-dv |
模型版本号 | 默认 v0.1.0，重复时提示覆盖 |
--bulidConfig |
-b |
生成编译配置（使能自动集成） | 无值参数，建议还是自行手动配置 |
--debug |
-d |
调试模式（输出详细日志） | 无值参数，问题排查时启用 |
3.2 输入目录结构要求*
<inputPath>/
├── keyword.txt # 关键词有序列表（不可修改）
├── mean_std.txt # 模型归一化参数（不可修改）
├── model_fornax.h # Fornax 平台导出的模型头文件（不可修改）
└── cmd_id.txt # 模型元信息（阈值、主唤醒词标识、事件ID等）
⚠️ 文件缺失将导致部署失败，请提前校验
4. 使用示例*
4.1 基础部署命令*
# 模式：BunKws+CTC-DeploymentMode
./kwsModelAutoDeploy BunKws+CTC-DeploymentMode \
-i ~/下载/v0.1.1 \
-r ../../../ovp_aiot/ \
-c test \
-p t1 \
-dv v0.1.1 \
-b
4.2 参数速查表*
# 查看主帮助
./kwsModelAutoDeploy -h
# 查看某模式帮助
./kwsModelAutoDeploy BunKws+CTC-DeploymentMode -h
5. 固件编译与烧录*
5.1 词条类型 和 事件 ID 配置*
若模型包含多个唤醒词/指令词，建议修改事件 ID 以区分上报：
-
编辑生成的词表文件：
ovp/vpa/olab_panda/vui/kws_engine/model_fst/bunkws/<customer>/<project>/kws_list.h -
修改示例：
// 格式: {"关键词", {保留}, 保留, 非AEC阈值, AEC阈值, 事件ID, 词条类型} {"小帆小帆", {0}, 1, 666, 333, 101, 1}, // 事件ID = 101，类型1：唤醒词 {"打开设备", {0}, 1, 666, 333, 102, 0}, // 事件ID = 102，类型0：二级指令词⚠️ 注意事项：
- 至少需要有一个唤醒词（词条类型为1），否则无法唤醒
- 唤醒词最好只有一个，不要超过三个，否则误唤醒率会比较高
- 事件 ID 对应串口协议中 离线语音唤醒事件上报（0x08） 命令上报的 ID
- 正常情况下（喇叭未播放时）唤醒效果较差可适当降低 非AEC下阈值 体验测试
- AEC下（喇叭播放时）唤醒效果较差可适当降低 AEC下阈值 体验测试
5.2 手动配置模型*
若烧录后唤醒词未更新，请手动配置：
# 1. 进入 SDK 根目录
cd ../../
# 2. 拷贝基础配置（根据硬件选择 io/ack 方案）
cp configs/lightning/lightning_*_flowctrl.config .config
# 3. 进入菜单配置
make menuconfig
模型配置路径：
Olab Panda Settings
└─> VUI Settings
└─> Enable Keyword Recognition
├─> Model Type Select: general bunkws
├─> Customer Select: <你的 -c 参数>
├─> Model Version Select: <你的 -p 参数> + <你的 -dv 参数>
├─> Language Model Select: model fst bunkws + <你的 -p 参数>
└─> Kws Select: [按需勾选词条]
⚠️ 注意事项：
一些需要和自己板子适配的配置注意对应修改
5.3 编译与烧录*
# === 编译固件 ===
cd ~/work/ovp/ovp_aiot
make clean;make
# === ubuntu 烧录固件 ===
cd tools/bootx
# 参数: <串口号> <波特率>
./flash_nor.sh 0 1000000
🔧 烧录提示
- 确保开发板进入下载模式（通常需按住 BOOT 键的同时按下 Reset 上电）
- 串口号
0对应/dev/ttyUSB0，请根据实际设备调整- windows系统请参考 NCDownloader使用说明
6. 常见问题排查*
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
部署报错 file not found |
输入目录文件缺失 | 检查 inputPath 下 4 个必需文件 |
编译失败 model not found |
-b 失效或手动配置错误 |
执行 make menuconfig 重新选择模型版本 |
| 唤醒词无响应 | 无唤醒类型为1词条 / 阈值过高 | 检查 kws_list.h 中唤醒类型，适当降低阈值 |
| 烧录卡住 | 串口权限 / 波特率不匹配 | sudo chmod 666 /dev/ttyUSB*，尝试降低波特率 |
📬 技术支持
如遇工具异常或模型兼容性问题，请提供：
1. 完整命令及报错日志
2. 模型原文件
3. SDK 版本信息（git log）
联系国芯微语音团队协助排查。