Linux SDK集成文档

# SparkChain 大模型识别 Linux SDK集成文档

## 1. 大模型识别简介

SparkChain支持开发者通过SDK进行大模型识别。开发者仅需往对应的接口中送入音频数据，则可以从监听回调中获取识别结果。大模型识别对比常规的语音识别，识别效果更好。并且当开发者如果有方言识别的需求，大模型识别可以不用切换方言参数，简化了开发者的代码逻辑。

## 2. 兼容性说明

| 类别     | 兼容范围                                                     |
| :------- | :----------------------------------------------------------- |
| 系统     | 支持x86，x86_64，arm和arm64架构，支持交叉编译，适配常见芯片型号。 |
| 开发环境 | 建议使用 VS Studio 进行开发                                  |

## 3. SDK集成包目录结构

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

├── Demo SparkChain的使用DEMO，DEMO中已经集成了SDK，您可以参考DEMO，集成SDK。集成前，请先测通DEMO，了解调用原理。

├── ReleaseNotes.txt SDK版本日志

├── SDK SparkChain SDK

│ └── [libSparkChain.so](http://libsparkchain.so/)

└── SparkChain 大模型识别 Linux SDK集成文档.pdf SparkChain集成指南

## 4. SDK工程配置

### 4.1 导入SDK库

将SDK/libs文件夹、头文件文件夹include存放到项目中，并在环境变量里添加库路径；

```c++
#include "../include/sparkchain.h"//必须导入 
#include "../include/sc_asr.h" //大模型识别
```

### 4.2 配置权限

如果需要存储日志，SDK日志路径需要读写权限，缺少读写权限，日志将无法正常存储。

## 5. 接口流程调用图

![](/media/202405/大模型识别Linux平台流程图_1715651528.png)

## 6. SDK初始化

**在使用SparkChain 星火大模型交互功能前，需要首先开通星火大模型授权并获取已开通授权的应用信息（appId、apiKey、apiSecret）。SDK全局只需要初始化一次。**初始化时，开发者需要构建一个SparkChainConfig实例config，把相关的appid信息以及日志设置等传入config中，然后再通过SparkChain::init(config)方法把config实例设置到SDK中。SparkChainConfig 结构如下：

```c++
class SPARKCHAIN_API SparkChainConfig { 
    public:    
    	static SparkChainConfig* builder();    
    	virtual ~SparkChainConfig();    
    	//配置appid    
    	virtual SparkChainConfig* appID(const char* appid)         = 0;    
    	//配置apiKey    
    	virtual SparkChainConfig* apiKey(const char* apiKey)       = 0;    
    	//配置apiSecret    
    	virtual SparkChainConfig* apiSecret(const char* apiSecret) = 0;    
    	//配置用户自定义标识    
    	virtual SparkChainConfig* uid(const char* uid)             = 0;    
    	//配置SDK工作路径    
    	virtual SparkChainConfig* workDir(const char* workDir)     = 0;    
    	//配置日志等级    
    	virtual SparkChainConfig* logLevel(int logLevel )          = 0;    
    	//配置日志存储路径    
    	virtual SparkChainConfig* logPath(const char* logPath)     = 0; 
};
```

SparkChainConfig接口说明：

初始化返回值：0：初始化成功，非0：初始化失败，请根据具体返回值参考错误码章节查询原因。

具体示例如下：

```c++
SparkChainConfig* config = SparkChainConfig::builder(); 
config->appID("$appId")      
    ->apiKey("$apiKey")      
    ->apiSecret("$apiSecret");//从平台获取的授权appid，apikey,apisecrety 
int ret = SparkChain::init(config);
```

## 7. 大模型识别初始化

在使用大模型识别功能前，需先通过其构造方法ASR()方法构建其实例，然后用该实例调用相应的方法去设置识别参数。

大模型识别构造方法如下：

```c++
class SPARKCHAIN_API ASR {    
    public:     	
    	ASR();    	
    	ASR(string language, string domain, string accent);    	
    	~ASR(); 
}
```

构造方法参数说明：

| 类型             | 说明                                       |
| ---------------- | ------------------------------------------ |
| 中文语音大模型   | language=zh_cn;domain=slm;accent=mandarin  |
| 听写多语种大模型 | language=mul_cn;domain=slm;accent=mandarin |

具体示例如下：

```c++
ASR asr = new ASR("mul_cn","slm","mandarin");
//ASR asr = new ASR();//缺省参数调用方式
```

## 8. 功能参数配置

SDK支持用户根据自身需求，通过构建的asr实例访问相关方法配置识别参数。中文语音大模型和听写多语种大模型所支持的功能不同，具体方法说明如下。

### 8.1 中文语音大模型

| 方法名 | 参数名 | 参数类型 | 说明 | 是否必填 | 默认值 |
| -------- | -------- | -------- | ------------------------------------------------------------ | ---------------------------------------------------- | ------ |
| language | language | String | 识别语种。 zh_cn：中文 | 如果通过构造方法传入，则这里可不用配置，否则必须设置 | |
| domain | domain | String | 应用领域。 slm:大模型识别 | 如果通过构造方法传入，则这里可不用配置，否则必须设置 | |
| accent | accent | String | 方言。 mandarin：中文普通话、其他语种 | 如果通过构造方法传入，则这里可不用配置，否则必须设置 | |
| vgap | vgap | int | 子句间隔：用于判定音频是否被切分为一个独立的句子，相邻两段语音之间的间隔超过给定值，上一段语音会被判定为一个独立子句。单位是毫秒。 最小值:300, 最大值:1000 | 否 | 300 |
| vadEos | vadEos | int | 尾静音截断：引擎判定结束的时间，连续检测给定时间长度的音频，均为静音，则引擎停止识别，单位是毫秒。最小值:600，最大值:60000 | 否 | 600 |
| vinfo | vinfo | boolean | 句子级别帧对齐:给出一次会话中，子句的vad边界信息。 false:不返回vad信息 true:返回vad信息 | 否 | false |
| dwa | dwa | String | 流式识别PGS：流式识别功能，打开后，会话过程中实时给出语音识别的结果，而不是子句结束时才给结果。 wpgs：开启流式结果返回功能。 | 否 | |
| proc | proc | boolean | 后处理功能关闭开关：关闭后处理的所有功能，仅做简单的json格式转换等格式处理操作。 false:关闭 true:开启 | 否 | false |
| ptt | ptt | boolean | 标点预测：在语音识别结果中增加标点符号。 false:关闭 true:开启 | 否 | false |
| smth | smth | boolean | 顺滑功能：将语音识别结果中的顺滑词（语气词、叠词）进行标记，业务侧通过标记过滤语气词最终展现识别结果。 false:关闭 true:开启 | 否 | false |
| nunum | nunum | boolean | 数字规整：将语音识别结果中的原始文字串转为相应的阿拉伯数字或者符号。 false:关闭 true:开启 | 否 | false |
| rlang | rlang | String | 字体。 zh-cn :简体中文 zh-hk :繁体香港 默认简体中文，受限功能，未授权AppId无法使用，如果开启后没有效果，可能是没有权限，需要提交工单申请 | 否 | |

### 8.2 听写多语种大模型

| 方法名 | 参数名 | 参数类型 | 说明 | 是否必填 | 默认值 |
| -------- | -------- | -------- | ------------------------------------------------------------ | ---------------------------------------------------- | ------ |
| language | language | String | 识别语种。 mul_cn：中文 | 如果通过构造方法传入，则这里可不用配置，否则必须设置 | |
| domain | domain | String | 应用领域。 slm:大模型识别 | 如果通过构造方法传入，则这里可不用配置，否则必须设置 | |
| accent | accent | String | 方言。 mandarin：中文普通话、其他语种 | 如果通过构造方法传入，则这里可不用配置，否则必须设置 | |
| vgap | vgap | int | 子句间隔：用于判定音频是否被切分为一个独立的句子，相邻两段语音之间的间隔超过给定值，上一段语音会被判定为一个独立子句。单位是毫秒。 最小值:300, 最大值:1000 | 否 | 300 |
| vadEos | vadEos | int | 尾静音截断：引擎判定结束的时间，连续检测给定时间长度的音频，均为静音，则引擎停止识别，单位是毫秒。最小值:600，最大值:60000 | 否 | 600 |
| vinfo | vinfo | boolean | 句子级别帧对齐:给出一次会话中，子句的vad边界信息。 false:不返回vad信息 true:返回vad信息 | 否 | false |
| ln | ln | String | 语种参数：支持两种模式，指定语种模式和免切模式 指定语种，比如当前会话是英文那么传参 ln=en 免切模式，不需要指定语种参数或传参ln=none 引擎将自动识别语种 | 否 | none |

语种参数详细说明:

引擎支持的语音识别功能语种列表及ln传参说明

**1、指定语种模式**，需要端侧给服务传带识别语音的语种，字段为ln，比如当前会话是英文，那么语种参数是"en"，详细见下面对外ID。

**2、免切模式**，不需要指定语种参数或者ln字段传参数"none"，识别引擎将自动识别语种。

| 对外ID | 语种       |
| :----- | :--------- |
| zh     | 中文       |
| en     | 英文       |
| ja     | 日语       |
| ko     | 韩语       |
| ru     | 俄语       |
| fr     | 法语       |
| es     | 西班牙语   |
| ar     | 阿拉伯语   |
| de     | 德语       |
| th     | 泰语       |
| vi     | 越南语     |
| hi     | 印地语     |
| pt     | 葡萄牙语   |
| it     | 意大利语   |
| ms     | 马来语     |
| id     | 印尼语     |
| fil    | 菲律宾语   |
| tr     | 土耳其语   |
| el     | 希腊语     |
| cs     | 捷克语     |
| ur     | 乌尔都语   |
| bn     | 孟加拉语   |
| ta     | 泰米尔语   |
| uk     | 乌克兰语   |
| kk     | 哈萨克语   |
| uz     | 乌兹别克语 |
| pl     | 波兰语     |
| mn     | 蒙语       |
| sw     | 斯瓦西里语 |
| ha     | 豪撒语     |
| fa     | 波斯语     |
| nl     | 荷兰语     |
| sv     | 瑞典语     |
| ro     | 罗马尼亚语 |
| bg     | 保加利亚语 |
| ug     | 维语       |
| tib    | 藏语       |

配置功能参数具体示例如下：

```c++
asr.language("mul_cn");
asr.accent("mandarin");
...
asr.domain("slm");
asr.vinfo(true);
```

## 9. 注册结果监听回调

大模型识别结果通过AsrCallbacks监听回调异步返回，监听回调接口如下：

```c++
class SPARKCHAIN_API ASRCallbacks { 
    public:    
    	virtual void onResult(ASRResult * result, void * usrTag) = 0;    
    	virtual void onError(ASRError * error,void * usrTag) = 0; 
};
```

ASRCallbacks数据结构说明：

- onResult为识别结果回调方法，参数说明如下：

| 参数   | 类型        | 说明           |
| :----- | :---------- | :------------- |
| result | ASRResult * | 识别结果结构体 |
| usrTag | void *      | 用户自定义标识 |

- ASRResult结构说明：

- vad结构体说明：

| 方法    | 返回值类型 | 说明                                     |
| :------ | :--------- | :--------------------------------------- |
| begin() | int        | 起始的端点帧偏移值，单位：帧（1帧=10ms） |
| end()   | int        | 结束的端点帧偏移值，单位：帧（1帧=10ms） |

- Transcription结构体说明：

| 方法 | 返回值类型 | 说明 |
| :--------- | :---------------- | :----------------------------------------------------------- |
| index() | int | 起始的端点帧偏移值，单位：帧（1帧=10ms） 注：以下两种情况下bg=0，无参考意义： 1)返回结果为标点符号或者为空； 2)本次返回结果过长。 |
| segments() | vector<Segment *> | 中文分词结构体 |

