# AIkit命令词识别 Windows SDK 文档

# 1. 离线命令词能力简介

用户对设备（手机、玩具、家电等）说出操作指令（即“命令词”），设备即作出相应的反馈，开启语音交互

支持多实例并发：否

协议类型：同步流式

# 2. 授权说明

授权方式支持【设备授权】

设备授权： 按照设备数和有效期授权，激活设备数达到授权量上限后，新设备将无法继续激活使用。SDK采集多个设备标识按照权重算法生成设备指纹精准标识设备，计量准确。支持所有平台。

在能力首次使用时，需要先激活后方可使用。激活时会获取授权license缓存到设备内部存储中。

在线激活: 在首次使用时，需要将设备联网，SDK初始化时获取授权license激活。设备激活后，即可在无网环境下使用。如果有恢复出厂设置或清空应用缓存等操作，将license清除后，能力将无法正常使用，将设备联网重启应用即可恢复。适用于设备可联网场景，激活过程简单。

# 3. 兼容性说明

类别	兼容范
接口	C++ 接口
网络	设备具备联网条件，可使用在线激活方式，首次使用需要连接网络。
开发环境	建议使用 Visual Studio 进行开发

# 4. SDK包组成

DEMO 中已经集成了SDK，您可以参考DEMO，集成SDK。集成前，请先测通DEMO，了解调用原理。如果您自己代码过于复杂，可以使用一个helloworld项目了解集成过程。

将SDK zip包解压缩，得到如下文件：

Demo //能力SDK Demo、SDK使用说明readme.txt，示例能力调用
SDK //能力SDK，导入SDK库时使用
resource //能力对应模型资源，多能力组合时，resource文件夹中包含多个子文件夹
测试报告 //SDK 测试报告
ReleaseNotes.txt //SDK版本日志

# 5. 接口调用流程

接口调用流程图

# 6. 快速集成指南

# 6.1 导入SDK库

将SDK/libs文件夹（包含libAIKit.so、各能力引擎库）、头文件文件夹include存放到项目中，并在环境变量里添加库路径；

#include "aikit_biz_api.h"
#include "aikit_constant.h"
#include "aikit_biz_config.h"

# 6.2 配置权限

SDK工作路径需要读写权限用于存储日志及授权license，缺少读写权限，能力将无法正常使用。

# 6.3 资源导入

复制resource文件夹中文资源到应用的工作目录，即为SDK初始化中的workDir。该路径需要赋可读、可写的权限。

# 6.4 SDK初始化

在使用能力前，需要首先初始化SDK，使用SDK提供的单能力或组合能力时，SDK均只需要初始化一次。SDK V2.2.13+版本SDK初始化示例代码如下：

AIKIT_Configurator::builder()
      .app()    
         .appID("")
         .apiKey("")
         .apiSecret("")
         .workDir("./") //指定SDK工作路径，此处仅为示例
        .auth()
         .ability("e75f07b62")
        .log()
         .logLevel(LOG_LVL_INFO)
         .logPath("./");
   
int ret = AIKIT_Init();
if(ret != 0){
    printf("AIKIT_Init failed:%d\n",ret);
    goto exit;
}

SDK初始化参数中appID、apiKey、apiSecret 和workDir为必填项。

初始化配置选项分为三个部分，分别是应用、授权、日志相关配置，可通过链式的调用方式去配置相关参数

模块	配置选项	类型	必填	说明
app	appID	string	是	应用ID
app	apiKey	string	是	离线引擎托管平台创建应用后，生成的唯一应用标识
app	apiSecret	string	是	离线引擎托管平台创建应用后，生成的唯一应用秘钥
app	workDir	string	是	SDK工作目录，默认授权缓存、读取能力资源、写SDK日志在此路径下
app	resDir	string	否	指定资源读取路径，不设置默认从workDir读取
auth	authType	string	否	离线授权类型（0或1），0-->(默认)设备级授权（DEVICE）和 1-->应用级授权（APP）
auth	channelID	string	否	渠道ID，存在多个能力集可指定使用的能力集
auth	UDID	string	否	用户自定义设备标识，需要服务端配置开启支持后才支持使用，建议设置长度低于256
auth	ability	string	是	竞争授权注册的能力id组合，格式如"xxxxx1;xxxxx2"，多个能力通过英文分号隔开，如果进行设置，则按照注册的能力进行授权，如果设置为空或者没有设置，则按照旧版sdkid的方式进行授权
log	logLevel	int	否	日志的输出等级：LOG_LVL_VERBOSE: verbose日志，日志最全LOG_LVL_DEBUG: debug级别LOG_LVL_WARN：警告级别信息LOG_LVL_INFO: 重要信息LOG_LVL_ERROR:错误级别日志LOG_LVL_FATAL:错误级别日志LOG_LVL_OFF:错误级别日志
log	logMode	int	否	模式： LOG_STDOUT:linux 控制台 LOG_FILE:文件形式
log	logPath	string	否	输出模式为文件时的文件名称（带有文件名称的路径）

