管理与支持产品文档捉虫活动邀您参加！> HOT
文档中心>实践教程>腾讯云智能体开发平台>前端页面接入（含demo）

前端页面接入（含demo）

最近更新时间：2025-05-20 09:32:52

我的收藏

本页目录：

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

环境配置

准备工作

1. 安装 nodejs 和 npm ，版本参考下方 npm & node 的环境指导部分。
2. 接入可参考 腾讯云智能体开发平台 对话端接口文档（WebSocket）-应用接口文档-文档中心-腾讯云 。

3. 下载demo文件包。
前端demo代码
4. 
了解统一渲染组件，详情参见npm地址。

说明：
如果不需要完整Demo，仅需要大模型回复的消息的前端渲染组件，可直接npm下载：
消息统一渲染组件（Vue 2 或 React）：lke-component - npm
消息统一渲染组件（Vue 3）：lke-component-vue3 - npm

node & npm的环境

1. node 建议使用 v14.x.x 版本
2. npm 推荐使用 v6.x.x 版本
// 检查node和npm版本
node -v
// v14.21.3
npm -v
// 6.14.18

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 的泄漏。

服务配置项

文件路径：scripts/static.js
1. 客户的SecretId:
const SecretId = 'SecretId'
2. 客户的SecretKey:
const SecretKey = 'SecretKey'
3. 应用的appkey:
const appId = 'appkey'

web配置项

文件路径：src/constants/static.js
1. 标识ws模式还是sse模式链接对话，可选值ws和sse。两者差异可查看 对话接口总体概述 。
const ACCESS_TYPE = 'ws'
2. 应用的appkey，同上服务配置项中的appId。
const APP_KEY = 'appkey'

启动服务

跨域配置处理

参考文件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');

安装依赖包

1. 检查npm源 npm。
2. 安装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包的源
npm config get registry
// https://registry.npmjs.org/

# 安装依赖
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，即可发起应用问答。


打包

如需部署，可以用以下方法打包成静态文件。
# build for production with minification
npm run build
打包时需要配置打包配置项，参见文件config/.env.prod，其中PUBLIC_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=''


部署示例

说明：
下列示例为在 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文件，生成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;
}


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中暂时不支持展示qa类型的参考来源。
搜索这个方法：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', '*') 此处统一配置'*'，用户可以根据自身域名情况做灵活修改。

第三方实践教程（视频）


中国站
目录