文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>腾讯云智能体开发平台>实践教程>前端页面接入（含demo）

前端页面接入（含demo）

最近更新时间：2025-08-20 09:48:11

我的收藏

本页目录：

说明：
本文档用于提供官方 demo，便于客户接入大模型，了解业务逻辑。
官方 demo 仅提供 vue2 版本，vue3 和 react 版本可参考 vue2 版本自行研发。

环境配置

准备工作

1. Node.js (推荐 v14.x.x 版本)。
2. npm（推荐 v6.x.x 版本）。
3. 【可选】前端 demo代码。
4. 【可选】对话消息渲染组件。
如果不需要完整Demo，仅需要大模型回复的消息的前端渲染组件，可不下载前端 demo 代码，直接 npm下载：
消息统一渲染组件（Vue 2 或 React）：lke-component - npm
消息统一渲染组件（Vue 3）：lke-component-vue3 - npm

port可用检测

// mac上可以使用以下命令,查看3000端口和9091端口是否被占用,占用情况会影响本地服务启动
lsof -i :3000
lsof -i :9091
// windows上可用
netstat -ano | findstr :3000
netstat -ano | findstr :9091

// 这两个端口根据本地启动服务的各自情况来处理
// 3000对应npm run serve启动的服务
// 9091对应npm run dev启动的服务

通用配置

获取密钥

进入 腾讯云控制台-访问管理 -访问密钥-API密钥管理，获取 SecretId 和 SecretKey。



注意：
只有新建密钥的时候才支持显示 SecretKey。如不记得之前的 SecretKey，可以新建一个，然后自行记录保存。或禁用原有的密钥（不再继续使用）后删除该密钥；删除之后就可以重新创建。

获取 appkey

打开应用列表， 单击调用， 即可获取 appkey。



注意：
在 demo 代码中，前端会把 appkey 的明文作为入参发送请求到后台或云 API，在无登录态的情况下，将 demo 传播给他人可能会造成您的 appkey 泄露。您可以通过后台使用 appkey 来对接口进行转发，或者在获取 appkey 之前做好资源限制来避免 appkey 的泄露。

获取 botbizid





服务配置项

文件路径：scripts/static.js
您需填写以下参数：
参数
说明
SecretId
在 云API密钥 上申请的标识身份的 SecretId
SecretKey
SecretId 对应的唯一 SecretKey。如无法找到，您可参见 腾讯云上只能看到 SecretId，看不到 SecretKey
appId
智能体应用的唯一凭证，对应智能体应用的 appkey。appkey 的获取方式请参见 BotAppKey 是什么，从哪里获取？
botId
智能体应用的唯一标识，对应智能体应用的 botbizid。botbizid 的获取方式请参见 BotBizID 是什么，从哪里获取？

web配置项

文件路径：src/constants/static.js
您需填写以下参数：
参数
说明
ACCESS_TYPE
接入方式。可选值为 ws 和 sse。ws 和 sse 的区别请参见 对话接口总体概述
APP_KEY
智能体应用的唯一凭证。appkey 的获取方式参见 BotAppKey 是什么，从哪里获取？
BOT_ID
智能体应用的唯一标识，对应智能体应用的 botbizid。botbizid 的获取方式请参见 BotBizID 是什么，从哪里获取？

启动服务

跨域配置处理

参考文件scripts/index.js
res.setHeader('Access-Control-Allow-Origin', '*');
res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
res.setHeader('Content-Type', 'application/json');

安装依赖包

检查 npm 源，安装 lke 统一渲染组件。
npm config get registry
// https://registry.npmjs.org/
// 检查Npm包的源
npm i lke-component
// 安装lke统一渲染组件
安装完毕后，结果显示如下：

说明：
建议 package 中使用依赖：
"less-loader": "^3.0.0"
"less": "^4.1.3"

安装依赖

# 安装依赖
npm install

# 启动服务 at http://localhost:3000/
npm run serve

# 启动web at http://localhost:9091
npm run dev

