星火微调服务Web API文档文档

1. Spark API V1 协议描述

本协议用于描述 Spark 大模型集成接口协议

本API服务为AI 大模型的产品化接口，支持内容审核，快速修复等功能

每次交互需要重新建立websocket连接，当完成交互时，需要请求侧主动发送close消息，完成接口的断开。

如果在生成的过程中需要终止，可以直接发送websocket的close消息，关闭连接即可

#2. 接口说明

#2.1 请求方法和URL

模型版本	url地址	domain
V1.5版本	ws(s): //spark-api.xf-yun.com/v1.1/chat	general
微调模型	ws(s): //spark-api-n.xf-yun.com/v1.1/chat	patch

#2.2 接口Demo

参见多种语言demo，目前已支持的语言：

（使用demo之前，你应该修改代码中的app_id，key和secret 鉴权参数）

go_demo.go
java_demo.java
python3_demo.py

具体可以从讯飞开放平台直接获取：星火大模型

#2.3 接口要求

接口类型：流式 ws(s)

接口鉴权：使用签名机制进行鉴权，签名详情参照鉴权说明

接口对接：需要按照文档标准的方法进行对接，服务仅保障文档内描述功能。

#2.4 接口权限说明

此服务与星火认知大模型V1.5 共用token授权。

#3. 请求

#3.1 请求协议示例

{
    "header": {
        "app_id": "123456",
        "uid": "39769795890"
        "patch_id":["xxx"]  //调用微调大模型时必传,否则不传
    },
    "parameter": {
        "chat": {
            "domain": "patch",  //调用微调大模型时，设置为“patch”
            "temperature": 0.5,
            "top_k": 4,
            "max_tokens": 2048,
            "auditing": "default",
            "chat_id":"xxx"
        }
    },
    "payload": {
        "message": {
            "text": [
                {
                    "role": "system",
                    "content": "你是星火认知大模型"
                },
                {
                    "role": "user",
                    "content": "今天的天气"
                }
            ]
        }
    }
}

#3.2 请求参数

#3.2.1 平台参数

header部分的字段介绍：

字段名	类型	是否必传	含义	限制
header.app_id	string	是	应用的app_id，需要在飞云交互平台申请	"maxLength":8
header.uid	string	否	每个用户的id，非必传字段，用于后续扩展	"maxLength":32
header.patch_id	array	否	用户微调训练后发布的模型服务ID，非必传字段，用于后续扩展（当调用微调模型时，必传）	"maxLength":32

#3.2.2 服务特性参数

#3.2.2.1 对话服务参数

字段名	类型	是否必传	含义	备注	默认值
parameter.chat	object	是	用于上传对话的参数信息
parameter.chat.domain	string	是	需要使用的领域	通用模型：general，其他领域具体值联系接口提供方。
parameter.chat.temperature	float	否	核采样阈值,向上调整可以增加结果的随机程度	取值范围 (0，1]	0.5
parameter.chat.top_k	int	否	从k个中随机选择一个(非等概率)	最小值1，最大值6。	4
parameter.chat.max_tokens	int	否	回答的tokens的最大长度	最小值是1, 最大值是4096。	2048
parameter.chat.auditing	string	否	内容审核的严格程度	strict表示严格审核策略；moderate表示中等审核策略；show表示演示场景参数；default表示默认的审核程度；（需继续下调策略需要申请）	default
parameter.chat.chat_id	string	否	用于关联会话chat	需要保障用户下唯一
parameter.chat.suppress_plugin	string	否	用于关闭云端搜索	目前传固定值，字符串格式： {"knowledge", "medical"}

#3.2.3 请求数据

#3.2.3.1 文本数据

payload.message段的参数：

字段	含义	数据类型	取值范围	默认值	说明	必填
text	文本数据	json object array	受Token限制，有效内容不能超过8192Token			是

单轮交互示例说明：

单轮交互只需要传递一个user角色的数据

[
    // 用户的提问
    {"role": "user", "content": "你会做什么？"}
]

多轮交互的格式示例：

