使用交互式 shell 监控和调试训练

本页面介绍如何使用交互式 shell 检查运行训练代码的容器。您可以浏览文件系统，并在 Vertex AI 上运行的每个预构建容器或自定义容器中运行调试实用程序。

使用交互式 shell 检查训练容器可帮助您调试训练代码或 Vertex AI 配置相关的问题。例如，您可以使用交互式 shell 执行以下操作：

运行跟踪和剖析工具。
分析 GPU 使用情况。
查看容器可用的 Google Cloud 权限。

您还可以使用 Cloud Profiler 调试自定义训练作业的模型训练性能。如需了解详情，请参阅使用 Profiler 分析模型训练性能。

准备工作

使用 CustomJob 资源、HyperparameterTuningJob 资源或自定义 TrainingPipeline 资源执行自定义训练时，您可以使用交互式 shell。准备训练代码和配置自定义训练资源时，请务必满足以下要求：

确保训练容器已安装 bash。

所有预构建训练容器都安装了 bash。如果您创建自定义容器进行训练，请使用包含 bash 的基础容器或在 Dockerfile 中安装 bash。
在支持交互式 shell 的区域中执行自定义训练。
确保想要访问交互式 Shell 的任何人都拥有正在运行自定义训练的 Google Cloud 项目的以下权限：
- aiplatform.customJobs.create
- aiplatform.customJobs.get
- aiplatform.customJobs.cancel
如果您自行启动自定义训练，则您很可能已具有这些权限，并可以访问交互式 shell。但是，如果要使用交互式 shell 检查组织中其他人创建的自定义训练资源，则可能需要获取这些权限。

获取这些权限的一种方法是要求组织管理员授予您 Vertex AI User 角色 (roles/aiplatform.user)。

高级案例的要求

如果您使用的是特定高级功能，请满足以下额外要求：

如果您为自定义训练资源附加自定义服务账号，请确保任何想要访问交互式 Shell 的用户都具有所附加的服务账号的 iam.serviceAccounts.actAs 权限。

自定义服务账号指南指明了您必须拥有此权限才能附加服务账号。此外，必须具有此权限才能在自定义训练期间查看交互式 Shell。

例如，如需使用附加的服务账号创建 CustomJob，必须具有该服务账号的 iam.serviceAccounts.actAs 权限。如果您的某个同事随后想要查看此 CustomJob 的交互式 Shell，则他们还必须具有相同的 iam.serviceAccounts.actAs 权限。
如果您已将项目配置为将 VPC Service Controls 与 Vertex AI 搭配使用，则需要考虑以下额外限制：
- 您无法使用专用 IP 进行自定义训练。如果您需要使用 VPC-SC 和 VPC 对等互连，则需要进行额外的设置才能使用交互式 Shell。按照使用 VPC-SC + VPC 对等互连的 Ray 信息中心和交互式 Shell 中的说明，在您的用户项目中使用 VPC-SC 和 VPC 对等互连配置交互式 Shell 设置。
- 在交互式 shell 中，您无法访问公共互联网或服务边界外的 Google Cloud 资源。
- 如需保护对交互式 Shell 的访问，除了 aiplatform.googleapis.com 之外，您还必须在服务边界内添加 notebooks.googleapis.com 作为受限服务。如果您仅限制 aiplatform.googleapis.com 而不限制 notebooks.googleapis.com，则用户可以从服务边界外的机器访问交互式 Shell，从而降低使用 VPC Service Controls 时的安全优势。
  
  注意：总体而言，我们建议您在创建服务边界时限制所有服务。请按照 VPC Service Controls 指南创建服务边界。

启用交互式 shell

要为自定义训练资源启用交互式 shell，请在创建 CustomJob、HyperparameterTuningJob 或自定义 TrainingPipeline 时将 enableWebAccess API 字段设置为 true。

以下示例展示了如何使用多种不同的工具执行此操作：

控制台

按照指南在 Google Cloud 控制台中创建自定义 TrainingPipeline。在训练新模型窗格中，当您到达模型详情步骤时，请执行以下操作：

点击高级选项。
选中启用训练调试功能复选框。

