ADP-Chat-Client是一个开源的AI智能体应用对话端。可以将腾讯云智能体开发平台（Tencent Cloud ADP） 开发的AI智能体应用快速部署为Web应用（或嵌入到小程序、Android、iOS 应用中）。支持实时对话、对话历史管理、语音输入、图片理解、第三方账户体系对接等功能。支持通过Docker快速部署。

• 部署
• 开发指南
  • 后端
  • 前端
• 专题
  • 变量-API参数

请确保机器满足最低要求：

• CPU >= 2 Core
• RAM >= 4 GiB
• 操作系统：Linux/macOS。如果你希望在Windows系统运行，需要通过WSL，或者使用Linux系统的云服务器

1. 克隆源代码并进入目录

git clone https://github.com/TencentCloudADP/adp-chat-client.git
cd 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=

⚠️ 注意：

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. Vendor: 固定为Tencent，后续支持其他平台可能会有其他选项

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

🎥 观看演示视频

为了正常使用本系统，需要开启/配置以下服务：

1. 对话标题：知识引擎原子能力：后付费设置，开启：原子能力_DeepSeek API-V3后付费
2. 语音输入：语音识别：设置，开启：所需区域的实时语音识别
3. 应用权限：请确保配置的 TC_SECRET_ID/TC_SECRET_KEY 所对应的账号拥有已添加的应用的权限，详情可参考平台端用户权限说明

默认支持GitHub OAuth协议，开发者可以根据需要进行配置：

# you can obtain it from https://github.com/settings/developers
OAUTH_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.com
OAUTH_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. 【本系统】：校验签名通过，自动创建、绑定账户，生成登录态，自动跳转到对话页面。

参数	描述
url	https://your-domain.com/account/customer?CustomerId=&Name=&Timestamp=&ExtraInfo=&Code=
CustomerId	您现有账户体系的uid
Name	您现有账户体系的username（可选）
Timestamp	当前时间戳
ExtraInfo	用户信息
Code	签名，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命令生成。

• python >= 3.12
• uv ~= 0.8

# 1. 执行【部署】的所有步骤
# 2. 复制刚刚编辑好的.env文件到server文件夹
cp deploy/default/.env server/.env

# 3. 初始化（仅首次运行）
make init_server

# 4. 继续下面的步骤，安装【前端】部分依赖

• node >= 20

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.bashrc
nvm install v22

# 初始化（仅首次运行）
make init_client

# 调试运行，同时运行前后端，终端会打印调试网址，如：[ui]   ➜  Local:   http://localhost:5173/
make dev

组成部分	描述
config	配置系统
core	核心逻辑，不与具体协议（如http或stdio）绑定
middleware	Sanic服务端的中间件
router	对外暴露的http入口，一般是对core的包装
static	静态文件
test	测试
util	其他辅助类

调用智能体对话时，可以向智能体传递参数，根据具体情况，可以选择在前端还是后端进行传递，这是一个后端附加API参数的示例

# 编辑文件：server/router/chat.py
class ChatMessageApi(HTTPMethodView):
    @login_required
    async def post(self, request: Request):
        parser = reqparse.RequestParser()
        parser.add_argument("Query", type=str, required=True, location="json")
        parser.add_argument("ConversationId", type=str, location="json")
        parser.add_argument("ApplicationId", type=str, location="json")
        parser.add_argument("SearchNetwork", type=bool, default=True, location="json")
        parser.add_argument("CustomVariables", type=dict, default={}, location="json")
        args = parser.parse_args(request)
        logging.info(f"ChatMessageApi: {args}")

        application_id = args['ApplicationId']
        vendor_app = app.get_vendor_app(application_id)

        # 新增以下代码，就能在对话时附加额外的API参数：
        from core.account import CoreAccount
        account = await CoreAccount.get(request.ctx.db, request.ctx.account_id)
        # 注意这里的json.dumps，腾讯云ADP约定：如果值是字典，需要进行一次json编码，转换为json字符串
        args['CustomVariables']['account'] = json.dumps({
            "id": str(account.Id),
            "name": account.Name,
        })
        logging.info(f"[ChatMessageApi] ApplicationId: {application_id},\n\
            CustomVariables: {args['CustomVariables']},\n\
            vendor_app: {vendor_app}")