Android SDK集成文档

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

## 1. 大模型识别简介

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

## 2. 兼容性说明

| 类别     | 兼容范围                                        |
| :------- | :---------------------------------------------- |
| 系统     | 支持armv7和armv8架构，兼容android 5.0及以上版本 |
| 开发环境 | 建议使用Android Studio 进行开发                 |

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

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

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

├── ReleaseNotes.txt SDK版本日志

├── SDK SparkChain SDK

│ └── SparkChain.aar

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

## 4. SDK工程配置

### 4.1 导入SDK库

复制SparkChain.aar到项目的libs目录下，然后在主Module的build.gradle文件中，增加如下配置：

```java
dependencies { 
    implementation files('libs/SparkChain.aar')    
}
```

### 4.2 配置权限

SparkChain SDK中默认配置了以下权限：

如果部分权限不需要，可通过如下配置去除，去除示例如下：

```java
 
<uses-permission android:name="android.permission.READ_PHONE_STATE" tools:node="remove" /> 
```

Android 10.0（API 29）及以上版本需要在application中做如下配置

```java
<application android:requestLegacyExternalStorage="true"/>
```

### 4.3 混淆配置

SparkChain SDK 已做过混淆，如果您项目中也使用了混淆，请在 proguard-rules.pro文件中添加如下配置保持SparkChain SDK 不再被混淆。

```java
-keep class com.iflytek.sparkchain.** {*;} 
-keep class com.iflytek.sparkchain.**
```

## 5. 接口流程调用图

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

## 6. SDK初始化

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

```java
//配置应用信息 
SparkChainConfig config =  SparkChainConfig.builder()        
    .appID("$appId")        
    .apiKey("$apiKey")        
    .apiSecret("$apiSecret"); 
int ret = SparkChain.getInst().init(getApplicationContext(), config); 
```

初始化参数说明：

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

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

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

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

```java
public class ASR {    
    public ASR() {            
    
    }
    
    public ASR(String language, String domain, String accent) {        
        ...    
    } 
}
```

构造方法参数说明：

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

具体示例如下：

