入门 (SDK for Java 2.x)

本教程向您展示如何使用 Amazon SDK for Java 2.x 从头到尾完成 Amazon Personalize 工作流程。

为避免产生不必要的费用，请在完成入门练习后，按照清理资源中的步骤，删除您在本教程中创建的资源。

有关更多示例，请参阅完成 Amazon Personalize 项目。

主题

先决条件
完成 Amazon Personalize 项目

先决条件

以下是完成本教程的先决条件步骤：

完成入门先决条件，设置所需权限并创建训练数据。您可以使用开始使用（控制台）或入门 (Amazon CLI) 练习中所用的相同源数据。如果您使用自己的源数据，请确保按照先决条件中的步骤设置数据格式。
按照《Amazon SDK for Java 2.x 开发者指南》中的设置 Amazon SDK for Java 2.x过程中的指定设置 SDK for Java 2.x 环境和 Amazon 凭证。

教程

在以下步骤中，您将项目设置为使用 Amazon Personalize 程序包并创建 Amazon Personalize SDK for Java 2.x 客户端。然后，将导入数据，创建解决方案版本并通过市场活动进行部署，随后获得建议。

完成先决条件后，将 Amazon Personalize 依赖项添加到 pom.xml 文件中，然后导入 Amazon Personalize 程序包。

将以下依赖项添加到 pom.xml 文件中。最新版本号可能与示例代码不同。


<dependency>
	<groupId>software.amazon.awssdk</groupId>
	<artifactId>personalize</artifactId>
	<version>2.16.83</version>
</dependency>
<dependency>
	<groupId>software.amazon.awssdk</groupId>
	<artifactId>personalizeruntime</artifactId>
	<version>2.16.83</version>
</dependency>
<dependency>
	<groupId>software.amazon.awssdk</groupId>
	<artifactId>personalizeevents</artifactId>
	<version>2.16.83</version>
</dependency>

将以下导入语句添加至您的项目。


// import client packages
import software.amazon.awssdk.services.personalize.PersonalizeClient;
import software.amazon.awssdk.services.personalizeruntime.PersonalizeRuntimeClient;
// Amazon Personalize exception package
import software.amazon.awssdk.services.personalize.model.PersonalizeException;
// schema packages
import software.amazon.awssdk.services.personalize.model.CreateSchemaRequest;
// dataset group packages
import software.amazon.awssdk.services.personalize.model.CreateDatasetGroupRequest;
import software.amazon.awssdk.services.personalize.model.DescribeDatasetGroupRequest;
// dataset packages
import software.amazon.awssdk.services.personalize.model.CreateDatasetRequest;
// dataset import job packages
import software.amazon.awssdk.services.personalize.model.CreateDatasetImportJobRequest;
import software.amazon.awssdk.services.personalize.model.DataSource;
import software.amazon.awssdk.services.personalize.model.DatasetImportJob;
import software.amazon.awssdk.services.personalize.model.DescribeDatasetImportJobRequest;
// solution packages
import software.amazon.awssdk.services.personalize.model.CreateSolutionRequest;
import software.amazon.awssdk.services.personalize.model.CreateSolutionResponse;
// solution version packages
import software.amazon.awssdk.services.personalize.model.DescribeSolutionRequest;
import software.amazon.awssdk.services.personalize.model.CreateSolutionVersionRequest;
import software.amazon.awssdk.services.personalize.model.CreateSolutionVersionResponse;
import software.amazon.awssdk.services.personalize.model.DescribeSolutionVersionRequest;
// campaign packages
import software.amazon.awssdk.services.personalize.model.CreateCampaignRequest;
import software.amazon.awssdk.services.personalize.model.CreateCampaignResponse;
// get recommendations packages
import software.amazon.awssdk.services.personalizeruntime.model.GetRecommendationsRequest;
import software.amazon.awssdk.services.personalizeruntime.model.GetRecommendationsResponse;
import software.amazon.awssdk.services.personalizeruntime.model.PredictedItem;
// Java time utility package
import java.time.Instant;

将 Amazon Personalize 依赖项添加到 pom.xml 文件并导入所需的程序包之后，创建以下 Amazon Personalize 客户端：


