封装训练应用

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

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

准备工作

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

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

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

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

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

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

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

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

为方便起见,您可以将配置值定义为环境变量,这种做法非常有用。以下变量包含用于暂存应用软件包的值:

TRAINER_PACKAGE_PATH="/path/to/your/application/sources"
MAIN_TRAINER_MODULE="trainer.task"
PACKAGE_STAGING_PATH="gs://your/chosen/staging/path"

此外,以下变量定义了运行作业时使用的值:

now=$(date +"%Y%m%d_%H%M%S")
JOB_NAME="your_name_$now"
JOB_DIR="gs://your/chosen/job/output/path"
REGION="us-east1"

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

gcloud ai-platform jobs submit training $JOB_NAME \
    --staging-bucket $PACKAGE_STAGING_PATH \
    --job-dir $JOB_DIR  \
    --package-path $TRAINER_PACKAGE_PATH \
    --module-name $MAIN_TRAINER_MODULE \
    --region $REGION \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value
  • --staging-bucket 指定了您要用于暂存训练和依赖项软件包的 Cloud Storage 位置。您的 GCP 项目必须有权访问该 Cloud Storage 存储分区,并且该存储分区应该位于您运行作业的区域。请参阅 AI Platform 服务的可用区域。如果未指定暂存存储分区,则 AI Platform 会在 job-dir 参数中指定的位置暂存软件包。

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

  • --package-path 指定了应用目录的本地路径。gcloud 工具根据 --package-path 所指定目录的父级目录中的 setup.py 文件,从您的代码构建 .tar.gz 分发软件包。该工具随后将此 .tar.gz 文件上传到 Cloud Storage,并使用它运行您的训练作业。

    如果预期位置没有 setup.py 文件,gcloud 工具会创建一个简单的临时 setup.py,并只将 --package-path 指定的目录包含在它构建的 .tar.gz 文件中。

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

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

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

使用依赖项

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

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

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

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

以下部分介绍了各种依赖项的添加过程。

添加标准 (PyPI) 依赖项

您可以在软件包的 setup.py 脚本中为其指定标准依赖项。AI Platform 使用 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.'
)

如果您使用 gcloud 命令行工具提交训练作业,它将自动使用您的 setup.py 文件来生成软件包。

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

python setup.py sdist

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

添加自定义依赖项

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

如果您使用 gcloud 工具运行训练作业,则可以在本地机器以及 Cloud Storage 上指定依赖项,该工具会帮您将依赖项暂存在云端:当您运行 gcloud ai-platform jobs submit training 命令时,请设置 --packages 标志以包含各依赖项并用英文逗号分隔。

您包含的每个 URI 都是分发软件包的路径,软件包采用 tar (.tar.gz) 或 whl (.whl) 压缩文件格式。AI Platform 会使用 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 $MAIN_TRAINER_MODULE \
    --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 $MAIN_TRAINER_MODULE \
    --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 示例通常采用以下结构。如果您在项目中采用与示例相似的组织结构,将更方便您参考示例进行操作。

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

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

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

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

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

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

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

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

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

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

训练应用项目的推荐结构

运行 gcloud ai-platform jobs submit training 时,请将 --package-path 设置为 trainer。这会让 gcloud 工具在 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 工具上传现有软件包

如果您自行构建软件包,则可以使用 gcloud 工具上传该软件包。请运行 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 $MAIN_TRAINER_MODULE \
    --region us-central1 \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value

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

如果您自行构建软件包并将其上传到 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 $MAIN_TRAINER_MODULE \
    --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 存储分区,最简单的方法是使用 gsutil 工具:

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

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

后续步骤