AI Workbench 项目规范#

每个AI Workbench 项目都包含一个名为 spec.yaml 的规范文件，用于定义和配置项目。该规范文件包含有关项目的信息，例如名称、描述、容器镜像、软件包和应用程序。AI Workbench 读取规范文件，并使用这些信息为项目构建和运行容器化的开发环境。

使用本文档了解以下内容

示例 AI Workbench 项目规范文件#

以下是 AI Workbench 项目 spec.yaml 文件的示例。

  1specVersion: v2
  2specMinorVersion: 1
  3meta:
  4  name: example-project
  5  image: project-example-project
  6  description: An example project using PyTorch
  7  labels: []
  8  createdOn: "2024-01-04T23:32:17Z"
  9  defaultBranch: main
 10layout:
 11- path: code/
 12  type: code
 13  storage: git
 14- path: models/
 15  type: models
 16  storage: gitlfs
 17- path: data/
 18  type: data
 19  storage: gitlfs
 20- path: data/scratch/
 21  type: data
 22  storage: gitignore
 23environment:
 24  base:
 25    registry: nvcr.io
 26    image: nvidia/ai-workbench/pytorch:1.0.2
 27    build_timestamp: "20231212000523"
 28    name: PyTorch
 29    supported_architectures: []
 30    cuda_version: "12.2"
 31    description: A Pytorch 2.1 environment with CUDA 12.2
 32    entrypoint_script: ""
 33    labels:
 34    - cuda12.2
 35    - pytorch2.1
 36    apps:
 37    - name: jupyterlab
 38      type: jupyterlab
 39      class: webapp
 40      start_command: jupyter lab --allow-root --port 8888 --ip 0.0.0.0 --no-browser
 41        --NotebookApp.base_url=\$PROXY_PREFIX --NotebookApp.default_url=/lab --NotebookApp.allow_origin='*'
 42      health_check_command: '[ \$(echo url=\$(jupyter lab list | head -n 2 | tail
 43        -n 1 | cut -f1 -d'' '' | grep -v ''Currently'' | sed "s@/?@/lab?@g") | curl
 44        -o /dev/null -s -w ''%{http_code}'' --config -) == ''200'' ]'
 45      timeout_seconds: 90
 46      stop_command: jupyter lab stop 8888
 47      user_msg: ""
 48      icon_url: ""
 49      webapp_options:
 50        autolaunch: true
 51        port: "8888"
 52        proxy:
 53          trim_prefix: false
 54        url_command: jupyter lab list | head -n 2 | tail -n 1 | cut -f1 -d' ' | grep
 55          -v 'Currently'
 56    - name: tensorboard
 57      type: tensorboard
 58      class: webapp
 59      start_command: tensorboard --logdir \$TENSORBOARD_LOGS_DIRECTORY --path_prefix=\$PROXY_PREFIX
 60        --bind_all
 61      health_check_command: '[ \$(curl -o /dev/null -s -w ''%{http_code}'' https://127.0.0.1:\$TENSORBOARD_PORT\$PROXY_PREFIX/)
 62        == ''200'' ]'
 63      timeout_seconds: 90
 64      stop_command: ""
 65      user_msg: ""
 66      icon_url: ""
 67      webapp_options:
 68        autolaunch: true
 69        port: "6006"
 70        proxy:
 71          trim_prefix: false
 72        url: https://127.0.0.1:6006
 73    programming_languages:
 74    - python3
 75    icon_url: ""
 76    image_version: 1.0.3
 77    os: linux
 78    os_distro: ubuntu
 79    os_distro_release: "22.04"
 80    schema_version: v2
 81    user_info:
 82      uid: "1001"
 83      gid: "1001"
 84      username: "appuser"
 85    package_managers:
 86    - name: apt
 87      binary_path: /usr/bin/apt
 88      installed_packages:
 89      - curl
 90      - git
 91      - git-lfs
 92      - vim
 93    - name: pip
 94      binary_path: /usr/local/bin/pip
 95      installed_packages:
 96      - jupyterlab==4.0.7
 97    package_manager_environment:
 98      name: ""
 99      target: ""
100execution:
101  apps: []
102  resources:
103    gpu:
104      requested: 1
105      sharedMemoryMB: 1024
106  secrets: []
107  mounts:
108  - type: project
109    target: /project/
110    description: project directory
111    options: rw
112  - type: volume
113    target: /data/tensorboard/logs/
114    description: Tensorboard Log Files
115    options: volumeName=tensorboard-logs-volume