PersonalizeClient personalizeClient = PersonalizeClient.builder()
  .region(region)
  .build();

PersonalizeRuntimeClient personalizeRuntimeClient = PersonalizeRuntimeClient.builder() 
  .region(region)
  .build();

初始化 Amazon Personalize 客户端后，导入您在完成入门先决条件时创建的历史数据。要将历史数据导入 Amazon Personalize，请执行以下操作：

将以下 Avro 架构作为 JSON 文件保存到您的工作目录中。此架构与您在完成入门先决条件时创建的 CSV 文件中的列相匹配。


{
  "type": "record",
  "name": "Interactions",
  "namespace": "com.amazonaws.personalize.schema",
  "fields": [
      {
          "name": "USER_ID",
          "type": "string"
      },
      {
          "name": "ITEM_ID",
          "type": "string"
      },
      {
          "name": "TIMESTAMP",
          "type": "long"
      }
  ],
  "version": "1.0"
}

使用以下 createSchema 方法创建 Amazon Personalize 架构。将以下内容作为参数传递：Amazon Personalize 服务客户端、架构名称以及您在上一步中创建的架构 JSON 文件的文件路径。该方法将返回新架构的 Amazon 资源名称 (ARN)。请将其存储以便将来使用。


    public static String createSchema(PersonalizeClient personalizeClient, String schemaName, String filePath) {

        String schema = null;
        try {
            schema = new String(Files.readAllBytes(Paths.get(filePath)));
        } catch (IOException e) {
            System.out.println(e.getMessage());
        }

        try {
            CreateSchemaRequest createSchemaRequest = CreateSchemaRequest.builder()
                    .name(schemaName)
                    .schema(schema)
                    .build();

            String schemaArn = personalizeClient.createSchema(createSchemaRequest).schemaArn();

            System.out.println("Schema arn: " + schemaArn);

            return schemaArn;

        } catch (PersonalizeException e) {
            System.err.println(e.awsErrorDetails().errorMessage());
            System.exit(1);
        }
        return "";
    }

创建数据集组。使用以下 createDatasetGroup 方法创建数据集组。将以下内容作为参数传递：Amazon Personalize 服务客户端和数据集组的名称。该方法将返回新数据集组的 ARN。请将其存储以便将来使用。


    public static String createDatasetGroup(PersonalizeClient personalizeClient, String datasetGroupName) {

        try {
            CreateDatasetGroupRequest createDatasetGroupRequest = CreateDatasetGroupRequest.builder()
                    .name(datasetGroupName)
                    .build();
            return personalizeClient.createDatasetGroup(createDatasetGroupRequest).datasetGroupArn();
        } catch (PersonalizeException e) {
            System.out.println(e.awsErrorDetails().errorMessage());
        }
        return "";
    }

创建。使用以下 createDataset 方法创建数据集。将以下内容作为参数传递：Amazon Personalize 服务客户端、数据集名称、架构的 ARN、数据集组的 ARN 以及数据集类型的 Interactions。该方法将返回新数据集的 ARN。请将其存储以便将来使用。


    public static String createDataset(PersonalizeClient personalizeClient,
            String datasetName,
            String datasetGroupArn,
            String datasetType,
            String schemaArn) {
        try {
            CreateDatasetRequest request = CreateDatasetRequest.builder()
                    .name(datasetName)
                    .datasetGroupArn(datasetGroupArn)
                    .datasetType(datasetType)
                    .schemaArn(schemaArn)
                    .build();

            String datasetArn = personalizeClient.createDataset(request)
                    .datasetArn();
            System.out.println("Dataset " + datasetName + " created.");
            return datasetArn;

        } catch (PersonalizeException e) {
            System.err.println(e.awsErrorDetails().errorMessage());
            System.exit(1);
        }
        return "";
    }

使用数据集导入作业导入数据。使用以下 createPersonalizeDatasetImportJob 方法创建数据集导入作业。

