# 精调服务_WebSocket协议

本文档旨在帮助开发者快速对接大模型 Web API 服务，详细描述接口调用方法、请求/响应参数、鉴权方式、WebSocket 连接管理及错误码信息。

# 1. 接口概述

# 1.1 请求地址

传输协议：支持 ws/wss，为确保数据安全，建议使用 wss 默认请求地址如下：

wss://maas-api.cn-huabei-1.xf-yun.com/v1.1/chat

说明：部分模型因部署配置不同，其请求地址可能略有差异，具体可参考服务管控>模型服务列表右侧调用信息

# 1.2 接口要求

接口类型：流式 WebSocket 接口接口对接：需要按照文档标准的方法进行对接，服务仅支持文档明确描述的功能，未提及的功能可能导致兼容性问题

# 1.3 鉴权方式

鉴权机制：使用签名机制进行鉴权，签名详情参考通用URL鉴权文档 (opens new window)

# 1.4 请求demo

在使用demo之前，请修改代码中的app_id、key、secret （用于签名鉴权）以及patch_id（调用微调大模型时必传）
demo python语言 (opens new window)
demo java语言 (opens new window)

# 2. 接口请求

# 2.1 请求示例

以下示例展示了一个完整的请求结构：

{
    "header": {
        "app_id": "123456",
        "uid": "39769795890",
        "patch_id":["xxx"]  // 调用微调大模型时必传,否则不传。对应为模型服务卡片上的resourceId
    },
    "parameter": {
        "chat": {
            "domain": "patch",  // 调用微调大模型时，对应为模型服务卡片上的serviceid
            "temperature": 0.5,
            "top_k": 4,
            "max_tokens": 2048,
            "auditing": "default",
            "chat_id":"xxx",
            "tools":[
                {
                    "type": "web_search",
                    "web_search": {
                        "enable": True,
                        "show_ref_label": False,
                        "search_mode": "normal"
                    }
                }
            ]
        }
    },
    "payload": {
        "message": {
            "text": [
                {
                    "role": "system",
                    "content": "你是星火认知大模型"
                },
                {
                    "role": "user",
                    "content": "今天的天气"  
                }
            ]
        }
    }
}

# 2.2 请求参数

接口请求字段由三个部分组成：header，parameter, payload。字段解释如下：

# 2.2.1 Header参数（平台参数）

字段	类型	是否必传	含义	限制
app_id	string	是	应用的app_id，需要在平台申请	maxLength:8
uid	string	否	每个用户的id，非必传字段，用于后续扩展	maxLength:32
patch_id	array	否	调用用户微调大模型时必传，对应resourceid，否则不传	maxLength:32

# 2.2.2 Parameter参数（服务特性参数）

# 2.2.2.1 对话服务参数（parameter.chat）

字段	类型	是否必传	含义	限制	备注
domain	string	是	取值为用户服务的serviceId		serviceId可从星辰网页获取
temperature	float	否	核采样阈值。用于决定结果随机性，取值越高随机性越强即相同的问题得到的不同答案的可能性越高	取值：[0,1]；默认值：0.5	无
top_k	int	否	从k个候选中随机选择一个（非等概率）	取值：[1, 6]；默认值：4	无
max_tokens	int	否	回答的tokens的最大长度	取值：[1,32768]；默认值：2048	限制生成回复的最大 token 数量，max_tokens的限制需要满足`输入promptToken + 设置参数max_tokens <= 32768 - 1`,参数设置过大可能导致回答中断，请酌情调整，建议取值16384以下
chat_id	string	否	用于关联用户会话		需保障用户下的唯一性
tools	array	否	通过该参数控制工具使用	工具列表
tools.type	string	是	可选值：web_search	当前工具列表中，仅支持联网搜索工具；
tools.web_search	object	否
tools.web_search.enable	bool	否，默认关闭（false）	true or false	enable：是否开启搜索功能，设置为true,模型会根据用户输入判断是否触发联网搜索，false则完全不触发；
tools.web_search.show_ref_label	bool	否，默认关闭（false）	true or false	show_ref_label 开关控制触发联网搜索时是否返回信源信息（仅在enable为true时生效）如果开启，则先返回搜索结果，之后再返回模型回复内容
tools.web_search.search_mode	string	否，默认标准搜索（normal）	deep/normal	search_mode 控制联网搜索策略（仅在enable为true时生效） normal：标准搜索模式，模型引用搜索返回的摘要内容回答问题 deep：深度搜索模式，模型引用搜索返回的全文内容，回复的更准确；同时会带来额外的token消耗

# 2.2.3 payload参数（请求数据）

