Python 环境

ACE Agent 快速入门脚本 包含打包为 wheel 的 Python 原生 ACE Agent 工具。您可以无缝使用 ACE Agent 工具来试用 NVIDIA ACE Agent 的关键功能，以及用于不同 Bot 的开发工作流程。ACE Agent 工具允许您在非容器化环境中快速开发功能，并迭代地测试 Bot 配置文件中的更改。Python 环境仅支持 CLI、服务器和事件接口。

注意

此环境不支持基于语音的 Bot，更适合想要使用原生设置构建基于文本的 Bot 的开发人员。

先决条件

在您开始使用 NVIDIA ACE Agent 之前，假定您满足以下先决条件。当前版本的 ACE Agent 仅在 NVIDIA 数据中心 GPU 上受支持。

1. 您拥有 NVIDIA GPU Cloud (NGC) 的访问权限并已登录。您已在本地系统上安装了 NGC CLI 工具，并且已登录到 NGC 容器注册表。有关 NGC 的更多详细信息，请参阅 NGC 文档。

2. 您已安装 Docker 和 NVIDIA 容器工具包。确保您已完成Docker 安装后步骤，以便以非 root 用户身份管理 Docker。

3. 您拥有 NVIDIA Volta、NVIDIA Turing、NVIDIA Ampere、NVIDIA Ada Lovelace 或 NVIDIA Hopper 架构的 GPU 访问权限。

4. 您的工作站上已安装 python >= 3.8.10 和 pip >= 23.1.2。

设置

1. 通过克隆 GitHub ACE 存储库 下载 NVIDIA ACE Agent 快速入门脚本。

git clone git@github.com:NVIDIA/ACE.git
cd ACE

1. 转到 ACE Agent microservices 目录。

cd microservices/ace_agent

1. 在 NGC_CLI_API_KEY 环境变量中设置您的 NGC 个人 API 密钥。

export NGC_CLI_API_KEY=...

1. 创建虚拟环境并激活它。

python3 -m venv venv && source venv/bin/activate

1. 安装 aceagent Python 包。

pip install deploy/wheel/aceagent-4.1.0-py3-none-any.whl

1. 根据 Bot 的配置，您可能需要导出其他环境变量。例如，使用 OpenAI 模型的 Bot 将需要设置 OPENAI_API_KEY 环境变量。

aceagent 工具公开了一个命令行界面以进行交互，并提供以下选项。

聊天引擎

聊天引擎公开了不同的接口，以使用文本与 Bot 进行交互，并支持 CLI、服务器和事件接口。

CLI 接口

此接口适用于 Bot 开发，并允许更快的迭代。

注意

CLI 接口只能用于在 bot_config.yaml 文件中具有 colang_disable_async_execution: True 配置的 Bot，因为 CLI 接口需要以同步模式响应每个用户查询。

闲聊示例 Bot 是一个用于进行 Small Talk 的简单对话 Bot，位于 快速入门脚本目录 中的 ./samples/chitchat_bot。执行以下步骤以使用 CLI 接口进行部署。

1. 在启动 Bot 之前，设置 OPENAI_API_KEY 环境变量。此 Bot 使用 OpenAI gpt-4-turbo 作为主要模型。

   export OPENAI_API_KEY=...
   

2. 启动 Bot 并通过您的工作站终端与其交互。

   aceagent chat cli -c samples/chitchat_bot/
   

例如

[YOU] Are you a person?
[BOT] No, I am just a chatbot.

[YOU] What is your name?
[BOT] I do not have a name yet.

CLI 接口

	类型	默认	描述
--config	路径	无	Bot 要使用的配置文件的目录或多个目录的必需路径。也可以指向单个配置文件。
--log-level	文本	警告	控制聊天引擎日志的详细级别。
--help			显示受支持的命令行参数列表。

HTTP 服务器接口

HTTP 服务器接口公开了多个 rest API，可用于与 Bot 交互、查看 Bot 的状态以及更新 Bot 的状态。

注意

