快速入门指南#

介绍#

注意

对于首次使用体验，我们强烈建议您从NIM Agent Blueprint：面向客户服务的数字人开始，以开始使用面向客户服务的数字人。

欢迎使用 NVIDIA Tokkio！虽然 Tokkio 有多个变体，但本指南将引导您使用裸机机器设置基本的数字人头像。在本快速入门结束时，您将拥有一个可以与之对话的数字头像。

如果您无法访问带有 NVIDIA GPU 的裸机机器来部署 Tokkio，请参阅部署了解云部署。

您可以期望看到头像的以下可视化效果，该头像根据 LLM 处理响应用户。本快速入门指南未详细说明 Tokkio 的所有可用自定义项。

Application UI

在高层次上，我们将引导您通过部署脚本安装 Tokkio。从终端运行部署脚本可以抽象化配置机器、拉取和部署 Tokkio 的复杂性。

先决条件#

本快速入门指南需要两台机器

  • 控制器实例：控制器实例是您将运行部署脚本的位置。

  • 应用程序实例：应用程序实例是 Tokkio 将安装的位置。

1. 配置控制器实例#

如前所述，控制器实例是您将运行部署脚本的位置。此机器必须满足以下要求

  • 操作系统：确保实例正在运行 Ubuntu 22.04。

  • SSH 密钥对：生成 SSH 密钥对，用于部署脚本的后续阶段。您可以按照以下步骤操作

    • 在您的控制器实例上打开终端

    • 运行以下命令生成 4096 位密钥，将your_email@example.com替换为您的电子邮件地址

      ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

    • 系统将提示您指定文件位置以保存密钥

      • 按 Enter 键接受默认位置（~/.ssh/id_rsa）。

      • 或者，指定自定义路径。

  • 无密码 Sudo 访问权限：确保控制器实例上的用户已启用无密码sudo访问权限。

    • 您可以通过运行sudo ls /root来测试此功能，并且此命令不应提示您输入密码。

    • 如果未设置此功能，请按照以下步骤操作，或联系您公司的系统管理员寻求支持。

      • 安全地编辑 sudoers 文件 使用 visudo 命令编辑 sudoers 文件。这可确保语法检查并防止错误。

        sudo visudo

      • 为您的用户添加无密码访问权限 滚动到定义用户权限的部分。添加一行以授予您的用户无密码 sudo 访问权限。将 username 替换为您的实际用户名

        username ALL=(ALL) NOPASSWD:ALL

        ALL=(ALL)：授予所有用户和组的管理权限。NOPASSWD:ALL：禁用所有 sudo 命令的密码提示。

2. 配置应用程序实例#

应用程序实例是 Tokkio Pipeline 将运行的位置。此机器必须满足以下要求

  • 操作系统：确保实例正在运行 Ubuntu 22.04。

  • GPU：您将至少需要 2xT4 或 2xL4 才能部署此单流 Tokkio 示例。

  • 分区大小：您将需要为应用程序实例分配至少 700 GB 的内存。

  • Kubernetes 注意事项：在首次运行一键式脚本之前，此实例不应有任何先前的 Kubernetes 安装正在运行。

  • 无密码 Sudo 访问权限：确保应用程序实例上的用户已启用无密码sudo访问权限。

    • 您可以通过运行sudo ls /root来测试此功能，并且此命令不应提示您输入密码。

    • 如果未设置此功能，请按照以下步骤操作，或联系您公司的系统管理员寻求支持。

      • 安全地编辑 sudoers 文件 使用visudo命令编辑 sudoers 文件。这可确保语法检查并防止错误。

        sudo visudo

      • 为您的用户添加无密码访问权限 滚动到定义用户权限的部分。添加一行以授予您的用户无密码 sudo 访问权限。将 username 替换为您的实际用户名

        username ALL=(ALL) NOPASSWD:ALL

        ALL=(ALL)：授予所有用户和组的管理权限。NOPASSWD:ALL：禁用所有 sudo 命令的密码提示。

  • IPv4 地址：请记下应用程序实例的 IP 地址以供稍后使用。在应用程序实例上，运行以下命令将 ssh 密钥复制到应用程序实例的授权密钥，以允许无密码通信

ssh-copy-id <app-instance-username>@<app-instance-ip-address>

3. 获取 NVIDIA API 密钥#

在继续操作之前，您将需要一个 NVIDIA API 密钥才能访问和拉取本快速入门安装所需的 Tokkio 资源。

要获取 API 密钥，请导航到NVIDIA API 目录。应该会出现一个标题为“Develop with this Blueprint”的弹出窗口。如果弹出窗口未出现，请选择屏幕右上角的下载蓝图以查看弹出窗口。选择“Generate API key”以创建密钥。现在，将其保存在安全位置。

作为提醒，您现在应该拥有来自控制器实例的 ssh 密钥、来自应用程序实例的 IPv4 地址以及您的 NVIDIA API 密钥。