多轮交互需要将之前的交互历史按照user->assistant->user->assistant规则进行拼接，并保证最后一条是user的当前问题。

[
    // 拼接对话历史信息:
    {"role": "user", "content": "你好"},              // 用户第一个问题   role是user,表示是用户的提问
    {"role": "assistant", "content": "你好！"},        // AI的第一个回复  role是assistant，表示是AI的回复
    {"role": "user", "content": "你是谁？"},           // 用户第二个问题
    {"role": "assistant", "content": "我是Spark API。"},  // AI的第二个回复
    // ...... 对话历史信息

    // 用户最新的提问
    {"role": "user", "content": "你会做什么？"}
]

字段解析：

字段	含义	数据类型	取值范围	默认值	说明
role	角色	string	user, assistant		user表示是用户的问题，assistant表示AI的回复
content	文本内容	string	--		该角色的对话内容

#4. 响应

#4.1 响应协议示例

#4.1.1 结果示例

{
    "header": {
        "code": 0,
        "message": "Success",
        "sid": "cht000704fa@dx16ade44e4d87a1c802",
        "status": 0
    },
    "payload": {
        "choices": {
            "status": 2,
            "seq": 0,
            "text": [
                {
                    "content": "xxxxs",
                    "index": 0,
                    "role": "assistant"
                }
            ]
        },
        "usage": {
            "text": {
                "completion_tokens": 0,
                "question_tokens": 0,
                "prompt_tokens": 0,
                "total_tokens": 0
            }
        }
    }
}

注意：插件结果和大模型结果会交替返回。

#4.1.2 异常结果

{
    "header": {
        "code": 10110,     // 错误码(重要)
        "message": "xxxx", // 错误描述信息(重要)
        "sid": "cht00120013@dx181c8172afb0001102",
        "status": 2,
    }
}

#4.2 响应参数

#4.2.1 平台参数

header部分的字段介绍：

字段名	类型	含义	备注
header.code	int	服务错误码	0表示正常，非0表示出错
header.sid	string	会话的sid
header.status	int	会话的状态	取值[0，1，2]，其中0表示第一个结果, 1表示中间结果, 2表示最后一个结果
header.message	string	返回消息描述	错误码的描述信息

#4.2.2 响应数据参数

文本响应：

choices（默认返回）

字段	含义	数据类型	取值范围	说明	必填
status	数据状态	int	0:开始, 1:开始, 2:结束	2表示文本响应结束	是
seq	数据序号	int	最小值:0, 最大值:9999999	数据序号	是
text	文本结果	json object array		是一个json 数组	是

token消耗响应：

usage（最后一个结果时，才会有该字段）

字段	含义	数据类型	取值范围	默认值	说明	必填
payload.usage.text	文本数据	json object

插件信息响应：

plugins（仅触发插件时返回）

字段	含义	数据类型	取值范围	默认值	说明	必填
text	文本数据	json object

#4.3 响应数据解析

#4.3.1 payload.choices.text格式解析

[
    {
        "content": "这是AI的回复文本",
        "index": 0,
        "role": "assistant"
    }
]

解析：

字段	含义	数据类型	默认值	说明
content	回答的结果	string	--	--
index	结果序号，在多候选中使用	int	0	--
role	角色	string	assistant	assistant说明这是AI的回复

#4.3.2 payload.usage.text格式解析

{
    "prompt_tokens": 0,
    "question_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0
}

解析：

字段	含义	数据类型	默认值	说明
completion_tokens	回答tokens大小	int	--	--
question_tokens	问题不带历史的tokens大小	int	--	单轮情况下，此数值会略小于prompt_tokens
prompt_tokens	问题总tokens大小	int	--	--
total_tokens	问题和回答的tokens大小	int	--	--

#4.3.4 结果格式补充说明

模型结果除了普通文本类型，为了满足排版需求，会出现以下的标记语言，建议集成方进行适配：

markdown（表格、列表等）

latex（数学公式）

#

#5. 使用方式

#5.1 连接管理

#5.1.1 建立ws连接