- Segment结构体说明：

| 方法    | 返回值类型 | 说明                       |
| :------ | :--------- | :------------------------- |
| text()  | string     | 字词                       |
| score() | int        | 得分，当前未实现，保留字段 |

- onError为识别错误回调方法，参数说明如下：

| 参数   | 类型       | 说明           |
| :----- | :--------- | :------------- |
| error  | ASRError * | 错误信息结构体 |
| usrTag | void *     | 用户自定义标识 |

- ASRError结构说明

| 方法     | 返回值类型 | 说明          |
| :------- | :--------- | :------------ |
| errMsg() | string     | 错误信息      |
| code()   | int        | 错误码        |
| sid()    | string     | 本次交互的sid |

具体示例如下：

```c++
class ASRCallbacksImpl : public ASRCallbacks { 
 void onResult(ASRResult * result, void * usrTag) override { 
 string result = result->bestMatchText();//解析识别结果 
 int status = result->status();//解析结果返回状态 
 string sid = result->sid();//解析sid 
 //以下信息需要开发者根据自身需求，如无必要，可不需要解析执行。 
 vector<Vad *> vads = result->vads();//解析vad结构体 
 for (Vad * v : vads) { 
 int begin = v->begin();//解析vad前端点 
 int end = v->end();//解析vad后端点 
 } 
 vector<Transcription *> transcriptions = result->transcriptions();//解析具体结果信息 
 for (auto item : transcriptions) { 
 vector<Segment *> segs = item->segments();//解析中文分词结构体 
 for (auto seg : segs) { 
 string word = seg->text();//解析词语 
 } 
 } 
 } 
 void onError(ASRError * error,void * usrTag) override { 
 int errCode = error->code();//错误码 
 string errMsg = error->errMsg();//错误信息 
 string sid = error->sid();//本次交互的sid 
 } 
}; 
ASRCallbacksImpl *mASRCallbacks = new ASRCallbacksImpl(); asr.registerCallbacks(mASRCallbacks);
```