# 6.5 引擎初始化

在调用能力前，需要先初始化引擎，引擎全局只需要初始化一次。传入引擎功能参数，示例代码如下：

AIKIT_ParamBuilder* engineParam = nullptr;
engineParam = AIKIT_ParamBuilder::create();//构造引擎功能参数，参数列表见下文
engineParam->param("decNetType","$paramValue",strlen("$paramValue"));
engineParam->param("punishCoefficient",$paramValue);
//engineParam->param("savePath","$paramValue",strlen("$paramValue"));
engineParam->param("wfst_addType",$paramValue);
ret = AIKIT_EngineInit("e75f07b62",AIKIT_Builder::build(engineParam));
if(ret != 0){
    printf("AIKIT_EngineInit failed:%d\n",ret);
    goto exit;
}

引擎功能参数说明：

功能标识	功能描述	数据类型	取值范围	必填
decNetType	解码类型	string	fsa:命令词, wfst:wfst解码, wfst_fsa:混合解码	是
punishCoefficient	fsa惩罚分数	double	最小值:0, 最大值:10	是
savePath	个性化资源保存路径	string	最小长度:0, 最大长度:32	否
wfst_addType	选择加载wfst资源	int	0:中文, 1:英文	是

AIKIT_EngineInit方法说明：

参数	类型	必填	说明
ability	char*	是	能力ID
param	AIKIT_BizParam*	否	引擎初始化参数,结构体可参考include文件夹中头文件"aikit_biz_type.h"中定义

返回：0 = 成功，其他 = 错误

# 6.6 配置自定义命令词

命令词一般由用户自定义配置在配置文件中，通过AIKIT_LoadData方法可配置多个命令词文件，用户根据业务需求通过AIKIT_SpecifyDataSet方法设置要生效的命令词文件。

每次会话时，均需要调用AIKIT_SpecifyDataSet 设置要生效的命令词，AIKIT_LoadData 方法初始化之后调用一次即可。

SDK 配置自定义命令词示例代码如下：

AIKIT_CustomBuilder *customData = AIKIT_CustomBuilder::create();
AEE_CustomData *customData = nullptr
customData->text("FSA", "./命令词.txt",strlen("./命令词.txt"),0);//传入个性化数据文件路径
int ret = AIKIT_LoadData("e75f07b62",AIKIT_Builder::build(customData));
int indexs[]={0};
AIKIT_SpecifyDataSet("e75f07b62","FSA",indexs,1);

个性化数据参数说明

数据段名称：FSA 数据类型：文本
AIKIT_LoadData 方法参数说明：设置个性化数据
该能力运行之前，需要调用AIKIT_LoadData方法，加载个性化配置数据，初始化前调用一次即可。

参数	类型	必填	说明
abilityId	char*	是	能力标识ID
data	AIKIT_CustomData*	是	个性化数据构造器

AIKIT_SpecifyDataSet 方法参数说明：

指定要使用的个性化数据集合，每次会话开启前需要调用。

参数	类型	必填	说明
abilityId	char*	是	能力标识ID
key	char*	是	个性化资源key
indexs	int[]	是	个性化资源索引数组
count	int	是	个性化数据索引数组成员个数

AIKIT_PreProcess 方法参数说明：

非必须方法，可不调用。为避免个性化数据重复加载耗时，可调用该预处理方法，对原始个性化资源进行预处理，再次调用能力时，则引擎会自动加载预处理后的资源。

参数	类型	必填	说明
abilityId	char*	是	能力标识ID
srcData	AIKIT_CustomData*	是	原始数据输入
data	AIKIT_CustomData**	是	结果数据输出

# 6.7 能力调用

# 6.7.1 创建能力会话

通过 start 方法开启会话，传入当前能力所需要指定的参数。示例代码如下：

AIKIT_ParamBuilder* paramBuilder = nullptr;
paramBuilder = AIKIT_ParamBuilder::create();
paramBuilder->param("languageType", "$paramValue");
paramBuilder->param("vadOn", "$paramValue");
//paramBuilder->param("vadLinkOn", false);
paramBuilder->param("vadEndGap", "$paramValue");
//paramBuilder->param("beamThreshold", 20);
//paramBuilder->param("hisGramThreshold", 3000);
//paramBuilder->param("vadSpeechEnd", 80);
//paramBuilder->param("vadResponsetime", 1000);
//paramBuilder->param("postprocOn", false);
ret = AIKIT_Start("e75f07b62",AIKIT_Builder::build(paramBuilder),nullptr,&handle);
if(ret != 0){
  printf("AIKIT_Start failed:%d\n", ret);
  goto exit;
}