然后，完成训练新模型工作流的其余部分。

gcloud

如果要创建 CustomJob，请运行 gcloud ai custom-jobs create 命令，并在此命令中指定 --enable-web-access 标志。
如果要创建 HyperparameterTuningJob，请运行 gcloud ai hp-tuning-jobs create 命令，并在此命令中指定 --enable-web-access 标志。

如需了解如何使用这些命令，请参阅创建 CustomJob 指南和创建 HyperparameterTuningJob 指南。

API

以下部分 REST 请求正文显示了如何为每种类型的自定义训练资源指定 enableWebAccess 字段：

CustomJob

以下示例是 projects.locations.customJobs.create API 方法的部分请求正文：

{
  ...
  "jobSpec": {
    ...
    "enableWebAccess": true
  }
  ...
}

如需查看发送 API 请求以创建 CustomJob 的示例，请参阅创建自定义训练作业。

HyperparameterTuningJob

以下示例是 projects.locations.hyperparameterTuningJobs.create API 方法的部分请求正文：

{
  ...
  "trialJobSpec": {
    ...
    "enableWebAccess": true
  }
  ...
}

如需查看发送 API 请求以创建 HyperparameterTuningJob 的示例，请参阅使用超参数调节。

自定义 TrainingPipeline

以下示例展示了 projects.locations.trainingPipelines.create API 方法的部分请求正文。根据是否要使用超参数调节功能，选择以下标签页之一：

不使用超参数调节

{
  ...
  "trainingTaskInputs": {
    ...
    "enableWebAccess": true
  }
  ...
}

使用超参数调节

{
  ...
  "trainingTaskInputs": {
    ...
    "trialJobSpec": {
      ...
      "enableWebAccess": true
    }
  }
  ...
}

如需查看发送 API 请求以创建自定义 TrainingPipeline 的示例，请参阅创建训练流水线。

Python

如需了解如何安装或更新 Vertex AI SDK for Python，请参阅安装 Vertex AI SDK for Python。如需了解详情，请参阅 Python API 参考文档。

运行以下方法之一时，将 enable_web_access 参数设置为 true：

如果您要创建 CustomJob，请使用 CustomJob.run 方法。
如果您要创建 HyperparameterTuningJob，请使用 HyperparameterTuningJob.run 方法。
如果要创建自定义 TrainingPipeline，请使用以下方法之一：

打开交互式 Shell

根据上一部分中的说明启动自定义训练后，Vertex AI 会生成一个或多个 URI，您可以使用这些 URI 来访问交互式 shell。Vertex AI 会为作业中的每个训练节点生成唯一的 URI。

您可以通过以下任一方式导航到交互式 shell：

点击 Google Cloud 控制台中的链接
使用 Vertex AI API 获取 shell 的网络访问 URI

从 Google Cloud 控制台导航

在 Google Cloud 控制台的 Vertex AI 部分中，转到以下页面之一：
- 如果您没有使用超参数调节，请转到自定义作业页面：
  
  打开“自定义作业”
- 如果您使用的是超参数微调，请转到超参数微调作业页面：
  
  转到“超参数调节作业”
点击自定义训练资源的名称。

如果您为自定义训练创建了 TrainingPipeline，请点击 TrainingPipeline 创建的 CustomJob 或 HyperparameterTuningJob 的名称。例如，如果您的流水线名为 PIPELINE_NAME，则该名称可能为 PIPELINE_NAME-custom-job 或 PIPELINE_NAME-hyperparameter-tuning-job。
在作业页面上，点击启动网络终端。如果您的作业使用多个节点，请点击要使用交互式 shell 的节点旁边的启动网络终端。

请注意，您只能在作业运行时访问交互式 shell。如果没有看到启动网络终端，可能是因为 Vertex AI 尚未开始运行作业，或者作业已完成或失败。如果作业的状态是 Queued 或 Pending，请稍等片刻，然后尝试刷新页面。

如果您使用的是超参数调节，则每个试验都有单独的启动网络终端链接。

从 API 获取 Web 访问 URI

