为预构建容器创建一个 Python 训练应用

您必须先创建一个包含训练应用的 Python 源分发，并将其上传到您的 Google Cloud 项目可以访问的 Cloud Storage 存储桶，然后才能使用预构建容器执行自定义训练。

创建源分发的替代方案

本指南介绍了如何手动创建源分发并将其上传到 Cloud Storage。在按照本指南进行操作之前，请考虑以下备用工作流，这在某些情况下可能更方便：

  • 如果您要在本地计算机上使用代码进行训练，并尽可能减少手动打包工作量，我们建议您使用 Google Cloud CLI 的自动打包功能。借助此功能，您只需一个命令即可构建 Docker 容器映像、将其推送到 Artifact Registry 并根据容器映像创建 CustomJob 资源。如需了解详情，请参阅 CustomJob 创建指南。

    如需使用自动打包，您必须在本地计算机上安装 Docker。此选项仅允许您创建 CustomJob，而不能创建 TrainingPipeline 或 HyperparameterTuningJob 资源。（了解自定义训练资源之间的差异。）

  • 如需进一步自定义容器映像并先在容器中本地运行代码，然后才在 Vertex AI 上运行，您可以使用 gcloud CLI 的 local-run 命令将代码容器化并在本地运行。然后，您可以手动将映像推送到 Artifact Registry。

    如需使用 local-run 命令，您必须在本地计算机上安装 Docker。

  • 如果您可以使用单个 Python 脚本编写训练代码，则可以使用 Python 版 Vertex AI SDK 的 CustomJob 类来创建自定义作业或者使用 CustomTrainingJob 类来创建自定义 TrainingPipeline。您的训练代码会自动打包为源分发并上传到 Cloud Storage。

  • 为获得最大的灵活性，您可以手动创建自定义容器映像，并将其推送到 Artifact Registry。

如果上述选项均不适合您的用例，或者您希望手动将训练应用打包为源分发，请按照本指南的其余部分进行操作。

准备工作

在准备在云端运行的训练应用之前，请完成以下步骤：

  1. 使用 Vertex AI 用于训练的预构建容器中提供的机器学习 (ML) 框架开发训练应用。确保您的训练应用符合训练代码要求。

    如果您是从头开始编写训练应用，我们建议您按照本文档下一部分中所述的应用结构来组织您的代码。

  2. 在您计划使用 Vertex AI 的同一 Google Cloud 项目中创建一个 Cloud Storage 存储桶。您将把训练应用存储在此存储桶中。（虽然可以使用其他 Google Cloud 存储桶中的存储桶，但这需要本指南讨论范围之外的其他配置。）

    为获得最佳性能，请确保 Cloud Storage 存储桶位于您计划使用 Vertex AI 的位置。

  3. 了解训练应用依赖的所有 Python 库，无论它们是自定义依赖项还是通过 PyPI 免费提供。

应用结构

使用预构建容器执行自定义训练时，您必须根据以下要求指定训练代码：

  • 以一个或多个 Python 源分发的形式提供代码。

    如果您使用 Vertex AI API 开始自定义训练，请在 packageUris 字段中指定这些源分发。

  • 在其中一个源分发中创建一个模块，用作训练的入口点。

    如果您使用 Vertex AI API 开始自定义训练，请在 pythonModule 字段中指定此模块。

满足这些要求后，您就可以通过任何方式构造训练应用。但是，我们建议您按照以下结构（在 Vertex AI 示例中经常使用）组织代码来构建单个 Python 源分发：

  • 使用包含 setup.py 文件的主项目目录。 下一部分提供了有关此文件内容的指导。

  • 在主项目目录中，创建一个名为 trainer/ 的子目录，用作训练代码的主软件包。

  • 在 trainer/ 中，创建一个名为 task.py 的模块，用作训练代码的入口点。

  • 要支持 trainer/task.py，请在 trainer/ 软件包中创建所需的任何其他 Python 模块，并在主项目目录中创建包含所需的其他代码的其他子目录。

  • 在每个子目录中创建一个 __init__.py 文件，使其成为软件包。

本指南的其余部分假定您的代码按此结构组织。

创建源分发

