Windows SDK集成文档

# SparkChain 文本交互 Windows SDK集成文档

## 1. 文本交互简介

SparkChain支持用户跟星火大模型之间的问答交互。

## 2. 兼容性说明

| 类别     | 兼容范围                          |
| :------- | :-------------------------------- |
| 系统     | 支持Windows x86，x64。            |
| 开发环境 | 建议使用 Visual 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

│ └── [libSparkChain.so](http://libsparkchain.so/)

└── SparkChain 文本交互 Linux SDK集成文档.pdf SparkChain集成指南

## 5. SDK工程配置

### 5.1 导入SDK库

将SDK/libs文件夹、头文件文件夹include存放到项目中，并在环境变量里添加库路径；

```c++
#include "../include/sparkchain.h"
```

### 5.2 配置权限

如果需要存储日志，SDK日志路径需要读写权限，缺少读写权限，日志将无法正常存储。

## 6. 接口流程调用图

![](/media/202405/Linux文本交互流程图_1714990279.png)

## 7. SDK 初始化

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

```c++
class SPARKCHAIN_API SparkChainConfig { 
    public:    
    	static SparkChainConfig* builder();    
    	virtual ~SparkChainConfig();    
    	//配置appid    
    	virtual SparkChainConfig* appID(const char* appid)         = 0;    
    	//配置apiKey    
    	virtual SparkChainConfig* apiKey(const char* apiKey)       = 0;    
    	//配置apiSecret    
    	virtual SparkChainConfig* apiSecret(const char* apiSecret) = 0;    
    	//配置用户自定义标识    
    	virtual SparkChainConfig* uid(const char* uid)             = 0;    
    	//配置SDK工作路径    
    	virtual SparkChainConfig* workDir(const char* workDir)     = 0;    
    	//配置日志等级    
    	virtual SparkChainConfig* logLevel(int logLevel )          = 0;    
    	//配置日志存储路径    
    	virtual SparkChainConfig* logPath(const char* logPath)     = 0; 
};
```

SparkChainConfig接口说明：

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

具体示例如下：

```c++
SparkChainConfig* config = SparkChainConfig::builder(); 
config->appID("$appId")      
    ->apiKey("$apiKey")      
    ->apiSecret("$apiSecret");//从平台获取的授权appid，apikey,apisecrety 
int ret = SparkChain::init(config);
```

## 8. LLM 初始化

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

| 功能 | 说明 |
| :------- | :----------------------------------------------------------- |
| 文本交互 | 构造方法： static LLM* textGeneration(LLMConfig* config = nullptr, Memory* memory = nullptr); 参数说明： config:星火大模型配置参数。如果不传入此参数，则默认使用generalv2。 memory:Memory，星火可以根据memory进行上下文关联回答 |

- LLMConfig 结构如下：

```c++
class SPARKCHAIN_API LLMConfig { 
    public:    
    	static LLMConfig* builder();    
    	virtual ~LLMConfig();    
    	//需要使用的领域    
    	virtual LLMConfig* domain(const char* domain)     = 0;    
    	//内容审核的场景策略    
    	virtual LLMConfig* auditing(const char* auditing) = 0;    
    	//配置关联会话chat_id标识，需要保障用户下唯一    
    	virtual LLMConfig* chatID(const char* chatID)     = 0;    
    	//配置核采样阈值，改变结果的随机程度    
    	virtual LLMConfig* temperature(float temperature) = 0;    
    	//配置从k个候选中随机选择⼀个（⾮等概率)    
    	virtual LLMConfig* topK(int topK)                 = 0;    
    	//回答的tokens的最大长度    
    	virtual LLMConfig* maxToken(int maxToken)         = 0;    
    	//配置chat服务器域名地址    
    	virtual LLMConfig* url(const char* url)           = 0;    
};
```

- 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。

具体构造示例如下：

```c++
Memory* window_memory = Memory::WindowMemory(5);//windowMemory 
Memory* token_memory = Memory::TokenMemory(8192);//tokenMemory 
/****** *文本交互 *******/ 
LLMConfig *chat_llmConfig = LLMConfig::builder(); 
chat_llmConfig->maxToken(2048); 
... 
chat_llmConfig->topK(4);//config配置可缺省，demo仅供展示如何使用,开发者根据实际情况选择。 
LLM *chat_llm = LLMFactory::textGeneration(chat_llmConfig,window_memory);
```

## 9. 同步调用

用户可以通过chat_llm->run方法向大模型发送文本交互请求，并获取交互结果，不支持单实例并发调用。调用接口如下：

```c++
LLMSyncOutput* run(const char* question, int ttl = 60);
```

run方法参数说明：

| 参数名 | 类型 | 说明 | 限制 | 是否必填 |
| :------- | :---------- | :------------------------- | :------------------------------------------------ | :------- |
| question | const char* | 输入信息文本，包含历史信息 | general：4096 tokens generalv2：8192 tokens | 是 |
| ttl | int | 同步调用超时时间 | 用户根据自身需求设置相应的超时时间，默认60秒 | 否 |

LLMSyncOutput数据结构说明：

具体调用示例如下：

```c++
//同步调用 
LLMSyncOutput* result = chat_llm->run("给我讲个笑话吧。"); 
//解析获取的结果，示例展示所有结果获取，开发者可根据自身需要，选择获取。 
const char* content  = result->getContent();//获取返回结果 
int contentLen       = result->getContentLen();//获取返回结果长度 
SparkChain::LLMResult::ContentType type = result->getContentType();//获取返回结果类型,TEXT:返回结果为文本,IMAGE:返回结果为图片  
int errCode          = result->getErrCode();//获取结果状态,0:调用成功，非0:调用失败 
const char* errMsg   = result->getErrMsg();//获取失败时的错误信息 
const char* role     = result->getRole();//获取角色信息 
const char* sid      = result->getSid();//获取本次交互的sid 
int completionTokens = result->getCompletionTokens();//获取回答的Token大小 
int promptTokens     = result->getPromptTokens();//包含历史问题的总Tokens大小 
int totalTokens      = result->getTotalTokens();//promptTokens和completionTokens的和，也是本次交互计费的Tokens大小
```

## 10. 异步调用

用户可以通过chat_llm->arun方法向大模型发送文本交互请求，通过监听回调获取交互结果，不支持单实例并发调用。

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

文本交互的异步请求结果通过LLMCallbacks监听回调返回，监听回调接口如下：

```c++
class SparkCallbacks : public LLMCallbacks {    
    void onLLMResult(LLMResult* result, void* usrContext) {          
    
    }    
    void onLLMEvent(LLMEvent* event, void* usrContext) {           
    
    }    
    void onLLMError(LLMError* error, void* usrContext) {           
    
    } 
};
```

LLMCallbacks数据结构说明：

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

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

- LLMResult结构说明：

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

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

- LLMEvent结构说明：

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

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

- LLMError结构说明：

具体示例如下：

```c++
class SparkCallbacks : public LLMCallbacks {    
    void onLLMResult(LLMResult* result, void* usrContext) {        
        //解析获取的交互结果，示例展示所有结果获取，开发者可根据自身需要，选择获取。        
        const char* content  = result->getContent();//获取返回结果        
        int contentLen       = result->getContentLen();//获取返回结果长度        
        SparkChain::LLMResult::ContentType type = result->getContentType();//获取返回结果类型,TEXT:返回结果为文本,IMAGE:返回结果为图片
        int status           = result->getStatus();//返回结果状态，0：结果返回第一帧，1：结果返回中间帧，2：结果返回最终帧        
        const char* role     = result->getRole();//获取角色信息        
        const char* sid      = result->getSid();//获取本次会话的sid        
        int completionTokens = result->getCompletionTokens();//获取回答的Token大小        
        int promptTokens     = result->getPromptTokens();//包含历史问题的总Tokens大小        
        int totalTokens      = result->getTotalTokens();//promptTokens和completionTokens的和，也是本次交互计费的Tokens大小    
    }    
    void onLLMEvent(LLMEvent* event, void* usrContext) {        
        //解析获取的事件结果，示例展示所有结果获取，开发者可根据自身需要，选择获取。        
        int eventId          = event->getEventID();//获取事件id        
        const char* eventMsg = event->getEventMsg();//获取事件信息        
        const char* sid      = event->getSid();//获取交互sid    
    }    
    void onLLMError(LLMError* error, void* usrContext) {        
        //解析获取的错误结果，示例展示所有结果获取，开发者可根据自身需要，选择获取。        
        int errCode        = error->getErrCode();//获取错误码        
        const char* errMsg = error->getErrMsg();//获取错误信息        
        const char* sid    = error->getSid();//获取交互sid    
    } 
}; 
SparkCallbacks* cbs = new SparkCallbacks(); chat_llm->registerLLMCallbacks(cbs);
```

### 10.2 请求调用

异步请求调用接口如下：

```c++
int arun(const char* question, void* usrTag = nullptr);
```

arun方法参数说明：

| 参数     | 类型        | 说明           | 限制                                        | 是否必填 |
| :------- | :---------- | :------------- | :------------------------------------------ | :------- |
| question | const char* | 输入信息文本   | general：4096 tokens generalv2：8192 tokens | 是       |
| usrTag   | void*       | 用户自定义标识 |                                             | 否       |

具体调用示例如下：

```c++
int ret = chat_llm->arun("给我讲个笑话吧。"); 
//带有用户自定义标识交互 
//char* usrContext = "myContext"; 
//int ret = chat_llm->arun("给我讲个笑话吧。",usrContext);
```

## 11. 停止调用

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

```c++
chat_llm->stop();
```

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

## 12. 逆初始化

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

```c++
SparkChain::unInit();
```

## 13. SDK API介绍

### 13.1 SparkChainConfig API

### 13.2 SparkChain API

### 13.3 LLMConfig API

### 13.4 Memory API

### 13.5 LLMFactory API

| 返回值类型 | 方法说明 |
| :--------- | :----------------------------------------------------------- |
| LLM* | static LLM* textGeneration(LLMConfig* config = nullptr, Memory* memory = nullptr) 构建星火大模型交互LLM |
| LLM* | static LLM* imageUnderstanding(LLMConfig* config = nullptr, Memory* memory = nullptr) 构建图片理解LLM |
| LLM* | static LLM* imageGeneration(int width = 512, int height = 512, LLMConfig* config = nullptr) 构建图片生成LLM |
| void | static void destroy(LLM* llm) 销毁LLM |

### 13.6 LLM API

### 13.7 LLMSyncOutput 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  | 授权错误：并发流控超限。并发路数超过授权路数限制             |