iOS SDK集成文档

## 1. 图片生成简介

SparkChain支持用户向大模型发送一个文本请求，大模型根据请求生成相应的图片**。**

## 2. 兼容性说明

| 类别     | 兼容范围                              |
| :------- | :------------------------------------ |
| 系统     | 支持arm64架构，兼容iOS 9.0 及以上版本 |
| 开发环境 | 建议使用Xcode 进行开发                |

## 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.framework

└── SparkChain 图片生成 iOS SDK集成文档.pdf SparkChain集成指南

## 5. SDK工程配置

### 5.1 导入SDK库

SparkChain iOS SDK 核心代码库由SparkChain.framework组成。在引入工程中时，在工程的General的frameworks,Libraries,and Embedded Content 中使用Embedded & sign

示例如下：

![](/media/202405/sparkChain1_1714992023.png)

### 5.2 设置BitCode

SparkChain iOS SDK暂不支持Bitcode，Xcode 7、Xcode 8默认开启了Bitcode，而Bitcode 需要工程依赖的所有类库同时支持，可关闭此设置，只需在Targets - Build Settings 中搜索Bitcode 即可，找到相应选项，设置为NO。

![](/media/202405/sparkChain2_1714992038.png)

## 6. 接口流程调用图

![](/media/202405/sparkChain4_1714992048.png)

## 7. 初始化

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

```
@interface SparkChainConfig : NSObject
//配置appid
@property(nonatomic, readonly, copy)NSString *appID;
//配置apiKey
@property(nonatomic, readonly, copy)NSString *apiKey;
//配置apiSecret
@property(nonatomic, readonly, copy)NSString *apiSecret;
//配置SDK工作路径
@property(nonatomic, readonly, copy)NSString *workDir;
//配置用户自定义标识
@property(nonatomic, readonly, copy)NSString *uid;
//配置日志等级
@property(nonatomic, readonly, copy)int logLevel;
//配置日志存储路径
@property(nonatomic, readonly, copy)NSString *logPath;
@end
```

具体初始化示例如下：

```
//配置应用信息
SparkChainConfig * config = [[SparkChainConfig alloc] init];
config.appID("appID")
     .apiKey("apiKey")
     .apiSecret("apiSecret");
int ret = [SparkChain.getInst init:config];
NSLog("初始化结果 ret = %d",ret);
```

初始化参数说明：

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

## 8. LLM初始化

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

| 功能 | 说明 |
| :------- | :----------------------------------------------------------- |
| 图片生成 | 构造方法： [LLMFactory imageGeneration:llmconfig] [LLMFactory imageGeneration:llmconfig width:xx height:xx] 参数说明： config:星火大模型配置参数。其中的domain为tti，其他domain参数不生效。 width:生成图片的宽度。参考下方分辨率说明, 不同的分辨率计费不同，请选择合适的使用 height:生成图片的高度。参考下方分辨率说明, 不同的分辨率计费不同，请选择合适的使用 |

- LLMConfig参数说明：

- 分辨率说明：

**注：** 图片生成按点数计费，不同分辨率计费不同，具体如下

| 分辨率（width * height） | 图点数 |
| :----------------------- | :----- |
| 512x512(默认)            | 6      |
| 640x360                  | 6      |
| 640x480                  | 6      |
| 640x640                  | 7      |
| 680x512                  | 7      |
| 512x680                  | 7      |
| 768x768                  | 8      |
| 720x1280                 | 12     |
| 1280x720                 | 12     |
| 1024x1024                | 14     |

具体构造示例如下：

```
//图片生成
LLMConfig * llmconfig = [[LLMConfig alloc] init];
llmconfig.maxToken(2048)
...
.topK(4);//config配置可缺省，示例仅供展示如何使用,开发者根据实际情况选择
LLM * llm = [LLMFactory imageGeneration:llmconfig width:1024 height:1024];
```

## 9. 同步调用

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

```
@interface LLM : NSObject
- (LLMOutput *)run:(NSString *)query;
@end
```

run方法参数说明：

| 参数名 | 类型     | 说明     | 限制       | 是否必填 |
| :----- | :------- | :------- | :--------- | :------- |
| query  | NSString | 文本内容 | 0-1000字符 | 是       |

LLMOutput数据结构说明。

具体示例如下：

```
NSString *content = @"帮我画一座山。";
//同步请求
LLMOutput * syncOutput = [self.llm run:content];
//解析获取的结果，示例展示所有结果获取，开发者可根据自身需要，选择获取
NSData *byte           = syncOutput.image; //获取交互结果
int errCode            = syncOutput.errCode;//获取结果ID,0:调用成功，非0:调用失败
NSString *errMsg       = syncOutput.errMsg;//获取错误信息
NSString *role         = syncOutput.role;//获取角色信息
NSString *sid          = syncOutput.sid;//获取本次交互的sid
int completionTokens   = syncOutput.completionTokens;//获取回答的Token大小
int promptTokens       = syncOutput.promptTokens;//包含历史问题的总Tokens大小
int totalTokens        = syncOutput.totalTokens;//promptTokens和completionTokens的和，也是本次交互计费的Tokens大小
```