功能参数说明：

功能标识	功能描述	数据类型	取值范围	必填	默认值
languageType	语种类型	int	0:中文, 1:英文	是
vadOn	开启vad	bool	true:开启, false:关闭	是
vadLinkOn	vad子句连接	bool	true:开启, false:关闭	否	false
vadEndGap	子句分割时间间隔，中文建议60，英文建议75	int	最小值:0, 最大值:100	是
beamThreshold	解码控制beam的阈值，中文建议20，英文建议25	int	最小值:0, 最大值:100	否	20
hisGramThreshold	解码Gram阈值，建议值3000	int	最小值:1, 最大值:10000	否	3000
vadSpeechEnd	vad后段点	int	最小值:0, 最大值:999999	否	80
vadResponsetime	vad前端点	int	最小值:0, 最大值:999999	否	1000
postprocOn	后处理开关	bool	true:开启, false:关闭	否	false

AIKIT_Start 方法说明：

参数	类型	必填	说明
ability	char*	是	能力标识ID
param	AIKIT_BizParam*	是	能力的配置和输入，可使用AIKIT_Builder快捷构建
usrContext	void*	否	用户上下文指针，保存在outHandle中，用以回调中使用
outHandle	AIKIT_HANDLE**（指针的指针）	是	生成的会话句柄

返回：AiHandle
AiHandle对象内部提供isSucess方法，用于判断会话是否启动成功

0=成功，其他=错误

# 6.7.2 送入数据

通过调用 AIKIT_Write 方法送入能力输入数据。
AIKIT_Write 方法说明：

参数	类型	必填	说明
handle	AIKIT_HANDLE*	是	AIKIT_Start生成的会话handle
input	AIKIT_InputData*	是	输入数据

送入数据实现代码如下：

AIKIT_DataBuilder* dataBuilder = AIKIT_DataBuilder::create();
//输入音频数据
char* audio;
AiAudio* audioData = AiAudio::get("audio")->data(audio,audioLen)->valid();
dataBuilder->payload(audioData);
 
int ret = AIKIT_Write(handle,AIKIT_Builder::build(dataBuilder));
if (ret != 0) {
  printf("AIKIT_Write:%d\n",ret);
  goto exit;
}

能力输入数据

数据段名称：audio 数据类型：音频

以下是音频输入参数含义说明：

字段	含义	数据类型	取值范围	默认值	说明	必填
encoding	音频编码	string	pcm	pcm	取值范围可枚举	否
sample_rate	采样率	int	16000	16000	音频采样率，可枚举	否
channels	声道数	int	1	1	声道数，可枚举	否
bit_depth	位深	int	16	16	单位bit，可枚举	否
data	音频数据	string			音频大小：0-10M	否
frame_size	帧大小	int	最小值:0, 最大值:1024	0	帧大小，默认0	否

# 6.7.3 获取能力输出结果

送入数据后，需要调用AIKIT_Read方法获取到能力结果，AIKIT_Read方法为阻塞式方法，当次送入数据处理完毕读取到结果后会返回结果状态码。如果有多次输入，读取到当次结果后，方可进行下一次数据输入。

read方法调用方法如下：

int ret = AIKIT_Read(handle, &output);
if (ret != 0)
{
  printf("AIKIT_Read:%d\n", ret);
  goto exit;
}

AIKIT_Read方法说明：

参数	类型	必填	说明
handle	AIKIT_HANDLE*	是	AIKIT_Start生成的会话handle
output	AIKIT_OutputData**(指针的指针)	是	输出数据

获取能力结果

结果通过outputData参数返回

能力结果数据格式及含义如下：

数据段名称：data 数据类型：文本

以下是文本输出参数含义说明：

字段	含义	数据类型	取值范围	默认值	说明
encoding	文本编码	string	utf8, gb2312	utf8	取值范围可枚举
compress	文本压缩格式	string	raw, gzip	raw	取值范围可枚举
format	文本格式	string	plain, json, xml	json	取值范围可枚举
data	文本数据	string			文本大小：0-1M

输出结果示例：

pgs： 我想
pgs： 我想听
pgs： 我想听周杰
pgs： 我想听周杰伦
pgs： 我想听周杰伦专辑
htk： <s>
我想听
周杰伦专辑
</s>
plain： 我想听周杰伦专辑
vad： {"sc":"0","ws":[{"bg":"78","ed":"303","status":"SpeechNormal"}]}
readable： {"sc":"12784","mode":"fsa","ismandarin":"true","bg":"78","ed":"303","ws":[{"sc":"0","w":"我想听","slot":"albumwant","pinyin":"","boundary":""},{"sc":"0","w":"周杰伦专辑","slot":"album","pinyin":"","boundary":""}]}
vad： {"sc":"0","ws":[{"bg":"-1","ed":"-1","status":"SpeechAutoFinish"}]}
readable： {"sc":"0","bg":"-1","ed":"-1","ws":[{"sc":"0","w":"。"}]}

