封装训练应用

您必须先将代码和所有依赖项上传到 Google Cloud 项目可访问的 Cloud Storage 存储分区,然后才能使用 AI Platform Training 运行训练应用。本页面介绍如何在云端封装和暂存应用。

如果您先在本地测试训练应用,然后再将其上传到云端,则可以获得最佳效果。使用 AI Platform Training 进行训练时,系统会根据使用的资源向您的账号收取费用

准备工作

在将训练应用迁移到云端之前,您必须完成以下步骤:

  1. 按照入门指南中的说明配置您的开发环境。
  2. 使用 AI Platform Training 托管的其中一个机器学习框架(TensorFlow、scikit-learn 或 XGBoost)开发您的训练应用。或者,构建自定义容器以自定义训练应用的环境。这样您就可以使用 AI Platform Training 托管框架之外的机器学习框架。

    如果您希望在训练后将经过训练的模型部署到 AI Platform Prediction,请参阅导出模型以进行预测指南,以确保训练软件包导出 AI Platform Prediction 可以使用的模型工件。

  3. 按照该指南设置一个用于存储训练应用数据和文件的 Cloud Storage 存储分区

  4. 了解训练应用所依赖的所有 Python 库,无论它们是自定义软件包,还是通过 PyPI 免费提供。

本文档讨论了以下因素,这些因素可影响您如何封装应用并将其上传到 Cloud Storage:

  • 使用 gcloud CLI(推荐)或编写您自己的解决方案代码。
  • 如有必要,手动构建软件包。
  • 如何添加您所用 AI Platform Training 运行时未安装的其他依赖项。

如需封装应用并将其与依赖项一同上传,最简单的方法是使用 gcloud CLI。只需使用一条命令 (gcloud ai-platform jobs submit training),即可封装并上传应用,以及提交第一项训练作业。

为方便起见,您可以将配置值定义为 shell 变量,这种做法非常有用:

PACKAGE_PATH='LOCAL_PACKAGE_PATH'
MODULE_NAME='MODULE_NAME'
STAGING_BUCKET='BUCKET_NAME'
JOB_NAME='JOB_NAME'
JOB_DIR='JOB_OUTPUT_PATH'
REGION='REGION'

请替换以下内容:

  • LOCAL_PACKAGE_PATH:本地环境中 Python 软件包的目录的路径
  • MODULE_NAME:训练模块的完全限定名称
  • BUCKET_NAME - Cloud Storage 存储桶的名称
  • JOB_NAME:训练作业的名称
  • JOB_OUTPUT_PATH:您希望训练作业在其中保存输出的 Cloud Storage 目录的 URI
  • REGION:您要运行训练作业的地区

如需详细了解对于以下命令中的值的要求,请参阅下面的列表。

以下示例展示了一条 gcloud ai-platform jobs submit training 命令,该命令会封装应用并提交训练作业:

gcloud ai-platform jobs submit training $JOB_NAME \
    --staging-bucket=$STAGING_BUCKET \
    --job-dir=$JOB_DIR  \
    --package-path=$PACKAGE_PATH \
    --module-name=$MODULE_NAME \
    --region=$REGION \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value
  • --staging-bucket 指定您要用于暂存训练软件包和依赖项软件包的 Cloud Storage 存储桶。您的 Google Cloud 项目必须拥有此 Cloud Storage 存储桶的访问权限,并且此存储桶必须位于运行作业的区域。请参阅 AI Platform Training 服务的可用区域。如果您没有指定暂存存储桶,AI Platform Training 会将您的软件包暂存在 job-dir 参数所指定的位置。

  • --job-dir 指定要用于存储训练作业输出文件的 Cloud Storage 位置。您的 Google Cloud 项目必须拥有此 Cloud Storage 存储分区的访问权限,且此存储分区应位于运行作业的区域。请参阅 AI Platform Training 服务的可用区域

  • --package-path 指定应用目录的本地路径。gcloud CLI 会根据 setup.py 文件(位于 --package-path 所指定目录的父目录中),通过您的代码构建 .tar.gz 分发软件包。然后,它会将此 .tar.gz 文件上传到 Cloud Storage,并使用该文件来运行您的训练作业。

    如果预期位置中没有 setup.py 文件,gcloud CLI 会创建一个简单的临时 setup.py,并仅将 --package-path 指定的目录加入其所构建的 .tar.gz 文件中。

  • --module-name 指定应用主模块的名称,该名称使用软件包的命名空间点表示法。这是用于启动应用的 Python 文件。例如,如果您的主模块为 .../my_application/trainer/task.py(请参阅推荐的项目结构),则该模块名称为 trainer.task

  • 如果您在配置文件 (config.yaml) 中指定了一个选项,同时又将该选项指定为命令行标志,则命令行中的值将覆盖配置文件中的值。
  • -- 标志标记了 gcloud 特有标志的结束以及您要传递至应用的 USER_ARGS 的开始。
  • AI Platform Training 特有的标志(例如 --module-name--runtime-version--job-dir)必须位于空 -- 标志之前。AI Platform Training 服务可解读这些标志。
  • 如果指定 --job-dir 标志,则该标志必须位于空 -- 标志之前,原因是 AI Platform Training 会使用 --job-dir 来验证路径。
  • 如果指定 --job-dir 标志,您的应用也必须对该标志进行处理。虽然 --job-dir 位于空 -- 之前,该标志也会作为命令行标志传递至您的应用。
  • 您可以根据需要定义任意数量的 USER_ARGS。AI Platform Training 会将 --user_first_arg--user_second_arg 等传递至您的应用。