## 10. 启动会话

开发者进行交互前，需通过asr.start()方法先启动会话。调用接口如下：

```c++
class SPARKCHAIN_API ASR {    
    public:     	
    	int start(void * usrTag = nullptr);    	
    	int start(const AudioAttributes & attributes,void * usrTag = nullptr); 
} 
class SPARKCHAIN_API AudioAttributes {
    public:
    	AudioAttributes(const AudioAttributes & attributes);
    
    	void setSampleRate(int sampleRate);

void setEncoding(const string & encoding);

void setChannels(int channels);

void setBitDepth(int bitdepth);

void setFrameSize(int framesize);
    	
    	
}
```

- start方法参数说明：

| 参数名     | 类型                  | 说明               | 是否必填 | 默认值  |
| :--------- | :-------------------- | :----------------- | :------- | :------ |
| attributes | const AudioAttributes | 输入数据格式结构体 | 否       | 16k,raw |
| usrTag     | void *                | 用户自定义标识     | 否       | nullptr |

- AudioAttributes结构说明：

| 方法名 | 返回值类型 | 参数名 | 参数类型 | 说明 |
| ------------- | ---------- | ---------- | ------------ | ------------------------------------------------------------ |
| setSampleRate | void | sampleRate | int | 输入音频的采样率，支持8k和16k |
| setEncoding | void | encoding | const string | 输入音频的编码格式 raw：原生音频（支持单声道的pcm） speex：speex压缩后的音频（8k） speex-wb：speex压缩后的音频（16k） 请注意压缩前也必须是采样率16k或8k单声道的pcm。 lame：mp3格式（仅中文普通话和英文支持，方言及小语种暂不支持） |
| setChannels | void | channels | int | 输入音频的声道 1:单声道(默认) 2:双声道 |
| setBitdepth | void | bitdepth | int | 位深 8:8bit 16:16bit(默认) |
| setFrameSize | void | frameSize | int | 帧大小 最小值:0, 最大值:1024 |