pgs:progressive格式的结果，即可以实时刷屏
htk:带有分词信息的结果，每一个分词结果占一行
plain:类比于htk，把一句话结果中的所有分词拼成完整一句，若有后处理，则也含有后处理的结果信息，plain是每一段话的最终结果
vad:语音端点检测，可以过滤掉输入音频中的静音部分，vad关键名词有前端点bg（音频非静音部分起始点）和后端点ed（音频非静音部分尾端点），引擎的一次调用（start接口到end接口）中，vad识别出后端点之后后续的音频将不会被送入识别引擎；如果两处都显示-1代表没有使用vad引擎。

结果json参数	字段含义
bg	vad前端点，单位是帧（10ms）
ed	识别结果，单位是帧（10ms）
status	vad模块的状态（NovadOrvaderror的意思就是没有开启vad或者vad报错，因为bg和ed都显示-1了）

readable:json格式的结果。

结果json参数	字段含义
sc	置信度
mode	命令词模式
ismandarin	是否是普通话
bg	vad前端点，单位是帧（10ms）
ed	识别结果，单位是帧（10ms）
w	识别结果
slot	命中的槽名
pinyin	拼音
boundary	边界词

注意：FSA命令词结点是可以有一个起点，多个终点的。用户在说一条命令时，命令内容必须包含一条完整的起点到终点的路径才可以被accept，如果识别到的音频内容不满足起点走到终点的要求，是不会有htk，plain，readable结果的。

# 6.7.4 结束会话

数据处理完毕，调用AIKIT_End方法结束会话，示例代码如下：

int ret = AIKIT_End(handle);
if (ret != 0)
{
  printf("AIKIT_End failed : %d\n", ret);
}

AIKIT_End方法说明:

参数	类型	必填	说明
handle	AIKIT_HANDLE*	是	AIKIT_Start生成的会话handle

# 6.8 SDK逆初始化

当不再使用能力时，需调用逆初始化方法释放资源，示例代码如下：

/**
* SDK逆初始化函数用以释放SDK所占资源 * @return 结果错误码，0=成功
*/
 
AIKITAPI int32_t AIKIT_UnInit();

# 7. 高级功能

# 7.1 日志配置

可根据需要设置日志输入级别、方式等。

/**
* 设置日志级别，模式，以及保存路径
* @param level 日志级别
* @param mode 日志输出模式
* @param path 输出模式为文件时的文件名称
* @return 错误码 0=成功，其他表示失败
*/
 AIKITAPI int32_t AIKIT_SetLogInfo(int32_t level, int32_t mode, const char* path);

日志配置参数说明

参数	类型	说明
level	int32_t	日志的输出等级： LOG_LVL_VERBOSE：最全日志信息 LOG_LVL_DEBUG: debug级别， LOG_LVL_WARN：警告级别信息 LOG_LVL_INFO: 重要信息 LOG_LVL_ERROR:错误级别日志 LOG_LVL_FATAL:错误级别日志 LOG_LVL_OFF:错误级别日志
LogMode	int	模式： LOG_STDOUT:linux 控制台 LOG_FILE:文件形式
path	const char*	输出模式为文件时的文件名称（带有文件名称的路径）

# 7.2 获取设备ID

通过传入字符类型的指针地址，来获取设备ID。

/**
* 获取设备ID
* @param deviceID 设备指纹输出字符串
* @return 结果错误码，0=成功
*/
 AIKITAPI int32_t AIKIT_GetDeviceID(const char** deviceID);

# 7.3 个性化数据卸载

已加载的个性化数据，如果不在使用或者需要替换，需要卸载已加载的个性化资源，示例代码如下：

/**
* 个性化数据加载
* @param ability 能力唯一标识
* @param key 个性化数据唯一标识
* @param index 个性化数据索引
* @return 错误码 0=成功，其他表示失败
*/
AIKITAPI int32_t AIKIT_UnLoadData("e75f07b62", "FSA", int index);

参数	类型	说明
ability	String	能力id
key_word	String	个性化数据唯一标识
index	String	个性化数据索引

# 7.4 设置授权时间间隔

设置在线授权校验间隔时长，默认为300s，可自定义设置，最短为60s，最长为24小时，单位秒，示例代码如下：

/**
* 设置授权更新间隔，单位为秒，默认为300秒
* AIKIT_Init前设置
* @param interval 间隔秒数
* @return 结果错误码，0=成功
*/
 
 AIKITAPI int32_t AIKIT_SetAuthCheckInterval(uint32_t interval);

# 7.5 获取SDK版本号

/**
* 获取SDK版本号
* @return SDK版本号
*/
 AIKITAPI const char* AIKIT_GetVersion();

在这篇文章中：