本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 建立批次推論任務
<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/home](https://console.aws.amazon.com/personalize/home)：// 開啟 Amazon Personalize 主控台並登入您的帳戶。

1. 在**資料集群組**頁面上，選擇您的資料集群組。

1. 在導覽窗格的**自訂資源**下，選擇**批次推論任務**。

1. 選擇 **Create batch inference job (建立批次推論任務)**。

1.  選擇批次推論任務類型。
   + 若要產生沒有佈景主題的項目建議，請選擇**項目建議**。
   +  如果您使用類似項目配方，並想要將描述性主題新增至類似項目的群組，請使用**內容產生器選擇主題建議**。若要產生佈景主題，您必須具有項目名稱資料和文字資料的項目資料集。如需詳細資訊，請參閱[來自 Content Generator 的具有主題的批次建議](themed-batch-recommendations.md)。

1. 在 **Batch inference job details (批次推論任務詳細資訊)** 的 **Batch inference job name (批次推論任務名稱)** 中，指定批次推論任務的名稱。

1. 針對**解決方案**，選擇解決方案，然後選擇您要用來產生建議**的解決方案版本 ID**。

1. 針對**結果數目**，選擇性地指定每行輸入資料的建議數目。預設為 25。

1.  如果您的批次任務使用佈景主題產生建議，請在**佈景主題建議詳細資訊**中，選擇包含項目資料集中項目名稱或標題的資料欄。此資料有助於產生更相關的主題。如需詳細資訊，請參閱[來自 Content Generator 的具有主題的批次建議](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 Resource Name (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.  選擇 **Create batch inference job (建立批次推論任務)**。即會開始建立批次推論任務，並出現 **Batch inference jobs (批次推論任務)** 頁面，其中顯示 **Batch inference job detail (批次推論任務詳細資訊)** 區段。

    當批次推論任務的狀態變更為**作用中**時，您可以從指定的輸出 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 Resource Name (ARN)，並將 取代`IAM service role ARN`為您在設定期間為 Amazon Personalize 建立的 IAM 服務角色的 ARN。此角色必須分別具有輸入和輸出 Amazon S3 儲存貯體的讀取和寫入存取權。選擇性地提供篩選條件 ARN 來篩選建議。如果您的篩選條件使用預留位置參數，請確定參數的值包含在您的輸入 JSON 中。如需詳細資訊，請參閱[篩選批次建議和使用者區段 （自訂資源）](filter-batch.md)。

`S3 output path` 使用輸入檔案`S3 input 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>/**。

此範例包含選用的使用者個人化配方特定`itemExplorationConfig`超參數： `explorationWeight`和 `explorationItemAgeCutOff`。選擇性地包含 `explorationWeight`和 `explorationItemAgeCutOff`值來設定探勘。如需詳細資訊，請參閱[使用者個人化配方](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>

若要產生類似項目的主題，您必須使用類似項目配方，且您的項目資料集必須具有文字欄位和項目名稱資料欄。如需 佈景主題建議的詳細資訊，請參閱 [來自 Content Generator 的具有主題的批次建議](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 Resource Name (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) ]

此範例包含選用的使用者個人化配方特定`itemExplorationConfig`超參數： `explorationWeight`和 `explorationItemAgeCutOff`。選擇性地包含 `explorationWeight`和 `explorationItemAgeCutOff`值來設定探勘。如需詳細資訊，請參閱[使用者個人化配方](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 ]

此範例包含選用的使用者個人化配方特定`itemExplorationConfig`欄位： `explorationWeight`和 `explorationItemAgeCutOff`。選擇性地包含 `explorationWeight`和 `explorationItemAgeCutOff`值來設定探勘。如需詳細資訊，請參閱[使用者個人化配方](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` 作為輸入參數來檢查任務的狀態。您也可以呼叫 ，列出 AWS 環境中所有 Amazon Personalize 批次推論任務[ListBatchInferenceJobs](API_ListBatchInferenceJobs.md)。

### 建立產生佈景主題的批次推論任務
<a name="batch-sdk-themes"></a>

若要產生類似項目的主題，您必須使用類似項目配方，且您的項目資料集必須具有文字欄位和項目名稱資料欄。如需 佈景主題建議的詳細資訊，請參閱 [來自 Content Generator 的具有主題的批次建議](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>/"}}
)
```