对话端接口文档（WebSocket）

WebSocket 是面向连接的，全双工通道。建立链接前需要先从服务端获取 Token。通过这个 token 才能与服务端创建 WebSocket 链接。Token 仅建立链接时有效，链接建立成功后废弃。

接入流程图：



1. 获取建立 Websocket 连接的 Token

1.1 调用方式

通过腾讯云 SDK 调用 GetWsToken 接口获取 Token，可参考 GetWsToken 文档。

说明：

获取的 Token 仅供一次会话连接使用，并且会过期，请在获取到 Token 后及时建立长连接，如需建立其他连接，需要重新获取 Token。

标签相关的值不再使用该接口传递，请参考下面  数据结构 中的 custom_variables 传入知识库检索范围相关参数 。

1.2 如何获取 AppKey

在应用管理界面，找到您处于运行中的应用（需要先发布），单击调用，会弹出“调用信息”窗口。



在调用信息窗口可以看到 AppKey，单击复制即可。



2. 使用 Token 建立 Websocket 连接

请求地址：wss://wss.lke.cloud.tencent.com/v1/qbot/chat/conn/?EIO=4&transport=websocket

请求协议：Socket.IO v4 （参考文档）

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 支持的事件

Socket.IO 事件格式如下，实现时需要注意其结构。建议尽可能使用 Socket.IO 提供的 标准 Client，或参考本文档下方提供的 前后端 Demo。

42["类型",{"payload":{事件体}}]

例如：
42["send",{"payload":{请参考下面各个不同事件的数据结构}}]

3.1 发送事件

事件名：send

事件方向：前端 > 后端

注意：

发送 send 事件前，需要先发布应用。

用户发出一条消息（发送事件）时，服务器会将该消息原样返回（回复事件，其中 is_from_self = true），以便确认消息被服务端收到并对应更新消息 ID、时间戳。

如果需要携带知识标签信息，请在获取 token 时携带。



数据结构：





file_infos

文件信息的数据结构：

3.2 回复事件

事件名：reply

事件方向：后端 > 前端

注意：

如果收到的消息中 is_evil == true 表示该消息命中敏感内容，发送失败。

因并发超限导致排队超时，会返回 "超出并发数限制" 错误。

数据结构：

knowledge 命中的知识的数据结构：



work_flow 工作流调试信息的数据结构：

current_node 当前工作流节点信息：

StatisticInfo LLM 统计信息：

quote_infos 引用信息数据结构：

效果如下：



quote_infos 示例（此处只展示，省略了部分结构）：

[    "reply",    {        "type": "reply",        "payload": {            "can_feedback": true,            "can_rating": false,            "content": "2025年2月13日腾讯股价情况如下：\n\n### 腾讯控股（00700.HK）港股市场表现\n\n- **股价波动**：腾讯控股股价在2025年2月13日经历了显著的波动，盘中振幅达到4.35%。这一波动既反映了市场情绪与资金博弈的短期影响，也体现了行业环境与公司基本面的长期逻辑。\n- **股价范围**：腾讯股价在当天最高达到464.6港币，最低跌至437港币。\n\n### 腾讯控股（TCTZF.us）美股市场表现\n\n- **股价上涨**：在美股市场，腾讯控股（TCTZF.us）股价在2025年2月13日盘中一度上涨5.05%，最新报58.10美元/股。\n- **市场反应**：这一异动引发了市场的广泛关注，投资者纷纷开始挖掘其背后的原因及影响。\n\n请注意，以上信息仅供参考，投资有风险，入市请谨慎。",                "quote_infos": [                {                    "index": 1,                    "position": 323                }            ],                    },        "message_id": "xxxxxxxxxxxxxxxxxxxxxxx"    }]

3.3 Token 统计事件

事件名：token_stat

事件方向：后端 > 前端

数据结构：

procedures 调用过程列表的数据结构：

示例：