## 10. 异步调用

用户可以通过llm.arun方法向大模型发送问题请求，并从监听回调中一次性获取交互结果，不支持单实例并发调用。

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

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

```
@protocol LLMCallback <NSObject>
- (void)llm:(LLM *)llm onResult:(LLMResult * _Nullable)result usrContext:(id _Nullable)usrContext;
- (void)llm:(LLM *)llm onEvent:(LLMEvent * _Nullable)event usrContext:(id _Nullable)usrContext;
- (void)llm:(LLM *)llm onError:(LLMError * _Nullable)error usrContext:(id _Nullable)usrContext;
@end
```

LLMCallbacks数据结构说明：

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

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

- LLMResult结构说明：

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

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

- LLMEvent结构说明：

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

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

- LLMError结构说明：

具体调用示例如下：

```
//实现数据回调函数
- (void)llm:(LLM *)llm onResult:(LLMResult *)result usrContext:(id)usrContext {
       //解析获取的交互结果，示例展示所有结果获取，开发者可根据自身需要，选择获取。
       NSData *byte           = result.image; //一次性返回完整结果，因此不需要获取status去判断结果是否返回完成
       NSString *role         = result.role;//获取角色信息
       NSString *sid          = result.sid;//获取本次交互的sid
       int completionTokens   = result.completionTokens;//获取回答的Token大小
       int promptTokens       = result.promptTokens;//包含历史问题的总Tokens大小
       int totalTokens        = result.totalTokens;//promptTokens和completionTokens的和，也是本次交互计费的Tokens大小
}
- (void)llm:(LLM *)llm onEvent:(LLMEvent *)event usrContext:(id)usrContext {
       NSLog(@"异步调用：eventID:%d  eventMsg:%@",event.eventID,event.eventMsg);
       int eventID        = event.eventID;//获取事件ID
       NSString *eventMsg = event.eventMsg;//获取事件信息
       NSString *sid      = event.sid;//本次交互的sid
}
- (void)llm:(LLM *)llm onError:(LLMError *)error usrContext:(id)usrContext {
       NSLog(@"异步调用：code:%d  msg:%@",error.errCode,error.errMsg);
       int errCode        = error.errCode;//获取结果ID,0:调用成功，非0:调用失败
       NSString *errMsg   = error.errMsg;//获取错误信息
       NSString *sid      = event.sid;//本次交互的sid
}
llm.callback = self;
```

#### 10.2 请求调用

异步请求调用接口如下：

```
@interface LLM : NSObject
- (int)arun:(NSString *)query;
- (int)arun:(NSString *)query usrContext:(id _Nullable)usrContext;
@end
```

arun方法参数说明：

| 参数         | 类型     | 说明           | 限制       | 是否必填 |
| :----------- | :------- | :------------- | :--------- | :------- |
| question     | NSString | 文本内容       | 0-1000字符 | 是       |
| `usrContext` | Object   | 用户自定义标识 |            | 否       |

具体示例如下：

```
//异步调用
NSString *query = @"帮我画一座山。";
int ret = [llm arun:query];
//用户带自定义标识
//NSString *myContext = @"myContext";
//int ret = [llm arun:query usrContext:myContext];
```

## 11. 停止请求调用

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

```
[llm stop];
```

## 12. 逆初始化

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

```
[[SparkChain getInst] unInit];
```

## 13. SDK API介绍

### 13.1 SparkChainConfig API

### 13.2 SparkChain API

### 13.3 LLMConfig API

### 13.4 LLMFactory API

| 返回值类型 | 方法说明                                                     |
| :--------- | :----------------------------------------------------------- |
| LLM        | + (LLM *)textGeneration:(LLMConfig * _Nullable)config 构建星火大模型交付LLM |
| LLM        | + (LLM *)imageGeneration:(LLMConfig * _Nullable)config width:(int)width height:(int)height 构建图片生成LLM |
| LLM        | + (LLM *)imageUnderstanding:(LLMConfig * _Nullable)config 构建图片生成LLM |

### 13.5 LLM API

### 13.6 LLMOutput API

### 13.7 LLMError API

### 13.8 LLMEvent API

### 13.9 LLMResult API

### 14. 错误码

错误码包含SDK错误码和云端错误码，SDK错误码用来反馈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  | 授权错误：并发流控超限。并发路数超过授权路数限制             |