Spark Android SDK接入文档
注意： 该接口可以正式使用。如您需要申请使用，请点击前往产品页面 。
Tips：
- 计费包含接口的输入和输出内容
- 1tokens 约等于1.5个中文汉字 或者 0.8个英文单词
- 星火V1.5支持[搜索]内置插件；星火V2.0和V3.0支持[搜索]、[天气]、[日期]、[诗词]、[字词]、[股票]六个内置插件
#1. SDK介绍
Spark SDK提供了一套快速集成星火大模型的工具，让开发者无需关注底层协议细节，提高开发效率。同时，它支持Android、Linux、iOS、Windows多个平台，方便开发者选择最适合自己的平台进行开发。Spark SDK可以帮助企业快速将星火大模型应用到业务场景中，提高效率和竞争力。本文档主要介绍Android平台集成过程。
#2. 兼容性说明
| 类别 | 兼容范围 |
|---|---|
| 系统 | 支持armv7和armv8架构，兼容android 5.0及以上版本 |
| 开发环境 | 建议使用Android Studio 进行开发 |
#3. 授权说明
星火认知大模型授权支持按照tokens授权和设备级授权两种方式。
tokens 授权：授权tokens总量，按照tokens 使用量计费，1 tokens 约等于1.5个中文汉字 或者 0.8个英文单词。
设备级授权：授权设备台数和有效期，按照设备指纹计量计费，此方式仅支持定制级客户，如有需要请与开放平台联系。
#4. SDK集成包目录结构
将SDK zip包解压缩，得到如下文件：
├── Demo Spark的使用DEMO，DEMO中已经集成了SDK，您可以参考DEMO，集成SDK。集成前，请先测通DEMO，了解调用原理。
├── ReleaseNotes.txt SDK版本日志
├── SDK Spark SDK
│ └── SparkChain.aar
└── SparkChain LLM Android SDK集成文档.pdf Spark集成指南
#5. 接口调用流程图
#6. SDK工程配置
#6.1 导入SDK库
复制SparkChain.aar到项目的libs目录下，然后在主Module的build.gradle文件中，增加如下配置：
implementation files('libs/SparkChain.aar')
#6.2 配置权限
Spark SDK中使用了如下权限：
| 权限 | 使用说明 |
|---|---|
| INTERNET | 必须权限，SDK需要访问网络获取结果。 |
| READ_EXTERNAL_STORAGE | 必须权限，SDK需要判断日志路径是否存在。 |
| WRITE_EXTERNAL_STORAGE | 必须权限，SDK写本地日志需要用到该权限。 |
| MANAGE_EXTERNAL_STORAGE | 可选权限，安卓10以上设备用于动态授权弹出授权框需要用到该权限，安卓10以上设备必选。 |
| READ_PHONE_STATE | 可选权限，用于获取设备标识。 |
SDK中已配置如下权限，如部分权限不需要，可通过如下配置去除
<!-- 移除SDK非必须权限示例 -->
<uses-permission android:name="android.permission.READ_PHONE_STATE" tools:node="remove" />
Android 10.0（API 29）及以上版本需要在application中做如下配置
<application android:requestLegacyExternalStorage="true"/>
#7. 快速集成
#7.1 SDK初始化
*在使用Spark SDK 星火大模型交互功能前，需要首先开通星火大模型授权并获取已开通授权的应用信息***（appId、apiKey、apiSecret）。SDK全局只需要初始化一次。初始化示例如下：
SparkChainConfig config = SparkChainConfig.builder()
.appID("$appId")
.apiKey("$apiKey")
.apiSecret("$apiSecret");//从平台获取的授权appid，apikey,apisecrety
int ret = SparkChain.getInst().init(getApplicationContext(), config);
Log.d(TAG,"sdk init:"+ret);
初始化参数说明：
| 参数名 | 类型 | 说明 | 是否必填 |
|---|---|---|---|
| appID | String | 创建应用后，生成的应用ID | 是 |
| apiKey | String | 创建应用后，生成的唯一应用标识 | 是 |
| apiSecret | String | 创建应用后，生成的唯一应用秘钥 | 是 |
| logLevel | int | 0：VERBOSE，1：DEBUG，2：INFO，3：WARN，4：ERROR，5：FATAL，100：OFF | 否 |
| logPath | String | 日志存储路径，设置则会把日志存在该路径下，不设置则会把日志打印在终端上 | 否 |
| uid | String | 用户自定义标识 | 否 |
初始化返回值：0：初始化成功，非0：初始化失败，请根据具体返回值参考错误码章节查询原因。
#7.2 配置星火大模型参数
首先需要配置星火大模型的相关参数，示例如下：
LLMConfig llmConfig = LLMConfig.builder();
llmConfig.domain("generalv2");
llmConfig.url("ws(s)://spark-api.xf-yun.com/v2.1/chat");//如果使用generalv2，domain和url都可缺省，SDK默认；如果使用general，url可缺省，SDK会自动补充；如果是其他，则需要设置domain和url。
LLM llm = new LLM(llmConfig);
参数说明：
| 字段 | 含义 | 类型 | 限制 | 是否必传 |
|---|---|---|---|---|
| domain | 需要使用的领域 | String | 取值为[general,generalv2]，默认generalv2 general：通用大模型V1.5版本 generalv2：通用大模型V2版本 general和generalv2对应的url不同，需要严格对应。url地址参见下文。 | 否 |
| url | 配置chat服务器域名地址 | String | general：ws(s): //spark-api.xf-yun.com/v1.1/chat generalv2：ws(s): //spark-api.xf-yun.com/v2.1/chat generalv3：ws(s): //spark-api.xf-yun.com/v3.1/chat domian 取值为 general或generalv2 时，SDK自动设置url，可缺省。 | 否 |
| maxToken | 回答的tokens的最大长度 | int | 取值范围1-4096，默认：2048 | 否 |
| temperature | 配置核采样阈值，改变结果的随机程度 | float | 最小：0, 最大：1，默认：0.5 | 否 |
| auditing | 内容审核的场景策略 | String | 当前仅支持default | 否 |
| topK | 配置从k个候选中随机选择⼀个（⾮等概率) | int | 取值范围1-6，默认值：4 | 否 |
| chatID | 配置关联会话chat_id标识，需要保障用户下唯一 | String | 否 |
#7.3 星火请求调用
当前支持同步调用和异步调用两种方式。用户可以通过run方法或者arun方法向大模型发送问题请求，获取大模型返回结果。run方法、arun方法不支持并发调用。
#7.3.1 同步调用
#7.3.1.1 请求调用
//同步调用
// 第一轮交互，如果不需要交互上下文，均可按照此方式调用
String question1 = "上海有什么景点？";
LLMOutput syncOutput = llm.run(question1);
if(syncOutput.getErrCode() == 0) {
Log.i(TAG, "同步调用：" + syncOutput.getRole() + ":" + syncOutput.getContent());
results = syncOutput.getContent();
}else {
Log.e(TAG, "同步调用：" + "errCode" + syncOutput.getErrCode() + " errMsg:" + syncOutput.getErrMsg());
}
//第二轮交互 示例带历史上下文的交互
String question2 = "那帮我安排一份旅游计划吧。";
try{
JSONArray array = new JSONArray();
JSONObject item_1 = new JSONObject();
item_1.put("role","user");
item_1.put("content",question1);
JSONObject item_2 = new JSONObject();
item_2.put("role","assistant");
item_2.put("content",results);
JSONObject item_3 = new JSONObject();
item_3.put("role","user");
item_3.put("content",question2);
array.put(item_1).put(item_2).put(item_3);
syncOutput = llm.run(array.toString());
if(syncOutput.getErrCode() == 0) {
Log.i(TAG, "同步调用：" + syncOutput.getRole() + ":" + syncOutput.getContent());
results = syncOutput.getContent();
}else {
Log.e(TAG, "同步调用：" + "errCode" + syncOutput.getErrCode() + " errMsg:" + syncOutput.getErrMsg());
}
}catch(Exception e){
e.printStackTrace();
}
run方法参数说明：
| 参数名 | 类型 | 说明 | 限制 | 是否必填 |
|---|---|---|---|---|
| question | String | 输入信息文本，包含历史信息 | general：4096 tokens generalv2:8192 tokens | 是 |
LLMOutput数据结构说明：
| 参数 | 类型 | 获取方法 | 说明 |
|---|---|---|---|
| errCode | int | getErrCode() | 调用结果状态，0：调用成功，非0：调用失败，具体原因请根据返回值参考错误码 |
| errMsg | String | getErrMsg() | 调用失败时的错误信息 |
| role | String | getRole() | 星火大模型的角色，assistant:：助手，user：用户 |
| content | String | getContent() | 调用结果 |
| completionTokens | int | getCompletionTokens() | 回答的Token大小 |
| promptTokens | int | getPromptTokens() | 包含历史问题的总Tokens大小 |
| totalTokens | int | getTotalTokens() | promptTokens和completionTokens的和，也是本次交互计费的Tokens大小 |
返回结果参考7.4节响应协议说明。
#7.3.2 异步调用
#7.3.2.1.注册结果监听回调
//异步调用
LLMCallbacks llmCallbacks = new LLMCallbacks() {
@Override
public void onLLMResult(LLMResult llmResult, Object usrContext) {
Log.d(TAG,"异步调用：" + "onLLMResult:" + " " + llmResult.getRole() + " " + llmResult.getContent());
}
@Override
public void onLLMEvent(LLMEvent event, Object usrContext) {
Log.w(TAG,"onLLMEvent:" + " " + event.getEventID() + " " + event.getEventMsg());
}
@Override
public void onLLMError(LLMError error, Object usrContext) {
Log.e(TAG,"onLLMError:" + " " + error.getErrCode() + " " + error.getErrMsg());
}
};
llm.registerLLMCallbacks(llmCallbacks);
LLMCallbacks数据结构说明：
| 方法 | 参数 | 类型 | 说明 |
|---|---|---|---|
| onLLMResult | result | LLMResult | 星火大模型结果实例 |
| usrContext | Object | 用户自定义标识 | |
| onLLMEvent | event | LLMEvent | 调用事件结果实例 |
| usrContext | Object | 用户自定义标识 | |
| onLLMError | error | LLMError | 错误信息结果实例 |
| usrContext | Object | 用户自定义标识 |
LLMResult数据结构说明：
| 结构类 | 方法 | 说明 |
|---|---|---|
| LLMResult | getRole | 星火大模型角色，assistant:：助手，user：用户 |
| getContent | 调用结果 | |
| getCompletionTokens() | 回答的Token大小 | |
| getPromptTokens() | 包含历史问题的总Tokens大小 | |
| getTotalTokens() | promptTokens和completionTokens的和，也是本次交互计费的Tokens大小 | |
| getStatus() | 返回结果状态，0：start，1：continue，2：end | |
| LLMEvent | getEventID | 事件ID，15：建立连接，19：连接断开 |
| getEventMsg | 事件信息 | |
| LLMError | getErrCode | 错误码ID |
| getErrMsg | 错误信息 |
#7.3.2.2 请求调用
String myContext = "myContext";
//异步调用
// 第一轮交互，如果不需要交互上下文，均可按照此方式调用
String question1 = "上海有什么景点？";
int ret = llm.arun(question1,myContext);
while (!isFinsh){
try {
Thread.sleep(100);
}catch (Exception e){
}
}
Log.d(TAG,"turn1:"+results);
isFinsh = false;
results = "";
//第二轮交互 示例带历史上下文的交互
String question2 = "那帮我安排一份旅游计划吧。";
try{
JSONArray array = new JSONArray();
JSONObject item_1 = new JSONObject();
item_1.put("role","user");
item_1.put("content",question1);
JSONObject item_2 = new JSONObject();
item_2.put("role","assistant");
item_2.put("content",results);
JSONObject item_3 = new JSONObject();
item_3.put("role","user");
item_3.put("content",question2);
array.put(item_1).put(item_2).put(item_3);
ret = llm.arun(array.toString(),myContext);
}catch(Exception e){
e.printStackTrace();
}
while (!isFinsh){
try {
Thread.sleep(100);
}catch (Exception e){
}
}
Log.d(TAG,"turn2:"+results);
arun方法参数说明：
| 参数 | 类型 | 说明 | 限制 | 是否必填 |
|---|---|---|---|---|
| question | String | 输入信息文本 | general：4096 tokens generalv2：8192 tokens | 是 |
| usrTag | Object | 用户自定义标识 | 否 |
返回结果参考7.4节响应协议说明。
#7.4 响应协议说明
该协议为中间协议，星火大模型是按照此协议格式返回结果。SDK已完成对此协议的解析和封装，获取相应字段方法请查询7.3节LLMOutput和LLMResult的结构说明。
# 接口为流式返回，此示例为最后一次返回结果，开发者需要将接口多次返回的结果进行拼接展示
{
"header":{
"code":0,
"message":"Success",
"sid":"cht000b2d3c@dx18a980cc0beb894540",
"status":2
},
"payload":{
"choices":{
"status":2,
"seq":9,
"text":[
{
"content":"”",
"role":"assistant",
"index":0
}
]
},
"usage":{
"text":{
"question_tokens":15,
"prompt_tokens":15,
"completion_tokens":61,
"total_tokens":76
}
}
}
}
协议结构说明
| 字段 | 含义 | 类型 | 说明 |
|---|---|---|---|
| header | 协议头部 | Object | 协议头部，用于描述平台特性的参数 |
| payload | 响应数据块 | Object | 数据段，携带响应的数据。 |
响应参数说明
| 字段 | 含义 | 类型 |
|---|---|---|
| sid | 本次会话的id | String |
| status | 数据状态 0:start，1:continue，2:end | int |
| seq | 数据序号，标明数据为第几块。最小值:0, 最大值:9999999 | int |
| content | 文本数据 | String |
| role | 星火大模型角色 | String |
| prompt_tokens | 包含历史问题的总Tokens大小 | int |
| completion_tokens | 回答的Token大小 | int |
| total_tokens | promptTokens和completionTokens的和，也是本次交互计费的Tokens大小 | int |
#7.5 SDK逆初始化
当SDK需要完整退出时，需调用逆初始化方法释放资源，示例代码如下：
SparkChain.getInst().unInit();
#8. 错误码
错误码包含SDK错误码和云端错误码，SDK错误码用来反馈SDK本地运行时遇到的错误；云端错误码用来反馈星火大模型交互时服务端错误。
#8.1 SDK错误码
| 错误码 | 含义 | 自查指南 |
|---|---|---|
| 0 | 操作成功 | |
| 18007 | 授权应用不匹配（apiKey、apiSecret） | apiKey、apiSecret 配置有误，请核对项目中配置的 apiKey、apiSecret 。 |
| 18301 | SDK未初始化 | 在使用大模型前请先初始化 SDK，如果有调用 uninit 方法，再次使用大模型交互时需要重新初始化。 |
| 18302 | SDK初始化失败 | 请根据init接口回调中返回的错误码参考此文档做对应检查 |
| 18303 | SDK 已经初始化 | 重复初始化导致，使用能力时，SDK 只需要初始化一次，请检查 SDK 初始化逻辑是否存在多次初始化。 |
| 18304 | 不合法参数 | 请参考demo及集成文档仔细检查所传参数是否正确。 |
| 18311 | sdk同一能力并发路数超出最大限制 | |
| 18312 | 此实例已处在运行态，禁止单实例并发运行 | |
| 18400 | 工作目录无写权限 | 在设置 workDir 时，请确保该工作路径有读写权限。若无法设置读写权限，请修改为有读写权限的工作路径。 |
| 18402 | 文件打开失败 | 请检查 日志中所打印的文件是否存在，以及对应路径下是否有读权限。 |
| 18500 | 未找到该参数 key | 请参照demo或集成文档仔细检查参数名拼写 |
| 18501 | 参数范围溢出，不满足约束条件 | 请根据文档检查调用 SDK 方法时所传参数范围，需要确保所传参数符合协议约束要求 |
| 18502 | SDK 初始化参数为空 | 请根据 SDK 集成文档检查 SDK 初始化代码，确保必填参数有值且合法 |
| 18503 | SDK 初始化参数中 appId 为空 | appId 为空值，请在 SDK 初始化时传入正确的 appId 值 |
| 18504 | SDK 初始化参数中 apiKey为空 | apiKey为空值，请在 SDK 初始化时传入正确的 apiKey值 |
| 18505 | SDK 初始化参数中 apiSecret 为空 | apiSecret 为空值，请在 SDK 初始化时传入正确的 apapiSecret 值 |
| 18509 | 必填参数缺失 | 请参考demo或者文档检查是否漏传必填参数 |
| 18700 | 通用网络错误 | 请检查网络连接是否正常 |
| 18701 | 网络不通 | 请检查网络连接是否正常 |
| 18702 | 网关检查不过 | 检查设备时间是否正确； 请检查 SDK 初始化时所传 apiKey、apiScrect 是否正确; |
| 18703 | 云端响应格式不对 | 请检查网络是否可以正常访问外网 |
| 18705 | 应用 ApiKey & ApiSecret 校验失败 | 请检查 apiKey、apiSecret 是否正确 |
| 18707 | 授权已过期 | 请检查授权期限 |
| 18708 | 无可用授权 | 没有授权或者授权已满 |
| 18712 | 网络请求 404 错误 | 请检查网络是否通畅 |
| 18713 | 设备指纹安全等级不匹配 | 设备指纹安全等级不符合要求 |
| 18714 | 应用信息有误 | 服务端无法查询到api_key，请检查api_key和api_secret信息是否填写正确 |
| 18717 | SDK授权不足 | 授权数量已满 |
| 18801 | 连接建立出错 | 请检查网络是否通畅 |
| 18802 | 结果等待超时 | 请检查网络是否通畅 |
| 18803 | 连接状态异常 | 请检查网络是否通畅 |
| 18902 | 并发超过路数限制 | 不支持并发 |
| 18903 | 大模型规划步骤为空 | 请检查请求数据的意图是否明确 |
| 18904 | 插件未找到 | 请检查是否使用了未存在的插件 |
| 18906 | 与大模型交互次数超限制 | |
| 18907 | 运行超限制时长 | |
| 18908 | 大模型返回结果格式异常 | |
| 18951 | 同一流式大模型会话，禁止并发交互请求 | |
| 18952 | 输入文本格式或内容非法 |
#8.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 | 表示本次会话内容有涉及违规信息的倾向；建议开发者收到此错误码后给用户一个输入涉及违规的提示 |
| 10110 | 服务忙，请稍后再试 |
| 10163 | 请求引擎的参数异常 引擎的schema 检查不通过 |
| 10222 | 引擎网络异常 |
| 10907 | token数量超过上限。对话历史+问题的字数太多，需要精简输入 |
| 11200 | 授权错误：该appId没有相关功能的授权 或者 业务量超过限制 |
| 11201 | 授权错误：日流控超限。超过当日最大访问量的限制 |
| 11202 | 授权错误：秒级流控超限。秒级并发超过授权路数限制 |
| 11203 | 授权错误：并发流控超限。并发路数超过授权路数限制 |
详见服务说明
最后修改时间： 1 年前