WebSocket
是面向链接的，全双工通道。建立链接前需要先从服务端获取 Token。通过这个 token 才能与服务端创建 WebSocket 链接。Token 仅建立链接时有效，链接建立成功后废弃。
接入流程图：
1. 获取建立 Websocket 连接的 Token
1.1 调用方式
说明：
获取的 Token
仅供一次会话连接使用
，并且
会过期
，请在获取到 Token 后及时建立长连接，如需建立其他连接，需要重新获取 Token。
如果需要携带标签信息，请在调用 GetWsToken 接口时传入。
1.2 如何获取 AppKey
在
应用管理
界面，找到您处于运行中的应用（需要先发布），单击
调用
，会弹出“调用信息”窗口。
在
调用信息
窗口可以看到 AppKey，单击
复制
即可。
2. 使用 Token 建立 Websocket 连接
请求地址：
wss://wss.lke.cloud.tencent.com/v1/qbot/chat/conn/?EIO=4&transport=websocket
说明：
2.1 建立连接
Websocket 连接建立成功后，服务器回包如下所示：
0{"sid":"xxx","upgrades":[],"pingInterval":25000,"pingTimeout":5000}
2.2 传递 token 鉴权
通过 Socket.IO 的 auth 消息传递。
在建立连接并收到服务器回包后，发送 Token 鉴权。发送 Token 格式如下所示：
40{"token":"xx-xx-xx-xx-xx"}
2.3 处理心跳包
服务器发送的心跳包如下（"2"是心跳包的内容）：
2
此时客户端需要响应（"3"是需要响应的内容）：
3
注意：
Socket io V4 有心跳包， 必须处理，否则会被服务器断开连接。
如果自己实现 Client，需要注意处理心跳包。本文档提供的 Demo 已经自动处理了心跳包。
3. WebSocket 支持的事件
42["类型",{"payload":{事件体}}]
3.1 发送事件
事件名：send
事件方向：
前端 > 后端
注意：
发送 send 事件前，需要先发布应用。
用户发出一条消息（发送事件）时，服务器会将该消息原样返回（回复事件，其中 is_from_self = true），以便确认消息被服务端收到并对应更新消息 ID、时间戳。
如果需要携带知识标签信息，请在获取 token 时携带。
数据结构：
|
名称
|
类型
|
是否必填
|
说明
|
|
request_id
|
string(255)
|
是
|
请求 ID，用于标识一个请求（作消息串联，建议每个请求使用不同的 request_id）
|
|
session_id
|
string(64)
|
是
|
会话 ID，用于标识一个会话（外部系统提供，建议不同的用户端会话传入
不同的
session_id，否则同一个应用下的不同用户的消息记录会串掉）
参数长度：2-64个字符
校验规则： ^[a-zA-Z0-9_-]{2,64}$ ，一般可以用 uuid 来生成该值
uuid 示例：1b9c0b03-dc83-47ac-8394-b366e3ea67ef
|
|
content
|
string(6000)
|
是
|
消息内容，如果发送图片，在此传递 markdown 格式的图片链接，例如，其中图片链接需要可公有读。
|
|
file_infos
|
Object 数组
|
否
|
|
|
custom_variables
|
map[string]string
|
否
|
自定义参数的值。可以配置多个key: value对，key为自定义参数的参数名称，value为对应的自定义参数的运行时的值。
|
|
system_role
|
string(2000)
|
否
|
角色指令（提示词）, 为空时使用应用配置默认设定，填写时取当前值。
|
file_infos 文件信息的数据结构：
|
名称
|
类型
|
是否必填
|
说明
|
|
file_name
|
string
|
是
|
文件名称
|
|
file_size
|
string
|
是
|
实时文档解析接口返回的文件大小
|
|
file_url
|
string
|
是
|
实时文档解析接口返回的文件 URL
|
|
file_type
|
string
|
是
|
文件类型
|
|
doc_id
|
string
|
是
|
实时文档解析接口返回的 doc_id
|
3.2 回复事件
事件名：reply
事件方向：
后端 > 前端
注意：
如果收到的消息中 is_evil == true 表示该消息命中敏感内容，发送失败。
因并发超限导致排队超时，会下发 "超出并发数限制" 错误。
数据结构：
|
名称
|
类型
|
说明
|
|
request_id
|
string(255)
|
请求 ID，用于标识一个请求（作消息串联，建议每个请求使用不同的 request_id）
|
|
content
|
string
|
回复消息内容
|
|
file_infos
|
Object 数组
|
文件信息
|
|
record_id
|
string(64)
|
消息唯一 ID
|
|
related_record_id
|
string(64)
|
关联的消息唯一 ID
|
|
session_id
|
string(64)
|
会话 ID，用于标识一个会话（外部系统提供，建议不同的用户端会话传入
不同的
session_id，否则同一个应用下的不同用户的消息记录会串掉）
|
|
is_from_self
|
bool
|
消息是否由客户端发出
|
|
can_rating
|
bool
|
该消息记录是否能评价
|
|
timestamp
|
int64
|
消息时间戳（秒级）
|
|
is_final
|
bool
|
消息是否已输出完成
流式模式下，消息会多次返回，每次返回均覆盖之前的答案
当 is_final == true 时，停止生成按钮隐藏，并且显示点赞点踩按钮
|
|
is_evil
|
bool
|
是否命中敏感内容
|
|
is_llm_generated
|
bool
|
是否为模型生成内容
|
|
reply_method
|
uint8
|
回复方式：
1: 大模型回复
2: 未知问题回复
3: 拒答问题回复
4: 敏感回复
5: 已采纳问答对优先回复
6: 欢迎语回复
7: 并发数超限回复
8: 全局干预知识
9: 任务流回复
10: 任务流答案
11: 搜索引擎回复
12: 知识润色后回复
13: 图片理解回复
14: 实时文档回复
|
|
knowledge
|
Object 数组
|
命中的知识
|
|
option_cards
|
string 数组
|
选项卡，任务流程专有
|
|
custom_params
|
string 数组
|
用户自定义业务参数，用于透传问答中业务参数
|
|
task_flow
|
Object
|
任务流程调试信息
|
knowledge 命中的知识的数据结构：
|
名称
|
类型
|
说明
|
|
id
|
string
|
命中的知识 ID
|
|
type
|
uint32
|
命中的知识类型：
1: 问答
2: 文档片段
|
task_flow 任务流程调试信息的数据结构：
|
名称
|
类型
|
说明
|
|
task_flow_name
|
string
|
任务流程名称
|
|
task_flow_id
|
string
|
任务流程 ID
|
|
query_rewrite
|
string
|
问题改写结果
|
|
hit_intent
|
string
|
命中的意图
|
|
slot_info
|
map[string]Object
|
运行时收集的槽位信息
|
|
api_response
|
map[string]Object
|
API 节点的返回信息
|
|
type
|
int
|
任务流程回复类型
0：任务流程回复
1：任务流程静默回复
2：任务流程拉回话术
3：任务流程自定义回复
|
3.3 token 统计事件
事件名：token_stat
事件方向：
后端 > 前端
数据结构：
|
名称
|
类型
|
说明
|
|
session_id
|
string(64)
|
会话 id
|
|
request_id
|
string(255)
|
对应发送事件对应的请求 id
|
|
record_id
|
string(64)
|
对应发送事件对应的消息记录 id
|
|
status_summary
|
string
|
本轮对话状态, 处理中: processing, 成功: success, 失败: failed
|
|
status_summary_title
|
string
|
本轮对话状态描述
|
|
elapsed
|
int
|
本轮调用耗时, 单位 ms
|
|
token_count
|
int
|
本轮请求消耗 token 数(当包含多个过程时, 计算将汇总)
|
|
procedures
|
Object 数组
|
调用过程列表
|
procedures 调用过程列表的数据结构：
|
名称
|
类型
|
说明
|
|
name
|
string
|
英文名, 与下面的 title 字段一一对应.
knowledge, task_flow, search_engine, image, large_language_model, pot_math, file
|
|
title
|
string
|
调用过程描述, 对应 name 字段, 各中文含义如下:
调用知识库, 调用任务流程, 调用搜索引擎, 调用图片理解, 大模型回复, 调用计算器, 阅读文件
|
|
status
|
string
|
调用过程状态, 处理中: processing, 成功: success, 失败: failed
|
|
input_count
|
int
|
当次过程输入消耗 token 数
|
|
output_count
|
int
|
当次过程输出消耗 token 数
|
|
count
|
int
|
当次过程消耗总 token 数：输入 + 输出
|
示例:
["token_stat",{"type": "token_stat","payload": {"elapsed": 1616,"order_count": 50000000,"procedures": [{"count": 323,"input_count": 308,"name": "knowledge","output_count": 15,"status": "success","title": "调用知识库"}],"record_id": "Hpe_20240625_185659_215_EsH2uf8L","request_id": "8PUcDU6xyQ-301747294000","session_id": "2d071ef7-ef76-44df-84a4-9210672ed700c8","status_summary": "success","status_summary_title": "调用知识库","token_count": 323,"used_count": 553},"message_id": "89d91395-06bc-4f2e-b240-06f7b4498b0c6e"}]
3.4 评价事件
事件名：rating
事件方向：
双向
注意：
客户端发出评价事件时候，客户端也会收到这个事件，以便客户端确认消息发出成功。
数据结构：
|
名称
|
类型
|
是否必填
|
说明
|
|
record_id
|
string(64)
|
是
|
消息ID（被评价的 reply 事件的消息 ID）
|
|
score
|
uint8
|
是
|
评分：
1：点赞
2：点踩
|
|
reasons
|
string 数组
|
否
|
所选原因（用户反馈的内容，可以有多个）
|
3.5 停止生成事件
事件名：stop_generation
事件方向：
前端 > 后端
数据结构：
|
名称
|
类型
|
是否必填
|
说明
|
|
record_id
|
string(64)
|
是
|
消息ID（需要停止生成的 reply 事件消息 ID）
|
3.6 参考来源事件
事件名：reference
事件方向：
后端 > 前端
数据结构：
|
名称
|
类型
|
说明
|
|
record_id
|
string(64)
|
消息唯一 ID
|
|
references
|
Object 数组
|
参考来源
|
references 参考来源的数据结构：
|
名称
|
类型
|
说明
|
|
id
|
uint64
|
说明：
该 id 字段对应 DescribeRefer 中的ReferBizIds 字段
|
|
type
|
uint32
|
参考来源类型
|