如需将智能体应用的对话功能嵌入您的业务系统，推荐使用腾讯云官方开源项目 ADP-Chat-Client 快速部署，实现大幅降低开发成本。
ADP-Chat-Client 是一个开源的 AI 智能体应用对话端解决方案，提供开箱即用的前端界面（支持灵活定制）与稳定可靠的后端服务。基于腾讯云智能体开发平台（Tencent Cloud ADP）开发的智能体应用可通过该项目快速部署为 Web 应用，或无缝嵌入 小程序、Android、iOS 等多端场景，直接复用平台已有的流程与架构，无需重复开发基础功能。支持实时对话、对话历史管理、语音输入、图片理解、第三方账户体系对接等功能。目前支持通过 Docker 快速部署。您可进入 ADP-Chat-Client GitHub 项目主页 查看该项目代码，或进入 ADP-Chat-Client 项目官网 查看详细介绍。
以下是使用 Docker 快速部署 ADP-Chat-Client 的具体流程：
在部署前，请保证您的机器满足以下最低要求：
CPU >= 2 Core
RAM >= 4 GiB
操作系统：Linux/macOS。如果您希望在 Windows 系统运行，需要通过 WSL，或者使用 Linux 系统的云服务器。
您也可以 使用腾讯云 CVM（云端服务器）来进行 ADP-chat-client 的部署，方便您更好地管理开发环境、保障数据安全，并确保在云端的稳定访问。
1. 克隆源代码并进入目录。
git clone https://github.com/TencentCloudADP/adp-chat-client.gitcd adp-chat-client
2. 安装 Docker 并设定镜像配置（如果系统上已经装好 Docker，可跳过该步骤）。
适用于 TencentOS Server 4.4。
bash script/init_env_tencentos.sh
适用于 Ubuntu Server 24.04。
bash script/init_env_ubuntu.sh
3. 复制 .env.example 文件到deploy文件夹。
cp server/.env.example deploy/default/.env
4. 修改 deploy/default/.env 文件中的配置项。
您需要根据您的腾讯云账户和 ADP 平台的相关信息，填入以下密钥和应用 Key：
# 腾讯云账户密钥：https://console.cloud.tencent.com/cam/capi
TC_SECRET_APPID=
TC_SECRET_ID=
TC_SECRET_KEY=
# ADP平台获取的智能体应用key：https://adp.cloud.tencent.com/
APP_CONFIGS='[
{
"Vendor":"Tencent",
"ApplicationId":"对话应用唯一Id，在本系统内唯一标识一个对话应用，推荐使用appid，或者使用uuidgen命令生成一个随机的uuid",
"Comment": "用户自定义备注，用于标识应用用途",
"AppKey": "",
"International": false
}
]'
# JWT密钥，一个随机字符串，可以使用uuidgen命令生成
SECRET_KEY=echo $(uuidgen)
注意：
1. APP_CONFIGS 内容为 JSON，注意遵循 JSON 规范，例如：最后一项末尾不能有逗号，不支持//注释。
2. Comment: 可以任意填写，方便自己定位对应的智能体应用。
3. International: 默认设为 false，如果是在国际站开发的智能体应用，此处设为 true。
4. ApplicationId: 进入任意 ADP 应用，在应用网址内查看 appid。
例如某个应用的链接为 https://adp.cloud.tencent.com/adp/#/app/knowledge/app-config?appid=1959******8208&appType=knowledge_qa&spaceId=default_space，则它的ApplicationId为1959******8208。
5. 制作镜像。
# 制作镜像（修改代码后需要重新运行，如果只是修改.env文件不需要重新pack）sudo make pack
6. 启动容器。
sudo make deploy
注意：
正式的生产系统需要通过自有域名申请 SSL 证书，并使用 Nginx 进行反向代理等方式部署到 https 协议。如果仅基于 http 协议部署，某些功能（如语音识别、消息复制等）可能无法正常工作。
7. 登录。
本系统支持和现有账户体系打通，此处演示基于 URL 跳转的登录方式：
sudo make url
上述命令可以获得登录 URL，在浏览器打开该 url 进行无感登录。
如果配置了 OAuth 登录方式，可以在浏览器打开 http://localhost:8000 进行登录。
8. 问题排查。
# 检查容器是否在运行，正常应该有2个容器：adp-chat-client-default, adp-chat-client-db-default
sudo docker ps
# 如果没有看到容器，意味着启动遇到问题，可以查看日志:
sudo make logs
为了正常使用本系统，需要开启/配置以下服务：
对话标题：知识引擎原子能力 > 后付费设置，开启原子能力_DeepSeek API-V3 后付费。
语音输入：语音识别设置，开启所需区域的实时语音识别。
应用权限：请确保配置的 TC_SECRET_ID/ TC_SECRET_KEY 所对应的账号拥有已添加的应用的权限，详情请参见 平台端用户权限 说明。
默认支持 GitHub OAuth 协议，开发者可以根据需要进行配置：
# you can obtain it from https://github.com/settings/developersOAUTH_GITHUB_CLIENT_ID=OAUTH_GITHUB_SECRET=
注意：
创建 GitHub OAuth 应用时，callback url 填写：SERVICE_API_URL+/oauth/callback/GitHub，例如：http://localhost:8000/oauth/callback/github。
默认支持 Microsoft Entra ID OAuth 协议，开发者可以根据需要进行配置：
# you can obtain it from https://entra.microsoft.comOAUTH_MICROSOFT_ENTRA_CLIENT_ID=OAUTH_MICROSOFT_ENTRA_SECRET=
注意：
创建 Microsoft Entra ID OAuth 应用时，callback url 填写：SERVICE_API_URL + /oauth/callback/ms_entra_id，例如：http://localhost:8000/oauth/callback/ms_entra_id。
OAuth 协议可以帮助实现无缝的身份验证和授权，开发者可以根据业务需求定制自己的认证方式。如需使用其他 OAuth 系统，可以根据具体协议修改 server/core/oauth.py 文件以适配。
如果您已经有自己的账户体系，但没有标准的 OAuth，希望用更简单的方法对接，可以采用 url 跳转方式来实现系统对接。
1. 【您现有的账户服务】：生成指向本系统的 URL，携带 CustomerId、Name、ExtraInfo、Timestamp、签名等信息。
2. 【用户】：用户点击该 URL，进行登录。
3. 【本系统】：校验签名通过，自动创建、绑定账户，生成登录态，自动跳转到对话页面。
参数 | 描述 |
| https://your-domain.com/account/customer?CustomerId=&Name=&Timestamp=&ExtraInfo=&Code= |
| 您现有账户体系的 uid |
| 您现有账户体系的 username（可选） |
| 当前时间戳 |
| 用户信息 |
| 签名，SHA256(HMAC(CUSTOMER_ACCOUNT_SECRET_KEY, CustomerId + Name + ExtraInfo + str(Timestamp))) |
注意：
1. 以上参数需要分别进行 url_encode，详细实现可以参考代码 server/core/account.py 内 CoreAccount.customer_auth 部分；生成 url 的方式可以参考 server/main.py 的 generate_customer_account_url。
2. 需要在 .env 文件中配置 CUSTOMER_ACCOUNT_SECRET_KEY，一个随机字符串，可以使用 uuidgen 命令生成。
如需更多开发调试信息，请前往 ADP-chat-client GitHub 项目主页 查看该项目代码或 ADP-chat-client 文件官网 查看详细介绍。
