Android SDK集成文档

# SparkChain 图像理解 Android SDK集成文档

## 1. 图像理解简介

SparkChain支持用户发送一张图片和文本，向大模型提问图片相关的问题，大模型基于发送的图片来给出相应的答案。

## 2. 兼容性说明

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

## 3. 授权说明

星火认知大模型授权支持按照tokens授权和设备级授权两种方式。

tokens 授权：授权tokens总量，按照tokens 使用量计费，1 tokens 约等于1.5个中文汉字 或者 0.8个英文单词。

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

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

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

├── ReleaseNotes.txt SDK版本日志

├── SDK SparkChain SDK

│ └── SparkChain.aar

└── SparkChain 图片理解 Android SDK集成文档.pdf SparkChain集成指南

## 5. SDK工程配置

### 5.1 导入SDK库

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

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

### 5.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"/>
```

### 5.3 混淆配置

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

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

## 6. 接口流程调用图

![](/media/202405/Android图片理解流程图_1714992161.png)

## 7. 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：初始化失败，请根据具体返回值参考错误码章节查询原因。

## 8. LLM 初始化

SDK是通过LLM实例和大模型进行交互的，不同的功能需要创建不同类型的LLM实例，SDK通过LLMFactory类向开发者提供相应功能的LLM实例。LLMFactory提供的LLM实例构造方法如下：

| 功能 | 说明 |
| :------- | :----------------------------------------------------------- |
| 图片理解 | 构造方法： public static LLM imageUnderstanding() public static LLM imageUnderstanding(Memory memory) public static LLM imageUnderstanding(LLMConfig config) public static LLM imageUnderstanding(LLMConfig config, Memory memory) 参数说明： config:星火大模型配置参数。其中的domain为image，其他domain参数不生效。 memory:Memory，星火可以根据memory进行上下文关联回答 |

- LLMConfig 结构如下：

```java
public class LLMConfig {    
    public LLMConfig uid(String uid) {...}    
    public LLMConfig domain(String domain) {...}    
    public LLMConfig auditing(String auditing) {...}    
    public LLMConfig chatID(String chatID) {...}    
    public LLMConfig temperature(float temperature) {...}    
    public LLMConfig topK(int topK) {...}    
    public LLMConfig maxToken(int maxToken) {...}    
    public LLMConfig url(String url) {...}  }
```

- LLMConfig参数说明：

- Memory支持windowMemory、tokenMemory两种模式，具体说明如下：

| 类型         | 说明                                                         | 构造参数类型 | 构造参数限制                                                 | 是否必填 |
| :----------- | :----------------------------------------------------------- | :----------- | :----------------------------------------------------------- | :------- |
| windowMemory | 通过会话轮数控制上下文范围，即一次提问和一次回答为一轮会话交互。用户可指定会话关联几轮上下文。 | int          | 最小值：0，最大值：无，实际送入长度受接口Token阈值限制       | 是       |
| tokenMemory  | 通过Token总长度控制上下文范围，1 token 约等于1.5个中文汉字 或者 0.8个英文单词。用户可指定历史会话Token长度 | int          | 最小值：0，最大值：general：4096 tokens，generalv2：8192 tokens | 是       |

开发者在使用memory中，可以通过调用llm.clearHistory()方法清空其memory。

具体构造示例如下：

```java
Memory window_memory = Memory.windowMemory(5);
//windowMemory Memory tokens_memory = Memory.tokenMemory(8192);//tokenMemory 
/****** *图片理解 *******/ 
LLMConfig image_llmConfig = LLMConfig.builder()    
    .maxToken(2048)    
    ... 
    .topK(4);//config配置可缺省，demo仅供展示如何使用,开发者根据实际情况选择。 