您可以在运行训练作业相关指南中深入了解作业提交标志。

使用依赖项

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

在 AI Platform Training 上运行训练作业时,该作业将在已安装许多常用 Python 软件包的训练实例(特别配置的虚拟机)上运行。请检查用于训练的运行时版本中包含的软件包,并记下尚未安装的所有依赖项。

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

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

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

添加标准 (PyPI) 依赖项

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

在应用的根目录(如果您遵循推荐的格式,则为 trainer 目录的上一级目录)中,创建一个名为 setup.py 的文件。

setup.py 中输入以下脚本,并插入您自己的值:

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 package.'
)

如果您使用 Google Cloud CLI 提交训练作业,它会自动使用您的 setup.py 文件生成软件包。

如果您没有使用 gcloud 提交训练作业,请使用以下命令运行脚本:

python setup.py sdist

如需了解详情,请参阅手动封装训练应用部分。

添加自定义依赖项

如需指定应用的自定义依赖项,您可以将这些依赖项的路径作为作业配置的一部分进行传递。您需要每个依赖项软件包的 URI。自定义依赖项必须位于 Cloud Storage 位置。AI Platform Training 使用 pip install 来安装自定义依赖项 自己的 setup.py 脚本中。

如果您使用 gcloud CLI 运行训练作业,则可以在本地机器和 Cloud Storage 上指定依赖项,随后该工具会为您将依赖项暂存到云端,具体做法如下:在运行 gcloud ai-platform jobs submit training 命令时设置 --packages 标志,以采用英文逗号分隔的列表形式添加依赖项。

您添加的每个 URI 都是一个分发包的路径,格式为 tar 压缩文件 (.tar.gz) 或压缩包 (.whl)。AI Platform Training 会安装 使用 pip install 打包 为训练作业分配的每台虚拟机上的资源。

以下示例指定了名为 dep1.tar.gzdep2.whl 的打包依赖项(每种受支持软件包类型各一个)以及应用源代码的路径:

gcloud ai-platform jobs submit training $JOB_NAME \
    --staging-bucket $PACKAGE_STAGING_PATH \
    --package-path /Users/mluser/models/faces/trainer \
    --module-name $MODULE_NAME \
    --packages dep1.tar.gz,dep2.whl \
    --region us-central1 \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value

同样,以下示例指定了名为 dep1.tar.gzdep2.whl 的打包依赖项(每种受支持软件包类型各一个),但使用已构建的训练应用:

gcloud ai-platform jobs submit training $JOB_NAME \
    --staging-bucket $PACKAGE_STAGING_PATH \
    --module-name $MODULE_NAME \
    --packages trainer-0.0.1.tar.gz,dep1.tar.gz,dep2.whl
    --region us-central1 \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value

如果您使用 AI Platform Training and Prediction API 直接运行训练作业,则必须自行将依赖项软件包暂存在一个 Cloud Storage 位置,然后使用该位置中软件包的路径。

手动构建软件包

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

