Linux SDK接入文档

注意：该接口可以正式使用。如您需要申请使用，请点击前往产品页面。

Tips：

计费包含接口的输入和输出内容

1tokens 约等于1.5个中文汉字或者 0.8个英文单词

星火V1.5支持[搜索]内置插件；星火V2.0和V3.0支持[搜索]、[天气]、[日期]、[诗词]、[字词]、[股票]六个内置插件

#1. SDK介绍

Spark SDK提供了一套快速集成星火大模型的工具，让开发者无需关注底层协议细节，提高开发效率。支持Android、Linux、iOS、Windows多个平台，方便开发者选择最适合自己的平台进行开发。Spark SDK可以帮助企业快速将星火大模型应用到业务场景中，提高效率和竞争力。本文档主要介绍Linux平台集成过程。

#2. 兼容性说明

类别	兼容范围
系统	支持x86，x86_64，arm和arm64架构，支持交叉编译，适配常见芯片型号。
开发环境	建议使用 VS 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
│ └── libSparkChain.so
└── Spark LLM Linux SDK集成文档.pdf Spark集成指南

#5. 接口调用流程图

#6. SDK工程配置

#6.1 导入SDK库

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

#6.2 配置权限

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

#7. 快速集成

#7.1 SDK初始化

**在使用Spark SDK 星火大模型交互功能前，需要首先开通星火大模型授权并获取已开通授权的应用信息（appId、apiKey、apiSecret）。SDK全局只需要初始化一次。**初始化示例如下：

初始化参数说明：

参数名	类型	说明	是否必填
appID	char*	创建应用后，生成的应用ID	是
apiKey	char*	创建应用后，生成的唯一应用标识	是
apiSecret	char*	创建应用后，生成的唯一应用秘钥	是
logLevel	int	0：VERBOSE，1：DEBUG，2：INFO，3：WARN，4：ERROR，5：FATAL，100：OFF	否
logPath	char*	日志存储路径，设置则会把日志存在该路径下，不设置则会把日志打印在终端上	否
uid	char*	用户自定义标识	否

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

#7.2 配置星火大模型参数

首先需要配置星火大模型的相关参数，示例如下：

参数说明：

字段	含义	类型	限制	是否必传
domain	需要使用的领域	char*	取值为[general,generalv2]，默认generalv2 general：通用大模型V1.5版本 generalv2：通用大模型V2版本 general和generalv2对应的url不同，需要严格对应。url地址参见下文。	否
url	配置chat服务器域名地址	char*	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	内容审核的场景策略	char*	当前仅支持default	否
topK	配置从k个候选中随机选择⼀个（⾮等概率)	int	取值范围1-6，默认值4	否
chatID	配置关联会话chat_id标识，需要保障用户下唯一	char*		否

#7.3 星火请求调用

当前支持同步调用和异步调用两种方式。用户可以通过run方法或者arun方法向大模型发送问题请求，获取大模型返回结果。run方法、arun方法不支持并发调用。

#7.3.1 同步调用

调用 run方法向大模型发起请求，并同步一次性返回大模型回答结果。该接口返回结果延迟时间取决于大模型返回的结果长度。

#7.3.1.1 请求调用

run方法参数说明：

参数名	类型	说明	限制	是否必填
question	char*	输入信息文本	general：4096 tokens generalv2：8192 tokens	是

LLMSyncOutput数据结构说明：

参数	类型	获取方法	说明
errCode	int	getErrCode()	调用结果状态，0：调用成功，非0：调用失败
errMsg	char*	getErrMsg()	调用失败时的错误信息
role	char*	getRole()	星火大模型的角色，assistant:：助手，user：用户
content	char*	getContent()	调用结果
completionTokens	int	getCompletionTokens()	回答的Token大小
promptTokens	int	getPromptTokens()	包含历史问题的总Tokens大小
totalTokens	int	getTotalTokens()	promptTokens和completionTokens的和，也是本次交互计费的Tokens大小

返回结果参考7.5节响应协议说明。

#7.3.2 异步调用

调用 arun方法向大模型发起请求，通过回调的方式异步回大模型回答结果。可在回调接口中接收异步返回的数据和数据和状态。

#7.3.2.1.注册结果回调

LLMCallbacks数据结构说明：

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

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

LLMResult结构说明：

方法	说明
getRole()	星火大模型角色，assistant:：助手，user：用户
getContent()	调用结果
getCompletionTokens()	回答的Token大小
getPromptTokens()	包含历史问题的总Tokens大小
getTotalTokens()	promptTokens和completionTokens的和，也是本次交互计费的Tokens大小
getStatus()	返回结果状态，0：start，1：continue，2：end

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

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

LLMEvent结构说明：

方法	说明
getEventID()	事件ID，15：建立连接，19：连接断开
getEventMsg()	事件信息

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

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

LLMError结构说明：

方法	说明
getErrCode()	错误码ID
getErrMsg()	错误信息

#7.3.2.2 请求调用

arun方法参数说明：

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

返回结果参考7.5节响应协议说明。

#7.4 多轮会话

如果交互需要上下文关联，需要把交互历史数据一并传入到run方法或者arun方法中。传入格式如下：

开发者需要构建如上格式的JsonArray字符串传入run或者arun方法中。

#7.5 响应协议说明

该协议为中间协议，星火大模型是按照此协议格式返回结果。SDK已完成对此协议的解析和封装，获取相应字段方法请查询7.3节LLMOutput和LLMResult的结构说明。

协议结构说明

字段	含义	说明
header	协议头部	协议头部，用于描述平台特性的参数
payload	响应数据块	数据段，携带响应的数据。

响应参数说明

字段	含义
sid	本次会话的id
status	数据状态 0:start，1:continue，2:end
seq	数据序号，标明数据为第几块。最小值:0, 最大值:9999999
content	文本数据
role	星火大模型角色
prompt_tokens	包含历史问题的总Tokens大小
completion_tokens	回答的Token大小
total_tokens	promptTokens和completionTokens的和，也是本次交互计费的Tokens大小

#7.6 SDK逆初始化

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

SparkChain::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. SDK介绍#

#2. 兼容性说明#

#3. 授权说明#

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

#5. 接口调用流程图#

#6. SDK工程配置#

#6.1 导入SDK库#

#6.2 配置权限#

#7. 快速集成#

#7.1 SDK初始化#

#7.2 配置星火大模型参数#

#7.3 星火请求调用#

#7.3.1 同步调用#

#7.3.1.1 请求调用#

#7.3.2 异步调用#

#7.3.2.1.注册结果回调#

#7.3.2.2 请求调用#

#7.4 多轮会话#

#7.5 响应协议说明#

#7.6 SDK逆初始化#

#8. 错误码#

#8.1 SDK错误码#

#8.2 服务端错误码#