iOS SDK接入文档
注意： 该接口可以正式使用。如您需要申请使用，请点击前往产品页面 。
Tips：
- 计费包含接口的输入和输出内容
- 1tokens 约等于1.5个中文汉字 或者 0.8个英文单词
- 星火V1.5支持[搜索]内置插件；星火V2.0支持[搜索]、[天气]、[日期]、[诗词]、[字词]、[股票]六个内置插件
#1. Spark SDK介绍
Spark SDK提供了一套快速集成星火大模型的工具，让开发者无需关注底层协议细节，提高开发效率。同时，它支持Android、Linux、iOS、Windows多个平台，方便开发者选择最适合自己的平台进行开发。Spark SDK可以帮助企业快速将星火大模型应用到业务场景中，提高效率和竞争力。本文档主要介绍iOS平台集成过程。
#2. 兼容性说明
参数说明：
| 类别 | 兼容范围 |
|---|---|
| 系统 | 支持arm64架构，兼容iOS 9.0 及以上版本 |
| 开发环境 | 建议使用Xcode 进行开发 |
#3. 授权说明
星火认知大模型授权支持按照tokens授权和设备级授权两种方式。
tokens 授权：授权tokens总量，按照tokens 使用量计费，1 tokens 约等于1.5个中文汉字 或者 0.8个英文单词。
设备级授权：授权设备台数和有效期，按照设备指纹计量计费，此方式仅支持定制级客户，如有需要请与开放平台联系。
#4. Spark SDK组成
将SDK zip包解压缩，得到如下文件：
├── Demo Spark的使用DEMO，DEMO中已经集成了SDK，您可以参考DEMO，集成SDK。集成前，请先测通DEMO，了解调用原理。
├── ReleaseNotes.txt SDK版本日志
├── SDK Spark SDK
│ └── Spark.framework
└── Spark LLM iOS SDK集成文档.pdf Spark SDK集成指南
#5. 接口调用流程图
#6. SDK工程配置
#6.1 导入SDK库
Spark iOS SDK 核心代码库由SparkChain.framework组成。在引入工程中时，在工程的General的frameworks,Libraries,and Embedded Content 中使用Embedded & sign
示例如下：
#6.2 设置BitCode
Spark iOS SDK暂不支持Bitcode，Xcode 7、Xcode 8默认开启了Bitcode，而Bitcode 需要工程依赖的所有类库同时支持，可关闭此设置，只需在Targets - Build Settings 中搜索Bitcode 即可，找到相应选项，设置为NO。
#7. 快速集成
#7.1 SDK初始化
在使用Spark SDK 星火大模型交互功能前，需要首先开通星火大模型授权并获取已开通授权的应用信息****（appId、apiKey、apiSecret）。SDK全局只需要初始化一次。初始化示例如下：：
SparkChainConfig * config = [[SparkChainConfig alloc] init];
config.appID("appID") //配置应用信息
.apiKey("apiKey")
.apiSecret("apiSecret");
int ret = [SparkChain.getInst init:config];
NSLog("初始化结果 ret = %d",ret);
初始化参数说明：
| 参数名 | 类型 | 说明 | 是否必填 |
|---|---|---|---|
| appID | NSString | 创建应用后，生成的应用ID | 是 |
| apiKey | NSString | 创建应用后，生成的唯一应用标识 | 是 |
| apiSecret | NSString | 创建应用后，生成的唯一应用秘钥 | 是 |
| logLevel | NSInteger | 0：VERBOSE，1：DEBUG，2：INFO，3：WARN，4：ERROR，5：FATAL，100：OFF | 否 |
| logPath | NSString | 日志存储路径，设置则会把日志存在该路径下，不设置则会把日志打印在终端上 | 否 |
| uid | NSString | 用户自定义标识 | 否 |
初始化返回值：0：初始化成功，非0：初始化失败，请根据具体返回值参考错误码章节查询原因。
#7.2 配置星火大模型参数
首先需要配置星火大模型的相关参数，示例如下：
LLMConfig * config = [[LLMConfig alloc] init];
config.domain(@"generalv2");
config.url(@"ws(s)://spark-api.xf-yun.com/v2.1/chat");//如果使用generalv2，domain和url都可缺省，SDK默认；如果使用general，url可缺省，SDK会自动补充；如果是其他，则需要设置domain和url。
LLM *llm = [[LLM alloc] initWithConfig:config];
参数说明：
| 字段 | 含义 | 类型 | 限制 | 是否必传 |
|---|---|---|---|---|
| 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 请求调用
//同步调用
// 第一轮交互，如果不需要交互上下文，均可按照此方式调用即可
NSString *query1 = @"上海有什么景点？";
LLMOutput *output = [llm run:query1];
if (output.errCode == 0) {
NSLog(@"同步调用：role:%@ content:%@",output.role,output.content);
}else{
NSLog(@"同步调用：errCode:%d errMsg:%@",output.errCode,output.errMsg);
}
//第二轮交互，示例带历史上下文
//构造历史上下文数据
NSString *query2 = @"那帮我带一份旅游计划吧。";
NSMutableArray *array = [[NSMutableArray alloc] init];
NSMutableDictionary *item1 = [[NSMutableDictionary alloc] init];
[item1 setValue:@"user" forKey:@"role"];
[item1 setValue:query1 forKey:@"content"];
NSMutableDictionary *item2 = [[NSMutableDictionary alloc] init];
[item2 setValue:@"assistant" forKey:@"role"];
[item2 setValue:result forKey:@"content"];
NSMutableDictionary *item3 = [[NSMutableDictionary alloc] init];
[item3 setValue:@"user" forKey:@"role"];
[item3 setValue:query2 forKey:@"content"];
[array addObject:item1];
[array addObject:item2];
[array addObject:item3];
NSError *error;
NSData *jsonData = [NSJSONSerialization dataWithJSONObject:array options:NSJSONWritingPrettyPrinted error:&error];
NSString *jsonString = [[NSString alloc] initWithData:jsonData encoding:NSUTF8StringEncoding];
//调用同步接口
output = [llm run:jsonString];
if(output.errCode == 0){
result = output.content;
NSLog(@"result2 == %@",result);
}else{
NSLog(@"%@",output.errMsg);
}
run方法参数说明：
| 参数名 | 类型 | 说明 | 限制 | 是否必填 |
|---|---|---|---|---|
| query | NSString | 输入信息文本，包含历史信息 | general：4096 tokensgeneralv2:8192 tokens | 是 |
LLMOutput数据结构说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| errCode | NSInteger | 调用结果状态，0：调用成功，非0：调用失败，具体原因请根据返回值参考错误码 |
| errMsg | NSString | 调用失败时的错误信息 |
| role | NSString | 星火大模型的角色，assistant:：助手，user：用户 |
| content | NSString | 调用结果 |
| completionTokens | NSInteger | 回答的Token大小 |
| promptTokens | NSInteger | 包含历史问题的总Tokens大小 |
| totalTokens | NSInteger | promptTokens和completionTokens的和，也是本次交互计费的Tokens大小 |
返回结果参考7.4节响应协议说明
#7.3.2 异步调用
#7.3.2.1.注册结果回调
//实现数据回调函数
- (void)llm:(LLM *)llm onResult:(LLMResult *)result usrContext:(id)usrContext {
NSLog(@"异步调用：content:%@ status:%d",result.content,result.status);
}
- (void)llm:(LLM *)llm onEvent:(LLMEvent *)event usrContext:(id)usrContext {
NSLog(@"异步调用：eventID:%d eventMsg:%@",event.eventID,event.eventMsg);
}
- (void)llm:(LLM *)llm onError:(LLMError *)error usrContext:(id)usrContext {
NSLog(@"异步调用：code:%d msg:%@",error.errCode,error.errMsg);
}
llm.callback = self;
LLMCallback数据结构说明：
| 方法 | 参数 | 类型 | 说明 |
|---|---|---|---|
| onResult | result | LLMResult | 星火大模型结果实例 |
| usrContext | id | 上下文 | |
| onEvent | event | LLMEvent | 调用事件结果实例 |
| usrContext | id | 上下文 | |
| onError | error | LLMError | 错误信息结果实例 |
| usrContext | id | 上下文 |
| 结构类 | 参数 | 说明 |
|---|---|---|
| LLMResult | role | 星火大模型角色，assistant:：助手，user：用户 |
| content | 调用结果 | |
| completionTokens | 回答的Token大小 | |
| promptTokens | 包含历史问题的总Tokens大小 | |
| totalTokens | promptTokens和completionTokens的和，也是本次交互计费的Tokens大小 | |
| status | 返回结果状态，0：start，1：continue，2：end | |
| LLMEvent | eventID | 事件ID，15：建立连接，19：断开连接 |
| eventMsg | 事件信息 | |
| LLMError | errCode | 错误码ID |
| errMsg | 错误信息 |
#7.3.2.2 请求调用
//异步调用
_sema = dispatch_semaphore_create(0);
dispatch_time_t time = dispatch_time(DISPATCH_TIME_NOW, 15);
NSString *myContext = @"myContext";
self.result = @"".mutableCopy;
//第一轮交互，如果不需要交互上下文，均可按照此方式调用
NSString *query1 = @"上海有什么景点？";
int ret = [llm arun:query1 usrContext:myContext];
dispatch_semaphore_wait(_sema, DISPATCH_TIME_FOREVER);
//第二轮交互 示例带历史上下文的交互
//构造历史上下文数据
self.result = @"".mutableCopy;
NSString *query2 = @"那帮我带一份旅游计划吧。";
NSMutableArray *array = [[NSMutableArray alloc] init];
NSMutableDictionary *item1 = [[NSMutableDictionary alloc] init];
[item1 setValue:@"user" forKey:@"role"];
[item1 setValue:query1 forKey:@"content"];
NSMutableDictionary *item2 = [[NSMutableDictionary alloc] init];
[item2 setValue:@"assistant" forKey:@"role"];
[item2 setValue:self.result forKey:@"content"];
NSMutableDictionary *item3 = [[NSMutableDictionary alloc] init];
[item3 setValue:@"user" forKey:@"role"];
[item3 setValue:query2 forKey:@"content"];
[array addObject:item1];
[array addObject:item2];
[array addObject:item3];
NSError *error;
NSData *jsonData = [NSJSONSerialization dataWithJSONObject:array options:NSJSONWritingPrettyPrinted error:&error];
NSString *jsonString = [[NSString alloc] initWithData:jsonData encoding:NSUTF8StringEncoding];
//调用异步接口
ret = [llm arun:jsonString usrContext:myContext];
dispatch_semaphore_wait(_sema, DISPATCH_TIME_FOREVER);
arun方法参数说明：
| 参数 | 类型 | 说明 | 限制 | 是否必填 |
|---|---|---|---|---|
| query | NSString | 输入信息文本 | general：4096 tokens,generalv2和generalv3：8192 tokens | 是 |
| usrContext | 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 | NSString |
| status | 数据状态 0:start，1:continue，2:end | NSInteger |
| seq | 数据序号，标明数据为第几块。最小值:0, 最大值:9999999 | NSInteger |
| content | 文本数据 | NSString |
| role | 星火大模型角色 | NSString |
| prompt_tokens | 包含历史问题的总Tokens大小 | NSInteger |
| completion_tokens | 回答的Token大小 | NSInteger |
| total_tokens | promptTokens和completionTokens的和，也是本次交互计费的Tokens大小 | NSInteger |
#7.5 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 年前