使用 projects.locations.customJobs.get API 方法或 projects.locations.hyperparameterTuningJobs.get API 方法查看您可以用来访问 shell 的 URI。

根据您使用的自定义训练资源类型，选择以下标签页之一以查看有关如何查找 webAccessUris API 字段的示例，其中包含作业中每个节点的交互式 shell URI：

CustomJob

以下标签页显示了发送 projects.locations.customJobs.get 请求的不同方式：

gcloud

运行 gcloud ai custom-jobs describe 命令：

gcloud ai custom-jobs describe JOB_ID \
  --region=LOCATION \
  --format=json

替换以下内容：

JOB_ID：作业的数字 ID。此 ID 是作业的 name 字段的最后一部分。您在创建作业时可能已看到该 ID。（如您不知道作业 ID，则可以运行 gcloud ai custom-jobs list 命令并查找相应的作业。）
LOCATION：您在其中创建作业的区域。

REST

在使用任何请求数据之前，请先进行以下替换：

LOCATION：您在其中创建作业的区域。
PROJECT_ID：您的项目 ID。
JOB_ID：作业的数字 ID。此 ID 是作业的 name 字段的最后一部分。您在创建作业时可能已看到该 ID。

HTTP 方法和网址：

GET https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/customJobs/JOB_ID

如需发送您的请求，请展开以下选项之一：

curl（Linux、macOS 或 Cloud Shell）

执行以下命令：

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/customJobs/JOB_ID"

PowerShell (Windows)

执行以下命令：

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/customJobs/JOB_ID" | Select-Object -Expand Content

在输出中，查找以下内容：

{
  ...
  "state": "JOB_STATE_RUNNING",
  ...
  "webAccessUris": {
    "workerpool0-0": "INTERACTIVE_SHELL_URI"
  }
}

如果您没有看到 webAccessUris 字段，可能是因为 Vertex AI 尚未开始运行您的作业。验证您是否在 state 字段中看到 JOB_STATE_RUNNING。如果状态为 JOB_STATE_QUEUED 或 JOB_STATE_PENDING，请稍等片刻，然后再次尝试获取项目信息。

HyperparameterTuningJob

以下标签页显示了发送 projects.locations.hyperparameterTuningJobs.get 请求的不同方式：

gcloud

运行 gcloud ai hp-tuning-jobs describe 命令：

gcloud ai hp-tuning-jobs describe JOB_ID \
  --region=LOCATION \
  --format=json

替换以下内容：

JOB_ID：作业的数字 ID。此 ID 是作业的 name 字段的最后一部分。您在创建作业时可能已看到该 ID。（如您不知道作业 ID，则可以运行 gcloud ai hp-tuning-jobs list 命令并查找相应的作业。）
LOCATION：您在其中创建作业的区域。

REST

在使用任何请求数据之前，请先进行以下替换：

LOCATION：您在其中创建作业的区域。
PROJECT_ID：您的项目 ID。
JOB_ID：作业的数字 ID。此 ID 是作业的 name 字段的最后一部分。您在创建作业时可能已看到该 ID。

HTTP 方法和网址：

GET https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/hyperparameterTuningJobs/JOB_ID

如需发送您的请求，请展开以下选项之一：

curl（Linux、macOS 或 Cloud Shell）

执行以下命令：

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/hyperparameterTuningJobs/JOB_ID"

PowerShell (Windows)

执行以下命令：

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/hyperparameterTuningJobs/JOB_ID" | Select-Object -Expand Content

在输出中，查找以下内容：

{
  ...
  "state": "JOB_STATE_RUNNING",
  ...
  "trials": [
    ...
    {
      ...
      "state": "ACTIVE",
      ...
      "webAccessUris": {
        "workerpool0-0": "INTERACTIVE_SHELL_URI"
      }
    }
  ],
}

当试用进入 ACTIVE 状态时，Vertex AI 会为每次超参数调节试用提供一组交互式 Shell URI。如果您希望获取用于之后试用的交互式 shell URI，请在这些试用开始后再次获取作业信息。

上述示例显示了单副本训练的预期输出：主训练节点的一个 URI。如果您要执行分布式训练，则输出会为每个训练节点包含一个 URI（由工作器池标识）。