# 打开页面 port视具体情况定 可能9091 可能9092 可能其他，注意前后一致性就好
http://localhost:9091/#/chat-demo


运行展示

本地访问域名http://localhost:9091/#/chat-demo，即可发起问答。







打包

打包时需要配置打包配置项，参见文件config/.env.prod，其中PUBLIC_PATH和SERVER_PATH根据用户需求和用户域名灵活修改。
// config/.env.prod
NODE_ENV='production'
SERVER_ENV='prod'
WS_BASE_URL='wss://wss.lke.cloud.tencent.com'
SSE_BASE_URL='https://wss.lke.cloud.tencent.com'
API_BASE_URL='https://lke.cloud.tencent.com/cgi/capi'
// 根据用户的域名做灵活修改
PUBLIC_PATH=''
// 根据部署服务的地址做灵活修改，本示例是在本地启动，所以配置如下
SERVER_PATH='http://localhost:3000'

如需部署，可以用以下方法打包成静态文件。
# build for production with minification
npm run build

部署

如果需要部署本机之外的机器访问 demo，推荐您使用 web server 的方式。
如需部署到 nginx 等 web server，以下是一个例子。注意，demo 中提供的 node 服务仅是一个为了跑通 demo 的最简单的例子（下列1-3步），我们强力推荐将 demo 改造成调用真实的后台服务，以避免潜在的安全漏洞。
1. 将 node 服务代码拷贝到服务器中，之后在这个文件夹中运行npm install。



2. 安装守护进程工具 pm2 PM2 - Home。
3. 用 pm2启动 node 服务。



4. 将代码中 node 服务的地址，替换为{您的 web server 具体的地址}/getDemoToken，例如https://mytest.com/getDemoToken，之后重新执行一次打包。
注意：
请再次确认 web server 具体的地址的协议是 http 还是 https 。

5. 将打包后的 dist 文件夹拷贝到服务器中，并将文件夹路径在 nginx 配置文件中设置为 root（也可以基于其他 root 对 location / 做相应的配置），重启 nginx 即可，可参考下图例子：


部署示例

说明：
下列示例为在 devCloud 上，启动一个部署的详细过程示例。不同的环境，执行操作和操作的代码会略有不同，请您灵活修改处理。
1. 将包拷贝到云服务器上，并解压。

# 解压
unzip qbot-api-demo.zip

2. 安装依赖。
检查 node 和 npm 版本，推荐 node v14.x.x npm v6.x.x 。
node -v
# v14.21.2
npm -v
# 6.14.17
安装 npm 依赖
  # 在/qbot-api-demo目录下，安装依赖
npm i
# /qbot-api-demo/scripts目录下执行，安装服务的依赖
npm i

上述操作会分别生成一个 node_modules 文件夹，如下图所示：


3. 安装 PM2，并启动服务。
全局安装 PM2 进程管理工具
# 全局安装pm2
npm install pm2 -g
启动服务
# 启动服务
pm2 start scripts/index.js
# 查看进程日志
pm2 logs

4. 安装 nginx，并部署 web 页面。
安装 nginx，启动 nginx。
# 安装nginx
sudo yum install nginx
# 启动nginx
sudo systemctl start nginx
nginx 启动成功后，访问 ip 可以看到 welcome nginx 页面。



部署 web 页面。
注意：
部署 web 页面时，首先检查调用api的路径是否正确，检查以下路径文件配置的 SERVER_PATH 配置是否和 serve 的 ip 和 port 一致。
qbot-api-demo/config/.env.local
qbot-api-demo/config/.env.prod
例如本次部署的 serve 在 devcloud，ip 为 9.134.11.xxx，port 为3000。
则 SERVER_PATH 配置如下：

# 打包web文件，生成dist文件夹
npm run build