具体示例如下：

```c++
asr.start();
//带有数据信息结构体的构建方式示例如下：
//AudioAttributes atr = new AudioAttributes();
//atr.setSampleRate(16000);
//atr.setEncoding("raw");
//atr.setChannels(1);
//asr.start(atr, null);
```

## 11. 送入数据

启动会话后，开发者可通过asr.write()方法送入要识别的音频，然后异步从监听回调中获取识别结果。write方法调用接口如下：

```c++
class SPARKCHAIN_API ASR {    
    public:     	
    	int write(const char * data, size_t len); 
}
```

write方法参数说明：

| 参数 | 类型         | 说明     |
| :--- | :----------- | :------- |
| data | const char * | 识别数据 |
| len  | size_t       | 数据长度 |

发送数据时，如果间隔时间太短，可能会导致引擎识别有误。建议每次发送音频间隔40ms，每次发送音频字节数为一帧音频大小的整数倍。

请注意不同音频格式一帧大小的字节数不同，我们建议：

1. 未压缩的PCM格式，每次发送音频间隔40ms，每次发送音频字节数1280B；
2. 讯飞定制speex格式，每次发送音频间隔40ms，假如16k的压缩等级为7，则每次发送61B的整数倍；
3. 标准开源speex格式，每次发送音频间隔40ms，假如16k的压缩等级为7，则每次发送60B的整数倍；

| 讯飞定制speex（压缩等级） | 0    | 1    | 2    | 3    | 4    | 5    | 6    | 7    | 8    | 9    | 10   |
| :------------------------ | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| speex 8k                  | 7    | 11   | 16   | 21   | 21   | 29   | 29   | 39   | 39   | 47   | 63   |
| speex-wb 16k              | 11   | 16   | 21   | 26   | 33   | 43   | 53   | 61   | 71   | 87   | 107  |

| 标准开源speex（压缩等级） | 0    | 1    | 2    | 3    | 4    | 5    | 6    | 7    | 8    | 9    | 10   |
| :------------------------ | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| speex 8k                  | 6    | 10   | 15   | 20   | 20   | 28   | 28   | 38   | 38   | 46   | 62   |
| speex-wb 16k              | 10   | 15   | 20   | 25   | 32   | 42   | 52   | 60   | 70   | 86   | 106  |

整个会话时长最多持续60s，或者超过10s未发送数据，服务端会主动断开连接。

