Bunkws 中文使用文档-v1.5*

目录*

Bunkws 介绍
版本历史
使用本地服务器搭建 BunKws 环境方法
使用云服务器搭建 BunKws 环境方法
Bunkws 工程说明
Bunkws 训练一个新的项目教程
Bunkws 使用自有指令词数据

Bunkws 介绍*

简介：*

Bunkws 是杭州国芯微自研的一款端到端唤醒词训练框架，其独创的从**"数据生成->模型训练->测试报告输出"**全链路自动化框架，让零算法基础的开发者也能完成从训练到芯片级模型落地，开启智能硬件开发的极简时代。

视频教程：

BunKws训练平台使用教程_本地服务器版本: https://www.bilibili.com/video/BV1pJjwzKE5K

BunKws训练平台使用教程_云服务器版: https://www.bilibili.com/video/BV1A6M7zbEpZ

核心特性：*

端到端唤醒词训练框架
支持中文 && 英文两种语种的模型
超轻量级模型，NPU编译器编译后模型大小约150KB、300KB

支持芯片：*

8002B（低功耗）
8002D（非低功耗）
GX8005
GX8006

目标用户：*

无算法背景的软件工程师

核心优势：*

一键式自动化流程：数据生成 → 数据准备 → 模型训练 → NPU部署文件生成 → 测试报告输出

版本历史*

版本号	更新日期	修改内容
v1.0	2025-03-26	初始发布版本
v1.1	2025-03-31	解决单个模型训练内存占用过大导致无法同时训练两个模型的问题
v1.2	2025-04-10	修复bug
v1.3	2025-04-28	增加用户自有语料训练流程
v1.4	2025-05-19	增加 GX8005/GX8006 系列芯片支持
v1.5	2025-06-06	更新使用云服务器搭建环境的方法

使用本地服务器搭建 BunKws 环境方法*

使用本地服务器搭建 BunKws 环境，需要用户自己准备带如下配置的服务器或者高配电脑，具体环境配置需要满足如下要求。

系统要求：*

最低配置：*

系统: ubuntu-18.04
CPU: x86_64 32核
内存: 128GB
存储: 4T-SSD
GPU: 2080Ti
CUDA版本: > 11.0

注意： 1. Bunkws 当前已适配过 Tesla P40、 2080Ti、4090Ti 显卡，其他显卡我们暂未验证。 2. 要求存储硬盘是SSD，如果是机械硬盘，那么训练速度会慢八倍左右。

推荐显卡及驱动配置：*

2080Ti/4090Ti
NVIDIA-SMI驱动版本: 525.105.17
CUDA版本: 12.0
Tesla P40
NVIDIA-SMI驱动版本: 550.90.07
CUDA版本: 12.4
注意：驱动版本的确定，需要根据系统版本，显卡型号和 CUDA 版本来确定，搜索方法请参考视频教程

Bunkws 安装及环境配置*

步骤一、Bunkws 相关文件下载*

Bunkws 相关文件均放置在一个 ftp 服务器上，并对外开源，用户只要登入该服务器，下载如下相关文件即可。
ftp 链接: 请联系我们的业务
用户名: 请联系我们的业务
密码: 请联系我们的业务

需下载文件：

 bunkws.tar.gz                    # Bunkws 框架核心文件
 corpus.tar.gz                    # Bunkws 语料库（比较大）
 Miniforge3-Linux-x86_64.sh        # 轻量级的Python环境管理工具安装脚本
 py36_tf115.tar.gz                # Python3 环境
 py37_tf114.tar.gz                # python3 环境
 th_12.tar.gz                     # python3 环境

下载命令