将静态页面部署到 nginx 。
# 把dist文件复制到nginx目录下
sudo cp -r ./dist/*   /usr/share/nginx/html
# 重启nginx
sudo systemctl restart nginx

再次访问目标 ip 会变成 chat-demo 页面。



说明：
如果需要个性化配置 nginx，可以访问/etc/nginx/nginx.conf文件，进行修改。可参考下列示例：
server {
    listen 80;
    server_name your-domain.com; # 替换为您的域名或 IP

    root /var/www/html; # 替换为您的静态文件路径
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    # 如果需要禁止访问某些文件
    location ~* \\.(htaccess|htpasswd|git|svn) {
        deny all;
    }

    # 如果需要启用 gzip 压缩
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
}

至此您已成功搭建前端 demo，您可以查看对话端接口文档

Q & A

如何判断是否拿到 token？

1. 检查http://localhost:3000/getDemoToken这个接口是否调通。
2. 在控制台中查看接口响应结果，如正常返回，结果应如下图所示。

说明：
在 demo 中是使用一个小 node 服务来调用这个接口，详情参见scripts/index.js。配置后调用获取到 token 进行鉴权，用户可以根据自身情况，把这个接口移植到自身服务中，根据自身业务逻辑进行改造。

如何判断当前使用的connect type？

1. 配置接入方式，在src/constants/static.js路径下配置，可搜索代码ACCESS_TYPE。
2. 实际接入方式，可查看控制台日志。


demo的 h5 页面组成 改 npm

demo 使用的 vue2，核心主体为回复内容，主要由以下几个部分构成：
思考+回答+参考来源+运行状态
1. 思考采用插件<MsgThought>渲染，这个插件引入来源于 lke统一渲染组件。
2. 内容主体采用<MsgContent>渲染，这个插件引入来源于 lke统一渲染组件。
// main.js
import lkeComponent from '@tencent/lke-component';
3. 运行状态使用<TokensBoardBfr>渲染。
说明：
TokensBoardBfr 组件在本地代码中，另外两个来自 lke 统一渲染组件，用户可以根据自身需求调整ui样式，优化回复的展示。
4. 参考来源使用<Reference>渲染。

各模块数据来源

1 主体内容部分来源 ws 的 reply 事件
搜索这个方法：listenReplyMsg ()
2 思考过程内容来源 ws 的 thought 事件
搜索这个方法：listenThought ()
3 运行状态内容来源 ws 的 token_stat 事件
搜索这个方法：listenTokenStat ()
4 参考来源内容来源 ws 的 reference 事件，demo 中暂时不支持展示问答类型的参考来源。
搜索这个方法：listenReference ()
参考来源分类参见方法getReferenceType：
getReferenceType (type) {
            // 参考来源类型 1-QA  2-文档 4-search 分三类展示 default展示search，本demo不支持展示QA类型
            switch (type) {
            case 1:
                return 'QA';
            case 2:
                return 'DOC';
            case 4:
            default:
                return 'SEARCH';
            }
        },

说明：
用户可以基于上述事件监听的数据，参考以上方法，以及接入文档中的事件中的协议解释，进行处理和改造。

参考来源角标怎么处理

参考来源 demo 中支持搜索类型和文档类型的展示，暂不支持问答类型的内容展示，其中搜索类型的参考来源展示可以支持在回答中展示小标，回溯定位到参考来源内容，如下图所示：



激活小标展示能力，需要在lke统一渲染组件中，配置showTags属性为true，如果不需要小标，可以设置该属性为false，关掉该功能。
设置回调函数littleTagClick可以获取到点击小标的事件信息和当前信息的record_id。

小标内容和位置会在监听到的reply事件中，返回的quote_infos字段回传，用户可以根据这个角标的内容和位置，自定义处理相应的业务逻辑。


跨域问题如何处理

处理跨域代码
res.setHeader('Access-Control-Allow-Origin', '*');
res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
res.setHeader('Content-Type', 'application/json');

说明：
该代码要根据用户业务逻辑和自身的域名进行灵活改造，('Access-Control-Allow-Origin', '*') 此处统一配置'*'，用户可以根据自身域名情况做灵活修改。

第三方实践教程（视频）


中国站
目录