AI Workbench 项目规范定义#

项目元数据#

规范文件包括项目元数据，例如版本、名称、描述和目录结构。以下是项目元数据字段。

字段

描述

用法示例

specVersion

当前项目规范的架构版本号。

 
1specVersion: v2

specMinorVersion

当前项目规范的架构次版本号。

 
1specMinorVersion: 1

meta

项目元数据，用于在 AI Workbench 应用程序中正确显示。

—

meta.name

项目的名称。

 
1name: hello-world

meta.image

项目容器镜像的名称。此镜像名称在计算机本地，不会推送到容器注册表。

 
1image: project-hello-world

meta.description

项目的描述。

 
1description: An example project using PyTorch

meta.labels

项目的标签列表。

—

meta.createdOn

项目创建时间，格式为 RFC 3339 字符串。

 
1createdOn: "2024-01-04T23:32:17Z"

meta.defaultBranch

项目的默认 Git 分支。

 
1defaultBranch: main

layout

有关项目目录的信息列表。AI Workbench 使用此信息来协调配置，例如通过向 .gitignore 或 .gitattributes 文件添加路径。

  • path 是相对于存储库根目录的项目目录。

  • type 是目录中内容的类型。有效值为 code、data、model。

  • storage 是目录中数据的存储方式。有效值为 git、gitlfs、gitignore。

 
1layout:
2  - path: data/scratch/
3    type: data
4    storage: gitignore

项目环境信息#

规范文件包括环境信息，例如项目的容器镜像以及其中安装的其他软件包。您可以手动配置规范的此部分，但通常情况下，它会从您创建项目时选择的环境镜像的标签自动填充。

警告

当环境版本更新时，对 spec.yaml 文件的 environment.base 部分中的数据进行的任何手动修改都将被覆盖。

在规范文件的 environment 部分中，所有字段都是 base 字段的子字段。

1environment:
2  base:
3    ... all fields

以下是 environment.base 字段。

字段

描述

用法示例

registry

具有镜像的容器注册表。

 
1registry: nvcr.io

image

项目容器在其之上构建的容器镜像。

 
1image: nvidia/pytorch:23.12-py3

build_timestamp

上次镜像构建的时间戳。对于时间戳，请指定年、月、日、小时、分钟、秒。

 
1build_timestamp: "20231212000523"

name

容器的名称。

 
1name: PyTorch

supported_architectures

镜像兼容的受支持架构列表。

 
1supported_architectures:
2
3  - "amd64"
4  - "arm64"

cuda_version

环境中安装的 CUDA 版本（如果适用）。此字段告诉 AI Workbench 主机驱动程序必须支持的 CUDA 版本。如果此值未正确设置，您可能会遇到运行时错误，而 AI Workbench 在启动容器时未能发出警告。

 
1cuda_version: "12.2"

description

容器的描述。

 
1description: A Pytorch 2.1 environment with CUDA 12.2

entrypoint_script

项目容器启动时运行的脚本的路径。

 
1entrypoint_script: /path/to/script.sh

labels

容器的标签列表，例如搜索词关键字或描述符。

 
1labels:
2  - cuda12.2
3  - pytorch2.1
4  - python3
5  - jupyterlab

apps

容器中安装的应用程序列表。有关 apps 中字段的定义，请参阅项目应用程序信息。

 
1apps:
2- name: jupyterlab
3  ... more fields
4- name: tensorboard
5  ... more fields

programming_languages

容器中安装的编程语言列表。

 
1programming_languages:
2  - python3

icon_url

容器的图标或图像的链接。

 
1icon_url: https://my-website.com/my-image.png

image_version

容器镜像的版本号（如果有）。

 
1image_version: 1.0.3

os

容器操作系统的名称。

 
1os: linux

os_distro

容器操作系统发行版的名称。

 
1os_distro: ubuntu

os_distro_release

容器操作系统发行版的发行版本。

 
1os_distro_release: "22.04"

schema_version

AI Workbench 当前读取的容器标签架构版本的元数据。

 
1schema_version: v2

user_info

有关容器进程应以哪个用户身份运行的信息。

 
1user_info:
2  uid: "1001"
3  gid: "1001"
4  username: "appuser"

package_managers

容器中安装的软件包管理器列表，以及每个软件包管理器的可选已安装软件包列表。

 
 1package_managers:
 2- name: conda
 3  binary_path: /opt/conda/bin/conda
 4  installed_packages:
 5  - python=3.9.18
 6  - pip
 7- name: apt
 8  binary_path: /usr/bin/apt
 9  installed_packages:
10  - ca-certificates
11  - curl
12- name: pip
13  binary_path: /opt/conda/bin/pip
14  installed_packages: []

package_manager_environment

应在安装软件包和启动应用程序之前激活的软件包管理器环境。如果您的容器在构建时使用虚拟环境或 conda，则此功能很有用。

 
1package_manager_environment:
2  name: ""
3  target: ""

项目应用程序信息#

规范文件包括有关环境中安装的应用程序和自定义应用程序的信息，例如运行它们的命令和参数。以下是应用程序信息字段。

字段

描述

用法示例

name

应用程序的名称。此名称显示在用户界面中。

 
1name: jupyterlab

type

应用程序的类型，用于确定运行哪些特定于应用程序的自动化。

 
1type: jupyterlab

class

应用程序的类别，用于确定哪些可选配置选项可用。有效值为 webapp、process 和 native。

 
1class: webapp

start_command

用于启动应用程序的 shell 命令。不得是阻塞命令。

 
1start_command: jupyter lab...

health_check_command

用于检查应用程序的运行状况或状态的 shell 命令。返回零表示应用程序正在运行且运行状况良好。返回非零表示应用程序未运行或运行状况不佳。

 
1health_check_command: '<code>'

timeout_seconds

AI Workbench 等待 health_check_command 完成的秒数。有效值大于 0 且小于 3600。默认值为 60。

 
1timeout_seconds: 90

stop_command

用于停止应用程序的 shell 命令。

 
1stop_command: jupyter lab stop 8888

user_msg

应用程序运行时向用户显示的可选消息。如果 class 为 webapp，则可以在消息中使用占位符字符串 {{URL}}，并在应用程序启动后填充该字符串。

 
1user_msg: ""

icon_url

用于应用程序的图标或图像的可选链接。

 
1icon_url: ""

webapp_options

如果 class 为 webapp，则以下选项可用。

  • autolaunch - 如果 AI Workbench 应自动为用户打开应用程序 URL，则为 True；否则为 false。

  • port - 应用程序在其上运行的端口。

  • proxy - 如果指定，则包括 trim_prefix - 如果 AI Workbench 反向代理应在将请求转发到应用程序之前删除特定于应用程序的 Url 前缀，则为 True；否则为 false。

  • url - 用于访问应用程序的静态 URI。

  • 或者 url_command - 用于获取应用程序 URI 的 shell 命令。此命令的输出被视为 URL。

如果 class 为 process，则以下选项可用。

  • wait_until_finished - 如果 AI Workbench 桌面应用程序应等待应用程序完成，则为 True；如果桌面应用程序应让其在后台运行，则为 false。如果 true，则桌面应用程序会在进程完成时通知您。CLI 始终等待。

 
1webapp_options:
2  autolaunch: true
3  port: "8888"
4  proxy:
5    trim_prefix: false
6  url_command: <your command>

1webapp_options:
2  autolaunch: true
3  port: "6006"
4  proxy:
5    trim_prefix: false
6  url: https://127.0.0.1:6006

1process_options:
2  wait_until_finished: true

项目运行时信息#

规范文件包括运行时信息，例如环境变量、要挂载在容器中的 GPU 数量以及自定义应用程序信息。以下是运行时信息字段。

字段

描述

用法示例

execution

有关如何运行项目的信息。

—

execution.apps

项目中安装的自定义应用程序列表，这些应用程序不是容器环境的一部分。有关 apps 中字段的定义，请参阅项目应用程序信息。

 
1apps:
2- name: jupyterlab
3  ... more fields
4- name: mychat
5  ... more fields

execution.resources

运行项目请求或需要的主机资源。

  • gpu 是请求的 GPU 数量。如果没有任何 GPU 可用，则可以启动不带任何 GPU 的项目。

  • sharedMemoryMB 是要分配给项目容器的共享内存量（以 MB 为单位）。

有关详细信息，请参阅硬件。

 
1resources:
2  gpu:
3    requested: 0
4  sharedMemoryMB: 0

execution.secrets

要在项目启动前设置的敏感环境变量列表。仅指定每个变量的名称和描述。每个变量的值不是规范文件的一部分，而是在运行时配置的。有关详细信息，请参阅密钥（敏感环境变量）。

 
1secrets:
2- variable: secret1
3  description: Secret 1

execution.mounts