[    "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

事件方向：双向

注意：

客户端发出评价事件时，客户端也会收到这个事件，以便客户端确认消息发出成功。

数据结构：

3.5 停止生成事件

事件名：stop_generation

事件方向：前端 > 后端

数据结构：

3.6 参考来源事件

事件名：reference

事件方向：后端 > 前端

数据结构：

references 参考来源的数据结构：

示例1：

参考来源类型为：

1：问答

2：文档片段

可调用 获取来源详情列表 接口查看参考来源详情, 此时 id 字段对应 DescribeRefer 中的 ReferBizIds 字段。

reference 事件：

[    "reference",    {        "type": "reference",        "payload": {            "record_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",            "references": [                {                    "doc_biz_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",                    "doc_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",                    "doc_name": "一百个成语典故及其历史人物故事+ (1).docx",                    "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",                    "name": "一百个成语典故及其历史人物故事+ (1)",                    "qa_biz_id": "0",                    "type": 2,                    "url": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"                }            ],            "trace_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"        },        "message_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"    }]

示例2：

参考来源类型为：

4：联网检索到的内容

此时，在收到的 thought 事件中或者 reply 事件中，content 字段下的 [3] [4] 表示就是 references 中联网检索到的来源的下标。

reply 事件(此处只展示，省略了部分结构)：

[    "reply",    {        "type": "reply",        "payload": {            "can_feedback": true,            "can_rating": false,            "content": "\n\n截至2025年2月13日14:59，《哪吒2》（《哪吒之魔童闹海》）总票房（含预售）            已突破**98亿元**，距离100亿大关仅一步之遥[3][4][7][8]。该票房成绩已超越《黑豹》，            成为全球影史票房榜前18名中唯一一部非好莱坞电影[3][4][8]。  \n\n根据灯塔专业版预测，《哪吒2》最终总票房可能达到**153.38亿元**，而猫眼预测则给出更高的**160.32亿元**[4]。            此外，影片海外票房已超过627万元人民币，观影",        },        "message_id": "**************************"    }]

reference 事件：

[    "reference",    {        "type": "reference",        "payload": {            "record_id": "**************************",            "references": [                {                    "doc_biz_id": "0",                    "doc_id": "0",                    "doc_name": "",                    "id": "1",                    "name": "破82亿元，进入全球票房榜前31！哪吒2海外首映看哭观众，有周边上架3天就卖光",                    "qa_biz_id": "0",                    "type": 4,                    "url": "https://new.qq.com/rain/a/20250210A04P8O00"                },                {                    "doc_biz_id": "0",                    "doc_id": "0",                    "doc_name": "",                    "id": "2",                    "name": "刚刚！哪吒2票房破90亿",                    "qa_biz_id": "0",                    "type": 4,                    "url": "https://new.qq.com/rain/a/20250211A07V6J00"                },                {                    "doc_biz_id": "0",                    "doc_id": "0",                    "doc_name": "",                    "id": "3",                    "name": "冲刺百亿票房！《哪吒2》总票房破98亿",                    "qa_biz_id": "0",                    "type": 4,                    "url": "https://view.inews.qq.com/a/20250213A04F7F00?scene=qqsearch"                },                {                    "doc_biz_id": "0",                    "doc_id": "0",                    "doc_name": "",                    "id": "4",                    "name": "《哪吒2》票房突破98亿元，影视股掀起涨停潮",                    "qa_biz_id": "0",                    "type": 4,                    "url": "https://view.inews.qq.com/a/20250213A04L4M00?scene=qqsearch"                },                {                    "doc_biz_id": "0",                    "doc_id": "0",                    "doc_name": "",                    "id": "5",                    "name": "哪吒2票房破30亿",                    "qa_biz_id": "0",                    "type": 4,                    "url": "https://new.qq.com/rain/a/20250202A03TL500"                },                {                    "doc_biz_id": "0",                    "doc_id": "0",                    "doc_name": "",                    "id": "6",                    "name": "哪吒2票房超去年冠军",                    "qa_biz_id": "0",                    "type": 4,                    "url": "https://new.qq.com/rain/a/20250203A02PAT00"                },                {                    "doc_biz_id": "0",                    "doc_id": "0",                    "doc_name": "",                    "id": "7",                    "name": "《哪吒2》票房突破98亿元",                    "qa_biz_id": "0",                    "type": 4,                    "url": "https://view.inews.qq.com/a/20250213A04DPH00?scene=qqsearch"                }                            ],            "trace_id": "**************************"        },        "message_id": "**************************"    }]

3.7 错误事件

事件名：error

事件方向：后端 > 前端

数据结构：

error 错误的数据结构：

3.8 思考事件

事件名：thought

事件方向：后端 > 前端

注意：

该事件目前只在使用 DeepSeek-R1 模型的时候有返回。

数据结构：

procedures 的数据结构：

debugging 的数据结构：

效果：



示例：

[    "thought",    {        "type": "thought",        "payload": {            "elapsed": 0,            "is_workflow": false,            "procedures": [                {                    "debugging": {                        "content": "\n好的，用户询问DeepSeek-R1的特点，这已经是第三次了。前两次我已经详细列出了它的高效性能、长上下文处理、多领域通用性、安全合规、多语言支持、灵活部署和高性价比等特点。用户可能是在确认信息，或者希望得到更简洁或不同角度的回答。\n\n我需要考虑用户为什么重复提问。可能的情况包括：用户没有完全理解之前的回答，需要更简明的总结；或者他们想确认信息的准确性；亦或是他们希望了解是否有新的更新。此外，用户可能是在测试回答的一致性，或者他们需要将信息用于特定场景，比如报告或比较不同模型。\n\n接下来，我应该检查之前的回答是否全面，是否有遗漏的重要特点。例如，是否提到了模型的训练数据、支持的框架、具体性能指标等。另外，用户可能对技术细节感兴趣，比如模型结构、训练方法，或者是实际应用"                    },                    "elapsed": 9954,                    "icon": "https://lke-realtime-1251316161.cos.ap-guangzhou.myqcloud.com/icon/thinking.png",                    "index": 0,                    "name": "thought",                    "plugin_type": 0,                    "status": "processing",                    "switch": "",                    "title": "思考",                    "workflow_name": ""                }            ],            "record_id": "piQ_20250208_140511_254_45ja7HPq",            "request_id": "rjbuFuYeDB-8487350785",            "session_id": "dfd04cd0-ef69-4fb6-a447-a0b44018a93f",            "trace_id": "9a9613dbaa9edd27958bd1180c524295 / piQ_20250208_140511_254_45ja7HPq",            "workflow_name": ""        },        "message_id": "7070ef0d-4c28-4d5a-abc8-2ea2e7fa027d"    }]

4. 错误码

5. 快速部署

adp-chat-client 代码内包括了一个完整连接建立和消息收发的流程。详细请查看 基于官方开源项目 adp-chat-client 的集成方案，来快速部署客户端并集成您的智能体应用，将智能体应用的对话功能嵌入您的业务系统。

6. 前端渲染组件

如果不需要完整客户端，仅需用于渲染大模型回复消息的前端组件，可直接通过 npm 安装：

消息统一渲染组件（Vue 2 或 React）：lke-component - npm

消息统一渲染组件（Vue 3）：lke-component-vue3 - npm

安装命令：

Vue2 示例代码

注册服务

// main.js
import Vue from 'vue'
import lkeComponent from 'lke-component'

Vue.use(lkeComponent)

使用示例

<template>
  <div>
    <!-- 思考过程 -->
    <MsgThought
      v-if="thought.content"
      :content="thought.content"
      :title="thought.title"
      :status="thought.status"
      :elapsed="thought.elapsed"
    />

    <!-- 消息内容 -->
    <MsgContent
      :content="message.content"
      :isFinal="message.isFinal"
      :isReplaceLinks="true"
      clazzMd="answer-md"
    />

    <!-- 加载状态 -->
    <MsgLoading
      v-if="loading"
      :loadingMessage="true"
      loadingText="正在思考..."
    />
  </div>
</template>

<script>
export default {
  data() {
    return {
      loading: false,
      message: {
        content: '',
        isFinal: true
      },
      thought: {
        content: '',
        title: '思考完成',
        status: 'success',
        elapsed: 0
      }
    }
  }
}
</script>

按需引入

<script>
import { MsgContent, MsgLoading, MsgThought } from 'lke-component'

export default {
  components: { MsgContent, MsgLoading, MsgThought }
}
</script>

Vue3 示例代码

全局注册

// main.js
import { createApp } from 'vue'
import App from './App.vue'
import lkeComponent from 'lke-component-vue3'
import 'lke-component-vue3/style.css'

createApp(App).use(lkeComponent).mount('#app')

使用示例代码

<template>
  <div>
    <MsgThought
      v-for="(thought, i) in thoughts"
      :key="i"
      :content="thought.content"
      :title="thought.title"
      :titleIcon="thought.titleIcon"
      :nodeName="thought.nodeName"
      :status="thought.status"
      :elapsed="thought.elapsed"
    />

    <MsgContent
      :content="message.content"
      :isFinal="message.isFinal"
      :isPrintAnimate="!message.isFinal"
    />
  </div>
</template>

<script setup>
import { ref } from 'vue'

const message = ref({
  content: '',
  isFinal: true
})

const thoughts = ref([])
</script>

按需引入组件

<script setup>import { MsgContent, MsgThought } from 'lke-component-vue3'import 'lke-component-vue3/style.css'</script>

React 示例代码

使用示例

import { useState } from 'react'
import { MsgContent, MsgThought } from 'lke-component/react'
import 'lke-component/css' // 必须引入样式

export default function Chat() {
  const [message, setMessage] = useState({
    content: '',
    isFinal: true
  })

  const [thoughts, setThoughts] = useState([])

  return (
    <div>
      {thoughts.map((thought, i) => (
        <MsgThought
          key={i}
          content={thought.content}
          title={thought.title}
          titleIcon={thought.titleIcon}
          nodeName={thought.nodeName}
          status={thought.status}
          elapsed={thought.elapsed}
          detailVisible={thought.detailVisible}
          onTitleClick={() => {
            // 切换展开/收起
            const next = [...thoughts]
            next[i].detailVisible = !next[i].detailVisible
            setThoughts(next)
          }}
        />
      ))}

      <MsgContent
        content={message.content}
        isFinal={message.isFinal}
        isReplaceLinks={true}
        clazzMd="answer-md"
      />
    </div>
  )
}