本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 训练作业中的增强清单文件
<a name="augmented-manifest"></a>

要在训练作业中随您的数据集包含元数据，请使用增强清单文件。使用增强清单文件时，您的数据集必须存储在 Amazon Simple Storage Service (Amazon S3) 中，并且必须配置训练作业以使用存储在该位置的数据集。您可以为一个或多个 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_Channel.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_Channel.html) 指定此数据集的位置和格式。增强清单只能支持管道输入模式。[https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_Channel.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_Channel.html)要了解有关管道输入模式的更多信息，请参阅**InputMode**中的部分。

指定通道参数时，您需要指定文件的路径，称为 `S3Uri`。Amazon SageMaker AI 根据`S3DataType`中[https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_S3DataSource.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_S3DataSource.html)指定的来解释此 URI。`AugmentedManifestFile` 选项定义随输入数据包括元数据的清单格式。在您有标记过的数据时，使用增强清单文件是一种替代的预处理方法。对于使用标记过数据的训练作业，您通常需要预处理数据集，从而在训练前将输入数据与元数据组合起来。如果您的训练数据集较大，预处理的时间可能会较长，成本高昂。

## 增强清单文件格式
<a name="augmented-manifest-format"></a>

增强清单文件必须采用 [JSON 行](http://jsonlines.org/)格式。在 JSON 行格式中，文件的每一行是一个完整的 JSON 对象，后跟换行分隔符。

在训练期间， SageMaker AI 会解析每行 JSON，并将其部分或全部属性发送到训练算法。您可以使用 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrainingJob.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrainingJob.html) API 的 `AttributeNames` 参数指定要传递哪些属性内容以及传递的顺序。该`AttributeNames`参数是 A SageMaker I 在 JSON 对象中查找的属性名称的有序列表，以用作训练输入。

例如，如果您为 `AttributeNames` 列出 `["line", "book"]`，则输入数据必须按指定顺序包括 `line` 和 `book` 的属性名称。对于本示例，以下增强清单文件内容有效：

```
{"author": "Herman Melville", "line": "Call me Ishmael", "book": "Moby Dick"}
{"line": "It was love at first sight.", "author": "Joseph Heller", "book": "Catch-22"}
```

SageMaker AI 会忽略未列出的属性名称，即使它们位于列出的属性之前、之后或介于列出的属性之间。

使用增强清单文件时，请遵循以下准则：
+ 在 `AttributeNames` 参数中列出的属性顺序确定了在训练作业中传递到算法的属性顺序。
+ 列出的`AttributeNames`可以是 JSON 行中所有属性的子集。 SageMaker AI 会忽略文件中未列出的属性。
+ 您可在 `AttributeNames` 中指定 JSON 格式允许的任意数据类型，包括文本、数字、数组或对象。
+ 要包括 S3 URI 作为属性名称，请将后缀 `-ref` 添加到其中。

如果属性名称包含后缀 `-ref`，则属性的值必须是指向数据文件的 S3 URI 并且训练作业可以访问该 URI。例如，如果 `AttributeNames` 包含 `["image-ref", "is-a-cat"]`，以下示例显示有效的增强清单文件：

```
{"image-ref": "s3://amzn-s3-demo-bucket/sample01/image1.jpg", "is-a-cat": 1}
{"image-ref": "s3://amzn-s3-demo-bucket/sample02/image2.jpg", "is-a-cat": 0}
```

如果是此清单文件的第一行 JSON， SageMaker AI 会从中检索`image1.jpg`文件`s3://amzn-s3-demo-bucket/sample01/`以及`"1"`用于图像分类的`is-a-cat`属性的字符串表示形式。

**提示**  
要创建增强的清单文件，请使用 Amazon G SageMaker round Truth 并创建标签任务。有关标注作业的输出的更多信息，请参阅[标注作业输出数据](sms-data-output.md)。

# 用于管道模式训练的增补清单文件格式
<a name="augmented-manifest-stream"></a>