wget --ftp-user=test --ftp-password=test@1234 ftp://ftp.nationalchip.com/bunkws.tar.gz .
wget --ftp-user=test --ftp-password=test@1234 ftp://ftp.nationalchip.com/corpus.tar.gz .
wget --ftp-user=test --ftp-password=test@1234 ftp://ftp.nationalchip.com/Miniforge3-Linux-x86_64.sh .
wget --ftp-user=test --ftp-password=test@1234 ftp://ftp.nationalchip.com/py36_tf115.tar.gz .
wget --ftp-user=test --ftp-password=test@1234 ftp://ftp.nationalchip.com/py37_tf114.tar.gz .
wget --ftp-user=test --ftp-password=test@1234 ftp://ftp.nationalchip.com/th_12.tar.gz .

注意：如果目标系统没有 wget 可以参照如下命令安装

sudo apt update          # 更新软件源
sudo apt install wget    # 安装 wget

步骤二、安装显卡驱动*

查看是否已经安装 NVIDIA 驱动

nvidia-smi -L

# 如下打印表示没安装
Command 'nvidia-smi' not found, but can be installed with:

apt install nvidia-340               # version 340.108-0ubuntu5.20.04.2, or
apt install nvidia-utils-390         # version 390.157-0ubuntu0.20.04.1
apt install nvidia-utils-450-server  # version 450.248.02-0ubuntu0.20.04.1
apt install nvidia-utils-470         # version 470.256.02-0ubuntu0.20.04.1
apt install nvidia-utils-470-server  # version 470.256.02-0ubuntu0.20.04.1
apt install nvidia-utils-535         # version 535.183.01-0ubuntu0.20.04.1
apt install nvidia-utils-535-server  # version 535.230.02-0ubuntu0.20.04.3
apt install nvidia-utils-550-server  # version 550.144.03-0ubuntu0.20.04.1
apt install nvidia-utils-565-server  # version 565.57.01-0ubuntu0.20.04.2
apt install nvidia-utils-570-server  # version 570.86.15-0ubuntu0.20.04.5
apt install nvidia-utils-435         # version 435.21-0ubuntu7
apt install nvidia-utils-440         # version 440.82+really.440.64-0ubuntu6
apt install nvidia-utils-418-server  # version 418.226.00-0ubuntu0.20.04.2

咨询管理员以安装其中一个软件。

查看显卡型号

sudo lshw -C display #命令
[sudo] liushk 的密码：
  *-display
       description: VGA compatible controller
       product: G200eR2
       vendor: Matrox Electronics Systems Ltd.
       physical id: 0
       bus info: pci@0000:0a:00.0
       version: 01
       width: 32 bits
       clock: 33MHz
       capabilities: pm vga_controller bus_master cap_list rom
       configuration: driver=mgag200 latency=0 maxlatency=32 mingnt=16
       resources: irq:19 memory:90000000-90ffffff memory:91800000-91803fff memory:91000000-917fffff memory:c0000-dffff
  *-display UNCLAIMED
       description: 3D controller
       product: GP102GL [Tesla P40]   #显卡型号
       vendor: NVIDIA Corporation
       physical id: 0
       bus info: pci@0000:82:00.0
       version: a1
       width: 64 bits
       clock: 33MHz
       capabilities: pm msi pciexpress cap_list
       configuration: latency=0
       resources: iomemory:3f00-3eff iomemory:3f80-3f7f memory:c8000000-c8ffffff memory:3f000000000-3f7ffffffff memory:3f800000000-3f801ffffff

在 NVIDIA 官网上寻找适配的驱动版本
NVIDIA 官网:
在目标系统上安装 NVIDIA 显卡驱动
如下以我电脑为例子，安装如下：
- Tesla P40
- NVIDIA-SMI驱动版本:
  - 推荐：550.90.07
- CUDA版本:
  - 推荐：12.4

#禁用默认驱动
sudo vi /etc/modprobe.d/blacklist.conf，将 blacklist nouveau 这句加到该文件中
sudo update-initramfs -u
#重启目标系统
sudo reboot
#安装 NVIDIA 显卡驱动
sudo ./NVIDIA-Linux-x86_64-550.90.07.run  -no-x-check -no-nouveau-check -no-opengl-files
# 重启目标系统
sud reboot

步骤三、解压 Bunkws 工程*