例如，如果作业拥有一个具有一个副本的主要工作器池和一个具有两个副本的辅助工作器池，则 webAccessUris 字段如下所示：

{
  "workerpool0-0": "URI_FOR_PRIMARY",
  "workerpool1-0": "URI_FOR_FIRST_SECONDARY",
  "workerpool1-1": "URI_FOR_SECOND_SECONDARY"
}

使用交互式 shell

如需将交互式 shell 用于训练节点，请导航到您在上一部分中找到的其中一个 URI。Bash shell 显示在浏览器中，让您能够访问 Vertex AI 在其中运行训练代码的容器的文件系统。

以下部分介绍了您在使用 shell 时需要考虑的一些事项，并提供了一些可以在 shell 中使用的监控工具示例。

防止作业结束

当 Vertex AI 运行完您的作业或试用时，您将立即失去对交互式 shell 的访问权限。如果发生这种情况，您可能会看到消息 command terminated with exit code 137，或者 shell 可能会停止响应。如果您在容器的文件系统中创建了任何文件，则作业结束后，这些文件将不会保留。

在某些情况下，您可能希望故意延长作业运行时间，以便使用交互式 shell 进行调试。例如，您可以将如下所示的代码添加到训练代码中，以便让作业在异常发生后至少继续运行一小时：

import time
import traceback

try:
    # Replace with a function that runs your training code
    train_model()
except Exception as e:
    traceback.print_exc()
    time.sleep(60 * 60)  # 1 hour

但请注意，只要作业继续运行，您就需要支付 Vertex AI Training 费用。

检查权限问题

交互式 Shell 环境使用 Vertex AI 用于运行训练代码的服务账号的应用默认凭据 (ADC) 进行身份验证。如需了解详情，您可以在 shell 中运行 gcloud auth list。

在 Shell 中，您可以使用 bq 和其他支持 ADC 的工具。这可以帮助您验证作业是否能够访问训练代码所需的特定 Cloud Storage 存储桶、BigQuery 表或其他 Google Cloud 资源。

使用 `py-spy` 直观呈现 Python 的执行

通过 py-spy，您可以剖析正在执行的 Python 程序，而无需进行修改。如需在交互式 shell 中使用 py-spy，请执行以下操作：

安装 py-spy：
```
pip3 install py-spy
```
在 shell 中运行 ps aux，并查找 Python 训练程序的 PID。
使用您在上一步中找到的 PID 运行 py-spy 文档中描述的任何子命令。
如果您使用 py-spy record 创建 SVG 文件，请将此文件复制到 Cloud Storage 存储桶，以便稍后在本地计算机上查看。例如：
```
gcloud storage cp profile.svg gs://BUCKET
```
将 BUCKET 替换为您有权访问的存储桶的名称。

使用 `perf` 分析性能

perf 可让您分析训练节点的性能。如需安装适合节点 Linux 内核的 perf 版本，请运行以下命令：

apt-get update
apt-get install -y linux-tools-generic
rm /usr/bin/perf
LINUX_TOOLS_VERSION=$(ls /usr/lib/linux-tools | tail -n 1)
ln -s "/usr/lib/linux-tools/${LINUX_TOOLS_VERSION}/perf" /usr/bin/perf

之后，您可以运行 perf 文档中介绍的任意子命令。

检索有关 GPU 使用情况的信息

在具有 GPU 的节点上运行的支持 GPU 的容器通常预装了几个命令行工具，可以帮助您监控 GPU 使用情况。例如：

使用 nvidia-smi 监控各种进程的 GPU 利用率。
使用 nvprof 收集各种 GPU 剖析信息。由于 nvprof 无法附加到现有进程，因此您可能需要使用该工具启动运行训练代码的其他进程。（这意味着您的训练代码将在节点上运行两次。）例如：
```
nvprof -o prof.nvvp python3 -m MODULE_NAME
```
将 MODULE_NAME 替换为训练应用的入口点模块的完全限定名称；例如 trainer.task。