4. 从 Github 获取部署脚本#

以下步骤应在控制器实例上完成。

要获取部署脚本，请从NVIDIA/ACE.git克隆 ACE GitHub 存储库，并导航到 baremetal 一键式脚本目录。

$ git clone https://github.com/NVIDIA/ACE.git
$ cd workflows/tokkio/scripts/one-click/baremetal

5. 配置一键式脚本部署#

我们需要配置控制器实例环境。导航到 config-template-examples/llm-ov-3d-coturn-1x-stream 目录并打开my-config.env文件。

$ cd config-template-examples/llm-ov-3d-coturn-1x-stream/
$ nano my-config.env

您需要在 .env 文件中填写以下信息。

注意

  • 默认 LLM 通过 NIM 访问。在本教程中，我们将使用 NIM 模型，无需其他步骤，您可以将 OpenAI API 密钥保持不变以用于本快速入门指南。

  • 目前，我们支持在与应用程序实例相同的机器上安装 turn 服务器 (coturn/twilio)，因此我们只需要一台机器。因此，APP_HOST_IPV4_ADDR和COTURN_HOST_IPV4_ADDR的值应相同。同样，APP_HOST_SSH_USER和COTURN_HOST_SSH_USER的值也相同。

export OPENAI_API_KEY="<replace-with-openai-api-key>"
export NGC_CLI_API_KEY="<replace-with-your-NVIDIA-personal-API-Key>"
export NVIDIA_API_KEY="<replace-with-you-NVIDIA-Personal-API-Key>"
export APP_HOST_IPV4_ADDR="<replace-with-the-ip-address-of-application-instance>"
export APP_HOST_SSH_USER="<replace-with-the-username-of-application-instance>"
export COTURN_HOST_IPV4_ADDR="<replace-with-the-ip-address-of-application-instance>"
export COTURN_HOST_SSH_USER="<replace-with-the-username-of-application-instance>"

然后，您需要根据您的 shell 将其源到环境中。

$ source my-config.env

上面的命令将环境变量源到当前 shell 会话，并且每次您想要操作部署（安装、卸载）时都需要重新执行。

接下来，在同一目录中，有config-template.yml文件。使用特定名称复制此文件，并将其向上移动两个目录级别。

$ cp config-template.yml <my-new-config-template-name.yml>
$ mv <my-new-config-template-name.yml> ../..
$ cd ../..

可以在此处找到config-template.yml和my-config.env以供参考。

部署#

请按照以下步骤准备好部署脚本以进行安装。

1. 运行部署脚本#

要安装 Tokkio，请使用您的config-template.yml运行以下命令。从预期输出中捕获 URL。

$ ./envbuild.sh install --component all --config-file ./<my-renamed-config-template.yml>

预期输出

***(Several output lines omitted for brevity)***
.
.
access_urls:
   app:
      app: http://<application-instance-ip>:80/
      grafana: http://<application-instance-ip>:32300/login
      kibana: http://<application-instance-ip>:31565/app/kibana
      prometheus: http://<application-instance-ip>:30090/graph
    turn: {}
ssh_command:
app:
    master: ssh -i /home/metroadmin/.ssh/id_rsa.pem -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -o ProxyCommand="ssh -i /home/metroadmin/.ssh/id_rsa.pem -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -W %h:%p ubuntu@<bastion-host-ip>" ubuntu@<application-instance-ip>
turn:
    master: ssh -i /home/metroadmin/.ssh/id_rsa.pem -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null ubuntu@<turn-server-ip>

2. 验证安装#

此时，您可以使用以下 ssh 命令登录到应用程序实例，检查并观察所有 Kubernetes Pod 是否已启动并正在运行。

$ ssh <application-instance-username>@<application-instance-IP-address>

$ kubectl get pods -n app

预期输出