此协议对应的接口为长连接接口，连接建立之后可以进行长时间的交互，用户交互完成之后应该主动关闭连接。

建立连接需要满足以下条件：

必须符合 websocket 协议规范（rfc6455）

需要按照要求进行签名请求

如果用户在60秒内没有交互数据，服务侧会主动断开。因此也建议用户在交互完成之后，主动关闭连接。

#5.1.2 关闭ws连接

正常交互结束后，客户端可以通过websocket协议发送Close类型消息关闭连接。

【建议用户在使用完毕之后，主动关闭websocket连接，不要故意长时间的占用ws连接资源！】

参考GoLand代码如下：

// 用户侧关闭连接
closeInfo := websocket.FormatCloseMessage(websocket.CloseNormalClosure, "close ws conn")
_ = conn.WriteControl(websocket.CloseMessage, closeInfo, time.Now().Add(2*time.Second))
_ = conn.Close()

除了正常交互连接断开之外，触发以下场景也会将连接断开

当用户持续持续60s空闲状态，不发送任何数据时，服务侧会主动断开连接。因此也建议用户在交互完成之后，主动关闭连接。

在服务进行升级、熔断等情况下，API可能会主动断开已完成交互连接，需要业务集成时，注意异常处理。

#5.2 内容审核说明

当返回10013或者10014错误码时，代码内容审核判断当前问题或回复的信息涉及敏感信息。返回错误的同时，在header.message字段中会携带当前的敏感提示语。

10013 表示用户的问题涉及敏感信息，服务侧拒绝处理此次请求。

10014 表示回复结果中涉及敏感信息，后续结果不可以展示给用户。

10019 表示当前的回复疑似敏感，结果文本可以给用户展示。服务会在返回全部结果后再返回该错误码，如果继续提问可能会导致被审核拦截。建议在收到该错误码后提示用户涉及敏感信息，并禁掉对话框，禁止用户继续提问。

如果需要调整内容审核的严格程度、敏感词等信息，请联系我们。

#6. 错误码列表

错误码	错误信息
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不足，并发超过授权等等。（联系我们开通授权或提高限制）
10018	用户在5分钟内持续发送ping消息，但并没有实际请求数据，会返回该错误码并断开ws连接。短链接使用无需关注
10019	该错误码表示返回结果疑似敏感，建议拒绝用户继续交互
10110	服务忙，请稍后再试。
10163	请求引擎的参数异常引擎的schema 检查不通过
10222	引擎网络异常
10223	LB找不到引擎节点
10907	token数量超过上限。对话历史+问题的字数太多，需要精简输入。
11200	授权错误：该appId没有相关功能的授权或者业务量超过限制（联系我们开通授权或提高限制）
11201	授权错误：日流控超限。超过当日最大访问量的限制。（联系我们提高限制）
11202	授权错误：秒级流控超限。秒级并发超过授权路数限制。（联系我们提高限制）
11203	授权错误：并发流控超限。并发路数超过授权路数限制。（联系我们提高限制）

星火微调服务Web API文档文档

1. Spark API V1 协议描述#

#2. 接口说明#

#2.1 请求方法和URL#

#2.2 接口Demo#

#2.3 接口要求#

#2.4 接口权限说明#

#3. 请求#

#3.1 请求协议示例#

#3.2 请求参数#

#3.2.1 平台参数#

#3.2.2 服务特性参数#

#3.2.2.1 对话服务参数#

#3.2.3 请求数据#

#3.2.3.1 文本数据#

#4. 响应#

#4.1 响应协议示例#

#4.1.1 结果示例#

#4.1.2 异常结果#

#4.2 响应参数#

#4.2.1 平台参数#

#4.2.2 响应数据参数#

#4.3 响应数据解析#

#4.3.1 payload.choices.text格式解析#

#4.3.2 payload.usage.text格式解析#

#4.3.4 结果格式补充说明#

##

#5. 使用方式#

#5.1 连接管理#

#5.1.1 建立ws连接#

#5.1.2 关闭ws连接#

#5.2 内容审核说明#

#6. 错误码列表#