payload.message 中的 text 字段为文本数据，类型为 JSON 数组，示例如下：

字段	类型	是否必传	含义	限制	备注
text	json object array	是	文本数据	受Token限制，有效内容不能超过8192Token

单轮交互：仅传递一条用户消息：

[
    {"role": "user", "content": "你会做什么？"}  
]

多轮交互：按 user -> assistant -> user -> assistant 顺序传递历史记录，最后一条为当前问题：

[
    {"role": "user", "content": "你好"},
    {"role": "assistant", "content": "你好！"},
    {"role": "user", "content": "你是谁？"},
    {"role": "assistant", "content": "我是 Spark API。"},
    {"role": "user", "content": "你会做什么？"}
]

字段说明：

字段	类型	是否必传	含义	限制	备注
role	string	是	角色	取值范围：system,user,assistant	通过system设置对话背景信息，user表示用户的问题，assistant表示AI的回复
content	string	是	文本内容	无	该角色的对话内容

# 3. 接口响应

# 3.1 响应示例

# 3.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
            }
        }
    }
}

注意： WebSocket模式中，接口为流式返回，此示例为最后一次返回结果，开发者需要将接口多次返回的结果进行拼接展示。

在返回检索信源的情况下，在大模型返回结果之前会先返回检索信源，结构如下：

{
    "header": {
        "code": 0,
        "message": "Success",
        "sid": "cht000b79a4@dx190da456b5db80a560",
        "status": 1
    },
    "payload": {
        "plugins": {
            "text": [
                {
                    "name": "ifly_search",
                    "content": "[{\"index\":1,\"url\":\"https://baike.baidu.com/item/%E6%9B%B9%E6%93%8D/6772\",\"title\":\"曹操（中国东汉末年权臣，曹魏政权的奠基者）_百度百科\"},{\"index\":2,\"url\":\"https://zhidao.baidu.com/question/437349472.html\",\"title\":\"曹操是哪一年出生的？ - 百度知道\"},{\"index\":3,\"url\":\"http://www.lidaishi.com/default.aspx?did=130019\",\"title\":\"曹操的一生事迹简介-历代史历史网\"},{\"index\":4,\"url\":\"https://zhidao.baidu.com/question/374585705.html\",\"title\":\"曹操生于哪一年? - 百度知道\"},{\"index\":5,\"url\":\"https://baike.baidu.hk/item/%E6%9B%B9%E6%93%8D/6772\",\"title\":\"曹操（中國東漢末年權臣，曹魏政權的奠基者）_百度百科\"}]",
                    "content_type": "text",
                    "content_meta": null,
                    "role": "tool",
                    "status": "finished",
                    "invoked": {
                        "namespace": "ifly_search",
                        "plugin_id": "ifly_search",
                        "plugin_ver": "",
                        "status_code": 200,
                        "status_msg": "Success",
                        "type": "local"
                    }
                }
            ]
        }
    }
}

# 3.1.2 异常结果示例

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

# 3.2 响应参数说明

# 3.2.1 header参数

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

# 3.2.2 响应数据参数

文本响应（字段choices，默认返回）：

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

token消耗信息（字段 usage，仅在最终响应时返回）：

字段	类型	是否必传	含义
usage.text	json object	是	文本数据

# 3.3 响应数据解析

# 3.3.1 payload.choices.text格式解析

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

字段	类型	是否必传	含义	取值范围	说明
content	string	是	回答的结果
reasoning_content	string	是	模型生成的思考文本内容(支持深度思考的模型才有此字段)
index	int	是	结果序号	0	在多候选中使用
role	string	是	角色	assistant	说明这是AI的回复

# 3.3.2 payload.usage.text格式解析

示例：

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

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

# 3.3.3 结果格式补充说明

模型返回的结果除了普通文本之外，可能还包含以下标记语言，建议集成方做好适配：

markdown（表格、列表等）
latex（数学公式）

# 4. 连接管理

# 4.1 建立连接

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

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

必须符合 websocket 协议规范（rfc6455）
若在 60 秒内无数据交互，服务端将主动断开连接，请确保在交互结束后主动关闭连接

# 4.2 关闭连接

正常交互结束后，客户端可以通过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()

提示：除正常交互外，以下情况也会导致连接断开：

客户端连续 60 秒未发送数据；
服务升级、熔断等特殊情况下，API 可能主动断开连接，需要业务集成时，请确保做好异常处理。

# 5. 错误码说明

# 5.1 错误码列表

错误码	错误信息
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	授权错误：并发流控超限。并发路数超过授权路数限制。（联系我们提高限制）

# 5.2 内容审核说明

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

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

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

在这篇文章中：