然后将输出文件转移到 Cloud Storage 存储桶，以便稍后在本地计算机上进行分析。例如：
```
gcloud storage cp prof.nvvp gs://BUCKET
```
将 BUCKET 替换为您有权访问的存储桶的名称。
如果遇到 GPU 错误（不是配置或 Vertex AI 问题），请使用 nvidia-bug-report.sh 创建错误报告。

然后将报告转移到 Cloud Storage 存储桶，以便稍后在本地计算机上分析或将其发送到 NVIDIA。例如：
```
gcloud storage cp nvidia-bug-report.log.gz gs://BUCKET
```
将 BUCKET 替换为您有权访问的存储桶的名称。

如果 bash 找不到上述任何 NVIDIA 命令，请尝试将 /usr/local/nvidia/bin 和 /usr/local/cuda/bin 添加到 shell 的 PATH：

export PATH="/usr/local/nvidia/bin:/usr/local/cuda/bin:${PATH}"

使用 VPC-SC + VPC 对等互连的 Ray 信息中心和交互式 Shell

配置 peered-dns-domains。

{
  VPC_NAME=NETWORK_NAME
  REGION=LOCATION
  gcloud services peered-dns-domains create training-cloud \
  --network=$VPC_NAME \
  --dns-suffix=$REGION.aiplatform-training.cloud.google.com.

  # Verify
  gcloud beta services peered-dns-domains list --network $VPC_NAME);
}

NETWORK_NAME：更改为对等互连的网络。
LOCATION：所需位置（例如 us-central1）。

配置 DNS managed zone。

{
  PROJECT_ID=PROJECT_ID
  ZONE_NAME=$PROJECT_ID-aiplatform-training-cloud-google-com
  DNS_NAME=aiplatform-training.cloud.google.com
  DESCRIPTION=aiplatform-training.cloud.google.com

  gcloud dns managed-zones create $ZONE_NAME  \
  --visibility=private  \
  --networks=https://www.googleapis.com/compute/v1/projects/$PROJECT_ID/global/networks/$VPC_NAME  \
  --dns-name=$DNS_NAME  \
  --description="Training $DESCRIPTION"
}

PROJECT_ID：您的项目 ID。您可以在 Google Cloud 控制台的欢迎页面中找到这些 ID。

记录 DNS 事务。

{
  gcloud dns record-sets transaction start --zone=$ZONE_NAME

  gcloud dns record-sets transaction add \
  --name=$DNS_NAME. \
  --type=A 199.36.153.4 199.36.153.5 199.36.153.6 199.36.153.7 \
  --zone=$ZONE_NAME \
  --ttl=300

  gcloud dns record-sets transaction add \
  --name=*.$DNS_NAME. \
  --type=CNAME $DNS_NAME. \
  --zone=$ZONE_NAME \
  --ttl=300

  gcloud dns record-sets transaction execute --zone=$ZONE_NAME
}

提交已启用交互式 Shell 和 VPC-SC 以及 VPC 对等互连的训练作业。

后续步骤

了解如何使用 Profiler 优化自定义训练作业的性能。
详细了解 Vertex AI 如何编排自定义训练。
了解训练代码要求。

使用交互式 shell 监控和调试训练

准备工作

高级案例的要求

启用交互式 shell

控制台

gcloud

API

CustomJob

HyperparameterTuningJob

自定义 TrainingPipeline

不使用超参数调节

使用超参数调节

Python

打开交互式 Shell

从 Google Cloud 控制台导航

从 API 获取 Web 访问 URI

CustomJob

gcloud

REST

curl（Linux、macOS 或 Cloud Shell）

PowerShell (Windows)

HyperparameterTuningJob

gcloud

REST

curl（Linux、macOS 或 Cloud Shell）

PowerShell (Windows)

使用交互式 shell

防止作业结束

检查权限问题

使用 py-spy 直观呈现 Python 的执行

使用 perf 分析性能

检索有关 GPU 使用情况的信息

使用 VPC-SC + VPC 对等互连的 Ray 信息中心和交互式 Shell

后续步骤

使用 `py-spy` 直观呈现 Python 的执行

使用 `perf` 分析性能