唤醒词识别算法

REVISION HISTORY¶

Revision No.	Description	Date
1.0.0	Initial release	12/23/2024

1. 概述¶

1.1. 算法说明¶

语音唤醒（Keywords Spotting, KWS）是检测语音流中是否有指定唤醒词的算法。

1.2. 注意¶

唤醒词支持定制，有需要请联系FAE。

1、一般为4个字最佳，过短容误识高，过长不便用户呼叫和记忆；

2、命令词中相邻汉字的声韵母区分度越大越好；

3、符合用户的语言习惯，尽量采用常用说法，内容具体直接；

4、应避免使用日常用语，如：“吃饭啦”；

5、生僻字和零声母字应尽量避免，如“语音识别”中“语音”两个字均为零声母字；

6、命令词中的字最好不要有语气词，如“啊”、“呢”等；

7、应避免使用叠词，如：“你好你好”；

1.3. 模型和命令词列表¶

模型名称	支持命令词
kws_help_call.img	"呼叫手机","救命救命"

2. API 参考¶

2.1. 功能模块API¶

API名称	功能
ALGO_KWS_CreateHandle	创建kws算法句柄
ALGO_KWS_InitHandle	初始化kws算法
ALGO_KWS_GetInputLength	获取kws算法输入的采样点数
ALGO_KWS_SetParams	设置kws算法参数
ALGO_KWS_Run	kws算法运行
ALGO_KWS_DeInitHandle	kws句柄反初始化
ALGO_KWS_ReleaseHandle	释放kws算法资源

2.2. ALGO_KWS_CreateHandle¶

功能

创建kws的句柄。

语法

MI_S32 ALGO_KWS_CreateHandle(KWS_HANDLE* handle);

形参

参数名称描述输入/输出

handle 句柄输出
返回值

返回值结果

0 成功

其他值失败, 参照错误码
依赖
- 头文件: sgs_kws_api.h
- 库文件: libsgsalgo_kws.so/ libsgsalgo_kws.a
举例

无。

2.3. ALGO_KWS_InitHandle¶

功能

初始化kws句柄。

语法

MI_S32 ALGO_KWS_InitHandle(KWS_HANDLE handle, const KwsInit_t init_info);

形参

参数名称描述输入/输出

handle kws句柄输入

init_info 初始化句柄的参数输入
返回值

返回值结果

0 成功

其他值失败, 参照错误码
依赖
- 头文件: sgs_kws_api.h
- 库文件: libsgsalgo_kws.so/ libsgsalgo_kws.a
注意
- KWS算法仅支持16kHz采样率，16bit采样位宽。
举例

无。

2.4. ALGO_KWS_GetInputLength¶

功能

获取每次输入算法样本的个数。

语法

MI_S32 ALGO_KWS_GetInputLength(KWS_HANDLE handle, MI_S32* input_length);

形参

参数名称描述输入/输出

handle kws算法handle 输入

input_length 样本长度输出
返回值

返回值结果

0 成功

其他值失败, 参照错误码
依赖
- 头文件: sgs_kws_api.h
- 库文件: libsgsalgo_kws.so/ libsgsalgo_kws.a

2.5. ALGO_KWS_SetParams¶

功能

设置kws的配置参数

语法

MI_S32 ALGO_KWS_SetParams(KWS_HANDLE handle, const KwsParams_t* params);

形参

参数名称描述输入/输出

handle kws算法handle 输入

params kws算法参数结构体输入
返回值

返回值结果

0 成功

其他值失败, 参照错误码
依赖
- 头文件: sgs_kws_api.h
- 库文件: libsgsalgo_kws.so/ libsgsalgo_kws.a

2.6. ALGO_KWS_Run¶

功能

运行kws算法。

语法

MI_S32 ALGO_KWS_Run(KWS_HANDLE handle, KwsInput_t* srcData, KwsResult_t* results);

形参

参数名称描述输入/输出

handle kws算法handle 输入

srcData kws算法输入数据输入

result kws算法输出结果输出
返回值

返回值结果

0 成功

其他值失败, 参照错误码
依赖
- 头文件: sgs_kws_api.h
- 库文件: libsgsalgo_kws.so/ libsgsalgo_kws.a

2.7. ALGO_KWS_DeInitHandle¶

功能

kws句柄反初始化。

语法

MI_S32 ALGO_KWS_DeInitHandle(KWS_HANDLE handle);

形参

参数名称描述输入/输出

handle kws算法句柄输入
返回值

返回值结果

0 成功

非0 失败，参照错误码
依赖
- 头文件: sgs_kws_api.h
- 库文件: libsgsalgo_kws.so/ libsgsalgo_kws.a

2.8. ALGO_KWS_ReleaseHandle¶

功能

释放句柄。

语法

MI_S32 ALGO_KWS_ReleaseHandle(KWS_HANDLE handle);

形参

参数名称描述输入/输出

handle 算法handle 输入
返回值

返回值结果

0 成功

其他值失败，参照错误码
依赖
- 头文件: sgs_kws_api.h
- 库文件: libsgsalgo_kws.so/ libsgsalgo_kws.a
举例

参考Demo code

3. KWS 数据类型¶

3.1. KWS模块相关数据类型定义¶

