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

# 创建批量推理作业
<a name="creating-batch-inference-job"></a>

 创建批量推理作业，根据 Amazon S3 的输入数据获取针对用户的批量物品建议。输入数据可以是 JSON 格式的用户列表或物品列表（或两者兼而有之）。您可以使用 Amazon Personalize 控制台 AWS Command Line Interface (AWS CLI) 或 AWS SDKs创建批量推理作业。

 创建批量推理作业时，您可以指定输入和输出位置的 Amazon S3 路径。Amazon S3 基于前缀。如果您为输入数据位置提供前缀，则 Amazon Personalize 会使用与该前缀匹配的所有文件作为输入数据。例如，如果您提供 `s3://amzn-s3-demo-bucket/folderName` 且存储桶中还有一个路径为 `s3://amzn-s3-demo-bucket/folderName_test` 的文件夹，则 Amazon Personalize 会使用两个文件夹中的所有文件作为输入数据。要仅使用特定文件夹中的文件作为输入数据，请使用前缀分隔符作为 Amazon S3 路径的结尾，例如 `/`: `s3://amzn-s3-demo-bucket/folderName/`。有关 Amazon S3 如何组织对象的更多信息，请参阅[组织、列出和处理您的对象](https://docs.aws.amazon.com/AmazonS3/latest/userguide/organizing-objects.html)。

 有关 Amazon Personalize 中批量工作流程的更多信息（包括权限要求、建议评分以及准备和导入输入数据），请参阅[使用自定义资源获取批量物品推荐](getting-batch-recommendations.md)。

**Topics**
+ [创建批量推理作业（控制台）](#batch-console)
+ [创建批量推理作业 (AWS CLI)](#batch-cli)
+ [创建批量推理作业 (AWS SDKs)](#batch-sdk)

## 创建批量推理作业（控制台）
<a name="batch-console"></a>

 完成[为批量建议准备输入数据](batch-data-upload.md)后，就可以创建批量推理作业了。此过程假定您已创建了一个解决方案和一个解决方案版本（经过训练的模型）。

**创建批量推理作业（控制台）**

1. 在[https://console.aws.amazon.com/personalize/家](https://console.aws.amazon.com/personalize/home)中打开 Amazon Personalize 控制台并登录您的账户。

1. 在**数据集组**页面，选择您的数据集组。

1. 在导航窗格的**自定义资源**下，选择**批量推理作业**。

1. 选择**创建批量推理作业**。

1.  选择批量推理作业类型。
   + 要生成不带主题的物品建议，请选择**物品建议**。
   +  如果您使用 Similar-Items 配方并想向相似物品组添加描述性主题，请选择**内容生成器中带有主题的建议**。要生成主题，必须有一个包含物品名称数据和文本数据的物品数据集。有关更多信息，请参阅 [内容生成器中带有主题的批量建议](themed-batch-recommendations.md)。

1. 在**批量推理作业详细信息**的**批量推理作业名称**中，指定批量推理作业的名称。

1. 对于**解决方案**，选择解决方案，然后选择要用于生成建议的**解决方案版本 ID**。

1. 对于**结果数量**，可以选择为每行输入数据指定建议的数量。默认值为 25。

1.  如果您的批处理作业生成了带有主题的建议，请在**带有主题的建议详细信息**中，选择物品数据集中包含物品名称或标题的列。这些数据可以帮助生成更相关的主题。有关更多信息，请参阅 [内容生成器中带有主题的批量建议](themed-batch-recommendations.md)。

1.  在**输入源**中，指定输入文件的 Amazon S3 路径。

   使用以下语法：**s3://amzn-s3-demo-bucket/<folder name>/<input JSON file name>.json**

    您的输入数据必须采用与您的解决方案使用的食谱对应的正确格式。有关输入数据的示例，请参阅[批量推理作业输入和输出 JSON 示例](batch-data-upload.md#batch-inference-job-json-examples)。

1. 对于**解密密钥**，如果您使用自己的密 AWS KMS 钥进行存储桶加密，请指定密钥的 Amazon 资源名称 (ARN)。Amazon Personalize 必须拥有使用您的密钥的权限 有关授予权限的信息，请参阅[授予 Amazon Personalize 使用您的 AWS KMS 密钥的权限](granting-personalize-key-access.md)。

1. 在**输出目标**中，指定输出位置的路径。我们建议使用不同的输出数据位置（文件夹或其他 Amazon S3 存储桶）。

    使用以下语法：**s3://amzn-s3-demo-bucket/<output folder name>/**

1. 对于**加密密钥**，如果您使用自己的 AWS KMS 密钥进行加密，请指定密钥的 ARN。Amazon Personalize 必须拥有使用您的密钥的权限 有关授予权限的信息，请参阅[授予 Amazon Personalize 使用您的 AWS KMS 密钥的权限](granting-personalize-key-access.md)。

1. 对于 **IAM 服务角色**，选择您在设置过程中为 Amazon Personalize 创建的 IAM 服务角色。此角色必须分别对您的输入和输出 Amazon S3 存储桶具有读写权限。

1.  在**筛选条件**中，（可选）选择一个筛选条件，以将筛选条件应用于批量建议。如果您的筛选器使用占位符参数，请确保这些参数的值包含在您的输入 JSON 中。有关更多信息，请参阅 [在您的输入 JSON 中提供筛选器值](filter-batch.md#providing-filter-values)。

1. 对于**标签**，可以选择添加任何标签。有关标记 Amazon Personalize 资源的更多信息，请参阅[为 Amazon Personalize 资源添加标签](tagging-resources.md)。

1.  选择**创建批量推理作业**。此时将开始创建批量推理作业，**批量推理作业**页面将显示，并显示**批量推理作业详细信息**部分。

    当批量推理作业的状态更改为**活动** 时，您可以从指定的输出 Amazon S3 存储桶中检索作业的输出。输出文件的名称将采用 `input-name.out` 格式。

## 创建批量推理作业 (AWS CLI)
<a name="batch-cli"></a>

完成[为批量建议准备输入数据](batch-data-upload.md)后，就可以通过 [CreateBatchInferenceJob](API_CreateBatchInferenceJob.md) 操作创建批量推理作业了。

**Topics**
+ [创建批量推理作业](#batch-cli-code-sample)
+ [创建生成主题的批量推理作业](#batch-cli-themes)

### 创建批量推理作业
<a name="batch-cli-code-sample"></a>

 您可以使用 `create-batch-inference-job` 命令创建批量推理作业。指定作业名称，将 `Solution version ARN` 替换为解决方案版本的 Amazon 资源名称 (ARN)，然后将 `IAM service role ARN` 替换为您在设置期间为 Amazon Personalize 创建的 IAM 服务角色的 ARN。此角色必须分别对您的输入和输出 Amazon S3 存储桶具有读写权限。（可选）提供筛选器 ARN 来筛选建议。如果您的筛选器使用占位符参数，请确保这些参数的值包含在您的输入 JSON 中。有关更多信息，请参阅 [筛选批量建议和用户细分（自定义资源）](filter-batch.md)。

将 `S3 input path` 和 `S3 output path` 替换为指向您的输入文件和输出位置的 Amazon S3 路径。我们建议使用不同的输出数据位置（文件夹或其他 Amazon S3 存储桶）。对输入和输出位置使用以下语法：**s3://amzn-s3-demo-bucket/<folder name>/<input JSON file name>.json** 和 **s3://amzn-s3-demo-bucket/<output folder name>/**。

该示例包括可选的 User-Personalization 食谱特定的 `itemExplorationConfig` 超参数：`explorationWeight` 和 `explorationItemAgeCutOff`。（可选）包括 `explorationWeight` 和 `explorationItemAgeCutOff` 值以配置浏览。有关更多信息，请参阅 [User-Personalization 食谱](native-recipe-new-item-USER_PERSONALIZATION.md)。

```
aws personalize create-batch-inference-job \
--job-name Batch job name \
--solution-version-arn Solution version ARN \
--filter-arn Filter ARN \
--job-input s3DataSource={path=s3://S3 input path} \
--job-output s3DataDestination={path=s3://S3 output path} \
--role-arn IAM service role ARN \
--batch-inference-job-config "{\"itemExplorationConfig\":{\"explorationWeight\":\"0.3\",\"explorationItemAgeCutOff\":\"30\"}}"
```

### 创建生成主题的批量推理作业
<a name="batch-cli-themes"></a>

要为相似的物品生成主题，您必须使用 Similar-Items 配方，并且您的物品数据集必须有一个文本字段和一个物品名称数据列。有关带有主题的建议的更多信息，请参阅[内容生成器中带有主题的批量建议](themed-batch-recommendations.md)。

以下代码创建了一个批量推理作业，该作业可生成带有主题的建议。将 `batch-inference-job-mode` 保留设置为 `THEME_GENERATION`。将 `COLUMN_NAME` 替换为存储物品名称数据的列的名称。

```
aws personalize create-batch-inference-job \
--job-name Themed batch job name \
--solution-version-arn Solution version ARN \
--filter-arn Filter ARN \
--job-input s3DataSource={path=s3://S3 input path} \
--job-output s3DataDestination={path=s3://S3 output path} \
--role-arn IAM service role ARN \
--batch-inference-job-mode THEME_GENERATION \
--theme-generation-config "{\"fieldsForThemeGeneration\": {\"itemName\":\"COLUMN_NAME\"}}"
```

## 创建批量推理作业 (AWS SDKs)
<a name="batch-sdk"></a>

完成[为批量建议准备输入数据](batch-data-upload.md)后，就可以通过 [CreateBatchInferenceJob](API_CreateBatchInferenceJob.md) 操作创建批量推理作业了。

**Topics**
+ [创建批量推理作业](#batch-sdk-code-sample)
+ [创建生成主题的批量推理作业](#batch-sdk-themes)

### 创建批量推理作业
<a name="batch-sdk-code-sample"></a>

 可以使用以下代码创建批量推理作业。指定作业名称、解决方案版本的 Amazon 资源名称 (ARN)，以及您在设置期间为 Amazon Personalize 创建的 IAM 服务角色的 ARN。此角色必须对您的输入和输出 Amazon S3 存储桶具有读写权限。

我们建议使用不同的输出数据位置（文件夹或其他 Amazon S3 存储桶）。对输入和输出位置使用以下语法：**s3:/amzn-s3-demo-bucket/<folder name>/<input JSON file name>.json** 和 **s3://amzn-s3-demo-bucket/<output folder name>/**。

 对于 `numResults`，指定您希望 Amazon Personalize 为每行输入数据预测的物品数量。（可选）提供筛选器 ARN 来筛选建议。如果您的筛选器使用占位符参数，请确保这些参数的值包含在您的输入 JSON 中。有关更多信息，请参阅 [筛选批量建议和用户细分（自定义资源）](filter-batch.md)。

------
#### [ SDK for Python (Boto3) ]

该示例包括可选的 User-Personalization 食谱特定的 `itemExplorationConfig` 超参数：`explorationWeight` 和 `explorationItemAgeCutOff`。（可选）包括 `explorationWeight` 和 `explorationItemAgeCutOff` 值以配置浏览。有关更多信息，请参阅 [User-Personalization 食谱](native-recipe-new-item-USER_PERSONALIZATION.md)。

```
import boto3

personalize_rec = boto3.client(service_name='personalize')

personalize_rec.create_batch_inference_job (
    solutionVersionArn = "Solution version ARN",
    jobName = "Batch job name",
    roleArn = "IAM service role ARN",
    filterArn = "Filter ARN",
    batchInferenceJobConfig = {
        # optional USER_PERSONALIZATION recipe hyperparameters
        "itemExplorationConfig": {      
            "explorationWeight": "0.3",
            "explorationItemAgeCutOff": "30"
        }
    },
    jobInput = 
       {"s3DataSource": {"path": "s3://amzn-s3-demo-bucket/<folder name>/<input JSON file name>.json"}},
    jobOutput = 
       {"s3DataDestination": {"path": "s3:/amzn-s3-demo-bucket/<output folder name>/"}}
)
```

------
#### [ SDK for Java 2.x ]

该示例包括可选的 User-Personalization 食谱特定的 `itemExplorationConfig` 字段：`explorationWeight` 和 `explorationItemAgeCutOff`。（可选）包括 `explorationWeight` 和 `explorationItemAgeCutOff` 值以配置浏览。有关更多信息，请参阅 [User-Personalization 食谱](native-recipe-new-item-USER_PERSONALIZATION.md)。

```
public static String createPersonalizeBatchInferenceJob(PersonalizeClient personalizeClient,
                                                        String solutionVersionArn,
                                                        String jobName,
                                                        String filterArn,
                                                        String s3InputDataSourcePath,
                                                        String s3DataDestinationPath,
                                                        String roleArn,
                                                        String explorationWeight,
                                                        String explorationItemAgeCutOff) {

  long waitInMilliseconds = 60 * 1000;
  String status;
  String batchInferenceJobArn;

  try {
      // Set up data input and output parameters.
      S3DataConfig inputSource = S3DataConfig.builder()
              .path(s3InputDataSourcePath)
              .build();
      S3DataConfig outputDestination = S3DataConfig.builder()
              .path(s3DataDestinationPath)
              .build();

      BatchInferenceJobInput jobInput = BatchInferenceJobInput.builder()
              .s3DataSource(inputSource)
              .build();
      BatchInferenceJobOutput jobOutputLocation = BatchInferenceJobOutput.builder()
              .s3DataDestination(outputDestination)
              .build();

      // Optional code to build the User-Personalization specific item exploration config.
      HashMap<String, String> explorationConfig = new HashMap<>();

      explorationConfig.put("explorationWeight", explorationWeight);
      explorationConfig.put("explorationItemAgeCutOff", explorationItemAgeCutOff);

      BatchInferenceJobConfig jobConfig = BatchInferenceJobConfig.builder()
              .itemExplorationConfig(explorationConfig)
              .build();
      // End optional User-Personalization recipe specific code.

      CreateBatchInferenceJobRequest createBatchInferenceJobRequest = CreateBatchInferenceJobRequest.builder()
              .solutionVersionArn(solutionVersionArn)
              .jobInput(jobInput)
              .jobOutput(jobOutputLocation)
              .jobName(jobName)
              .filterArn(filterArn)
              .roleArn(roleArn)
              .batchInferenceJobConfig(jobConfig)   // Optional
              .build();

      batchInferenceJobArn = personalizeClient.createBatchInferenceJob(createBatchInferenceJobRequest)
              .batchInferenceJobArn();
      DescribeBatchInferenceJobRequest describeBatchInferenceJobRequest = DescribeBatchInferenceJobRequest.builder()
              .batchInferenceJobArn(batchInferenceJobArn)
              .build();

      long maxTime = Instant.now().getEpochSecond() + 3 * 60 * 60;

      // wait until the batch inference job is complete.
      while (Instant.now().getEpochSecond() < maxTime) {

          BatchInferenceJob batchInferenceJob = personalizeClient
                  .describeBatchInferenceJob(describeBatchInferenceJobRequest)
                  .batchInferenceJob();

          status = batchInferenceJob.status();
          System.out.println("Batch inference job status: " + status);

          if (status.equals("ACTIVE") || status.equals("CREATE FAILED")) {
              break;
          }
          try {
              Thread.sleep(waitInMilliseconds);
          } catch (InterruptedException e) {
              System.out.println(e.getMessage());
          }
      }
      return batchInferenceJobArn;

  } catch (PersonalizeException e) {
      System.out.println(e.awsErrorDetails().errorMessage());
  }
  return "";
}
```

------
#### [ SDK for JavaScript v3 ]

```
// Get service clients module and commands using ES6 syntax.
import { CreateBatchInferenceJobCommand } from "@aws-sdk/client-personalize";
import { personalizeClient } from "./libs/personalizeClients.js";

// Or, create the client here.
// const personalizeClient = new PersonalizeClient({ region: "REGION"});

// Set the batch inference job's parameters.

export const createBatchInferenceJobParam = {
  jobName: "JOB_NAME",
  jobInput: {
    s3DataSource: {
      path: "INPUT_PATH",
    },
  },
  jobOutput: {
    s3DataDestination: {
      path: "OUTPUT_PATH",
    },
  },
  roleArn: "ROLE_ARN",
  solutionVersionArn: "SOLUTION_VERSION_ARN",
  numResults: 20,
};

export const run = async () => {
  try {
    const response = await personalizeClient.send(
      new CreateBatchInferenceJobCommand(createBatchInferenceJobParam),
    );
    console.log("Success", response);
    return response; // For unit tests.
  } catch (err) {
    console.log("Error", err);
  }
};
run();
```

------

处理批处理作业可能需要一段时间才能完成。您可以通过调用 [DescribeBatchInferenceJob](API_DescribeBatchInferenceJob.md) 和传递 `batchRecommendationsJobArn` 作为输入参数来检查作业的状态。您也可以通过调[ListBatchInferenceJobs](API_ListBatchInferenceJobs.md)用列出您 AWS 环境中的所有 Amazon Personalize 批量推理作业。

### 创建生成主题的批量推理作业
<a name="batch-sdk-themes"></a>

要为相似的物品生成主题，您必须使用 Similar-Items 配方，并且您的物品数据集必须有一个文本字段和一个物品名称数据列。有关带有主题的建议的更多信息，请参阅[内容生成器中带有主题的批量建议](themed-batch-recommendations.md)。

以下代码创建了一个批量推理作业，该作业可生成带有主题的建议。将 `batchInferenceJobMode` 保留设置为 `"THEME_GENERATION"`。将 `COLUMNN_NAME` 替换为存储物品名称数据的列的名称。

```
import boto3

personalize_rec = boto3.client(service_name='personalize')

personalize_rec.create_batch_inference_job (
    solutionVersionArn = "Solution version ARN",
    jobName = "Batch job name",
    roleArn = "IAM service role ARN",
    filterArn = "Filter ARN",
    batchInferenceJobMode = "THEME_GENERATION",
    themeGenerationConfig = {
      "fieldsForThemeGeneration": {
          "itemName": "COLUMN_NAME"
      }
    },
    jobInput = 
       {"s3DataSource": {"path": "s3://amzn-s3-demo-bucket/<folder name>/<input JSON file name>.json"}},
    jobOutput = 
       {"s3DataDestination": {"path": "s3://amzn-s3-demo-bucket/<output folder name>/"}}
)
```