解压主工程文件
```
tar xzvf bunkws.tar.gz -C ~
```
解压 Bunkws 语料库

 tar xzvf corpus.tar.gz -C ~

步骤四、安装及迁移工作环境：*

安装miniforge3

./Miniforge3-Linux-x86_64.sh
source ~/.bashrc
#解压环境
tar xzvf py37_tf114.tar.gz -C ~/miniforge3/envs
tar xzvf th_12.tar.gz -C ~/miniforge3/envs
tar xzvf py36_tf115.tar.gz -C ~/miniforge3/envs

#设置 miniforge3 环境变量
#把如下内容，追加到 ~/.bashrc 文件中，并且把 `liushk` 改成自己的目标系统用户名
# >>> conda initialize >>>
# !! Contents within this block are managed by 'conda init' !!
__conda_setup="$('/home/liushk/miniforge3/bin/conda' 'shell.bash' 'hook' 2> /dev/null)"
if [ $? -eq 0 ]; then
    eval "$__conda_setup"
else
    if [ -f "/home/liushk/miniforge3/etc/profile.d/conda.sh" ]; then
        . "/home/liushk/miniforge3/etc/profile.d/conda.sh"
    else
        export PATH="/home/liushk/miniforge3/bin:$PATH"
    fi
fi
unset __conda_setup
# <<< conda initialize <<<

#添加完成后生效
source ~/.bashrc

配置 Torch 模型缓存及路径适配

mkdir -p ~/.cache/
cp -r bunkws/envs/torch ~/.cache/
#路径适配修改

sed -i "s|/home/sundy|$HOME|g" ~/miniforge3/envs/py37_tf114/bin/pip
sed -i "s|/home/sundy|$HOME|g" ~/miniforge3/envs/py37_tf114/bin/gxnpuc
sed -i "s|/home/sundy|$HOME|g" ~/miniforge3/bin/conda

激活环境安装依赖库

source ~/.bashrc

conda activate py37_tf114
cd bunkws/tools/logfbank
python setup.py develop
sudo apt install ffmpeg

使用云服务器搭建 BunKws 环境方法*

使用云服务器搭建 BunKws 环境，不需要用户准备或者购买实体服务器，电脑等硬件，直接租用指定的云服务商的硬件平台，拷贝我们指定的镜像就可以快速获得 BunKws 环境。
使用该方法就可以不需要过多的搭建环境，一些软件安装、可以直接使用镜像中的即可。

云服务简介*

国芯微使用优云智算平台开源 BunKws镜像，用户可以在该平台上直接部署镜像来获得 BunKws 使用环境，优云智算是UCloud优刻得（优刻得科技股份有限公司）旗下的GPU算力租赁平台，致力于为AI、深度学习、科学计算相关客户提供丰富多样的算力资源。国芯微的开源训练平台 alchemy 和 bunkws 已制作成镜像，发布在优云智算上，客户有需求可以直接使用。

Bunkws 安装及环境配置*

步骤一、账户准备*

注册账户：按照提示注册账户即可，无任何特殊操作
地址：https://console.compshare.cn/
账户充值：如果账号内余额不足，需要先充值。
地址：https://console.compshare.cn/uaccount/recharge

步骤二、获取镜像，创建实例*

点击：控制台->部署实例

部署实例-1

社区镜像->镜像名称输入想要部署的镜像名，如 bunkws

选择镜像-2

选择GPU、CPU 配置

选择配置-3

选择磁盘空间

选择磁盘空间-4

选择付款方式为包时

付费-5

步骤三、远程登入，进入环境*

按上述操作创建实例后，就会自动生成一个登入口令，使用 ssh 远程登入该云服务器，命令和密码从控制台复制

在终端中登入远程服务器

sshlogin

登入后，后续操作和本地服务器没有区别，都是使用 linux 终端操作。

补充说明：*

保存镜像*

如果用户在国芯微发布镜像的基础上，修改了一些内容，需要自己私有保存，可以将当前环境重新制作成镜像，这样就算后面删除实例，也能保存下自己的修改。镜像制作完成后，下次部署实例时就可以选择该镜像。