请按照以下步骤手动构建软件包:

  1. 在应用软件包的每个目录中,添加一个名为 __init__.py 的文件,该文件可以为空,也可以包含导入该软件包(该目录中的任何模块)时要运行的代码。

  2. 在要加入 .tar.gz 分发软件包中的所有代码的父目录(如果您遵循推荐的模式,则为 trainer 目录的上一级目录)中,添加一个名为 setup.pySetuptools 文件,其中包含以下内容:

    • setuptools.find_packagessetuptools.setup 的导入语句。

    • setuptools.setup 的调用,至少包含以下参数:

      • _name_ 设置为软件包命名空间的名称。

      • _version_ 设置为此软件包版本的版本号。

      • _install_requires_ 设置为应用所需的软件包列表,包括类似 'docutils>=0.3' 的版本要求。

      • _packages_ 设置为 find_packages()。该参数指示 Setuptools,以“导入软件包”的形式(在 Python 中,您使用类似 from trainer import util 的语句从这些软件包导入模块)将父目录下所有包含 __init__.py 文件的子目录都加入“分发软件包”(包含所有代码的 `.tar.gz 文件)中。

      • _include_package_data_ 设置为 True

  3. 运行 python setup.py sdist 来创建您的 .tar.gz 分发软件包。

推荐的项目结构

您可以通过任何方式构造您的训练应用。不过,AI Platform Training 示例通常采用以下结构。如果您在项目中采用与示例相似的组织结构,将更方便您参考示例进行操作。

  • 使用包含 setup.py 文件的主项目目录。

    setup.py 文件中使用 setuptoolsfind_packages() 函数确保所有子目录都包含在您构建的 .tar.gz 分发软件包中。

  • 使用名为 trainer 的子目录来存储主应用模块。

  • 将您的主应用模块命名为 task.py

  • 在实现应用所需的主项目目录中创建其他任何子目录。

  • 在每个子目录中创建一个 __init__.py 文件。Setuptools 使用这些文件来识别包含待封装代码的目录,这些文件可以为空。

在 AI Platform Training 示例中,trainer 目录通常包含以下源文件:

  • task.py 包含管理训练作业的应用逻辑。

  • model.py 包含模型的逻辑。

  • util.py 包含用于运行训练应用的代码(如果存在)。

训练应用项目的推荐结构

当您运行 gcloud ai-platform jobs submit training 时,请将 --package-path 设置为 trainer。这会让 gcloud CLI 在 trainer 的父目录(您的主项目目录)中查找 setup.py 文件。

Python 模块

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

例如,如果您遵循上一部分中推荐的结构,则您的主模块是 task.py。由于此模块位于名为 trainer 的导入软件包(包含 __init__.py 文件的目录)内,其完全限定名称是 trainer.task。因此,如果您通过 gcloud ai-platform jobs submit training 提交作业,请将 --module-name 标志设置为 trainer.task

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

使用 gcloud CLI 上传现有软件包

如果您自行构建软件包,则可以使用 gcloud CLI 上传该软件包。运行 gcloud ai-platform jobs submit training 命令:

  • --packages 标志设置为已打包应用的路径。

  • --module-name 标志设置为应用主模块的名称,该名称使用软件包的命名空间点表示法。这是用于启动应用的 Python 文件。例如,如果您的主模块为 .../my_application/trainer/task.py(请参阅推荐的项目结构),则该模块名称为 trainer.task

以下示例展示了如何使用与运行命令位于同一目录的 tar 压缩软件包(在本例中名为 trainer-0.0.1.tar.gz)。主函数位于名为 task.py: 的模块中

gcloud ai-platform jobs submit training $JOB_NAME \
    --staging-bucket $PACKAGE_STAGING_PATH \
    --job-dir $JOB_DIR \
    --packages trainer-0.0.1.tar.gz \
    --module-name $MODULE_NAME \
    --region us-central1 \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value

通过 gcloud CLI 使用已在云端的现有软件包

如果您自行构建软件包并将其上传到 Cloud Storage 位置,则可以使用 gcloud 上传该软件包。运行 gcloud ai-platform jobs submit training 命令:

  • --packages 标志设置为已打包应用的路径。

  • --module-name 标志设置为应用主模块的名称,该名称使用软件包的命名空间点表示法。这是用于启动应用的 Python 文件。例如,如果您的主模块为 .../my_application/trainer/task.py(请参阅推荐的项目结构),则该模块名称为 trainer.task

以下示例展示了如何使用位于 Cloud Storage 存储分区的 tar 压缩软件包:

gcloud ai-platform jobs submit training $JOB_NAME \
    --job-dir $JOB_DIR \
    --packages $PATH_TO_PACKAGED_TRAINER \
    --module-name $MODULE_NAME \
    --region us-central1 \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value

其中 $PATH_TO_PACKAGED_TRAINER 是环境变量,表示已在云端的现有软件包的路径。例如,该路径可以指向以下 Cloud Storage 位置,其中包含一个名为 trainer-0.0.1.tar.gz 的 tar 压缩软件包:

PATH_TO_PACKAGED_TRAINER=gs://$CLOUD_STORAGE_BUCKET_NAME/trainer-0.0.0.tar.gz

手动上传软件包

如果需要,您可以手动上传软件包。最常见的原因是您想要直接调用 AI Platform Training and Prediction API 来启动训练作业。如需将软件包与任何自定义依赖项手动上传到 Cloud Storage 存储桶,最简单的方法是使用 gcloud storage 命令工具:

gcloud storage cp /local/path/to/package.tar.gz  gs://bucket/path/

不过,如果您可以使用命令行执行此操作,则只需在设置训练作业时使用 gcloud ai-platform jobs submit training 上传软件包即可。如果无法使用命令行,您可以使用 Cloud Storage 客户端库以编程方式上传

后续步骤