构建 Python 源分发是一个广泛的主题，在很大程度上超出了本文档的讨论范围。为方便起见，本部分概述了如何使用 Setuptools 构建源分发以用于 Vertex AI。您也可以使用其他库来执行相同的操作。

  1. 创建一个 setup.py 文件，告诉 Setuptools 如何创建源分发。基本的 setup.py 包含以下内容：

    • setuptools.find_packages 和 setuptools.setup 的导入语句。

    • 对 setuptools.setup 的调用，至少包含以下参数：

      • name 设置为源分发的名称。

      • version 设置为此源分发版本的版本号。

      • install_requires 设置为应用所需的依赖项列表，包括版本要求，例如 'docutils>=0.3'。

      • packages 设置为 find_packages()。 这会指示 Setuptools 将父目录中所有包含 __init__.py 文件的子目录添加为软件包。

      • include_package_data 设置为 True。

    以下示例展示了训练应用的基本 setup.py 文件：

    from setuptools import find_packages
from setuptools import setup

setup(
    name='trainer',
    version='0.1',
    packages=find_packages(),
    include_package_data=True,
    description='My training application.'
)

  2. 运行以下命令创建源分发 dist/trainer-0.1.tar.gz：

    python setup.py sdist --formats=gztar

Python 应用依赖项

依赖项是您在代码中 import 的软件包。您的应用可能需要多个依赖项才能正常运行。

对于自定义训练作业中的每个副本，您的代码在已安装许多常用 Python 依赖项的容器中运行。查看您打算用于训练的预构建容器中包含的依赖项，并记下尚未安装的所有依赖项。您只需要为预构建容器中尚未安装的依赖项完成以下步骤。

您可能需要添加以下两种类型的依赖项：

  • 标准依赖项，这是 PyPI 中提供的常用分发软件包
  • 自定义依赖项，例如您自己开发的软件包，或组织内部的软件包。

以下部分介绍了每个类型的过程。

标准 (PyPI) 依赖项

您可以在应用的 setup.py 脚本中指定应用的标准依赖项。Vertex AI 使用 pip 在其为作业分配的副本上安装您的训练应用。pip install 命令会查找您配置的依赖项并进行安装。

以下示例展示了类似于上一部分的 setup.py。但是，此 setup.py 会告知 Vertex AI 在安装训练应用时安装 some_PyPI_package：

from setuptools import find_packages
from setuptools import setup

REQUIRED_PACKAGES = ['some_PyPI_package>=1.0']

setup(
    name='trainer',
    version='0.1',
    install_requires=REQUIRED_PACKAGES,
    packages=find_packages(),
    include_package_data=True,
    description='My training application.'
)

自定义依赖项

如需指定应用的自定义依赖项，您可以将这些依赖项的路径作为作业配置的一部分进行传递。您需要每个依赖项的源分发的 URI。自定义依赖项必须位于 Cloud Storage 位置。Vertex AI 使用 pip install 来安装自定义依赖项，因此这些依赖项可以在其 setup.py 脚本中拥有自己的标准依赖项。

您添加的每个 URI 都是源分发的路径，其格式为 tar 压缩文件 (.tar.gz) 或 whl 压缩文件 (.whl)。Vertex AI 会使用 pip install 在其为训练作业分配的每个副本上安装各个依赖项。

如果您使用 Vertex AI API 启动自定义训练，请在 packageUris 字段中指定这些依赖项的 Cloud Storage URI 以及训练应用。

Python 模块

您的应用可包含多个模块（Python 文件）。您必须标识包含应用入口点的模块。训练服务通过调用 Python 来运行该模块，方式与在本地运行一样。

例如，如果您遵循上一部分推荐的结构，则主模块是 task.py。由于此模块位于名为 trainer 的导入软件包（包含 __init__.py 文件的目录）内，其完全限定名称是 trainer.task。因此，如果您使用 Vertex AI API 开始自定义训练，请将 moduleName 字段设置为 trainer.task。

如需详细了解模块，请参阅 Python 软件包指南。

将源分发上传到 Cloud Storage

您可以使用 gcloud CLI 将源分发和所有自定义依赖项上传到 Cloud Storage 存储桶。例如：

gcloud storage cp dist/trainer-0.1.tar.gz CLOUD_STORAGE_DIRECTORY

将 CLOUD_STORAGE_DIRECTORY 替换为您的 Google Cloud 项目可访问的存储桶中的 Cloud Storage 目录的 URI（以 gs:// 开头，以 / 结尾）。

如需了解将源分发上传到 Cloud Storage 的其他方式，请参阅 Cloud Storage 文档中的上传对象。

后续步骤