安装指南#

本文档提供了在 Google Cloud Platform (GCP) 上部署 Tokkio Workflow 的全面指南。虽然在 GCP 环境中实现 Tokkio Workflow 有多种方法，但本指南侧重于使用 Tokkio 约定式部署脚本的特定部署方法。这些脚本自动化了设置 Tokkio Workflow 及其所需基础设施组件的过程。

先决条件#

GCP 先决条件#

  1. 具有管理员权限的 GCP 控制台访问权限

  2. 具有所有者角色和相应密钥文件的服务帐户设置

  3. 用于部署状态的云存储桶

  4. 公共 DNS 区域

硬件#

控制器实例#

  • Ubuntu 22.04 操作系统

  • 生成 SSH 密钥对

  • 确保无密码 sudo 访问

访问权限#

  • 访问启动 Tokkio Pipeline 应用程序期间使用的所有工件。例如，NGC 上的 Tokkio 应用程序 Helm chart。

基础设施布局#

在 GCP 上设置 Tokkio Workflow 需要创建多个云资源，例如 VPC、实例组、防火墙规则、服务帐户、云 DNS、云负载均衡等。下图显示了在 GCP 上启动的组件的总体布局。

GCP Deployment Architecture

注意

此设置中的许多资源可能不属于免费层级，您可以查看 GCP 计费参考页面以了解成本影响。

安装步骤#

  1. 克隆 NVIDIA/ACE.git 存储库并导航到 gcp 部署脚本目录

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

  1. 准备配置文件，可以通过复制基本 config-template.yml 或复制 config-template-examples 文件夹下的示例配置文件之一。

#list of example templates
config-template-examples/
├── llm-ov-3d-rp-6x-streams
│   ├── config-template.yml
│   └── my-config.env
└── llm-ue-3d-coturn-3x-streams
    ├── config-template.yml
    ├── my-config.env
    └── user-helm-override-values.yml

复制您选择的配置模板作为此安装的基本配置模板。

cp config-template-examples/llm-ov-3d-rp-6x-streams/config-template.yml ./my-config.yml

  1. 使用您的特定设置修改 my-config.yml

vi my-config.yml

  1. 设置环境变量。

  • 与 config-template 文件类似，您可以从 config-template-examples 文件夹复制示例 env 文件

  • 使用您的特定设置修改环境变量文件

cp config-template-examples/llm-ov-3d-rp-6x-streams/my-config.env my-env-file.env
vi my-env-file.env

  1. Source 环境变量文件

source my-env-file.env

  1. 运行安装命令

./envbuild.sh install --component all --config-file ./my-config.yml

  1. 在日志末尾捕获安装结果。输出将如下面的示例所示。

access_urls:
  api_endpoint: "https://<api_sub_domain>.<base_domain>"
  elasticsearch_endpoint: "https://elastic-<name>.<base_domain>"
  grafana_endpoint: "https://grafana-<name>..<base_domain>"
  kibana_endpoint: "https://kibana-<name>..<base_domain>"
  ui_endpoint: "https://<ui_sub_domain>.<base_domain>"
ssh_command:
app:
  bastion: ssh -i /home/my-user/.ssh/id_rsa -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null <username>@<bastion-instance-ip-address>
  master: ssh -i /home/my-user/.ssh/id_rsa -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -o ProxyCommand="ssh -i /home/my-user/.ssh/id_rsa -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -W %h:%p <username>@<bastion-instance-ip-address>" <username>@<app-instance-ip-address>
turn:
  master: ssh -i /home/my-user/.ssh/id_rsa -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null <username>@<turn-instance-ip-address>

  1. 验证安装

  • 检查 pod 状态：kubectl get pods \-n \<application-namespace\>

  • 等待所有 pod 达到 Ready 状态（可能需要长达 60 分钟）

  • 一旦所有 pod 运行状况良好，您可以使用安装输出中的 URL access_urls.ui_endpoint 访问 UI

  • 首次打开时，浏览器应提示 UI 运行所需的麦克风、扬声器或摄像头等权限。接受权限后，UI 应加载。

Verify Installation

卸载步骤#

仅卸载应用程序#

  • Source 正确的环境变量文件

source my-env-file.env

  • 运行以下命令以仅卸载应用程序组件

./envbuild.sh uninstall --component app --config-file ./my-config.yml

  • 通过以下命令清除先前安装中的任何 persistent-volumes

kubectl delete pv -n <application-namespace>

卸载整个设置#

  • Source 正确的环境变量文件

source my-env-file.env

  • 运行以下卸载命令