将以下内容作为参数传递：Amazon Personalize 服务客户端、作业的名称、您的 ARN、存储训练数据的 Amazon S3 桶路径 (s3://bucket name/folder name/ratings.csv) 以及服务角色的 ARN（您在入门先决条件期间创建了此角色）。该方法将返回数据集导入作业的 ARN。（可选）将其存储起来以备后用。


    public static String createPersonalizeDatasetImportJob(PersonalizeClient personalizeClient,
            String jobName,
            String datasetArn,
            String s3BucketPath,
            String roleArn) {

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

        try {
            DataSource importDataSource = DataSource.builder()
                    .dataLocation(s3BucketPath)
                    .build();

            CreateDatasetImportJobRequest createDatasetImportJobRequest = CreateDatasetImportJobRequest.builder()
                    .datasetArn(datasetArn)
                    .dataSource(importDataSource)
                    .jobName(jobName)
                    .roleArn(roleArn)
                    .build();

            datasetImportJobArn = personalizeClient.createDatasetImportJob(createDatasetImportJobRequest)
                    .datasetImportJobArn();
            DescribeDatasetImportJobRequest describeDatasetImportJobRequest = DescribeDatasetImportJobRequest.builder()
                    .datasetImportJobArn(datasetImportJobArn)
                    .build();

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

            while (Instant.now().getEpochSecond() < maxTime) {

                DatasetImportJob datasetImportJob = personalizeClient
                        .describeDatasetImportJob(describeDatasetImportJobRequest)
                        .datasetImportJob();

                status = datasetImportJob.status();
                System.out.println("Dataset import 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 datasetImportJobArn;

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

导入数据后，创建解决方案和解决方案版本，如下所示。解决方案 包含用于训练模型的配置，解决方案版本 是经过训练的模型。

使用以下 createPersonalizeSolution 方法创建新解决方案。将以下内容作为参数传递：Amazon Personalize 服务客户端、数据集组 Amazon 资源名称 (ARN)、解决方案名称以及 User-Personalization 食谱的 ARN (arn:aws:personalize:::recipe/aws-user-personalization)。该方法将返回新解决方案的 ARN。请将其存储以便将来使用。


    public static String createPersonalizeSolution(PersonalizeClient personalizeClient,
            String datasetGroupArn,
            String solutionName,
            String recipeArn) {

        try {
            CreateSolutionRequest solutionRequest = CreateSolutionRequest.builder()
                    .name(solutionName)
                    .datasetGroupArn(datasetGroupArn)
                    .recipeArn(recipeArn)
                    .build();

            CreateSolutionResponse solutionResponse = personalizeClient.createSolution(solutionRequest);
            return solutionResponse.solutionArn();

        } catch (PersonalizeException e) {
            System.err.println(e.awsErrorDetails().errorMessage());
            System.exit(1);
        }
        return "";
    }

使用以下 createPersonalizeSolutionVersion 方法创建解决方案版本。将上一步中解决方案的 ARN 作为参数传递。以下代码首先检查您的解决方案是否准备就绪，然后创建解决方案版本。在训练期间，代码使用 DescribeSolutionVersion 操作来检索解决方案版本的状态。训练完成后，方法将返回新解决方案版本的 ARN。请将其存储以便将来使用。


    public static String createPersonalizeSolutionVersion(PersonalizeClient personalizeClient, String solutionArn) {
        long maxTime = 0;
        long waitInMilliseconds = 30 * 1000; // 30 seconds
        String solutionStatus = "";
        String solutionVersionStatus = "";
        String solutionVersionArn = "";

        try {
            DescribeSolutionRequest describeSolutionRequest = DescribeSolutionRequest.builder()
                    .solutionArn(solutionArn)
                    .build();

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

            // Wait until solution is active.
            while (Instant.now().getEpochSecond() < maxTime) {

                solutionStatus = personalizeClient.describeSolution(describeSolutionRequest).solution().status();
                System.out.println("Solution status: " + solutionStatus);

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

            if (solutionStatus.equals("ACTIVE")) {

                CreateSolutionVersionRequest createSolutionVersionRequest = CreateSolutionVersionRequest.builder()
                        .solutionArn(solutionArn)
                        .build();

                CreateSolutionVersionResponse createSolutionVersionResponse = personalizeClient
                        .createSolutionVersion(createSolutionVersionRequest);
                solutionVersionArn = createSolutionVersionResponse.solutionVersionArn();

                System.out.println("Solution version ARN: " + solutionVersionArn);

                DescribeSolutionVersionRequest describeSolutionVersionRequest = DescribeSolutionVersionRequest.builder()
                        .solutionVersionArn(solutionVersionArn)
                        .build();

                while (Instant.now().getEpochSecond() < maxTime) {

                    solutionVersionStatus = personalizeClient.describeSolutionVersion(describeSolutionVersionRequest)
                            .solutionVersion().status();
                    System.out.println("Solution version status: " + solutionVersionStatus);

                    if (solutionVersionStatus.equals("ACTIVE") || solutionVersionStatus.equals("CREATE FAILED")) {
                        break;
                    }
                    try {
                        Thread.sleep(waitInMilliseconds);
                    } catch (InterruptedException e) {
                        System.out.println(e.getMessage());
                    }
                }
                return solutionVersionArn;
            }
        } catch (PersonalizeException e) {
            System.err.println(e.awsErrorDetails().errorMessage());
            System.exit(1);
        }
        return "";
    }

有关更多信息，请参阅创建解决方案和解决方案版本。在您创建解决方案版本时，可以在继续前评估其性能。有关更多信息，请参阅通过指标评估解决方案版本。

训练并评估解决方案版本后，使用 Amazon Personalize 市场活动进行部署。使用以下 createPersonalCampaign 方法部署解决方案版本。将以下内容作为参数传递：Amazon Personalize 服务客户端、您在上一步中创建的解决方案版本的 Amazon 资源名称 (ARN) 以及市场活动名称。该方法将返回新市场活动的 ARN。请将其存储以便将来使用。


public static String createPersonalCompaign(PersonalizeClient personalizeClient, String solutionVersionArn, String name) {

    try {
        CreateCampaignRequest createCampaignRequest = CreateCampaignRequest.builder()
            .minProvisionedTPS(1)
            .solutionVersionArn(solutionVersionArn)
            .name(name)
            .build();

        CreateCampaignResponse campaignResponse = personalizeClient.createCampaign(createCampaignRequest);
        System.out.println("The campaign ARN is "+campaignResponse.campaignArn());
        return campaignResponse.campaignArn();

    } catch (PersonalizeException e) {
        System.err.println(e.awsErrorDetails().errorMessage());
        System.exit(1);
    }
}

有关 Amazon Personalize 市场活动的更多信息，请参阅创建市场活动。

创建市场活动之后，您可以使用它来获得建议。使用以下 getRecs 方法为用户获取建议。将以下内容作为参数传递：Amazon Personalize 运行时客户端、您在上一步中创建的市场活动的 Amazon 资源名称 (ARN) 以及您导入的历史数据中的用户 ID（例如 123）。该方法会在屏幕上打印出推荐物品列表。


    public static void getRecs(PersonalizeRuntimeClient personalizeRuntimeClient, String campaignArn, String userId) {

        try {
            GetRecommendationsRequest recommendationsRequest = GetRecommendationsRequest.builder()
                    .campaignArn(campaignArn)
                    .numResults(20)
                    .userId(userId)
                    .build();

            GetRecommendationsResponse recommendationsResponse = personalizeRuntimeClient
                    .getRecommendations(recommendationsRequest);
            List<PredictedItem> items = recommendationsResponse.itemList();
            for (PredictedItem item : items) {
                System.out.println("Item Id is : " + item.itemId());
                System.out.println("Item score is : " + item.score());
            }

        } catch (AwsServiceException e) {
            System.err.println(e.awsErrorDetails().errorMessage());
            System.exit(1);
        }
    }

完成 Amazon Personalize 项目

有关向您展示如何使用适用于 Java 2.x 的 SDK 完成亚马逊个性化工作流程的 all-in-one 项目，请参阅上的 Amazon-Personalize-Java -App。 GitHub该项目包括使用不同的配方训练多个解决方案版本，以及记录 PutEvents 操作中的事件。

有关其他示例，请参阅在 Amazon SDK 示例存储库的个性化文件夹中找到的代码。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

入门 (SDK for Python (Boto3))

清理资源