制作镜像

删除实例*

注意：优云智算平台我们之前部署实例时选择了“包时”，实例使用完成后，我们需要删除该实例，否则会一直计费。计费规则是，只要创建实例就开始计费，不管有无使用，故此如果自己长期不使用该训练平台建议删除该实例，当然删除实例后自己的修改也会被抹除，如果要保存自己的私有修改，可以自己创建一个新的镜像，具体规则可以参考优云智算平台文档
在实例列表中找到自己创建的实力，点击操作，选择删除即可

删除实例

Bunkws 工程说明*

目录结构：*

liushk@SPD-R730xd:~/bunkws$ tree -L 1
.
├── egs                 #用户训练工程主目录
├── envs
├── local               #本地化脚本
├── README.md
├── tools               #核心工具链
└── bunkws               #唤醒词引擎

工程示例：*

中文项目：earphone
该项⽬下暂有两个版本，根据需要选取
- v0.1.0 版本，npu 编译后⼤⼩为 300KB，用于非低功耗 GX8002D 芯片的模型
- v0.1.1 版本，npu 编译后⼤⼩为 120KB，用于低功耗 GX8002 芯片的模型
英文项目：hi_ella
该项⽬下暂只有一个版本
- v0.1.0 版本，npu 编译后⼤⼩为 150KB ，用于低功耗 GX8002 芯片的模型

Bunkws 训练一个新的项目教程*

步骤一、新建项目工程：*

拷贝/新建新工程方法

# 我的 home 路径如下: /home/liushk
# 那么我的通用数据存储路径: /home/liushk/corpus

#进入示例模版工程
cd ~/bunkws/egs
cp -r earphone xxxx  # 中文项目
# 或
cp -r hi_ella xxx   # 英文项目

例如:
我本次训练的是一个中文项目，名称我取名为aiot，根据工程示例工程的解释，我可以选择 v0.1.0 版本，npu 编译后⼤⼩为 300KB 或者 v0.1.1 版本，npu 编译后⼤⼩为 120KB
我本次项目空间大，可以选择大一点模型，那么我选择 v0.1.0 版本，如下所有介绍均以该项目为例，操作如下：
```
#进入示例模版工程
cd ~/bunkws/egs
cp -r earphone aiot  # 中文项目
```

步骤二、配置数据存储路径*

在前面的下载相关文件步骤中，下载过通用语料 corpus.tar.gz，并且在解压 BunKws 工程步骤中已经解压在 home目录下，那么我的配置路径方法如下：

# 我的 home 路径如下: /home/liushk
# 那么我的通用数据存储路径: /home/liushk/corpus
# 我选择该新项目训练过程中产生的数据，存储路径为 /home/liushk/corpus/kws/aiot
# 创建模型训练数据存储路径
 mkdir -p /home/liushk/corpus/kws/aiot
cd ~/bunkws/egs/aiot/v0.1.0
# 配置路径

vim run.sh
#把该文件中如下内容修改成如下

corpus_dir=/home/liushk/corpus #通用语料路径
project_dir=/home/liushk/corpus/kws/aiot

步骤三、创建需要的唤醒词、指令词*

在上述步骤中，我们创建了一个/home/liushk/corpus/kws/aiot 目录用于存储本项目的所有生成数据集过程中的语料，Bunkws 框架定义，在 project_dir 路径下，回自动读取 cmd.txt 内容作为唤醒词、指令词
创建方法如下：

# 我的 home 路径如下: /home/liushk
# 那么我的通用数据存储路径: /home/liushk/corpus
# 我选择该新项目训练过程中产生的数据，存储路径为 /home/liushk/corpus/kws/aiot


vim  /home/liushk/corpus/kws/aiot/cmd.txt

#写入格式如下，一个指令、唤醒词一行，以换行分割，除唤醒词、指令词以外不要有其他内容

你好小树
打开灯光
关闭灯光

步骤四、运行 Bunkws 训练目标模型，检查报告输出*