数据类型	定义
MAX_KWS_STRLEN	kws算法文件名称最大长度
MAX_KWS_NUM	kws算法最大命令词数目
KwsInit_t	kws算法初始化数据结构体
KwsParams_t	kws算法参数设置结构体
KwsInput_t	kws算法输入数据结构体
KwsResult_t	kws算法输出结构体
KWS_HANDLE	kws句柄

3.2. MAX_KWS_STRLEN¶

说明

定义kws算法文件名称最大长度。
定义
```
#define MAX_KWS_STRLEN 256
```

3.3. MAX_KWS_NUM¶

说明

kws算法最大命令词数目。
定义
```
#define MAX_KWS_NUM 16
```

3.4. KwsInit_t¶

说明

kws算法初始化参数结构体。

定义

typedef struct KwsInit_
{
    MI_U8 ipu_firmware_bin[MAX_KWS_STRLEN];
    MI_U8 kws_model_path[MAX_KWS_STRLEN];
    MI_U8 units_path[MAX_KWS_STRLEN];
    MI_U32 beam_size;
    MI_BOOL create_device;
    MI_BOOL destroy_device;
}KwsInit_t;

成员

成员名称	描述
ipu_firmware_bin	ipu_firmware_bin的路径，无则不用设置
kws_model_path	kws模型的路径
units_path	kws的建模单元
beam_size	beam_search的大小，越大recall越高，误检越高，建议值为10，必须大于0
create_device	是否创建ipu device
destroy_device	是否销毁ipu device

相关数据类型及接口

ALGO_KWS_InitHandle

3.5. KwsParams_t¶

说明

定义kws算法参数结构体。

定义

typedef struct
{
    MI_FLOAT threshold[MAX_KWS_NUM];
    MI_BOOL strict[MAX_KWS_NUM];
    MI_U8 key_words[MAX_KWS_NUM][MAX_KWS_STRLEN];
    MI_U32 words_num;
}KwsParams_t;

成员

成员名称	描述
threshold	kws的阈值，建议值为-8，越大recall越低，误检越低
strict	是否采用严格模型，建议值为true。false时recall高，误检高
key_words	设置命令词，必须采用utf-8的编码格式，查看代码文件是否是uft-8
words_num	命令词的个数

相关数据类型及接口

ALGO_KWS_SetParams

3.6. KwsInput_t¶

说明

定义kws算法输入数据结构体。

定义

typedef struct
{
    void* p_vir_addr;
    MI_S32 sample_rate; //only support 16000
    MI_S32 bit_width;  //only support 16
    MI_S32 channel;    //only support 1
    MI_U16 length;
}KwsInput_t;

成员

成员名称	描述
p_vir_addr	输入数据的地址
sample_rate	输入语音数据的采样率，只支持16k
bit_width	输入语音数据的位宽，只支持short型16bits
channel	语音的通道数，只支持1通道
length	输入数据的长度，和ALGO_KWS_GetInputLength长度保持一致

相关数据类型及接口

ALGO_KWS_Run

3.7 KwsResult_t¶

说明

定义KWS算法的句柄类型。

定义

typedef struct
{
    MI_FLOAT score;
    MI_U8 centence[MAX_KWS_STRLEN];
    MI_U32 id;
}KwsResult_t;

成员

成员名称描述

score 命令词的分值

centence 识别到的命令词

id 属于第几个命令词
注意事项

无。
相关数据类型及接口

ALGO_KWS_Run

3.8. KWS_HANDLE¶

说明

定义kws算法的句柄类型。
定义
```
typedef void* KWS_HANDLE;
```
成员

成员名称描述
注意事项

无。
相关数据类型及接口

ALGO_KWS_CreateHandle

ALGO_KWS_InitHandle

ALGO_KWS_GetInputLength

ALGO_KWS_SetParams

ALGO_KWS_Run

ALGO_KWS_DeInitHandle

ALGO_KWS_ReleaseHandle

4. 错误码 ¶

错误码	数值	描述
E_ALGO_SUCCESS	0	操作成功
E_ALGO_HANDLE_NULL	1	算法句柄为空
E_ALGO_INVALID_PARAM	2	无效的输入参数
E_ALGO_DEVICE_FAULT	3	硬件错误
E_ALGO_LOADMODEL_FAIL	4	加载模型失败
E_ALGO_INIT_FAIL	5	算法初始化失败
E_ALGO_NOT_INIT	6	算法尚未初始化
E_ALGO_INPUT_DATA_NULL	7	算法输入数据为空
E_ALGO_INVALID_INPUT_SIZE	8	无效的算法输入数据维度
E_ALGO_INVALID_LICENSE	9	无效的license许可
E_ALGO_MEMORY_OUT	10	内存不足
E_ALGO_FILEIO_ERROR	11	文件读写操作错误
E_ALGO_INVALID_OUTPUT_SIZE	12	无效的算法输出数据维度

参数名称	描述	输入/输出
handle	kws句柄	输入
init_info	初始化句柄的参数	输入

参数名称	描述	输入/输出
handle	kws算法handle	输入
params	kws算法参数结构体	输入

成员名称	描述
score	命令词的分值
centence	识别到的命令词
id	属于第几个命令词

返回值	结果
0	成功
其他值	失败, 参照错误码

返回值	结果
0	成功
其他值	失败, 参照错误码

返回值	结果
0	成功
其他值	失败, 参照错误码

返回值	结果
0	成功
其他值	失败, 参照错误码