通过增强清单格式，您可以使用文件在管道模式下进行训练，而无需创建 RecordIO 文件。您需要将训练通道和验证通道指定为 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrainingJob.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrainingJob.html) 请求的 `InputDataConfig` 参数的值。只有使用管道输入模式的通道才支持增强清单文件。对于每个通道，数据提取自其增强清单文件，并通过通道的指定管道（按顺序）流式传输到算法。管道模式使用先进先出 (FIFO) 方法，因此记录按照排队的顺序处理。有关管道输入模式的信息，请参阅[https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_Channel.html#SageMaker-Type-Channel-InputMode](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_Channel.html#SageMaker-Type-Channel-InputMode)。

具有 `"-ref"` 后缀的属性名称指向预先格式化的二进制数据。在某些情况下，算法知道如何解析数据。在另一些情况下，您可能需要包装数据，针对算法来分隔记录。如果算法与 [RecordIO 格式数据](https://mxnet.apache.org/api/architecture/note_data_loading#data-format)兼容，请为 `RecordWrapperType` 指定 `RecordIO` 以解决此问题。如果算法不与 `RecordIO` 格式兼容，请为 `RecordWrapperType` 指定 `None` 并确保针对您的算法正确解析了数据。

使用 `["image-ref", "is-a-cat"]` 示例，如果您使用 RecordIO 包装，则将以下数据流发送到队列：

`recordio_formatted(s3://amzn-s3-demo-bucket/foo/image1.jpg)recordio_formatted("1")recordio_formatted(s3://amzn-s3-demo-bucket/bar/image2.jpg)recordio_formatted("0")`

未使用 RecordIO 格式包装的图像，将通过对应的 `is-a-cat` 属性值流式处理为一个记录。由于算法可能没有正确的分隔图像和属性，这可能会导致问题。有关使用增强清单文件进行图像分类的详细信息，请参阅[使用增强清单图像格式训练](https://docs.aws.amazon.com/sagemaker/latest/dg/image-classification.html#IC-augmented-manifest-training)。

通常使用增强清单文件和管道模式时，EBS 卷的大小限制不适用。这包括原本必须位于 EBS 卷大小限制内的设置，例如 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_S3DataSource.html#SageMaker-Type-S3DataSource-S3DataDistributionType                 ](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_S3DataSource.html#SageMaker-Type-S3DataSource-S3DataDistributionType                 )。有关管道模式以及如何使用该模式的更多信息，请参阅[使用您自己的训练算法 – 输入数据配置](your-algorithms-training-algo.html#your-algorithms-training-algo-running-container-inputdataconfig)。

## 使用增强清单文件
<a name="augmented-manifest-create"></a>

以下各节将向您展示如何在 Amazon SageMaker 训练作业中使用增强的清单文件，无论是通过 A SageMaker I 控制台还是使用 SageMaker Python SDK 以编程方式使用。

### 使用增强清单文件（控制台）
<a name="augmented-manifest-console"></a>

要完成此过程，您需要：
+ 存储了增强清单文件的 S3 存储桶的 URL。
+ 将在增强清单文件中列出的数据存储到 S3 存储桶中。
+ 您要存储作业输出的 S3 存储桶的 URL。

**在训练作业中使用增强清单文件（控制台）**

1. 打开 Amazon A SageMaker I 控制台，网址为[https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/)。

1. 在导航窗格中，选择 **Training (训练)**，然后选择 **Training jobs (训练作业)**。

1. 选择 **Create training job (创建训练作业)**。

1. 为训练作业提供一个名称。在 AWS 账户的某个 AWS 区域内，该名称必须是唯一的。名称可以包括 1 到 63 个字符。有效字符：a-z、A-Z、0-9 和 . : \$1 = @ \$1 % -（连字符）。

1. 选择要使用的算法。有关支持的内置算法的信息，请参阅[Amazon 中的内置算法和预训练模型 SageMaker](algos.md)。如果您希望使用自定义算法，请确保该算法与管道模式兼容。

1. （可选）对于 **Resource configuration (资源配置)**，请接受默认值，如果要减少计算时间，请增加资源消耗。

   1. （可选）对于 **Instance type (实例类型)**，选择您要使用的 ML 计算实例类型。在大多数情况下 **ml.m4.xlarge** 便足够。

   1. 对于 **Instance count (实例计数)**，请使用默认值 `1`。

   1. （可选）对于 **Additional volume per instance (GB) (每个实例的附加卷 (GB))**，请选择您要预配置的 ML 存储卷的大小。在大部分情况下，您可以使用默认值 `1`。如果您使用大数据集，请使用较大的大小。

1. 为训练数据集提供有关输入数据的信息。

   1. 对于 **Channel name (通道名称)**，请接受默认值 (**train**) 或者输入更有意义的名称，例如 **training-augmented-manifest-file**。

   1. 对于 **InputMode**，选择 **Pip** e。

   1. 对于 **S3 数据分配类型**，选择**FullyReplicated**。进行增量训练时，完全复制会导致各个 ML 计算实例使用扩展数据集的完整副本。对于基于神经的算法，例如 [神经主题模型 (NTM) 算法](ntm.md)，请选择 `ShardedByS3Key`。

   1. 如果在增强清单文件中指定的数据未压缩，请将 **Compression type (压缩类型)** 设置为 **None (无)**。如果使用 gzip 压缩了数据，请将其设置为 **Gzip**。

   1. （可选）对于 **Content type (内容类型)**，请指定相应的 MIME 类型。内容类型是多用途 Internet 邮件扩展 (MIME) 类型的数据。

   1. 对于 **Record wrapper (记录包装程序)**，如果在增强清单文件中指定的数据集以 RecordIO 格式保存，则选择 **RecordIO**。如果您的数据集未另存为 RecordIO 格式的文件，请选择 **None (无)**。

   1. 对于 **S3 数据类型**，选择**AugmentedManifestFile**。

   1. 对于 **S3 location (S3 位置)**，提供您存储增强清单文件的存储桶的路径。

   1. 对于**AugmentedManifestFile 属性名称**，请指定要使用的属性的名称。属性名称必须存在于增强清单文件中，并且区分大小写。

   1. （可选）要添加更多属性，请选择 **Add row（添加行）** 并为各个属性指定其他属性名称。

   1. （可选）要调整属性名称的顺序，请选择名称旁边的上移或下移按钮。使用增强清单文件时，指定属性名称的顺序非常重要。

   1. 选择**完成**。

1. 对于 **Output data configuration (输出数据配置)**，请提供以下信息：

   1. 对于 **S3 location (S3 位置)**，键入存储输出数据的 S3 存储桶的路径。

   1. （可选）您可以使用 AWS Key Management Service (AWS KMS) 加密密钥对静态输出数据进行加密。对于 **Encryption key (加密密钥)**，请提供密钥 ID 或其 Amazon 资源编号 (ARN)。有关更多信息，请参阅 [KMS 托管的加密密钥](https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingKMSEncryption.html)。

1. （可选）对于 **Tags (标签)**，向训练作业添加一个或多个标签。*标签*是您定义并分配到 AWS 资源的元数据。在这种情况下，您可以使用标签来帮助您管理训练作业。标签包含由您定义的键和值。例如，您可能希望创建一个标签，使用 **Project** 作为键，其值引用与训练作业相关的项目，例如 **Home value forecasts**。

1. 选择**创建训练作业**。 SageMaker AI 创建并运行训练作业。

训练作业完成后， SageMaker AI 会将模型工件存储在存储桶中，您在 “输出**数据配置**” 字段中为 **S3 输出路径**提供了该存储桶的路径。要部署模型以获取预测，请参阅[将模型部署到 Amazon EC2](ex1-model-deployment.md)。

### 使用增强清单文件 (API)
<a name="augmented-manifest-api"></a>

以下内容展示了如何使用 A SageMaker I 高级别 Python 库使用增强的清单文件训练模型：

```
import sagemaker

# Create a model object set to using "Pipe" mode.
model = sagemaker.estimator.Estimator(
    training_image,
    role,
    instance_count=1,
    instance_type='ml.p3.2xlarge',
    volume_size = 50,
    max_run = 360000,
    input_mode = 'Pipe',
    output_path=s3_output_location,
    sagemaker_session=session
)

# Create a train data channel with S3_data_type as 'AugmentedManifestFile' and attribute names.
train_data = sagemaker.inputs.TrainingInput(
    your_augmented_manifest_file,
    distribution='FullyReplicated',
    content_type='application/x-recordio',
    s3_data_type='AugmentedManifestFile',
    attribute_names=['source-ref', 'annotations'],
    input_mode='Pipe',
    record_wrapping='RecordIO'
)

data_channels = {'train': train_data}

# Train a model.
model.fit(inputs=data_channels, logs=True)
```

训练作业完成后， SageMaker AI 会将模型工件存储在存储桶中，您在 “输出**数据配置**” 字段中为 **S3 输出路径**提供了该存储桶的路径。要部署模型以获取预测，请参阅[将模型部署到 Amazon EC2](ex1-model-deployment.md)。