HTTP 接口只能用于在 bot_config.yaml 文件中具有 colang_disable_async_execution: True 配置的 Bot，因为 HTTP 接口需要以同步模式响应每个用户查询。

闲聊示例 Bot 是一个用于进行 Small Talk 的简单对话 Bot，位于 快速入门脚本目录 中的 ./samples/chitchat_bot。执行以下步骤以使用服务器接口进行部署。

1. 在启动 Bot 之前，设置 OPENAI_API_KEY 环境变量。此 Bot 使用 OpenAI gpt-4-turbo 作为主要模型。

   export OPENAI_API_KEY=...
   

2. 在服务器接口中启动 Bot 以部署基于 fastapi 的 rest 服务器。

   aceagent chat server -c samples/chitchat_bot/
   

   您可以按照 HTTP 接口 通过 HTTP 与 Bot 进行交互。Bot 响应文本可以在 Response[“response”][“text”] 下找到。

   CURL

   curl -X POST http://127.0.0.1:9000/chat \
       -H "Content-Type: application/json" \
       -H "Accept: application/json" \
       -d '{"UserId": "1", "Query": "Hello"}'
   

服务器接口

	类型	默认	描述
--config	路径	无	Bot 要使用的配置文件的目录或多个目录的必需路径。也可以指向单个配置文件。
--port	整数	9000	ACE Agent 的 HTTP 接口的端口。
--workers	整数	1	启动 Web 服务器的 uvicorn 工作进程数。
--log-level	文本	警告	控制聊天引擎日志的详细级别。
--help			显示受支持的命令行参数列表。

事件接口

事件接口需要运行 Redis 服务器。与事件接口的通信（输入和输出）使用 Redis 流进行。设置本地 Redis 服务器的最简单方法是使用官方 Redis 容器镜像（替代安装方法可以在官方 Redis 文档中找到）

docker run -d --rm --name redis --net host redis

您可以尝试股票示例 Bot，它位于 快速入门目录 中的 ./samples/stock_bot。该 Bot 使用 OpenAI gpt-4-turbo 作为主要模型。设置 OpenAI API 密钥环境变量。

export OPENAI_API_KEY=...

要使用事件接口启动 Bot，请运行

aceagent chat event --config samples/stock_bot

这将启动事件接口并等待流 ace_agent_system_events 上的 PipelineAcquired 事件。这些事件表明新的流或管线已变为可用。ACE Agent 将生成一个事件工作进程，该工作进程将专用于此流，以将任何事件转发到配置的 Bot。

您可以使用 ACE Agent 事件接口异步 API 模式与 Bot 进行交互。您可以使用 事件示例客户端 来试用 Bot。

事件接口

	类型	默认	描述
--config	路径	无	Bot 要使用的配置文件的目录或多个目录的必需路径。也可以指向单个配置文件。
--event-provider-name	文本	redis	目前，仅支持 redis。我们计划支持其他消息代理或事件提供程序。
--event-provider-host	文本	localhost	事件提供程序（例如，redis 服务器）正在运行的主机地址。
--event-provider-port	整数	6379	事件提供程序正在监听的端口（例如，redis 服务器端口）。
--port	整数	9000	ACE Agent 的 HTTP 接口的端口。如果您需要一种以编程方式检查 ACE Agent 的运行状况状态的方法（例如，作为集群部署中活跃度或就绪度探测的一部分），则这是必需的。
--workers	整数	1	启动 Web 服务器的 uvicorn 工作进程数。
--log-level	文本	警告	聊天是否应详细输出聊天引擎的日志。
--help			显示受支持的命令行参数列表。

插件服务器

插件服务器是基于 FastAPI 的服务器，使 ACE Agent 能够通过 REST 接口与第三方应用程序或 API 进行交互。它公开了一个 Swagger 端点，允许开发人员在沙盒环境中轻松编写和验证插件服务器。

食物订购 Bot 是一个虚拟助手 Bot，可以帮助您下食物订单。它可以列出菜单中的项目，在您的购物车中添加、删除和替换项目，并帮助您下订单。要为食物订购示例 Bot 部署插件服务器，请运行

