# AIKit 离线命令词 Linux SDK 集成文档

# 1. 离线命令词能力简介（能力id：e75f07b62）

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

支持多实例并发：否

协议类型：同步流式

# 2. 授权说明

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

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

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

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

# 3. 兼容性说明

# 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 "./include/aikit_biz_api.h"
#include "./include/aikit_constant.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为必填项。

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

# 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;
}

引擎功能参数说明：

AIKIT_EngineInit方法说明：

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

# 6.6 个性化数据

个性化数据一般为用户自定义配置文件，用户根据业务需求配置个性化数据，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方法，加载个性化配置数据。

AIKIT_SpecifyDataSet 方法参数说明：

指定要使用的个性化数据集合，未调用，则默认使用所有loadData加载的数据。

AIKIT_PreProcess 方法参数说明：

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

# 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;
}

功能参数说明：

AIKIT_Start 方法说明：

返回：AiHandle

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

0=成功，其他=错误

# 6.7.2 送入数据

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

送入数据实现代码如下：

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 数据类型：音频

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

# 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方法说明：

获取能力结果

结果通过outputData参数返回

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

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

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

# 6.7.4 结束会话

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

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

AIKIT_End方法说明:

# 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); 

日志配置参数说明

# 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);

# 7.4 设置授权时间间隔

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

/** 
* 设置授权更新间隔，单位为秒，默认为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();

# 8. Linux平台常见问题

1. SDK 错误码返回18700，错误日志出现 “online license activate ret:18700 ；auth request failed:2007,未发现SDK” 如何解决?

appid 未授权该SDK 能力，请申请授权后使用该能力。

2. SDK 错误码返回18714，错误日志出现 “[{"message":"HMAC signature cannot be verified: fail to retrieve credential"}]” 如何解决?

appid、apiKey、apiSecret 配置有误，请检查配置。

3. SDK 初始化返回 18007，错误日志出现"httpPost failed! 401{"message":"HMAC signature does not match"}；online license activate ret:18714；AEE_Init ret 18007"，如何解决？

apiKey 或 apiSecret 有误，请检查apiKey、apiSecret 的值是否正确，并替换为正确的值。

4. SDK 初始化时返回18704，错误日志出现“auth request failed:2003,未发现应用”；“AEE_Init ret 18704,”，如何解决？

appid 不存在或appid 未授权，请使用正确的 appid。

5. SDK 初始化时返回18400，错误日志出现 “workDir does not have write permission sdcard/xxxx/xxx”，“AEE_Init ret 18400”

SDK 初始化时设置的SDK工作路径即“workDir” 无读写权限，请确保SDK 初始化时，SDK工作路径具有读写权限。

6. SDK 在初始化引擎时，返回 18601，错误日志出现 “AEE_EngineInit:e09712bcb11 ret 18601”；“ability: xxxxxxx not exist”，如何解决？

能力（能力id为 xxxxxx）不存在，初始化引擎时传入的能力id有误，请检查能力id是否正确；或改能力未授权，请确认该能力是否已申请授权。

7. 调用SDK 的start 或 AEE_Start 方法时，返回错误码 18105，错误日志出现“AEE_Start:e09712bcb ret 18105”; "cannot find dependent resource: xxxxxx",如何解决？

该错误为资源未找到，请检查是否将资源导入到了SDK的工作路径下。

8. 日志中出现“AEE_Start: xxxxxxx ret 18310; AEE_Start failed:18310”错误日志如何解决？

流式接口能力，调用 AEE_Start 或 start 方法开始的会话，未调用AEE_End 或 end 方法打断或正常结束，再次调用AEE_Srart则SDK会返回18310错误，同一个能力SDK不支持并发调用，需要结束本次会话之后，才能开始下一次会话。

9. 日志中出现“[ERROR]:[ getAbility]-[0474]:ability:64b9b706 not exist AEE_EngineInit: xxxxxxx ret 18601” ，错误码返回18601 错误，如何解决？

请检查确认引擎初始化及调用能力时所传能力id参数是否正确；如果能力ID无误，SDK日志中打印的 xxxxxx 能力未授权。

10. 日志中出现“auth request failed:2015,无效的指纹”、“online license activate ret:18713”，SDK返回18713错误，如何解决？

应用安全等级与设备指纹不符，须申请调整appid 安全等级；

11. arm和mips架构如何使用SDK？

目前官网离线能力的linux SDK只有x86架构，如果需要arm，mips架构的，需要线下人工提供交叉编译，交叉编译属于增值服务。编译规则如下：
编译收费：
1、已购买交叉编译的离线能力的装机量套餐，可以免费提供2次交叉编译服务。
2、未购买交叉编译的离线能力的装机量套餐，则按次收费，699/次。
编译须知：
1、如有交叉编译申请需求，请先下载填写交叉编译申请表格 (opens new window)，提交到工单中。
2、由于目前编译服务需跨部门协助，且编译流程复杂，自提交完整编译信息后7个工作日内提供。
3、编译成功后，技术同事会提供专属付款链接，确定支付后会提供编译库文件或SDK包。
4、因编译链及设备环境的差异，无法保证百分百编译成功。

12. AIkit离线命令词FSA文件书写规范指南

https://developer.xfyun.cn/thread/117340

13. AIkit离线命令词FSA文件编码格式

答：FSA文件编码格式必须为GBK

# 错误码