LLM image_llm = LLMFactory.imageUnderstanding(image_llmConfig,tokens_memory);
```

## 9. 同步调用

用户可以通过image_llm.run方法向大模型发送图片理解请求，获取大模型返回结果，不支持单实例并发调用。调用接口如下：

```java
public class LLM { 
    public LLMOutput run(String question, byte[] image) { 	
        ... 
    } 	
    public LLMOutput run(String question, byte[] image, int ttl) { 	
        ... 
    }     
}
```

run方法参数说明：

| 参数名   | 类型   | 说明                       | 限制                                         | 是否必填                                                     |
| :------- | :----- | :------------------------- | :------------------------------------------- | :----------------------------------------------------------- |
| question | String | 输入信息文本，包含历史信息 | general：4096 tokens generalv2：8192 tokens  | 是                                                           |
| image    | byte[] | 输入图片的二进制数据流     | 模型自动判断格式，直接传二进制数据即可       | 是(多轮交互中，除了第一轮交互需要传入图片外，第二轮开始可以不传图片，SDK的memory会自动拼接图片数据流) |
| ttl      | int    | 同步调用超时时间           | 用户根据自身需求设置相应的超时时间，默认30秒 | 否                                                           |

LLMOutput数据结构说明：

具体调用示例如下(已省略把图片转换成二进制数据流代码，具体参考Demo，这里只展示接口如何使用):

```java
byte[] imageData = null; 
...//省略把图片转换成二进制数据流代码 
LLMOutput syncOutput = image_llm.run("图片的内容是什么？",imageData); 
//解析获取的结果，示例展示所有结果获取，开发者可根据自身需要，选择获取。 
String content       = syncOutput.getContent();//获取调用结果 
int errCode          = syncOutput.getErrCode();//获取结果ID,0:调用成功，非0:调用失败 
String errMsg        = syncOutput.getErrMsg();//获取错误信息 
String role          = syncOutput.getRole();//获取角色信息 
String sid           = syncOutput.getSid();//获取本次交互的sid 
int completionTokens = syncOutput.getCompletionTokens();//获取回答的Token大小 
int promptTokens     = syncOutput.getPromptTokens();//包含历史问题的总Tokens大小 
int totalTokens      = syncOutput.getTotalTokens();//promptTokens和completionTokens的和，也是本次交互计费的Tokens大小
```

## 10. 异步调用

用户可以通过image_llm.arun方法向大模型发送图片理解请求，获取大模型返回结果，不支持单实例并发调用。

### 10.1 注册结果监听回调

图片理解的异步请求结果通过LLMCallbacks监听回调返回，LLMCallbacks监听回调接口如下：

```java
LLMCallbacks llmCallbacks = new LLMCallbacks() {    
    @Override 
    public void onLLMResult(LLMResult llmResult, Object usrContext) {    	 
    
    }      
    @Override    
    public void onLLMEvent(LLMEvent event, Object usrContext) {  		    
    
    }      
    @Override    
    public void onLLMError(LLMError error, Object usrContext) {            
    
    } 
};
```

LLMCallbacks数据结构说明：

- onLLMResult为星火请求结果回调，参数说明如下：

| 参数       | 类型      | 说明               |
| :--------- | :-------- | :----------------- |
| result     | LLMResult | 星火大模型结果实例 |
| usrContext | Object    | 用户自定义标识     |

- LLMResult结构说明：

- onLLMEvent为星火请求事件回调，参数说明如下：

| 参数       | 类型     | 说明             |
| :--------- | :------- | :--------------- |
| event      | LLMEvent | 调用事件结果实例 |
| usrContext | Object   | 用户自定义标识   |

- LLMEvent结构说明：

- onLLMError为星火请求错误回调，参数说明如下：

| 参数       | 类型     | 说明             |
| :--------- | :------- | :--------------- |
| error      | LLMError | 错误信息结果实例 |
| usrContext | Object   | 用户自定义标识   |

- LLMError结构说明：

具体调用示例如下：

```java
LLMCallbacks llmCallbacks = new LLMCallbacks() {    
    @Override 
    public void onLLMResult(LLMResult llmResult, Object usrContext) {    	
        //解析获取的交互结果，示例展示所有结果获取，开发者可根据自身需要，选择获取。        
        String content       = llmResult.getContent();//获取交互结果    	
        int status           = llmResult.getStatus();//返回结果状态        
        String role          = llmResult.getRole();//获取角色信息        
        String sid           = llmResult.getSid();//本次交互的sid        
        int completionTokens = llmResult.getCompletionTokens();//获取回答的Token大小        
        int promptTokens     = llmResult.getPromptTokens();//包含历史问题的总Tokens大小        
        int totalTokens      = llmResult.getTotalTokens();//promptTokens和completionTokens的和，也是本次交互计费的Tokens大小 
    }      
    @Override    
    public void onLLMEvent(LLMEvent event, Object usrContext) {        
        int eventId     = event.getEventID();//获取事件ID        
        String eventMsg = event.getEventMsg();//获取事件信息        
        String sid      = event.getSid();//本次交互的sid    
    }      
    @Override    
    public void onLLMError(LLMError error, Object usrContext) {        
        int errCode   = error.getErrCode();//返回错误码        
        String errMsg = error.getErrMsg();//获取错误信息        
        String sid    = error.getSid();//本次交互的sid    
    } 
}; 
image_llm.registerLLMCallbacks(llmCallbacks);
```

### 10.2 请求调用

异步请求调用接口如下：

```java
public class LLM { 
    public int arun(String question, byte[] image) { 	
        ... 
    } 	
    public int arun(String question, byte[] image, Object usrTag) { 	
        ... 
    }     
}
```

arun方法参数说明：

| 参数     | 类型   | 说明                   | 限制                                        | 是否必填                                                     |
| :------- | :----- | :--------------------- | :------------------------------------------ | :----------------------------------------------------------- |
| question | String | 输入信息文本           | general：4096 tokens generalv2：8192 tokens | 是                                                           |
| image    | byet[] | 输入图片的二进制数据流 | 模型自动判断格式，直接传二进制数据即可      | 是(多轮交互中，除了第一轮交互需要传入图片外，第二轮开始可以不传图片，SDK的memory会自动拼接图片数据流) |
| usrTag   | Object | 用户自定义标识         |                                             | 否                                                           |

具体调用示例如下(已省略把图片转换成二进制数据流代码，具体参考Demo，这里只展示接口如何使用):

```java
byte[] imageData = null; 
...//省略把图片转换成二进制数据流代码 
image_llm.arun("图片的内容是什么？",imageData);
```

## 11. 停止调用

如果开发者不需要此次交互结果，可以通过调用stop()方法抛弃此结果，然后重新进行下一次交互。注意，虽然调用此方法可以让SDK抛弃此次交互结果，但由于本次交互已经产生，因此还是会扣取相应的token量。具体调用如下：

```java
image_llm.stop();
```

如果不需要继续使用SDK，需要执行逆初始化释放资源。逆初始化执行步骤参考第12节。

## 12. 逆初始化

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

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

## 13. SDK API介绍

### 13.1 SparkChainConfig API

### 13.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初始化结果码 |

### 13.3 LLMConfig API

### 13.4 Memory API

### 13.5 LLMFactory API

| 返回值类型 | 方法说明 |
| :--------- | :----------------------------------------------------------- |
| LLM | public static LLM textGeneration(LLMConfig config, Memory memory) 构建文本交互LLM |
| LLM | public static LLM textGeneration(LLMConfig config) 构建文本交互LLM |
| LLM | public static LLM textGeneration(Memory memory) 构建文本交互LLM |
| LLM | public static LLM textGeneration() 构建文本交互LLM |
| LLM | public static LLM imageUnderstanding(LLMConfig config, Memory memory) 构建图片理解LLM |
| LLM | public static LLM imageUnderstanding(LLMConfig config) 构建图片理解LLM |
| LLM | public static LLM imageUnderstanding(Memory memory) 构建图片理解LLM |
| LLM | public static LLM imageUnderstanding() 构建图片理解LLM |
| LLM | public static LLM imageGeneration(int width, int height, LLMConfig config) 构建图片生成LLM |
| LLM | public static LLM imageGeneration(int width, int height) 构建图片生成LLM |
| LLM | public static LLM imageGeneration(LLMConfig config) 构建图片生成LLM |
| LLM | public static LLM imageGeneration() 构建图片生成LLM |

### 13.6 LLM API

### 13.7 LLMOutput API

### 13.8 LLMError API

### 13.9 LLMEvent API

### 13.10 LLMResult API

## 14. 错误码

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

### 14.1 SDK错误码

### 14.2 云端错误码

| 错误码 | 错误信息                                                     |
| :----- | :----------------------------------------------------------- |
| 错误码 | 错误信息                                                     |
| 0      | 成功                                                         |
| 10000  | 升级为ws出现错误                                             |
| 10001  | 通过ws读取用户的消息出错                                     |
| 10002  | 通过ws向用户发送消息 错                                      |
| 10003  | 用户的消息格式有错误                                         |
| 10004  | 用户数据的schema错误                                         |
| 10005  | 用户参数值有错误                                             |
| 10006  | 用户并发错误：当前用户已连接，同一用户不能多处同时连接。     |
| 10007  | 用户流量受限：服务正在处理用户当前的问题，需等待处理完成后再发送新的请求。（必须要等大模型完全回复之后，才能发送下一个问题） |
| 10008  | 服务容量不足，联系工作人员                                   |
| 10009  | 和引擎建立连接失败                                           |
| 10010  | 接收引擎数据的错误                                           |
| 10011  | 发送数据给引擎的错误                                         |
| 10012  | 引擎内部错误                                                 |
| 10013  | 输入内容审核不通过，涉嫌违规，请重新调整输入内容             |
| 10014  | 输出内容涉及敏感信息，审核不通过，后续结果无法展示给用户     |
| 10015  | appid在黑名单中                                              |
| 10016  | appid授权类的错误。比如：未开通此功能，未开通对应版本，token不足，并发超过授权 等等 |
| 10017  | 清除历史失败                                                 |
| 10019  | 表示本次会话内容有涉及违规信息的倾向；建议开发者收到此错误码后给用户一个输入涉及违规的提示 |
| 10021  | 输入审核不通过                                               |
| 10022  | 模型生产的图片涉及敏感信息，审核不通过                       |
| 10110  | 服务忙，请稍后再试                                           |
| 10163  | 请求引擎的参数异常 引擎的schema 检查不通过                   |
| 10222  | 引擎网络异常                                                 |
| 10907  | token数量超过上限。对话历史+问题的字数太多，需要精简输入     |
| 11200  | 授权错误：该appId没有相关功能的授权 或者 业务量超过限制      |
| 11201  | 授权错误：日流控超限。超过当日最大访问量的限制               |
| 11202  | 授权错误：秒级流控超限。秒级并发超过授权路数限制             |
| 11203  | 授权错误：并发流控超限。并发路数超过授权路数限制             |