项目使用的外部文件夹和文件列表，以及它们在项目容器中的位置。配置挂载所需的必填值（如源目录）不是规范文件的一部分，而是在运行时配置的。

  • 对于 type，有效值为 project、host、volume 或 tmp。恰好有一个 project 挂载（否则容器启动失败）。

  • target 是项目容器内的目标位置。目标位置是绝对路径，包括尾部斜杠。

有关详细信息，请参阅AI Workbench 挂载。

 
1mounts:
2  - type: project
3    target: /project/
4    description: project directory
5    options: rw

自定义您的容器#

如果您想更改单个项目的容器环境的行为，您可以手动编辑 spec.yaml 文件中包含的元数据。首先，按照以下描述修改您的 spec.yaml 文件，然后重新构建您的项目环境。

注意

如果您想使用预构建的容器之一并进行简单的自定义，例如添加软件包，请参阅演练：自定义您的环境和环境配置。

如果您想创建完全自定义的容器，以便用于您自己的项目，或者您可以发布并与其他 AI Workbench 用户共享，请参阅使用您自己的容器。这是一个高级场景。

使用以下列表来确定要对规范文件进行的更改。

  • 必需更改 — 必须发生的更改才能自定义项目容器。没有这些更改，您的项目将无法正确构建。

  • 建议更改 — 您应该对项目容器进行的最佳实践更改。这些是 NVIDIA AI Workbench 客户端软件使用的字段。您的项目可能仍然可以构建，组件可能仍然可以运行；但是，您在 AI Workbench UI 中处理项目的体验可能会受到负面影响。

  • 可选更改 — 仅当这些字段与您的项目相关时才更改它们。

要自定义您的容器，请导航到项目的 .project/spec.yaml 文件，并滚动到 environment 部分。使用下表中的信息来编辑您的规范文件。每个字段的完整描述和用法示例都在AI Workbench 项目规范定义中。

字段

更改？

建议操作

registry

必需

指定您感兴趣的容器的容器注册表；如果您有 Dockerfile，您可能需要先构建容器并将其推送到注册表。

image

必需

指定您感兴趣的容器的容器镜像（以及标签，如果有）；如果您有 Dockerfile，您可能需要先构建容器并将其推送到注册表。如果需要，还包括命名空间，但不包括注册表。

build_timestamp

可选

无需手动更新。当您构建环境时，AI Workbench 会更新此字段。

name

必需

指定容器的名称。如果保持不变，AI Workbench 会在 UI 中显示旧的容器信息。

supported_architectures

建议

指定容器支持的架构列表，或者如果不适用，则留空列表。

cuda_version

必需

指定此容器中安装的 CUDA 版本，或者如果不适用，则留空。如果未更新，AI Workbench 会错误地匹配驱动程序。

description

必需

指定容器的简明且信息丰富的描述。如果保持不变，AI Workbench 会在 UI 中显示旧的容器信息。

entrypoint_script

可选

如果您的项目在容器启动时需要任何自定义操作，我们提供了一个您可能想要使用的入口点脚本的位置。在此处指定脚本的位置。

labels

建议

指定要附加到容器旁边的搜索词关键字或标签列表。将这些视为容器的搜索词关键字或描述符。

apps

建议

指定容器中安装的应用程序。有关详细信息，请参阅项目应用程序信息。

programming_languages

建议

指定此容器中安装的编程语言，或者如果不适用，则留空。

icon_url

可选

如果您希望 AI Workbench 显示图标作为此容器的一部分，请在此处链接到图标图像的 URL，或者将其留空以使用默认值。

image_version

建议

指定容器镜像的版本号（如果有）。

os

建议

指定容器操作系统的名称。

os_distro

建议

指定容器操作系统发行版的名称。

os_distro_release

建议

指定容器操作系统发行版的发行版本。

schema_version

可选

无需更新此字段。但是，如果错误，项目会中断。当前版本为 v2。

user_info

建议

当您运行容器时，AI Workbench 会自动为您配置用户，但此字段会覆盖该用户。

package_managers

建议

对于容器中的每个软件包管理器，指定软件包管理器的名称、管理器二进制文件的完整路径以及该管理器安装的软件包的逗号分隔列表。如果此项保持不变，则软件包管理器小部件可能无法正常工作，尤其是在您使用 venv 或 conda 环境时。

package_manager_environment

建议

指定应在安装软件包和启动应用程序之前激活的软件包管理器环境。如果您的容器在构建时使用虚拟环境或 conda，则此功能很有用。
在本页中