NAME                                                        READY   STATUS    RESTARTS      AGE
a2f-a2f-deployment-98c7fb777-lnp6w                          1/1     Running   0             72m
ace-agent-chat-controller-deployment-0                      1/1     Running   0             72m
ace-agent-chat-engine-deployment-5f8db599f6-6mkh9           1/1     Running   0             72m
ace-agent-plugin-server-deployment-645cf865b5-vvcvw         1/1     Running   0             72m
anim-graph-sdr-envoy-sdr-deployment-5b7cc55b6b-cbbz6        3/3     Running   0             72m
catalog-rag-deployment-67547fd54-lrcf2                      1/1     Running   0             72m
chat-controller-sdr-envoy-sdr-deployment-78b54b7f86-fnvql   3/3     Running   0             72m
ds-sdr-envoy-sdr-deployment-85bbfdb4c4-lbksh                3/3     Running   0             72m
ds-visionai-ds-visionai-deployment-0                        1/1     Running   0             72m
ia-animation-graph-microservice-deployment-0                1/1     Running   0             72m
ia-omniverse-renderer-microservice-deployment-0             1/1     Running   0             72m
ia-omniverse-renderer-microservice-deployment-1             1/1     Running   0             72m
ia-omniverse-renderer-microservice-deployment-2             1/1     Running   0             72m
mongodb-mongodb-666765487c-tzxxw                            1/1     Running   0             72m
occupancy-alerts-api-app-84576db5c9-qb7dr                   1/1     Running   0             72m
occupancy-alerts-app-5cfcc9f75-b84xb                        1/1     Running   0             72m
redis-redis-79c99cdd97-kl77x                                1/1     Running   0             72m
redis-timeseries-redis-timeseries-69bb884965-fnn44          1/1     Running   0             72m
renderer-sdr-envoy-sdr-deployment-55df9ccc6f-v66rr          3/3     Running   0             72m
riva-speech-547fb9b8c5-7w8h4                                1/1     Running   0             72m
tokkio-cart-manager-deployment-65d8547cbc-vplnq             1/1     Running   0             72m
tokkio-ingress-mgr-deployment-65dfdc79f6-4pvcg              3/3     Running   0             72m
tokkio-ui-server-deployment-79c9749686-ztxrq                1/1     Running   0             72m
tokkio-umim-action-server-deployment-674cccc898-qgz26       1/1     Running   0             72m
triton0-bbd77d78f-rz62w                                     1/1     Running   0             72m
vms-vms-67876bcb9b-q655s                                    1/1     Running   0             72m

3. 访问 Tokkio 应用程序#

  • 浏览器设置：此安装未设置任何 CA 证书。为了克服浏览器限制，我们需要在 Chrome 中启用一些标志。

    • 在您要访问 UI 的机器上，打开 Chrome 浏览器并导航到chrome://flags。

    • 搜索Insecure origins treated as secure标志。

    • 选择启用。

    • 在其下添加以下 Chrome 标志。http://<application-instance-ip>:80，http://<application-instance-ip>:30888，ws://<application-instance-ip>:30888。

    • 按照 Chrome 说明重新启动浏览器并完成此步骤。

  • 一旦所有 Pod 都运行，您应该能够使用在运行部署脚本后在终端输出中显示的 URL 之一访问 Tokkio。您可以在 Chrome 浏览器中输入 ui_endpoint URL 以与 Tokkio 交互。例如，http://<application-instance-ip>:80

    • 您可能会遇到站点不安全警告。出现此警告是因为我们未使用任何 CA 签名证书。确认 IP 地址和端口正确，然后阅读并按照浏览器中的说明绕过此警告。

    • 首次访问 UI 时，浏览器应提示您授予 UI 运行所需的权限，例如麦克风、扬声器或摄像头。接受权限后，UI 应加载。

查看安装详细信息#

要在稍后查看安装输出，请运行以下命令。您将收到 Tokkio 首次安装时的相同输出。

$ ./envbuild.sh info --config-file ./<my-renamed-config-template.yml>

预期输出

access_urls:
   app:
      app: http://<application-instance-ip>:80/
      grafana: http://<application-instance-ip>:32300/login
      kibana: http://<application-instance-ip>:31565/app/kibana
      prometheus: http://<application-instance-ip>:30090/graph
    turn: {}
ssh_command:
app:
    master: ssh -i /home/metroadmin/.ssh/id_rsa.pem -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -o ProxyCommand="ssh -i /home/metroadmin/.ssh/id_rsa.pem -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -W %h:%p ubuntu@<bastion-host-ip>" ubuntu@<application-instance-ip>
turn:
    master: ssh -i /home/metroadmin/.ssh/id_rsa.pem -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null ubuntu@<turn-server-ip>

卸载 Tokkio 应用程序#

如果您决定卸载整个设置，请运行以下命令。确保您已将my-config.env中的变量源到您的 shell。

source my-config.env
$ ./envbuild.sh uninstall --component all --file config-template.yml

故障排除#

如果您无法按照本快速入门指南中概述的步骤操作，请参阅故障排除进行故障排除。

下一步#

现在您已经拥有一个可用的 Tokkio 头像，有多种不同的方法可以部署或自定义应用程序。下图提供了用户旅程流程图，说明了您在浏览文档时可以期望的内容。

Application UI

云部署#

除了在裸机机器上部署此基本 Tokkio 示例外，您还可以选择在云中通过 AWS、GCP 或 Azure 部署 Tokkio。

参考工作流程#

在本快速入门指南中部署的 Tokkio 应用程序版本是 LLM-RAG 参考工作流程的最简单版本。如果您想部署不同的参考工作流程，请参阅参考工作流程。

自定义#

在本快速入门指南中部署的 Tokkio 应用程序版本是 LLM-RAG 参考工作流程的最简单版本。如果您想自定义您的 Tokkio 部署，请参阅以下指南

本页内容