```java
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    | 藏语       |

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

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

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

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

```java
public interface AsrCallbacks {    
    void onResult(ASR.ASRResult asrResult, Object usrContext);     
    void onError(ASR.ASRError asrError, Object usrContext); 
}
```

AsrCallbacks数据结构说明：

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

| 参数       | 类型          | 说明           |
| :--------- | :------------ | :------------- |
| asrResult  | ASR.ASRResult | 识别结果结构体 |
| usrContext | Object        | 用户自定义标识 |

- ASR.ASRResult结构说明：

- Vad结构体说明：

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

- Transcription结构体说明：

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

- Segment结构体说明：

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

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

| 参数       | 类型         | 说明           |
| :--------- | :----------- | :------------- |
| asrError   | ASR.ASRError | 错误信息结构体 |
| usrContext | Object       | 用户自定义标识 |

- ASR.ASRError结构说明

| 方法        | 返回值类型 | 说明          |
| :---------- | :--------- | :------------ |
| getErrMsg() | String     | 错误信息      |
| getCode()   | int        | 错误码        |
| getSid()    | String     | 本次交互的sid |

具体示例如下：

```java
AsrCallbacks mAsrCallbacks = new AsrCallbacks() { 
 @Override 
 public void onResult(ASR.ASRResult asrResult, Object o) { 	
 int vad_begin = -1; 
 int vad_end = -1; 
 String word = null; 
 String result = asrResult.getBestMatchText();//解析识别结果 
 int status = asrResult.getStatus();//解析结果返回状态 
 String sid = asrResult.getSid();//解析sid 
 //以下信息需要开发者根据自身需求，如无必要，可不需要解析执行。 
 List<Vad> vads = asrResult.getVads();//解析vad结构体 
 for(Vad vad:vads){ 	
 vad_begin = vad.getBegin();//解析vad前端点 
 vad_end = vad.getEnd();//解析vad后端点 
 } 
 List<Transcription> transcriptions = asrResult.getTranscriptions();//解析具体结果信息 
 for(Transcription transcription : transcriptions){ 
 List<Segment> segments = transcription.getSegments();//解析中文分词结构体 
 for(Segment segment:segments){ 
 word = segment.getText();//解析词语 
 } 
 } 
 } 
 @Override 
 public void onError(ASR.ASRError asrError, Object o) { 	
 int errCode = asrError.getCode();//错误码 
 String errMsg = asrError.getErrMsg();//错误信息 
 String sid = asrError.getSid();//本次交互的sid 
 } 
}; 
asr.registerCallbacks(mAsrCallbacks);
```

## 10. 启动会话

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

```java
public class AudioAttributes { 
    public AudioAttributes() {            
    
    }         
    public void setSampleRate(int mSampleRate) {        
        ...    
    }     
    public void setEncoding(String mEncoding) {        
        ...    
    }	     
} 
public class ASR {    
    public int start(Object usrTag) {        
        ...    
    }     
    public int start(AudioAttributes attributes, Object usrTag) {        
        ...    
    } 
}
```

- start方法参数说明：

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

- AudioAttributes结构说明：

| 方法名 | 返回值类型 | 参数名 | 参数类型 | 说明 |
| ------------- | ---------- | ----------- | -------- | ------------------------------------------------------------ |
| setSampleRate | void | mSampleRate | int | 输入音频的采样率，支持8k和16k |
| setEncoding | void | mEncoding | 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 |

具体示例如下：

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

## 11. 送入数据

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

```java
public class ASR {    
    public int write(byte[] data) {        
        ...    
    } 
}
```

write方法参数说明：

| 参数 | 类型   | 说明     |
| :--- | :----- | :------- |
| data | byte[] | 识别数据 |

发送数据时，如果间隔时间太短，可能会导致引擎识别有误。建议每次发送音频间隔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格式音频？

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

具体示例如下：

```java
byte[] data = new byte[1280]; 
...//省略获取音频的过程 
asr.write(data);
```

## 12. 停止会话

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

```java
public class ASR {    
    public int stop(boolean immediate) {        
        ...    
    } 
}
```

stop方法参数说明：

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

具体示例如下：

```java
asr.stop(false);
```

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

## 13. 逆初始化

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

```java
SparkChain.getInst().unInit();
```

## 14. SDK API介绍

### 14.1 SparkChainConfig API

### 14.2 SparkChain API

| 返回值类型 | 方法说明 |
| :--------- | :----------------------------------------------------------- |
| SparkChain | public static SparkChain getInst() 获取SparkChain实例 |
| int | public int init(Context context, SparkChainConfig config) SDK初始化 |
| int | public int init(Context context) SDK初始化 |
| int | public int unInit() SDK逆初始化 |
| int | public int getInitCode() 获取SDK初始化结果码 |

### 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                                        | 参数值不合法                                 | 检查报错信息中的参数值是否在取值范围内                       |
| 10009         | input invalid data                                      | 输入数据非法                                 | 检查输入数据                                                 |
| 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                                           | 参数错误                                     | 引擎编解码错误                                               |
| 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未发送数据并且未关闭连接                      |
| 10222         | context deadline exceeded                               | 1.上传的数据超过了接口上限； 2.SSL证书无效； | 1.检查接口上传的数据（文本、音频、图片等）是否超越了接口的最大限制，可到相应的接口文档查询具体的上限； 2. 请将log导出发到工单：https://console.xfyun.cn/workorder/commit； |
| 10223         | RemoteLB: can't find valued addr                        | lb 找不到节点                                | 提交工单                                                     |
| 10313         | appid cannot be empty                                   | appid不能为空                                | 检查common参数是否正确上传，或common中的app_id参数是否正确上传或是否为空 |
| 10317         | invalid version                                         | 版本非法                                     | 联系技术人员                                                 |
| 10700         | not authority                                           | 引擎异常                                     | 按照报错原因的描述，对照开发文档检查输入输出，如果仍然无法排除问题，请提供sid以及接口返回的错误信息，到控制台提交工单联系技术人员排查。 |
| 11200         | auth no license                                         | 没有权限                                     | 检查是否使用了未授权的功能，或者总的调用次数已超越上限       |
| 11201         | auth no enough license                                  | 日流控超限                                   | 可联系商务提高每日调用次数                                   |
| 11502         | server error: too many datas in resp                    | 服务配置错误                                 | 提交工单                                                     |
| 11503         | server error :atmos return an error data                | 服务内部响应数据错误                         | 提交工单                                                     |
| 100001~100010 | WrapperInitErr                                          | 调用引擎时出现错误                           | 提交工单                                                     |