./envbuild.sh uninstall --component all --config-file ./my-config.yml

警告

此步骤将卸载整个 Kubernetes 集群，以及在安装步骤中启动的 GCP 基础设施资源。因此请谨慎使用。

准备环境变量#

config template yml 文件包含有关基础设施和应用程序需求的多个输入。为了方便使用，其中一些已连接到查找环境变量。例如 {{ lookup(‘env’, ‘NGC_CLI_API_KEY’) }} 正在将其扩展到 NGC_CLI_API_KEY 环境变量。这意味着，我们可以为 NGC_CLI_API_KEY 设置一个环境变量及其值，并且 OneClick 脚本可以自动访问它。

通过 vi my-env-file.env 准备一个文件来保存这些环境变量及其值，并使用实际值填充它们。示例如下所示。

cat my-env-file.env
export OPENAI_API_KEY="<replace-with-actual-value>"
export NGC_CLI_API_KEY="<replace-with-actual-value>"
export NVIDIA_API_KEY="<replace-with-actual-value>"
export CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE="<replace-with-absolute-path-where-service-account-key-json-file-stored>"
export CLOUDSDK_CORE_PROJECT="<replace-with-gcp-project-id>"

使用 source 命令将这些变量加载到您当前的 shell 会话中。source 命令读取并执行当前 shell 环境中指定文件中的命令，使文件中定义的变量在 shell 中可用。

警告

如果您修改了 <my-env-file.env> 文件或启动了新的 shell，您将必须在运行 ./envbuild.sh 命令之前再次运行 source <my-env-file.env>。

其他注意事项#

成本#

此设置中的许多资源可能会超出 GCP 免费层级限制。查看 GCP 免费计划条款以更好地理解。并且，使用 GCP 价格计算器估算超出免费层级限制的成本。通过 Cloud Billing 控制台监控使用情况，并设置预算和警报以避免意外费用。

安全#

Tokkio 在生产环境中的安全性由部署它的最终用户负责。在生产环境中部署时，请让安全专家审查任何潜在的风险和威胁；定义信任边界，保护通信通道，集成 AuthN & AuthZ 和适当的访问控制，保持部署（包括容器）为最新，并确保容器安全且没有漏洞。

基本技能和背景#

熟悉 Google Cloud Platform (GCP)#

用户应基本了解 Google Cloud Platform，包括其核心服务和计费模型。以下是用户应熟悉的一些关键领域。

  • 资源管理：了解 GCP 的资源层次结构，包括组织、文件夹和项目，对于有效的成本管理和访问控制至关重要。

  • 身份和访问管理 (IAM)：熟悉 IAM 角色和权限对于保护资源和管理用户访问权限至关重要。

  • 核心服务：了解基本的 GCP 服务，如 Compute Engine、Cloud Storage，非常重要。

  • Cloud Console：熟悉 GCP 的管理图形界面是资源配置和管理所必需的，特别是对于设置一次性先决条件。

  • 网络：基本了解虚拟私有云 (VPC) 和相关的网络概念非常重要。

熟悉命令行界面 (CLI)#

  • 基本命令：用户应熟练掌握基本的命令行操作，例如导航目录、执行脚本和管理文件。

  • 环境配置：了解环境变量以及 PATH 设置在 Linux 上的工作方式将极大地帮助操作 OneClick 脚本。

  • 脚本编写基础知识：基本的脚本编写知识（例如，shell 脚本编写）对于理解 OneClick 脚本的运行方式以及排除可能出现的任何问题非常有益。

熟悉 YAML#

  • YAML 语法和结构：YAML 由于其可读性和灵活性，通常用于云原生应用程序中的配置文件。部署脚本中使用的配置模板使用 YAML 格式。用户应熟悉 YAML 语法和结构。

熟悉 Kubernetes 生态系统#

Tokkio 管线是一个云原生应用程序，并使用容器化、Kubernetes、helm 等概念。用户需要熟悉这些概念才能从使用部署脚本和应用程序中获得最佳结果。

  • Kubernetes 基础知识：用户应基本了解 Kubernetes 核心概念，例如 pod、服务和部署

  • kubectl：熟悉 kubectl 命令行工具，该工具用于与 Kubernetes 集群交互，包括查询正在运行的应用程序 pod 的状态或日志等。

  • Helm：了解 Kubernetes 的 Helm 包管理器，它通过管理 chart（预配置的 Kubernetes 资源定义的集合）简化了应用程序部署。以及如何将 helm 与覆盖值一起使用将有助于正确配置模板。

在本页中