运行训练脚本
一键训练 (一键完成，数据生成、数据准备、模型训练、模型测试和部署)
```
 ./run.sh  # 一键训练
```

分阶段执行（可以自主控制运行步骤，主要为了在微调迭代使用，减少不必要的时间，但是请注意，步骤顺序有前后依赖，数据准备好，不可训练）

 # 数据生成
 ./run.sh --stage -1 --stop_stage -1
 # 数据准备
 ./run.sh --stage 0 --stop_stage 1
 # 模型训练
 ./run.sh --stage 2 --stop_stage 2
 # 模型测试和部署
 ./run.sh --stage 3 --stop_stage 3

Bunkws 运行完成之后，会输出几份模型和测试报告，根据测试报告结果，挑出你最认可的模型即可
注意: 报告输出路径，会在运行结束时候打印出来，报告有打印输出，也有详细的 xlsx表格根据需要获取即可

输出文件说明：*

模型文件:
情况一、选择 v0.1.0 版本训练
- 该版本仅支持 GX8002D 芯片
- 模型输出：model_grus.h
情况二、选择 v0.1.1 版本训练
- 该版支持 GX8002、GX8005/GX8006 芯片
- GX8002 模型输出：model_grus.h
- GX8005/GX8006 模型输出：model_fornax.h(模型)，mean_std.txt (归一化参数)
测试报告: report.xlsx
关键词列表: keyword.txt

如何使用自有指令词数据, 进行训练*

自有数据质量要求
每条指令的 wav 要求:
- 至少300人，每人10句，总数至少3000句
- 男女比例 1：1
- 地域分布要均衡
- 年龄段分布也要均衡，如特殊项目要倾斜，比如儿童玩具项目，那么儿童比例增加
采样率为16000
单通道
int 16bit 或float 32bit
数据尽量采用专业高保真麦克风录制，或手机录制, 录制的软件不要过任何信号处理算法
录制的数据，尽量不要有噪声(底噪也不要有), 信噪比大于20dB
指令词数据的目录形式, 假设当前指令词的父目录为aito，指令词有两个: a和b, 每个指令词有2条wav，则目录形式为:

aito
├── a
│   ├── 1.wav
│   └── 2.wav
└── b
    ├── 1.wav
    └── 2.wav

2 directories, 4 files

如何在脚本里加入自有指令词数据：
假设在earphone/v0.1.0工程下，添加自有数据，aito的绝对路径：/home/liushk/aito
- 打开egs/v0.1.0/run.sh编辑如下字段
```
 vi run.sh
 corpus_type=hifi    #说明语料类型（高保真）
 hifi_corpus=/home/liushk/aito #添加语料路径
```

运行 run.sh

 ./run.sh   # 运行训练模型，和上述正常 “一键训练” 模型流程一致

Bunkws 中文使用文档-v1.5*

目录*

Bunkws 介绍*

简介：*

核心特性：*

支持芯片：*

目标用户：*

核心优势：*

版本历史*

使用本地服务器搭建 BunKws 环境方法*

系统要求：*

最低配置：*

推荐显卡及驱动配置：*

Bunkws 安装及环境配置*

步骤一、Bunkws 相关文件下载*

步骤二、安装显卡驱动*

步骤三、解压 Bunkws 工程*

步骤四、安装及迁移工作环境：*

使用云服务器搭建 BunKws 环境方法*

云服务简介*

Bunkws 安装及环境配置*

步骤一、账户准备*

步骤二、获取镜像，创建实例*

步骤三、远程登入，进入环境*

补充说明：*

保存镜像*

删除实例*

Bunkws 工程说明*

目录结构：*

工程示例：*

Bunkws 训练一个新的项目教程*

步骤一、 新建项目工程：*

步骤二、配置数据存储路径*

步骤三、创建需要的唤醒词、指令词*

步骤四、运行 Bunkws 训练目标模型，检查报告输出*

输出文件说明：*

如何使用自有指令词数据, 进行训练*

步骤一、新建项目工程：*