aceagent plugin-server deploy --config samples/food_ordering_bot/plugin_config.yaml

要停止插件服务器，请运行

aceagent plugin-server stop

插件服务器

	类型	默认	描述
--config	路径	无	包含 plugin_config.yaml 文件的当前工作目录的必需相对路径。
--port	整数	9002	插件服务器将启动的端口。
--log-level	文本	警告	控制插件服务器日志的详细级别。
--help			显示受支持的命令行参数列表。

模型部署

为了按照 Bot 配置中的 model_config.yaml 中所述部署 NLP 模型以及 NLP 服务器，请运行

aceagent models deploy --config samples/food_ordering_bot/model_config.yaml

此命令为食物订购 Bot 部署食物订购意图槽模型。

模型部署

	类型	默认	描述
--config	路径	无	包含 model_config.yaml 文件的当前工作目录的必需相对路径。
--model-repository-path	路径	./model_repository	将存储 Triton Inference Server 的优化模型的路径。
--no-cache	布尔值	False	默认情况下，使用缓存的 Triton 模型计划。将标志设置为 True 以重建 Triton 计划。缓存的模型存储在 $PWD/.cache 目录中。
--gpus	文本	1	要用于部署的 GPU。允许的格式为 3 [使用总共 3 个 GPU]，device=0,1 [使用设备 0 和 1]。
--speech	布尔值	False	如果 model_config.yaml 中指定了语音模型（ASR 和 TTS），则将标志设置为 True 以部署语音模型。
--help			显示受支持的命令行参数列表。

NLP 服务器

NLP 服务器提供了一个统一的接口，用于在对话管线中集成不同的 NLP 模型。它利用已经过生产测试的模型服务器，如 NVIDIA Triton Inference Server 和 Riva Speech Server，同时还允许在管线中轻松集成实验性自定义模型。

如果您已经使用 Triton Inference Server 或 Riva Server 部署了模型，则可以通过运行以下命令来部署 NLP 服务器 REST 接口

aceagent nlp-server deploy --config samples/food_ordering_bot/model_config.yaml

NLP 服务器

	类型	默认	描述
--config	路径	无	包含 model_config.yaml 文件的当前工作目录的必需相对路径。
--custom_model_dir	路径	无	包含 NLP 服务器的自定义模型客户端的目录。
--port	整数	9003	插件服务器将启动的端口。
--log-level	文本	INFO	控制插件服务器和 NLP 服务器日志的详细级别。
--workers	整数	1	启动 NLP 服务器的 uvicorn 工作进程数。
--help			显示受支持的命令行参数列表。

清理

您可以使用以下命令停止所有正在运行的服务器和模型

aceagent chat stop
aceagent models stop
aceagent nlp-server stop
aceagent plugin-server stop

Python 原生应用程序

您可以使用 aceagent 包编写 Python 应用程序并与之交互。

注意

Python 原生应用程序仅支持在 bot_config.yaml 文件中具有 colang_disable_async_execution: True 配置的 Bot。

以同步方式与 Bot 交互

import json
from chat_engine import CreateBots, Core
from time import sleep

bots = CreateBots.from_path(config_dir=["samples/chitchat_bot/"])

while not bots[0].is_ready:
    sleep(1)

request = {"UserId": "1", "Query": "Hello"}
response = Core.get_response(bots[0], request)

print(response.get("Response").get("Text"))

与流式 Bot 交互

from chat_engine import CreateBots, Core
from time import sleep
import asyncio
import json

bots = CreateBots.from_path(config_dir=["samples/chitchat_bot/"])

while not bots[0].is_ready:
    sleep(1)


async def chat():
    request = {"UserId": "1", "Query": "Tell me a joke"}
    streaming_handler = await Core.stream_response_async(bots[0], request)

    print("[BOT] ", end="", flush=True)
    async for chunk in streaming_handler:
        if not chunk:
            break
        parsed = json.loads(chunk)
        if parsed["Response"]["IsFinal"]:
            break

        print(parsed["Response"]["Text"], end="", flush=True)

if __name__ == "__main__":
    asyncio.run(chat())