注意：针对用户传参，识别服务如何识别传入的音频是讯飞定制speex格式还是标准开源speex格式音频？

```c++
通过是否传入speex_size（speex音频帧长，仅在speex音频时使用）参数来区分 
1、当传入speex_size参数时，会当成标准开源格式进行处理 
2、当未传入speex_size参数时，会当成讯飞定制格式进行处理
```

具体示例如下：

```c++
//示例仅展示从本地读取文件，具体获取音频逻辑需要开发者自己实现 
char * data = new char[1280]; 
...//省略获取音频的过程 
asr.write(data);
```

## 12. 停止会话

当开发者送完数据后，需要调用asr.stop()方法通知SDK层数据已传完。之后云端则会下发最终的识别结果，然后结束本轮交互。stop方法调用接口如下：

```c++
class SPARKCHAIN_API ASR {    
    public:     	
    	int stop(bool immediate = false); 
}
```

stop方法参数说明：

| 参数 | 类型 | 说明 |
| :-------- | :--- | :----------------------------------------------------------- |
| immediate | bool | true：调用stop后，SDK不管后续云端结果，立即结束。 false：调用stop后，SDK会等云端发送完最终结果后再结束。 |

具体示例如下：

```c++
asr.stop();
```

如果不需要继续使用SDK，需要执行逆初始化释放资源。具体参考逆初始化章节。

## 13. 逆初始化

当SDK需要完整退出时，需调用逆初始化方法释放资源，示例代码如下：

```c++
SparkChain::unInit();
```

## 14. SDK API介绍

### 14.1 SparkChainConfig API

### 14.2 SparkChain API

### 14.3 ASR API

### 14.4 ASRResult API

### 14.5 ASRError API

### 14.6 ASR AudioAttributes API

## 15. 错误码

错误码包含SDK错误码和云端错误码。

### 15.1 SDK错误码

### 15.2 云端错误码

备注：如出现下述列表中没有的错误码，可到 [这里](https://www.xfyun.cn/document/error-code) 查询。

| 错误码 | 错误描述                                                | 说明                         | 处理方式                                                     |
| ------ | ------------------------------------------------------- | ---------------------------- | ------------------------------------------------------------ |
| 10005  | licc fail                                               | appid授权失败                | 确认appid是否正确，是否开通了听写服务                        |
| 10006  | Get audio rate fail                                     | 获取某个参数失败             | 检查报错信息中的参数是否正确上传                             |
| 10007  | get invalid rate                                        | 参数值不合法                 | 检查报错信息中的参数值是否在取值范围内                       |
| 10010  | AIGES_ERROR_NO_LICENSE                                  | 引擎授权不足                 | 请到控制台提交工单联系技术人员                               |
| 10014  | AIGES_ERROR_TIME_OUT                                    | 会话超时                     |                                                              |
| 10019  | service read buffer timeout, session timeout            | session超时                  | 检查是否数据发送完毕但未关闭连接                             |
| 10043  | Syscall AudioCodingDecode error                         | 音频解码失败                 | 检查aue参数，如果为speex，请确保音频是speex音频并分段压缩且与帧大小一致 |
| 10101  | engine inavtive                                         | 引擎会话已结束               | 检查是否引擎已结束会话但客户端还在发送数据，比如音频数据虽然发送完毕但并未关闭websocket连接，还在发送空的音频等 |
| 10114  | session timeout                                         | 会话超时                     | 检查整个会话是否已经超过了60s                                |
| 10139  | invalid param                                           | 参数错误                     | 引擎编解码错误                                               |
| 10313  | appid cannot be empty                                   | appid不能为空                | 检查common参数是否正确上传，或common中的app_id参数是否正确上传或是否为空 |
| 10317  | invalid version                                         | 版本非法                     | 联系技术人员                                                 |
| 11200  | auth no license                                         | 没有权限                     | 检查是否使用了未授权的功能，或者总的调用次数已超越上限       |
| 11201  | auth no enough license                                  | 日流控超限                   | 可联系商务提高每日调用次数                                   |
| 10160  | parse request json error                                | 请求数据格式非法             | 检查请求数据是否是合法的json                                 |
| 10161  | parse base64 string error                               | base64解码失败               | 检查发送的数据是否使用了base64编码                           |
| 10163  | param validate error:/common 'app_id' param is required | 缺少必传参数，或者参数不合法 | 检查报错信息中的参数是否正确上传                             |
| 10165  | invalid handle                                          | 无效的句柄                   | 检查下传入第一帧音频时，是否上传了status=0                   |
| 10200  | read data timeout                                       | 读取数据超时                 | 检查是否累计10s未发送数据并且未关闭连接                      |