本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 从 Amazon Personalize 获取建议 [创建推荐器](creating-recommenders.md)或[创建市场活动](campaigns.md)后，就可以获取建议。根据您的资源，您可以实时获得建议，也可以通过批量工作流程获得建议。 + 使用自定义资源，您可以获得实时建议或批量建议。要获得实时建议，您必须先创建自定义市场活动，然后才能获得建议。要获得批量建议，您无需创建市场活动。 + 对于域数据集组中的推荐器，您只能获得实时建议。 以下主题介绍了如何以及在何时使用每种推荐类型。对于批量推荐和实时推荐，您都可以筛选结果。有关更多信息，请参阅 [筛选建议和用户细分](filter.md)。 **Topics** + [建议分数](#how-scores-work) + [Amazon Personalize 中的实时物品推荐](recommendations.md) + [Amazon Personalize 中的实时操作推荐](get-action-recommendations.md) + [获取个性化排名（自定义资源）](rankings.md) + [利用上下文元数据提高建议的相关性](contextual-metadata.md) + [使用自定义资源获取批量物品推荐](getting-batch-recommendations.md) + [使用自定义资源获取批量用户细分](getting-user-segments.md) ## 建议分数 通过使用 User-Personalization-v 2、用户个性化、2、个性化排名和 PERSONALIZED\$1AC Personalized-Ranking-v TIONS 配方创建的自定义解决方案，Amazon Personalized\$1ACTIONS 在推荐中包含每件商品的分数。这些分数表示 Amazon Personalize 对于用户接下来将选择哪个物品或操作的相对确定性。分数越高，意味着确定性越大。 + 有关 User-Personalization-v 2 分数和用户个性化的信息，请参阅[推荐评分的工作原理（自定义资源）](recommendations.md#how-recommendation-scoring-works)。 + 有关 PERSONALIZED\$1ACTIONS 配方的分数的信息，请参阅[操作建议评分的工作原理](get-action-recommendations.md#how-action-recommendation-scoring-works)。 + 有关 Personalized-Ranking-v 2 分数和个性化排名建议的信息，请参阅。[个性化排名评分的工作原理](rankings.md#how-ranking-scoring-works) 对于批量推理作业，物品分数的计算方法如 [推荐评分的工作原理（自定义资源）](recommendations.md#how-recommendation-scoring-works)和 [个性化排名评分的工作原理](rankings.md#how-ranking-scoring-works)中所述。您可以在批量推理作业的输出 JSON 文件中查看分数。 # Amazon Personalize 中的实时物品推荐 如果您的应用场景或配方生成了物品推荐，那么在[创建推荐器](creating-recommenders.md)或[创建市场活动](campaigns.md)之后，即可为用户获取实时的个性化或相关物品推荐。 如果您的域应用场景或配方提供[实时个性化](use-case-recipe-features.md#about-real-time-personalization)（例如*热门精选*应用场景或 *User-Personalization-v2* 配方），则当您记录用户与目录的交互时，Amazon Personalize 会根据用户的最新活动更新推荐。有关记录实时事件和个性化设置的更多信息，请参阅[记录实时事件以影响推荐](recording-events.md)。 获得实时物品推荐后，您可以执行以下操作： + 如果您将市场活动配置为返回推荐物品的元数据，则可以指定要包括在 [GetRecommendations](API_RS_GetRecommendations.md) API 操作中的列。或者，您可以在使用 Amazon Personalize 控制台测试市场活动时指定列。有关代码示例，请参阅[获取实时推荐的物品元数据](getting-recommendations-with-metadata.md)。有关为市场活动启用元数据的信息，请参阅[推荐中的物品元数据](campaigns.md#create-campaign-return-metadata)。有关为推荐器启用元数据的信息，请参阅[在推荐中为 Amazon Personalize 中的域推荐器启用元数据](create-recommender-return-metadata.md)。 + 对于某些应用场景和配方，您可以在推荐请求中指定推广。*推广* 定义了其他业务规则，这些规则适用于可配置的建议物品子集。有关更多信息，请参阅 [通过实时推荐推广物品](promoting-items.md)。 + 您可以根据自定义条件筛选结果。例如，您可能不想推荐用户已经购买的产品，或者只推荐针对特定年龄段的物品。有关更多信息，请参阅 [筛选建议和用户细分](filter.md)。 **注意** 如果您使用了 PERSONALIZED\$1RANKING 自定义食谱，请参阅[获取个性化排名（自定义资源）](rankings.md)。 **Topics** + [推荐评分的工作原理（自定义资源）](#how-recommendation-scoring-works) + [User-Personalization-v2 的推荐理由](#recommendation-reasons) + [获取实时物品推荐](getting-real-time-item-recommendations.md) + [获取实时推荐的物品元数据](getting-recommendations-with-metadata.md) + [通过实时推荐推广物品](promoting-items.md) ## 推荐评分的工作原理（自定义资源） 借助 User-Personalization-v2 和 User-Personalization 配方，Amazon Personalize 可根据用户的交互数据和元数据为物品生成分数。这些分数表示 Amazon Personalize 对于用户是否与接下来的物品交互的相对确定性。分数越高，意味着确定性越大。 **注意** Amazon Personalize 不会显示域推荐器或者 Similar-Items、SIMS 或 Popularity-Count 食谱的分数。有关 Personalized-Ranking 建议分数的信息，请参阅 [个性化排名评分的工作原理](rankings.md#how-ranking-scoring-works)。 Amazon Personalize 会为每个物品生成一个分数，表示该物品与其他物品之间的相对关系，分数范围从 0 到 1（包括 0 和 1）。借助 User-Personalization-v2，Amazon Personalize 可为部分物品生成分数。借助 User-Personalization，Amazon Personalize 可对目录中的所有物品评分。 如果您使用 User-Personalization-v2 并对推荐应用筛选条件，那么根据筛选条件删除的推荐数量，Amazon Personalize 可能会添加占位符物品。这样做是为了符合推荐请求的 `numResults`。这些物品是基于交互数据量的热门物品，符合您的筛选条件。它们没有针对用户的相关性评分。 对于 User-Personalization-v2 和 User-Personalization，所有分数的总和等于 1。例如，如果您要获取用户的影片推荐，并且物品数据集和交互数据集中显示了三部影片，则其分数可能为 `0.6`、`0.3` 和 `0.1`。同样，如果您的库存中有 1 万部电影，则得分最高的电影的分数可能非常小（平均分数为 `.001`），但由于评分是相对的，推荐仍然有效。 在数学术语中，每个用户-物品对（u,i）的分数是根据以下公式计算的，其中 `exp` 是指数函数，w̅u 和 wi/j 分别是用户和物品嵌入内容，希腊字母西格玛（Σ）表示包含分数的所有物品的总和： ![\[描绘了用于计算推荐中每个物品分数的公式。\]](http://docs.aws.amazon.com/zh_cn/personalize/latest/dg/images/get_recommendations_score.png) ## User-Personalization-v2 的推荐理由 如果您使用 User-Personalization-v2，模型通常不会推荐的物品会包含一个 `reason` 清单。这些理由说明了为什么在推荐中包括该物品。可能的原因包括： + 推广物品 - 表示您在推荐请求中应用的推广活动中包括该物品。 + 浏览 - 表示该物品包括在浏览中。使用浏览时，推荐包括的物品具有更少的交互数据或用户相关性。有关浏览的更多信息，请参阅[浏览](https://docs.aws.amazon.com/personalize/latest/dg/use-case-recipe-features.html#about-exploration)。 + 热门物品 - 表示该物品作为占位符热门物品包括在内。如果您使用筛选条件，那么根据筛选条件删除的推荐数量，Amazon Personalize 可能会添加占位符物品以满足推荐请求的 `numResults`。这些物品是基于交互数据的热门物品，符合您的筛选条件。它们没有针对用户的相关性评分。 # 获取实时物品推荐 您可以通过 Amazon Personalize 控制台、AWS Command Line Interface (AWS CLI) 或 AWS SDK 从 Amazon Personalize 推荐器或自定义市场活动中获取实时物品推荐。 **Topics** + [获取物品建议（控制台）](#get-real-time-recommendations-console) + [获取物品建议 (AWS CLI)](#get-item-rec-cli) + [获取物品建议 (AWS SDK)](#get-item-rec-sdk) ## 获取物品建议（控制台） 要通过 Amazon Personalize 控制台获取建议，您需要在推荐器（域数据集组）或自定义市场活动的详情页面上提供请求信息。 **获得建议** 1. 打开 Amazon Personalize 控制台（网址为 [https://console.aws.amazon.com/personalize/home](https://console.aws.amazon.com/personalize/home)），并登录您的账户。 1. 选择包含您要使用的市场活动或推荐器的数据集组。 1. 在导航窗格中，选择**市场活动** 或**推荐器**。 1. 选择目标市场活动或推荐器。 1. 对于活动，在**测试市场活动结果**下，根据您使用的食谱输入建议请求详细信息。对于推荐器，选择**测试推荐器**，然后根据使用案例输入建议请求详细信息。 如果您在用户登录（匿名用户）之前为其记录了事件，则可以通过提供来自这些事件的 `sessionId`（就像是其 `userId`），获取针对此用户的建议。有关为匿名用户记录事件的更多信息，请参阅[为匿名用户记录事件](recording-events.md#recording-anonymous-user-events)。 1. （可选）选择筛选器。有关更多信息，请参阅 [筛选建议和用户细分](filter.md)。 1. 如果您使用上下文元数据，请为每个上下文提供数据。对于每个上下文，为**键** 输入元数据字段。对于**值**，输入上下文数据。有关更多信息，请参阅 [利用上下文元数据提高建议的相关性](contextual-metadata.md)。 1. 如果您在市场活动或推荐器的建议中启用了元数据，请为**物品数据集列**选择要包含在建议结果中的元数据列。有关为市场活动启用元数据的信息，请参阅[推荐中的物品元数据](campaigns.md#create-campaign-return-metadata)。有关为推荐器启用元数据的信息，请参阅[在推荐中为 Amazon Personalize 中的域推荐器启用元数据](create-recommender-return-metadata.md)。 1. 如果您想推广一部分物品，可以选择填写**推广**字段。有关更多信息，请参阅 [通过实时推荐推广物品](promoting-items.md)。 1. 选择**获得建议**。此时，将显示一个包含针对用户推荐的前 25 个物品的表格。如果您使用 User-Personalization-v2，则每个推荐物品都会包含一份理由清单，说明为什么在推荐中包括该物品。有关更多信息，请参阅 [User-Personalization-v2 的推荐理由](recommendations.md#recommendation-reasons)。 ## 获取物品建议 (AWS CLI) 使用以下代码从市场活动中获得建议。要从推荐器中获得建议，请将 `campaign-arn` 参数替换为 `recommender-arn`。 指定要获取建议的用户的 ID 及市场活动或推荐器的 Amazon 资源名称 (ARN)。这时，将显示为用户推荐的前 10 个物品的列表。如果您使用 User-Personalization-v2，则每个推荐物品都会包含一份理由清单，说明为什么在推荐中包括该物品。有关更多信息，请参阅 [User-Personalization-v2 的推荐理由](recommendations.md#recommendation-reasons)。 要更改推荐物品的数量，请更改 `numResults` 的值。默认值为 25 个物品。最大值为 500 个物品。如果您使用 RELATED\$1ITEMS 食谱来训练支持市场活动的解决方案版本，请将 `user-id` 参数替换为 `item-id` 并指定物品 ID。 如果您在用户登录（匿名用户）之前为其记录了事件，则可以通过提供来自这些事件的 `sessionId`（就像是其 `userId`），获取针对此用户的建议。有关为匿名用户记录事件的更多信息，请参阅[为匿名用户记录事件](recording-events.md#recording-anonymous-user-events)。 ``` aws personalize-runtime get-recommendations \ --campaign-arn campaign arn \ --user-id User ID \ --num-results 10 ``` ## 获取物品建议 (AWS SDK) 以下代码展示了如何使用 AWS SDK 从市场活动中为用户获取 Amazon Personalize 推荐。要从推荐器中获得建议，请将 `campaignArn` 参数替换为 `recommenderArn`。 指定要获取建议的用户的 ID 及市场活动或推荐器的 Amazon 资源名称 (ARN)。这时，将显示为用户推荐的前 10 个物品的列表。如果您使用 User-Personalization-v2，则每个推荐物品都会包含一份理由清单，说明为什么在推荐中包括该物品。有关更多信息，请参阅 [User-Personalization-v2 的推荐理由](recommendations.md#recommendation-reasons)。 要更改推荐物品的数量，请更改 `numResults` 的值。默认值为 25 个物品。最大值为 500 个物品。如果您使用 RELATED\$1ITEMS 食谱来训练支持市场活动的解决方案版本，请将 `userId` 参数替换为 `itemId` 并指定物品 ID。 如果您在市场活动或推荐器的建议中启用了元数据，则可以指定要包含在响应中的物品数据集元数据列。有关代码示例，请参阅[在推荐中包括物品元数据（AWS SDK）](getting-recommendations-with-metadata.md#getting-recommendations-with-metadata-sdk)。有关启用元数据的信息，请参阅[推荐中的物品元数据](campaigns.md#create-campaign-return-metadata)。 如果您在用户登录（匿名用户）之前为其记录了事件，则可以通过提供来自这些事件的 `sessionId`（就像是其 `userId`），获取针对此用户的建议。有关为匿名用户记录事件的更多信息，请参阅[为匿名用户记录事件](recording-events.md#recording-anonymous-user-events)。 ------ #### [ SDK for Python (Boto3) ] ``` import boto3 personalizeRt = boto3.client('personalize-runtime') response = personalizeRt.get_recommendations( campaignArn = 'Campaign ARN', userId = 'User ID', numResults = 10 ) print("Recommended items") for item in response['itemList']: print (item['itemId']) ``` ------ #### [ SDK for Java 2.x ] ``` 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 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); } } ``` ------ #### [ SDK for JavaScript v3 ] ``` // Get service clients module and commands using ES6 syntax. import { GetRecommendationsCommand } from "@aws-sdk/client-personalize-runtime"; import { personalizeRuntimeClient } from "./libs/personalizeClients.js"; // Or, create the client here. // const personalizeRuntimeClient = new PersonalizeRuntimeClient({ region: "REGION"}); // Set the recommendation request parameters. export const getRecommendationsParam = { campaignArn: "CAMPAIGN_ARN" /* required */, userId: "USER_ID" /* required */, numResults: 15 /* optional */, }; export const run = async () => { try { const response = await personalizeRuntimeClient.send( new GetRecommendationsCommand(getRecommendationsParam), ); console.log("Success!", response); return response; // For unit tests. } catch (err) { console.log("Error", err); } }; run(); ``` ------ # 获取实时推荐的物品元数据 如果您将市场活动或推荐器配置为返回推荐物品的元数据，则可以指定要包括在 [GetRecommendations](API_RS_GetRecommendations.md) API 操作中的列。或者，您可以在使用 Amazon Personalize 控制台测试市场活动时指定列。 有关为市场活动启用元数据的信息，请参阅[推荐中的物品元数据](campaigns.md#create-campaign-return-metadata)。有关为推荐器启用元数据的信息，请参阅[在推荐中为 Amazon Personalize 中的域推荐器启用元数据](create-recommender-return-metadata.md)。 以下代码示例展示了如何使用 AWS CLI 或 AWS SDK 指定要包括的元数据列。要使用 Amazon Personalize 控制台完成此操作，请在测试市场活动时指定列。有关更多信息，请参阅 [获取物品建议（控制台）](getting-real-time-item-recommendations.md#get-real-time-recommendations-console)。 **Topics** + [在推荐中包括物品元数据（AWS CLI）](#getting-recommendations-with-metadata-cli) + [在推荐中包括物品元数据（AWS SDK）](#getting-recommendations-with-metadata-sdk) ## 在推荐中包括物品元数据（AWS CLI） 如果您在市场活动或推荐器的建议中启用了元数据，则可以指定要包含在响应中的物品数据集元数据列。以下代码示例显示了如何在请求建议时指定元数据列。 ``` aws personalize-runtime get-recommendations \ --campaign-arn campaign arn \ --user-id User ID \ --num-results 10 \ --metadata-columns "{\"ITEMS\": ["\"columnNameA"\","\"columnNameB"\"]}" ``` ## 在推荐中包括物品元数据（AWS SDK） 如果您在市场活动或推荐器的建议中启用了元数据，则可以指定要包含在响应中的物品数据集元数据列。以下代码示例显示了如何在请求建议时指定元数据列。 ``` import boto3 personalizeRt = boto3.client('personalize-runtime') response = personalizeRt.get_recommendations( campaignArn = 'Campaign ARN', userId = 'User ID', numResults = 10 metadataColumns = { "ITEMS": ['columnNameA','columnNameB'] } ) print("Recommended items") for item in response['itemList']: print(item['itemId']) print(item['metadata']) ``` # 通过实时推荐推广物品 对于所有域应用场景和一些自定义配方，您可以在获得实时推荐时指定推广。 *推广* 定义了其他业务规则，这些规则适用于可配置的建议物品子集。例如，您可能有一款流应用程序，想要推广自己的节目和电影，但也想推荐相关的内容。您可以使用推广来指定一定比例的推荐物品必须来自*内部* 类别。根据您的食谱和任何请求筛选器，其余的推荐物品将继续是相关建议。 要应用推广，请在建议请求中指定以下内容： + 要应用推广筛选器的推荐物品的百分比。 + 指定推广标准的筛选器。有关更多信息，请参阅 [推广筛选器](#promotion-filters)。 在建议响应中，推广物品相对于其他推荐物品是随机放置的，但相对于其他推广物品按排序顺序列出。根据您的食谱，不属于推广的推荐物品将按与用户的相关性、受欢迎程度或相似度进行排序。如果没有足够的物品符合推广标准，则结果将包含尽可能多的推广物品。 您可以使用 Amazon Personalize 控制台、AWS Command Line Interface (AWS CLI) 或 AWS SDK 将推广应用于建议。 **Topics** + [支持推广的使用案例和食谱](#promotion-use-case-recipes) + [推广筛选器](#promotion-filters) + [推广新物品](#promoting-new-items) + [推广物品（控制台）](#promoting-items-console) + [推广物品 (AWS CLI)](#promoting-items-cli) + [推广物品 (AWS SDK)](#promoting-items-sdk) ## 支持推广的使用案例和食谱 所有使用案例都支持推广。以下自定义食谱支持推广： + [User-Personalization-v2](native-recipe-user-personalization-v2.md) 和 [User-Personalization](native-recipe-new-item-USER_PERSONALIZATION.md) 配方 + [Similar-Items](native-recipe-similar-items.md) 和 [SIMS](native-recipe-sims.md) 配方 + [Trending-Now](native-recipe-trending-now.md) 和 [热门程度-计数](native-recipe-popularity.md) 配方 ## 推广筛选器 将推广应用于建议请求时，您可以选择一个指定推广标准的筛选器。您可以使用现有筛选器或创建新的筛选器。您可以像在 Amazon Personalize 中创建和管理其他筛选器一样创建和管理推广筛选器。有关创建和管理筛选器的信息，请参阅[筛选结果](filter.md)。 推广筛选器和您在推广之外选择的筛选器（*请求筛选器*）之间的唯一区别是 Amazon Personalize 如何应用它们。推广筛选器仅适用于推广物品，而请求筛选器仅适用于剩余的推荐物品。如果您指定了请求筛选器和推广筛选器，并且想要将这两个筛选器应用于推广物品，则推广筛选器的表达式必须同时包含这两个表达式。合并两个表达式的方式取决于您使用的数据集。有关筛选器表达式、其规则以及如何创建此类内容的更多信息，请参阅[筛选条件表达式](filter-expressions.md)。 **筛选器表达式示例** 以下表达式仅包含“内部”类别中的物品。如果您想在建议中推广自己的内容，则可以使用此表达方式。 ``` INCLUDE ItemID WHERE Items.OWNER IN ("in-house") ``` 以下表达式仅包括在您指定的时间戳之后创建的物品。您可以使用此表达式来推广推荐中的新物品。 ``` INCLUDE ItemID WHERE Items.CREATION_TIMESTAMP > $DATE ``` 以下表达式显示了如何将请求筛选器应用于推广物品。它仅包括作为推广物品的可用服装。在这种情况下，还会在请求筛选器表达式中使用 `Items.AVAILABLE IN ("True")`，因此所有建议都适用于可用的物品。 ``` INCLUDE ItemID WHERE Items.CATEGORY IN ("clothing") AND Items.AVAILABLE IN ("True") ``` 有关筛选器示例的更完整列表，请参阅[筛选器表达式示例](filter-expression-examples.md)。 ## 推广新物品 如果您使用 [User-Personalization-v2 配方](native-recipe-user-personalization-v2.md)，Amazon Personalize 会向用户推荐最相关的物品，并更频繁地推荐带有交互数据的现有物品。为确保推荐中包括一些新物品，您可以根据创建时间戳对包括物品的推荐请求应用推广。 如果您尚未使用推广，则您的筛选条件表达式可以推广在特定日期之后创建的物品： ``` INCLUDE ItemID WHERE Items.CREATION_TIMESTAMP > $DATE ``` 如果您已经在使用推广，则可以创建一个将推广和新物品条件语句关联起来的表达式： ``` INCLUDE ItemID WHERE Items.CATEGORY IN ("clothing") OR Items.CREATION_TIMESTAMP > $DATE ``` ## 推广物品（控制台） 要使用 Amazon Personalize 控制台在建议中推广某些商品，请创建筛选器，然后在建议请求中提供推广详情。有关其他字段的信息，请参阅[获取物品建议（控制台）](getting-real-time-item-recommendations.md#get-real-time-recommendations-console)。 **在建议中推广物品** 1. 打开 Amazon Personalize 控制台（网址为 [https://console.aws.amazon.com/personalize/home](https://console.aws.amazon.com/personalize/home)），并登录您的账户。 1. 选择包含您要使用的市场活动或推荐器的数据集组。 1. 创建一个筛选器来指定推广条件（如果尚未创建）。为推广创建筛选器的方式与创建请求筛选器的方法相同。有关创建和管理筛选器的信息，请参阅[筛选结果](filter.md)。 1. 在导航窗格中，选择**推荐器** 或**活动**。 1. 选择目标市场活动或推荐器。 1. 对于市场活动，在**测试市场活动结果**下，根据您使用的食谱输入建议请求详细信息。对于推荐器，选择**测试推荐器**，然后输入建议请求详细信息。 1. （可选）为请求选择筛选器。此筛选器仅适用于非推广物品。有关创建和管理筛选器的信息，请参阅[筛选结果](filter.md)。 1. 如果您使用上下文元数据，请为每个上下文提供数据。对于每个上下文，为**键** 输入元数据字段。对于**值**，输入上下文数据。有关更多信息，请参阅 [利用上下文元数据提高建议的相关性](contextual-metadata.md)。 1. 对于**推广**，指定以下内容： + **推广物品百分比**：输入要应用推广的推荐物品所占的百分比。 + **筛选器**：选择用于指定推广标准的筛选器。此筛选器适用于推广物品，而不是您在步骤 7 中可能指定的任何请求筛选器。 + **筛选器参数**：如果您的推广使用的筛选器带有占位符参数，请为每个参数输入值以设置筛选条件。要为一个参数使用多个值，请用英文逗号分隔每个值。 1. 选择**获得建议**。此时，将显示一个包含针对用户推荐的前 25 个物品的表格。**推广物品**列显示该物品是否因为您的推广而被收录。推广物品相对于其他推荐物品是随机放置的，但相对于其他推广物品按排序顺序列出。根据您的使用案例或食谱，不属于推广的推荐物品将按与用户的相关性、受欢迎程度或相似度进行排序。如果没有足够的物品符合推广标准，则结果将包含尽可能多的推广物品。 ## 推广物品 (AWS CLI) 以下代码展示了如何使用 AWS CLI 和自定义市场活动在建议中推广物品。要使用推荐器推广物品，请将 `campaign-arn` 参数替换为 `recommender-arn`，并为推荐器指定 Amazon 资源名称 (ARN)。对于推广字段，指定以下内容： + 名称：为推广命名。建议响应使用该名称来标识推广的物品。 + percent-promoted-items：要应用推广的推荐物品所占的百分比。在此示例中，50% 的物品将成为推广物品。 + filterArn：指定用于定义推广条件的筛选器的 Amazon 资源名称 (ARN)。有关更多信息，请参阅 [推广筛选器](#promotion-filters)。 + 参数名称和值：如果您的筛选器表达式有任何参数，请提供参数名称（区分大小写）和值。例如，如果您的筛选器表达式具有 `$GENRE` 参数，请提供 GENRE 作为键，并提供一个或多个类型（例如 *Comedy*）作为值。用英文逗号分隔多个值。使用 AWS CLI 时，对于每个值，都必须使用 `/` 字符对引号和 `/` 字符进行转义。以下代码示例显示如何设置值的格式。 该代码显示了如何同时使用请求筛选器和推广筛选器。推广筛选器仅适用于推广物品，而请求筛选器仅适用于剩余的推荐物品。有关更多信息，请参阅 [推广筛选器](#promotion-filters)。 有关其他字段的信息，请参阅[获取物品建议 (AWS SDK)](getting-real-time-item-recommendations.md#get-item-rec-sdk) 和[使用上下文元数据获得个性化排名](get-personalized-rankings-sdk.md#personalized-ranking-contextual-metadata-example)。 ``` aws personalize-runtime get-recommendations \ --campaign-arn CampaignArn \ --user-id 1 \ --num-results 10 \ --filter-arn RequestFilterArn \ --filter-values '{ "RequestFilterParameterName": "\"value\"", "RequestFilterParameterName": "\"value1\",\"value2\",\"value3\"" }' \ --promotions "[{ \"name\": \"promotionName\", \"percentPromotedItems\": 50, \"filterArn\": \"PromotionFilterARN\", \"filterValues\": {\"PromotionParameterName\":\"\\\"value1, value2\\\"\"} }]" ``` 这时，将显示推荐的物品列表。推广物品相对于其他推荐物品是随机放置的，但相对于其他推广物品按排序顺序列出。根据您的食谱，不属于推广的推荐物品将按与用户的相关性、受欢迎程度或相似度进行排序。如果没有足够的物品符合推广标准，则结果将包含尽可能多的推广物品。 ``` { "itemList": [ { "itemId1": "123", "score": .0117211, "promotionName": "promotionName" }, { "itemId2": "456", "score": .0077976 }, { "itemId3": "789", "score": .0067171 }, ..... ] ``` ## 推广物品 (AWS SDK) 以下代码展示了如何使用 SDK for Python (Boto3)、SDK for Java 2.x 和自定义市场活动在建议中推广物品。要使用推荐器推广物品，请将 `campaignArn` 参数替换为 `recommenderArn`，并为推荐器指定 Amazon 资源名称 (ARN)。对于推广字段，指定以下内容： + 名称：指定推广的名称。建议响应包含该名称来标识推广的物品。 + percentPromotedItems：要应用推广的推荐物品所占的百分比。 + promotionFilterARN：指定用于定义推广条件的筛选器的 Amazon 资源名称 (ARN)。有关更多信息，请参阅 [推广筛选器](#promotion-filters)。 + 任何参数名称和值：如果您的筛选器表达式包含任何参数，请为筛选器表达式中的每个参数提供参数名称（区分大小写）和值。例如，如果您的筛选器表达式具有 `$GENRE` 参数，请提供 `"GENRE"` 作为键，并提供一个或多个类型（例如 "\$1"Comedy"\$1"）作为值。用英文逗号分隔多个值。例如 `"\"comedy\",\"drama\",\"horror"\"`。 以下代码显示了如何同时使用请求筛选器和推广筛选器。推广筛选器仅适用于推广物品，而请求筛选器仅适用于剩余的推荐物品。有关更多信息，请参阅 [推广筛选器](#promotion-filters)。 有关其他字段的信息，请参阅[获取物品建议 (AWS SDK)](getting-real-time-item-recommendations.md#get-item-rec-sdk) 和[使用上下文元数据获得个性化排名](get-personalized-rankings-sdk.md#personalized-ranking-contextual-metadata-example)。 ------ #### [ SDK for Python (Boto3) ] ``` import boto3 personalizeRt = boto3.client('personalize-runtime') response = personalizeRt.get_recommendations( campaignArn = "CampaignARN", userId = '1', numResults = 10, filterArn = 'RequestFilterARN', filterValues = { "RequestFilterParameterName": "\"value1\"", "RequestFilterParameterName": "\"value1\",\"value2\",\"value3\"" .... }, promotions = [{ "name" : "promotionName", "percentPromotedItems" : 50, "filterArn": "promotionFilterARN", "filterValues": { "PromotionParameterName": "\"Value1\",\"Value2\"" ... } }] ) print("Recommended items") for item in response['itemList']: print (item['itemId']) if ("promotionName" in item): print(item['promotionName']) ``` ------ #### [ SDK for Java 2.x ] ``` public static void getRecommendationsWithPromotedItems(PersonalizeRuntimeClient personalizeRuntimeClient, String campaignArn, String userId, String requestFilterArn, String requestParameterName, String requestParameterValue1, String requestParameterValue2, String promotionName, int percentPromotedItems, String promotionFilterArn, String promotionParameterName, String promotionParameterValue1, String promotionParameterValue2) { try { Map promotionFilterValues = new HashMap<>(); promotionFilterValues.put(promotionParameterName, String.format("\"%1$s\",\"%2$s\"", promotionParameterValue1, promotionParameterValue2)); Promotion newPromotion = Promotion.builder() .name(promotionName) .percentPromotedItems(percentPromotedItems) .filterArn(promotionFilterArn) .filterValues(promotionFilterValues) .build(); List promotionList = new List<>(); promotionList.add(newPromotion); Map requestfilterValues = new HashMap<>(); requestfilterValues.put(requestParameterName, String.format("\"%1$s\",\"%2$s\"", requestParameterValue1, requestParameterValue2)); GetRecommendationsRequest recommendationsRequest = GetRecommendationsRequest.builder() .campaignArn(campaignArn) .numResults(20) .userId(userId) .filterArn(requestFilterArn) .fitlerValues(requestFilterValues) .promotions(promotionList) .build(); GetRecommendationsResponse recommendationsResponse = personalizeRuntimeClient.getRecommendations(recommendationsRequest); List items = recommendationsResponse.itemList(); for (PredictedItem item: items) { System.out.println("Item Id is : "+item.itemId()); System.out.println("Item score is : "+item.score()); System.out.println("Promotion name is : "+item.promotionName()); } } catch (PersonalizeRuntimeException e) { System.err.println(e.awsErrorDetails().errorMessage()); System.exit(1); } } ``` ------ #### [ SDK for JavaScript v3 ] ``` // Get service clients and commands using ES6 syntax. import { GetRecommendationsCommand, PersonalizeRuntimeClient } from "@aws-sdk/client-personalize-runtime"; // create personalizeRuntimeClient. const personalizeRuntimeClient = new PersonalizeRuntimeClient({ region: "REGION", }); // set recommendation request param export const getRecommendationsParam = { campaignArn: "CAMPAIGN_ARN", /* required */ userId: "USER_ID", /* required */ numResults: 25, /* optional */ filterArn: "FILTER_ARN", /* provide if you are applying a custom filter */ filterValues: { "PARAM_NAME": "\"PARAM_VALUE\"" /* provide if your filter has a placeholder parameter */ }, promotions: [ { name: "PROMOTION_NAME", /* specify the name of the promotion. The recommendation response includes the name to identify promoted items. */ percentPromotedItems: 50, /* the percentage of recommended items to apply the promotion to. */ filterArn: "PROMOTION_FILTER_ARN", /* the Amazon Resource Name (ARN) of the filter that defines the promotion criteria. */ filterValues: { "PARAM_NAME": "\"PARAM_VALUE\"" /* provide if your promotion filter has a placeholder parameter */ }, }, ], }; export const run = async () => { try { const response = await personalizeRuntimeClient.send(new GetRecommendationsCommand(getRecommendationsParam)); console.log("Success!", "\nItems are: "); response.itemList.forEach(element => console.log(element.itemId)) return response; // For unit tests. } catch (err) { console.log("Error", err); } }; run(); ``` ------ 这时，将显示推荐的物品列表。推广物品相对于其他推荐物品是随机放置的，但相对于其他推广物品按排序顺序列出。根据您的食谱，不属于推广的推荐物品将按与用户的相关性、受欢迎程度或相似度进行排序。如果没有足够的物品符合推广标准，则结果将包含尽可能多的推广物品。 ``` { "itemList": [ { "itemId1": "123", "score": .0117211, "promotionName": "promotionName" }, { "itemId2": "456", "score": .0077976 }, { "itemId3": "789", "score": .0067171 }, ..... ] ``` # Amazon Personalize 中的实时操作推荐 如果您使用 PERSONALIZED\$1ACTIONS 配方，则可以实时从市场活动中获得操作建议。您可以使用 Amazon Personalize 控制台、AWS Command Line Interface (AWS CLI) 或 AWS SDK 获得操作建议。 **Topics** + [操作建议评分的工作原理](#how-action-recommendation-scoring-works) + [获取操作建议（控制台）](#get-action-recommendations-console) + [获取操作建议 (AWS CLI)](#get-action-recommendations-cli-example) + [获取操作建议 (AWS SDK)](#get-action-recommendations-sdk-example) ## 操作建议评分的工作原理 借助 Next-Best-Action 配方，Amazon Personalize 会根据用户将与操作交互的可能性为操作生成分数。分数可以介于 0 - 1.0 之间。越接近 1.0，用户将与操作交互的可能性就越大。 如果您尚未导入任何操作交互数据，则所有建议操作的分数都将为 0.0。如果 Amazon Personalize 在*浏览*过程中建议操作，则该物品的分数将为 0.0。Amazon Personalize 使用浏览来建议没有操作交互数据的操作。有关浏览的更多信息，请参阅[探索](use-case-recipe-features.md#about-exploration)。 ## 获取操作建议（控制台） 要通过 Amazon Personalize 控制台获取建议，您需要在自定义市场活动的详情页面上提供请求信息。 **获取操作建议** 1. 打开 Amazon Personalize 控制台（网址为 [https://console.aws.amazon.com/personalize/home](https://console.aws.amazon.com/personalize/home)），并登录您的账户。 1. 选择包含要使用的市场活动的数据集组。 1. 在导航窗格中，在**自定义资源**下选择**市场活动**。 1. 选择目标市场活动。 1. 在**测试市场活动结果**下，输入您的建议请求详细信息。 如果您在用户登录（匿名用户）之前为其记录了事件，则可以通过提供来自这些事件的 `sessionId`（就像是其 `userId`），获取针对此用户的建议。有关为匿名用户记录事件的更多信息，请参阅[为匿名用户记录事件](recording-events.md#recording-anonymous-user-events)。 1. （可选）选择筛选器。有关更多信息，请参阅 [筛选建议和用户细分](filter.md)。 1. 选择**获得建议**。此时将显示一个表，其中包含向用户建议的前 5 个操作。 ## 获取操作建议 (AWS CLI) 使用以下代码从市场活动中获得操作建议。指定要获取其建议的用户的 ID 及市场活动的 Amazon 资源名称 (ARN)。 要更改建议操作的数量，请更改 `numResults` 的值。默认为 5 个操作。最多为 100 个操作。 要按自定义条件筛选操作建议，您可以创建筛选条件并将其应用于 `get-action-recommendations` 操作。有关更多信息，请参阅 [筛选建议和用户细分](filter.md)。 如果您在用户登录（匿名用户）之前为其记录了事件，则可以通过提供来自这些事件的 `sessionId`（就像是其 `userId`），获取针对此用户的建议。有关为匿名用户记录事件的更多信息，请参阅[为匿名用户记录事件](recording-events.md#recording-anonymous-user-events)。 ``` aws personalize-runtime get-action-recommendations \ --campaign-arn campaign arn \ --user-id User ID \ --num-results 10 ``` ## 获取操作建议 (AWS SDK) 以下代码展示了如何从市场活动中为用户获取 Amazon Personalize 建议。指定要获取其建议的用户的 ID 及市场活动的 Amazon 资源名称 (ARN)。 要更改建议操作的数量，请更改 `numResults` 的值。默认为 5 个操作。最多为 100 个操作。 要按自定义条件筛选操作建议，您可以创建筛选条件并将其应用于 [GetActionRecommendations](API_RS_GetActionRecommendations.md) API 请求。有关更多信息，请参阅 [筛选建议和用户细分](filter.md)。 如果您在用户登录（匿名用户）之前为其记录了事件，则可以通过提供来自这些事件的 `sessionId`（就像是其 `userId`），获取针对此用户的建议。有关为匿名用户记录事件的更多信息，请参阅[为匿名用户记录事件](recording-events.md#recording-anonymous-user-events)。 ``` import boto3 personalizeRt = boto3.client('personalize-runtime') response = personalizeRt.get_action_recommendations( campaignArn = 'Campaign ARN', userId = 'User ID', numResults = 10 ) print("Recommended actions") for item in response['actionList']: print (item['actionId']) ``` # 获取个性化排名（自定义资源） 个性化排名是为特定用户重新排名的推荐物品的列表。要获得个性化排名，请调用 [GetPersonalizedRanking](API_RS_GetPersonalizedRanking.md) API 操作或在控制台中从市场活动中获取建议。 **注意** 必须已使用 PERSONALIZED\$1RANKING 类型的配方创建支持市场活动的解决方案。有关更多信息，请参阅 [选择食谱](working-with-predefined-recipes.md)。 **Topics** + [个性化排名评分的工作原理](#how-ranking-scoring-works) + [获取个性化排名（控制台）](get-ranking-recommendations-console.md) + [获取个性化排名 (AWS CLI)](get-personalized-rankings-cli.md) + [获取个性化排名 (AWS SDK)](get-personalized-rankings-sdk.md) + [Personalized-Ranking 示例笔记本](#real-time-recommendations-personalized-ranking-example) ## 个性化排名评分的工作原理 与使用 User-Personalization-v2 和 User-Personalization 配方创建的解决方案的 `GetRecommendations` 操作返回的分数相似，`GetPersonalizedRanking` 分数总和为 1，但只有输入物品获得分数且推荐分数往往更高。如果某个项目在最近一次训练中不存在，则该项目的分数为 0。 在数学上，GetPersonalizedRanking 的评分函数与 `GetRecommendations` 相同，但它只考虑输入物品。这意味着分数接近 1 的可能性更高，因为将分数进行划分的其他选择更少： ![\[描绘了用于计算评分中每个物品分数的公式。\]](http://docs.aws.amazon.com/zh_cn/personalize/latest/dg/images/get_personalized_ranking.png) # 获取个性化排名（控制台） 要从 Amazon Personalize 控制台获取用户的个性化排名，请选择您要使用的市场活动，然后提供他们的用户 ID，指定您要为该用户排名的物品列表，（可选）选择筛选器，并（可选）提供任何上下文数据。 **获得针对用户的个性化排名** 1. 打开 Amazon Personalize 控制台（网址为 [https://console.aws.amazon.com/personalize/home](https://console.aws.amazon.com/personalize/home)），并登录您的账户。 1. 选择包含要使用的市场活动的数据集组。 1. 在导航窗格中，选择**市场活动**。 1. 在**活动**页面上，选择目标市场活动。 1. 在**测试市场活动结果** 下，输入要为其获取建议的用户的**用户 ID**。 1. 对于**物品 ID**，输入要为用户排名的物品列表。 1. （可选）选择筛选器。有关更多信息，请参阅 [筛选建议和用户细分](filter.md)。 1. 如果您在市场活动的建议中启用了元数据，请为**物品数据集列**选择要包含在建议结果中的元数据列。有关启用元数据的信息，请参阅[推荐中的物品元数据](campaigns.md#create-campaign-return-metadata)。 1. 如果活动使用上下文元数据（有关要求，请参阅[利用上下文元数据提高建议的相关性](contextual-metadata.md)），则可以选择提供上下文数据。 对于每个上下文，为**键** 输入元数据字段，对于**值**，输入上下文数据。 1. 选择**获取个性化物品排名**。此时将显示一个表格，其中包含按用户预期兴趣顺序排名的物品。 # 获取个性化排名 (AWS CLI) 以下代码示例显示了如何使用 AWS CLI 获得个性化排名的不同变体。 **Topics** + [获取个性化排名](#personalized-ranking-cli-sample) + [在个性化排名中包含物品元数据](#getting-personalized-ranking-with-metadata-cli) ## 获取个性化排名 使用以下 `get-personalized-ranking` 命令，通过 AWS CLI 获得个性化排名。指定市场活动的 Amazon 资源名称 (ARN)、用户的用户 ID，并提供要为用户排名的物品的物品 ID 列表（每个项用空格隔开）。要排名的物品必须位于您用于训练解决方案版本的数据中。这将显示已排名的建议列表。Amazon Personalize 会将列表中的第一个物品视为用户最感兴趣的物品。 ``` aws personalize-runtime get-personalized-ranking \ --campaign-arn Campaign ARN \ --user-id 12 \ --input-list 3 4 10 8 12 7 ``` ## 在个性化排名中包含物品元数据 如果您在市场活动的建议中启用了元数据，则可以指定要包含在响应中的物品数据集元数据列。有关启用元数据的信息，请参阅[推荐中的物品元数据](campaigns.md#create-campaign-return-metadata)。 以下代码示例显示了如何在请求个性化排名时指定元数据列。 ``` aws personalize-runtime get-personalized-ranking \ --campaign-arn Campaign ARN \ --user-id 12 \ --input-list 3 4 10 8 12 7 --metadata-columns "{\"ITEMS\": ["\"columnNameA"\","\"columnNameB"\"]}" ``` # 获取个性化排名 (AWS SDK) 以下代码示例显示了如何使用 AWS SDK 获得个性化排名的不同变体。 **Topics** + [获取个性化排名](#personalized-ranking-sdk-sample) + [在个性化排名中包含物品元数据](#getting-personalized-ranking-with-metadata-sdk) + [使用上下文元数据获得个性化排名](#personalized-ranking-contextual-metadata-example) ## 获取个性化排名 以下代码展示了如何为用户获取个性化排名。指定用户的 ID 和要为用户排名的物品 ID 列表。物品 ID 必须位于您用于训练解决方案版本的数据中。这将返回已排名的建议列表。Amazon Personalize 会将列表中的第一个物品视为用户最感兴趣的物品。 ------ #### [ SDK for Python (Boto3) ] ``` import boto3 personalizeRt = boto3.client('personalize-runtime') response = personalizeRt.get_personalized_ranking( campaignArn = "Campaign arn", userId = "UserID", inputList = ['ItemID1','ItemID2'] ) print("Personalized Ranking") for item in response['personalizedRanking']: print (item['itemId']) ``` ------ #### [ SDK for Java 2.x ] ``` public static List getRankedRecs(PersonalizeRuntimeClient personalizeRuntimeClient, String campaignArn, String userId, ArrayList items) { try { GetPersonalizedRankingRequest rankingRecommendationsRequest = GetPersonalizedRankingRequest.builder() .campaignArn(campaignArn) .userId(userId) .inputList(items) .build(); GetPersonalizedRankingResponse recommendationsResponse = personalizeRuntimeClient.getPersonalizedRanking(rankingRecommendationsRequest); List rankedItems = recommendationsResponse.personalizedRanking(); int rank = 1; for (PredictedItem item : rankedItems) { System.out.println("Item ranked at position " + rank + " details"); System.out.println("Item Id is : " + item.itemId()); System.out.println("Item score is : " + item.score()); System.out.println("---------------------------------------------"); rank++; } return rankedItems; } catch (PersonalizeRuntimeException e) { System.err.println(e.awsErrorDetails().errorMessage()); System.exit(1); } return null; } ``` ------ #### [ SDK for JavaScript v3 ] ``` // Get service clients module and commands using ES6 syntax. import { GetPersonalizedRankingCommand } from "@aws-sdk/client-personalize-runtime"; import { personalizeRuntimeClient } from "./libs/personalizeClients.js"; // Or, create the client here. // const personalizeRuntimeClient = new PersonalizeRuntimeClient({ region: "REGION"}); // Set the ranking request parameters. export const getPersonalizedRankingParam = { campaignArn: "CAMPAIGN_ARN" /* required */, userId: "USER_ID" /* required */, inputList: ["ITEM_ID_1", "ITEM_ID_2", "ITEM_ID_3", "ITEM_ID_4"], }; export const run = async () => { try { const response = await personalizeRuntimeClient.send( new GetPersonalizedRankingCommand(getPersonalizedRankingParam), ); console.log("Success!", response); return response; // For unit tests. } catch (err) { console.log("Error", err); } }; run(); ``` ------ ## 在个性化排名中包含物品元数据 如果您在市场活动的建议中启用了元数据，则可以指定要包含在响应中的物品数据集元数据列。有关启用元数据的信息，请参阅[推荐中的物品元数据](campaigns.md#create-campaign-return-metadata)。 以下代码示例显示了如何在请求个性化排名时指定元数据列。 ``` import boto3 personalizeRt = boto3.client('personalize-runtime') response = personalizeRt.get_personalized_ranking( campaignArn = "Campaign arn", userId = "UserID", inputList = ['ItemID1','ItemID2'], metadataColumns = { "ITEMS": ['columnNameA','columnNameB'] } ) print("Personalized Ranking") for item in response['personalizedRanking']: print (item['itemId']) print (item['metadata']) ``` ## 使用上下文元数据获得个性化排名 使用以下代码，根据上下文元数据获取个性化排名。对于 `context`，对于每个键值对，提供元数据字段作为键，提供上下文数据作为值。在以下示例代码中，键为 `DEVICE`，值为 `mobile phone`。替换这些值，将 `Campaign ARN` 和 `User ID` 替换为您自己的值。此外，将 `inputList` 更改为用于训练解决方案的数据中的物品 ID 列表。Amazon Personalize 会将列表中的第一个物品视为用户最感兴趣的物品。 ``` import boto3 personalizeRt = boto3.client('personalize-runtime') response = personalizeRt.get_personalized_ranking( campaignArn = "Campaign ARN", userId = "User ID", inputList = ['ItemID1', 'ItemID2'], context = { 'DEVICE': 'mobile phone' } ) print("Personalized Ranking") for item in response['personalizedRanking']: print(item['itemId']) ``` ## Personalized-Ranking 示例笔记本 有关展示如何使用 Personalized-Ranking 食谱的示例 Jupyter 笔记本，请参阅 [Personalize Ranking 示例](https://github.com/aws-samples/amazon-personalize-samples/blob/master/next_steps/core_use_cases/personalized_ranking/personalize_ranking_example.ipynb)。 # 利用上下文元数据提高建议的相关性 要提高建议相关性，请在获得物品建议或获得个性化排名时添加用户的上下文元数据，例如他们的设备类型或一天中的时间。 要使用上下文元数据，项目交互数据集的架构必须具有上下文数据的元数据字段。例如，DEVICE 字段（请参阅[为 Amazon Personalize 架构创建架构 JSON 文件](how-it-works-dataset-schema.md)）。在考虑用于上下文元数据的字段时，请选择项目交互数据集中历史数据可用值的字段，以及何时获得项目推荐或获得个性化项目排名的字段。 对于域数据集组，以下推荐器使用案例可以使用上下文元数据： + [为您推荐](ECOMMERCE-use-cases.md#recommended-for-you-use-case)（ECOMMERCE 域） + [热门精选](VIDEO_ON_DEMAND-use-cases.md#top-picks-use-case)（VIDEO\$1ON\$1DEMAND 域） 对于自定义资源，使用上下文元数据的食谱包括以下内容： + [User-Personalization-v2](native-recipe-user-personalization-v2.md) 和 [User-Personalization](native-recipe-new-item-USER_PERSONALIZATION.md) + [Personalized-Ranking-v2](native-recipe-personalized-ranking-v2.md) 和 [Personalized-Ranking](native-recipe-search.md) 有关情境信息的更多信息，请参阅以下 M AWS achine Learning 博客文章：[利用情境信息提高 Amazon Personalize 推荐的相关性](https://aws.amazon.com/blogs/machine-learning/increasing-the-relevance-of-your-amazon-personalize-recommendations-by-leveraging-contextual-information/)。 您可以通过 Amazon Personalize 控制台、AWS Command Line Interface (AWS CLI) 或 AWSSDKs，获取包含上下文元数据的推荐。 ## 使用情境相关元数据获取推荐 (AWSPython SDK) 要提高建议相关性，请在获得物品建议或获得个性化排名时添加用户的上下文元数据，例如他们的设备类型或一天中的时间。 使用以下代码，根据上下文元数据获取建议。对于 `context`，对于每个键值对，提供元数据字段作为键，提供上下文数据作为值。在以下示例代码中，键为 `DEVICE`，值为 `mobile phone`。替换这些值，将 `Campaign ARN` 和 `User ID` 替换为您自己的值。如果您创建了推荐器，请将 `campaignArn` 替换为 `recommenderArn`。这时，将显示为用户推荐的物品列表。 ``` import boto3 personalizeRt = boto3.client('personalize-runtime') response = personalizeRt.get_recommendations( campaignArn = 'Campaign ARN', userId = 'User ID', context = { 'DEVICE': 'mobile phone' } ) print("Recommended items") for item in response['itemList']: print (item['itemId']) ``` # 使用自定义资源获取批量物品推荐 借助自定义资源，您可以通过异步批量流获得物品建议。例如，您可以获取电子邮件列表中所有用户的产品建议，或者获得库存中的[物品间相似度](native-recipe-similar-items.md)。 要获取物品的批量建议，您可以使用批量推理作业。*批量推理作业* 是一种工具，可从 Amazon S3 存储桶导入您的批量输入数据，使用您的自定义解决方案版本生成*物品建议*，然后将物品建议导出到 Amazon S3 存储桶。根据食谱，您的输入数据是用户或物品列表，或者是用户列表，每个用户列表都含有一组物品。 如果您的解决方案使用 Similar Items 配方，并且您的物品数据集包含文本数据和物品标题数据，则可以为每组物品生成带有主题的批量建议。有关更多信息，请参阅 [内容生成器中带有主题的批量建议](themed-batch-recommendations.md)。 创建自定义解决方案版本后，新数据如何影响批量物品推荐取决于其类型、导入方法和所用的自定义配方。有关新数据如何影响批量推荐的信息，请参阅[新数据如何影响批量推荐（自定义资源）](how-new-data-influences-batch-recommendations.md)。 **Topics** + [批量工作流程](#batch-worfklow-steps) + [指南和要求](#batch-permissions-req) + [批量工作流程评分](#batch-scoring) + [内容生成器中带有主题的批量建议](themed-batch-recommendations.md) + [为批量建议准备输入数据](batch-data-upload.md) + [创建批量推理作业](creating-batch-inference-job.md) + [批量推理作业输出示例](batch-inference-job-output-examples.md) ## 批量工作流程 批量工作流程如下所示： 1. 准备好您的输入数据并以 JSON 格式将其上传到 Amazon S3 存储桶。输入数据的格式取决于您使用的食谱。请参阅[为批量建议准备输入数据](batch-data-upload.md)。 1. 为输出数据创建一个单独的位置，可以是文件夹，也可以是其他 Amazon S3 存储桶。 1. 创建批量推理作业。请参阅[创建批量推理作业](creating-batch-inference-job.md)。 1. 批量推理完成后，从 Amazon S3 中的输出位置检索物品建议。 ## 指南和要求 以下是获取批量建议的指南和要求： + 您的 Amazon Personalize IAM 服务角色必须有权读取文件并将其添加到您的 Amazon S3 存储桶。有关授予权限的信息，请参阅[批量工作流程的服务角色策略](granting-personalize-s3-access.md#role-policy-for-batch-workflows)。有关存储桶权限的更多信息，请参阅《Amazon Simple Storage Service 开发人员指南》**中的[用户策略示例](https://docs.aws.amazon.com/AmazonS3/latest/userguide/example-policies-s3.html)。如果您使用 AWS Key Management Service (AWS KMS) 进行加密，则必须向 Amazon Personalize 和 Amazon Personalize IAM 服务角色授予使用您密钥的权限。有关更多信息，请参阅 [授予 Amazon Personalize 使用您的 AWS KMS 密钥的权限](granting-personalize-key-access.md)。 + 在创建批量推理作业之前，必须创建自定义解决方案和解决方案版本。不过，您无需创建 Amazon Personalize 市场活动。如果您创建了域数据集组，则仍然可以创建自定义资源。 + 要生成带有建议的主题，您必须使用 Similar-Items 配方。而且您必须有一个包含文本数据和物品标题数据的物品数据集。有关带有主题的建议的更多信息，请参阅[内容生成器中带有主题的批量建议](themed-batch-recommendations.md)。 + 输入数据的格式必须按[为用户细分准备输入数据](prepare-input-data-user-segment.md)所述来设置。 + 您无法通过 Trending-Now 或 Next-Best-Action 配方获得批量建议。 + 如果您使用带有占位符参数的筛选器，则必须在 `filterValues` 对象的输入数据中包含参数的值。有关更多信息，请参阅 [在您的输入 JSON 中提供筛选器值](filter-batch.md#providing-filter-values)。 + 我们建议您使用与输入数据不同的位置来存储输出数据（文件夹或其他 Amazon S3 存储桶）。 + 批量推荐可能与实时推荐不完全相同。这是因为批量推理作业需要更长的时间才能完成，并且仅考虑作业开始前 15 分钟可用的数据。 ## 批量工作流程评分 批量建议包括以下分数： + 对于 User-Personalization 和 Personalized-Ranking 食谱，Amazon Personalize 计算批量推理作业建议分数，如 [推荐评分的工作原理（自定义资源）](recommendations.md#how-recommendation-scoring-works)和 [个性化排名评分的工作原理](rankings.md#how-ranking-scoring-works)所述。您可以在批量推理作业的输出 JSON 文件中查看分数。 + 使用 Similar-Items 配方，如果您获得带有主题的批量建议，Amazon Personalize 会根据主题与每个物品的相关程度对每组相关物品进行排名。每个物品都包含从 0 到 1 的分数。分数越高，该物品与主题的关系就越密切。有关带有主题的建议的更多信息，请参阅[内容生成器中带有主题的批量建议](themed-batch-recommendations.md)。 # 内容生成器中带有主题的批量建议 **重要** 当您获得带有主题的批量建议时，会产生额外的成本。有关更多信息，请参阅 [Amazon Personalize 定价](https://aws.amazon.com/personalize/pricing/)。 如果您使用 [Similar-Items 食谱](native-recipe-similar-items.md)，Amazon Personalize 内容生成器可以向批量建议添加描述性主题。*内容生成器*是一种生成式人工智能功能，由 Amazon Personalize 管理。 当您获得带有主题的批量建议时，Amazon Personalize 内容生成器会为每组相似的物品添加一个描述性主题。该主题基于物品数据集中的物品描述和物品名称数据。Amazon Personalize 将主题包含在批量推理作业的输出中。您可以使用这些主题使应用程序或营销信息中的文本更具吸引力。 例如，如果您收到关于早餐食品的相关物品建议，Amazon Personalize 可能会生成一个主题，例如*快起床吧*或*早晨必备品*。您可以使用该主题来替换通用的轮播标题，例如*经常一起购买*。或者，您可以将该主题纳入促销电子邮件或营销活动中，以获得新的菜单选项。 AWS 不监视内容生成器中的主题。要确认主题质量，您可以使用为每个建议的物品生成的分数。有关更多信息，请参阅 [对带有主题的批量建议进行排名和评分](#themed-batch-rec-scoring)。 **Topics** + [支持的区域](#themes-regions) + [指南和要求](#themed-batch-requirements) + [对带有主题的批量建议进行排名和评分](#themed-batch-rec-scoring) + [生成带有主题的批量建议](#getting-themed-batch-rec) ## 支持的区域 Amazon Personalize 内容生成器仅在以下 AWS 区域推出： + 美国东部（弗吉尼亚州北部） + 美国西部（俄勒冈） + 亚太地区（东京） ## 指南和要求 以下是生成带有主题的建议的指南和要求： + 您的输入文件最多可以有 100 个物品。有关批量建议的输入数据的信息，请参阅[为批量建议准备输入数据](batch-data-upload.md)。 + 您的解决方案必须使用[Similar-Items 食谱](native-recipe-similar-items.md)。 + 您必须拥有包含以下数据的物品数据集。这些数据可以帮助生成更相关的主题。 + 它必须有一个文本字段，例如 DESCRIPTION 字段。有关文本数据的信息，请参阅[非结构化文本元数据](items-datasets.md#text-data)。 + 它必须有一个包含物品名称数据的字符串列，例如 TITLE 字段。 如果您的物品数据集没有此数据，则可以添加它。有关更新现有数据的信息，请参阅[训练后更新数据集中的数据](updating-datasets.md)。 ## 对带有主题的批量建议进行排名和评分 当您收到带有主题的批量建议时，Amazon Personalize 会根据主题与每个物品的相关性程度对每组物品进行排名。每个物品都包含一个大致范围为 -0.1 和 0.6 的分数。分数越高，该物品与主题的关系就越密切。您可以使用分数来设置一个阈值，以仅显示与主题密切相关的物品。 例如，Amazon Personalize 返回的主题可能为 `For your sweet tooth`，相关物品及其分数可能是：硬糖（分数为 0.19884521）、巧克力（分数为 0.17664525）、苹果（分数为 0.08994528）、冰棒（分数为 0.14294521）、红薯（分数为 0.07794527）和胡萝卜（分数为 0.04994523）。在您的应用程序中，您可以添加一条规则，仅包含分数等于 `.10` 或更高的物品，从而去掉水果和蔬菜。 以下示例显示生成带有主题的电影建议的批量推理作业的输出格式。 ``` {"input":{"itemId":"40"},"output":{"recommendedItems":["36","50","44","22","21","29","3","1","2","39"],"theme":"Movies with a strong female lead","itemsThemeRelevanceScores":[0.19994527,0.183059963,0.17478035,0.1618133,0.1574806,0.15468733,0.1499242,0.14353688,0.13531424,0.10291852]}} {"input":{"itemId":"43"},"output":{"recommendedItems":["50","21","36","3","17","2","39","1","10","5"],"theme":"The best movies of 1995","itemsThemeRelevanceScores":[0.184988,0.1795761,0.11143453,0.0989443,0.08258403,0.07952615,0.07115086,0.0621634,-0.138913,-0.188913]}} ... ``` ## 生成带有主题的批量建议 要生成带有主题的批量建议，请按照[批量工作流程](getting-batch-recommendations.md#batch-worfklow-steps)中所述完成批量工作流程。您以与 `RELATED_ITEMS` 配方相同的方式准备输入数据。有关示例，请参阅[RELATED\$1ITEMS 配方](batch-data-upload.md#batch-input-related-items)。 创建批量推理作业时，您可以启用主题生成并指定物品数据集的物品标题列。 + 有关使用 Amazon Personalize 控制台创建用于生成主题的批量推理作业的信息，请参阅[创建批量推理作业](creating-batch-inference-job.md)。 + 有关说明如何使用适用于 Python 的 SDK (Boto3) 创建用于生成主题的批量推理作业的代码示例，请参阅[创建生成主题的批量推理作业](creating-batch-inference-job.md#batch-sdk-themes)。 # 为批量建议准备输入数据 批量推理作业可从 Amazon S3 存储桶导入您的批量输入 JSON 数据，使用您的自定义解决方案版本生成建议，然后将物品建议导出到 Amazon S3 存储桶。在获取批量建议之前，您必须准备好 JSON 文件并将其上传到 Amazon S3 存储桶。我们建议您在 Amazon S3 存储桶中创建输出文件夹，或者使用单独的输出 Amazon S3 存储桶。然后，您可以使用相同的输入数据位置运行多个批量推理作业。 如果您使用带有占位符参数的筛选器（如 `$GENRE`），则必须在输入 JSON 的 `filterValues` 对象中提供参数的值。有关更多信息，请参阅 [在您的输入 JSON 中提供筛选器值](filter-batch.md#providing-filter-values)。 **准备和导入数据** 1. 根据您的食谱设置批量输入数据的格式。您无法通过 Trending-Now 食谱获得批量建议。 + 对于 USER\$1PERSONALIZATION 食谱和 Popularity-Count 食谱，您的输入数据是包含 userId 列表的 JSON 文件 + 对于 RELATED\$1ITEMS 食谱，您的输入数据是 itemID 列表 + 对于 PERSONALIZED\$1RANKING 食谱，您的输入数据是 userId 列表，每个用户 ID 都与一组 itemId 配对 用新行分隔每行。有关输入数据的示例，请参阅[批量推理作业输入和输出 JSON 示例](#batch-inference-job-json-examples)。 1. 将您的输入 JSON 上传到 Amazon S3 存储桶中的输入文件夹。有关更多信息，请参阅《Amazon Simple Storage Service 用户指南》**中的[使用拖放功能上传文件和文件夹](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/upload-objects.html)。 1. 为输出数据创建一个单独的位置，可以是文件夹，也可以是其他 Amazon S3 存储桶。通过为输出 JSON 创建单独的位置，您可以使用相同的输入数据位置运行多个批量推理作业。 1. 创建批量推理作业。Amazon Personalize 会将解决方案版本的建议输出到输出数据位置。 ## 批量推理作业输入和输出 JSON 示例 如何将输入数据格式设置为您使用的食谱的格式。如果您使用带有占位符参数的筛选器（如 `$GENRE`），则必须在输入 JSON 的 `filterValues` 对象中提供参数的值。有关更多信息，请参阅 [在您的输入 JSON 中提供筛选器值](filter-batch.md#providing-filter-values)。 以下各节列出了格式正确的 JSON 批量推理作业输入和输出示例。您无法通过 Trending-Now 食谱获得批量建议。 **Topics** + [USER\$1PERSONALIZATION 食谱](#batch-input-user-personalization) + [POPULAR\$1ITEMS 配方（仅 Popularity-Count）](#batch-input-popular-items) + [PERSONALIZED\$1RANKING 食谱](#batch-input-ranking) + [RELATED\$1ITEMS 配方](#batch-input-related-items) ### USER\$1PERSONALIZATION 食谱 下面显示了 USER\$1PERSONALIZATION 配方的格式正确的 JSON 输入和输出示例。如果您使用 User-Personalization-v2，则每个推荐物品都会包含一份理由清单，说明为什么在推荐中包括该物品。此列表可以为空。有关可能原因的信息，请参阅[User-Personalization-v2 的推荐理由](recommendations.md#recommendation-reasons)。 ------ #### [ Input ] 用新行分隔每个 `userId`，如下所示。 ``` {"userId": "4638"} {"userId": "663"} {"userId": "3384"} ... ``` ------ #### [ Output ] ``` {"input":{"userId":"4638"},"output":{"recommendedItems":["63992","115149","110102","148626","148888","31685","102445","69526","92535","143355","62374","7451","56171","122882","66097","91542","142488","139385","40583","71530","39292","111360","34048","47099","135137"],"scores":[0.0152238,0.0069081,0.0068222,0.006394,0.0059746,0.0055851,0.0049357,0.0044644,0.0042968,0.004015,0.0038805,0.0037476,0.0036563,0.0036178,0.00341,0.0033467,0.0033258,0.0032454,0.0032076,0.0031996,0.0029558,0.0029021,0.0029007,0.0028837,0.0028316]},"error":null} {"input":{"userId":"663"},"output":{"recommendedItems":["368","377","25","780","1610","648","1270","6","165","1196","1097","300","1183","608","104","474","736","293","141","2987","1265","2716","223","733","2028"],"scores":[0.0406197,0.0372557,0.0254077,0.0151975,0.014991,0.0127175,0.0124547,0.0116712,0.0091098,0.0085492,0.0079035,0.0078995,0.0075598,0.0074876,0.0072006,0.0071775,0.0068923,0.0066552,0.0066232,0.0062504,0.0062386,0.0061121,0.0060942,0.0060781,0.0059263]},"error":null} {"input":{"userId":"3384"},"output":{"recommendedItems":["597","21","223","2144","208","2424","594","595","920","104","520","367","2081","39","1035","2054","160","1370","48","1092","158","2671","500","474","1907"],"scores":[0.0241061,0.0119394,0.0118012,0.010662,0.0086972,0.0079428,0.0073218,0.0071438,0.0069602,0.0056961,0.0055999,0.005577,0.0054387,0.0051787,0.0051412,0.0050493,0.0047126,0.0045393,0.0042159,0.0042098,0.004205,0.0042029,0.0040778,0.0038897,0.0038809]},"error":null} ... ``` ------ ### POPULAR\$1ITEMS 配方（仅 Popularity-Count） 下面显示了 Popularity-Count 配方的格式正确的 JSON 输入和输出示例。您无法通过 Trending-Now 食谱获得批量建议。 ------ #### [ Input ] 用新行分隔每个 `userId`，如下所示。 ``` {"userId": "12"} {"userId": "105"} {"userId": "41"} ... ``` ------ #### [ Output ] ``` {"input": {"userId": "12"}, "output": {"recommendedItems": ["105", "106", "441"]}} {"input": {"userId": "105"}, "output": {"recommendedItems": ["105", "106", "441"]}} {"input": {"userId": "41"}, "output": {"recommendedItems": ["105", "106", "441"]}} ... ``` ------ ### PERSONALIZED\$1RANKING 食谱 以下显示了 PERSONALIZED\$1RANKING 配方的格式正确的 JSON 输入和输出示例。 ------ #### [ Input ] 用新行分隔每个 `userId` 和要排名的 `itemIds` 列表，如下所示。 ``` {"userId": "891", "itemList": ["27", "886", "101"]} {"userId": "445", "itemList": ["527", "55", "901"]} {"userId": "71", "itemList": ["27", "351", "101"]} ... ``` ------ #### [ Output ] ``` {"input":{"userId":"891","itemList":["27","886","101"]},"output":{"recommendedItems":["27","101","886"],"scores":[0.48421,0.28133,0.23446]}} {"input":{"userId":"445","itemList":["527","55","901"]},"output":{"recommendedItems":["901","527","55"],"scores":[0.46972,0.31011,0.22017]}} {"input":{"userId":"71","itemList":["29","351","199"]},"output":{"recommendedItems":["351","29","199"],"scores":[0.68937,0.24829,0.06232]}} ... ``` ------ ### RELATED\$1ITEMS 配方 下面显示了 RELATED\$1ITEMS 配方的格式正确的 JSON 输入和输出示例。 ------ #### [ Input ] 用新行分隔每个 `itemId`，如下所示。 ``` {"itemId": "105"} {"itemId": "106"} {"itemId": "441"} ... ``` ------ #### [ Output ] ``` {"input": {"itemId": "105"}, "output": {"recommendedItems": ["106", "107", "49"]}} {"input": {"itemId": "106"}, "output": {"recommendedItems": ["105", "107", "49"]}} {"input": {"itemId": "441"}, "output": {"recommendedItems": ["2", "442", "435"]}} ... ``` ------ 下面显示了带有主题的 Similar-Items 配方的格式正确的 JSON 输入和输出示例。 ------ #### [ Input ] 用新行分隔每个 `itemId`，如下所示。 ``` {"itemId": "40"} {"itemId": "43"} ... ``` ------ #### [ Output ] ``` {"input":{"itemId":"40"},"output":{"recommendedItems":["36","50","44","22","21","29","3","1","2","39"],"theme":"Movies with a strong female lead","itemsThemeRelevanceScores":[0.19994527,0.183059963,0.17478035,0.1618133,0.1574806,0.15468733,0.1499242,0.14353688,0.13531424,0.10291852]}} {"input":{"itemId":"43"},"output":{"recommendedItems":["50","21","36","3","17","2","39","1","10","5"],"theme":"The best movies of 1995","itemsThemeRelevanceScores":[0.184988,0.1795761,0.11143453,0.0989443,0.08258403,0.07952615,0.07115086,0.0621634,-0.138913,-0.188913]}} ... ``` ------ # 创建批量推理作业 创建批量推理作业，根据 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) ## 创建批量推理作业（控制台） 完成[为批量建议准备输入数据](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//.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//** 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) 完成[为批量建议准备输入数据](batch-data-upload.md)后，就可以通过 [CreateBatchInferenceJob](API_CreateBatchInferenceJob.md) 操作创建批量推理作业了。 **Topics** + [创建批量推理作业](#batch-cli-code-sample) + [创建生成主题的批量推理作业](#batch-cli-themes) ### 创建批量推理作业 您可以使用 `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//.json** 和 **s3://amzn-s3-demo-bucket//**。 该示例包括可选的 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\"}}" ``` ### 创建生成主题的批量推理作业 要为相似的物品生成主题，您必须使用 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) 完成[为批量建议准备输入数据](batch-data-upload.md)后，就可以通过 [CreateBatchInferenceJob](API_CreateBatchInferenceJob.md) 操作创建批量推理作业了。 **Topics** + [创建批量推理作业](#batch-sdk-code-sample) + [创建生成主题的批量推理作业](#batch-sdk-themes) ### 创建批量推理作业 可以使用以下代码创建批量推理作业。指定作业名称、解决方案版本的 Amazon 资源名称 (ARN)，以及您在设置期间为 Amazon Personalize 创建的 IAM 服务角色的 ARN。此角色必须对您的输入和输出 Amazon S3 存储桶具有读写权限。 我们建议使用不同的输出数据位置（文件夹或其他 Amazon S3 存储桶）。对输入和输出位置使用以下语法：**s3:/amzn-s3-demo-bucket//.json** 和 **s3://amzn-s3-demo-bucket//**。 对于 `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//.json"}}, jobOutput = {"s3DataDestination": {"path": "s3:/amzn-s3-demo-bucket//"}} ) ``` ------ #### [ 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 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 批量推理作业。 ### 创建生成主题的批量推理作业 要为相似的物品生成主题，您必须使用 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//.json"}}, jobOutput = {"s3DataDestination": {"path": "s3://amzn-s3-demo-bucket//"}} ) ``` # 批量推理作业输出示例 当您创建批量推理作业时，该作业会从 Amazon S3 存储桶导入您的批量输入数据，使用您的解决方案版本生成*物品建议*，并将建议以 JSON 格式导出到 Amazon S3 存储桶。 以下各节按食谱类型列出了批量推理作业的输出文件示例。您无法通过 Trending-Now 或 Next-Best-Action 配方获得批量建议。 **Topics** + [USER\$1PERSONALIZATION 食谱](#batch-inference-output-user-personalization) + [POPULAR\$1ITEMS 食谱](#batch-inference-output-popular-items) + [PERSONALIZED\$1RANKING 食谱](#batch-inference-output-personalized-ranking) + [RELATED\$1ITEMS 配方](#batch-inference-output-related-items) ## USER\$1PERSONALIZATION 食谱 下面是 USER\$1PERSONALIZATION 食谱的输出 JSON 文件示例。 ``` {"input":{"userId":"4638"},"output":{"recommendedItems":["63992","115149","110102","148626","148888","31685","102445","69526","92535","143355","62374","7451","56171","122882","66097","91542","142488","139385","40583","71530","39292","111360","34048","47099","135137"],"scores":[0.0152238,0.0069081,0.0068222,0.006394,0.0059746,0.0055851,0.0049357,0.0044644,0.0042968,0.004015,0.0038805,0.0037476,0.0036563,0.0036178,0.00341,0.0033467,0.0033258,0.0032454,0.0032076,0.0031996,0.0029558,0.0029021,0.0029007,0.0028837,0.0028316]},"error":null} {"input":{"userId":"663"},"output":{"recommendedItems":["368","377","25","780","1610","648","1270","6","165","1196","1097","300","1183","608","104","474","736","293","141","2987","1265","2716","223","733","2028"],"scores":[0.0406197,0.0372557,0.0254077,0.0151975,0.014991,0.0127175,0.0124547,0.0116712,0.0091098,0.0085492,0.0079035,0.0078995,0.0075598,0.0074876,0.0072006,0.0071775,0.0068923,0.0066552,0.0066232,0.0062504,0.0062386,0.0061121,0.0060942,0.0060781,0.0059263]},"error":null} {"input":{"userId":"3384"},"output":{"recommendedItems":["597","21","223","2144","208","2424","594","595","920","104","520","367","2081","39","1035","2054","160","1370","48","1092","158","2671","500","474","1907"],"scores":[0.0241061,0.0119394,0.0118012,0.010662,0.0086972,0.0079428,0.0073218,0.0071438,0.0069602,0.0056961,0.0055999,0.005577,0.0054387,0.0051787,0.0051412,0.0050493,0.0047126,0.0045393,0.0042159,0.0042098,0.004205,0.0042029,0.0040778,0.0038897,0.0038809]},"error":null} ... ``` ## POPULAR\$1ITEMS 食谱 以下示例显示了 Popularity-Count 食谱的输出 JSON 文件的格式。您无法通过 Trending-Now 食谱获得批量建议。 ``` {"input": {"userId": "12"}, "output": {"recommendedItems": ["105", "106", "441"]}} {"input": {"userId": "105"}, "output": {"recommendedItems": ["105", "106", "441"]}} {"input": {"userId": "41"}, "output": {"recommendedItems": ["105", "106", "441"]}} ... ``` ## PERSONALIZED\$1RANKING 食谱 以下示例显示了 PERSONALIZED\$1RANKING 食谱的输出 JSON 文件的格式。 ``` {"input":{"userId":"891","itemList":["27","886","101"]},"output":{"recommendedItems":["27","101","886"],"scores":[0.48421,0.28133,0.23446]}} {"input":{"userId":"445","itemList":["527","55","901"]},"output":{"recommendedItems":["901","527","55"],"scores":[0.46972,0.31011,0.22017]}} {"input":{"userId":"71","itemList":["29","351","199"]},"output":{"recommendedItems":["351","29","199"],"scores":[0.68937,0.24829,0.06232]}} ... ``` ## RELATED\$1ITEMS 配方 以下示例显示了 RELATED\$1ITEMS 食谱的输出 JSON 文件的格式。 ``` {"input": {"itemId": "105"}, "output": {"recommendedItems": ["106", "107", "49"]}} {"input": {"itemId": "106"}, "output": {"recommendedItems": ["105", "107", "49"]}} {"input": {"itemId": "441"}, "output": {"recommendedItems": ["2", "442", "435"]}} ... ``` 以下示例显示了带有主题的 Similar-Items 配方的输出 JSON 文件的格式。有关带有主题的建议的更多信息，请参阅[内容生成器中带有主题的批量建议](themed-batch-recommendations.md)。 ``` {"input":{"itemId":"40"},"output":{"recommendedItems":["36","50","44","22","21","29","3","1","2","39"],"theme":"Movies with a strong female lead","itemsThemeRelevanceScores":[0.19994527,0.183059963,0.17478035,0.1618133,0.1574806,0.15468733,0.1499242,0.14353688,0.13531424,0.10291852]}} {"input":{"itemId":"43"},"output":{"recommendedItems":["50","21","36","3","17","2","39","1","10","5"],"theme":"The best movies of 1995","itemsThemeRelevanceScores":[0.184988,0.1795761,0.11143453,0.0989443,0.08258403,0.07952615,0.07115086,0.0621634,-0.138913,-0.188913]}} ... ``` # 使用自定义资源获取批量用户细分 要获取*用户细分*，您可以使用批量细分作业。*批量细分作业* 是一种工具，可从 Amazon S3 存储桶导入您的批量输入数据，并使用通过 USER\$1SEGMENTATION 食谱训练的解决方案版本为每一行输入数据生成*用户细分*。 根据食谱，输入数据是 JSON 格式的物品列表或物品元数据属性列表。对于物品属性，您的输入数据可以包含基于多个元数据属性创建用户细分的表达式。批量细分作业将用户细分导出到输出 Amazon S3 存储桶。根据每个用户与您输入数据中物品交互的概率，按降序对每个用户细分进行排序。 在生成用户细分时，Amazon Personalize 会考虑来自批量和单独导入的数据集中的数据： + 对于批量数据，Amazon Personalize 仅使用上次完整解决方案版本训练中提供的批量数据生成细分。而且，它仅使用您以 FULL（替换现有数据）导入模式导入的批量数据。 + 对于单独数据导入操作的数据，Amazon Personalize 使用上次完整解决方案版本训练中提供的数据生成用户细分。要让较新的记录影响用户细分，请创建新解决方案版本，然后创建批量细分作业。 生成用户细分的工作原理如下： 1. 准备好您的输入数据并以 JSON 格式将其上传到 Amazon S3 存储桶。输入数据的格式取决于您使用的食谱和要创建的作业。请参阅[为用户细分准备输入数据](prepare-input-data-user-segment.md)。 1. 为输出数据创建一个单独的位置，可以是不同的文件夹，也可以是不同的 Amazon S3 存储桶。 1. 创建批量细分作业。请参阅[使用批量细分作业来获取用户细分](creating-batch-seg-job.md)。 1. 批量细分作业完成后，从 Amazon S3 的输出位置检索用户细分。 **Topics** + [获取用户细分的准则和要求](#batch-seg-permissions-req) + [为用户细分准备输入数据](prepare-input-data-user-segment.md) + [使用批量细分作业来获取用户细分](creating-batch-seg-job.md) + [批量细分作业输出格式示例](batch-segment-job-output-examples.md) ## 获取用户细分的准则和要求 以下是获取批量细分的指南和要求： + 您必须使用 USER\$1SEGMENTATION 食谱。 + 您的 Amazon Personalize IAM 服务角色需要权限来读取文件并将其添加到您的 Amazon S3 存储桶。有关授予权限的信息，请参阅[批量工作流程的服务角色策略](granting-personalize-s3-access.md#role-policy-for-batch-workflows)。有关存储桶权限的更多信息，请参阅《Amazon Simple Storage Service 开发人员指南》**中的[用户策略示例](https://docs.aws.amazon.com/AmazonS3/latest/userguide/example-policies-s3.html)。 如果您使用 AWS Key Management Service (AWS KMS) 进行加密，则必须向 Amazon Personalize 和 Amazon Personalize IAM 服务角色授予使用您密钥的权限。有关更多信息，请参阅 [授予 Amazon Personalize 使用您的 AWS KMS 密钥的权限](granting-personalize-key-access.md)。 + 在创建批量推理作业之前，必须创建自定义解决方案和解决方案版本。不过，您无需创建 Amazon Personalize 市场活动。如果您创建了域数据集组，则仍然可以创建自定义资源。 + 输入数据的格式必须按[为用户细分准备输入数据](prepare-input-data-user-segment.md)所述来设置。 + 如果您使用 Item-Attribute-Affinity 配方，则输入数据中的属性不能包含非结构化文本物品元数据，例如产品描述。 + 如果您使用带有占位符参数的筛选器，则必须在 `filterValues` 对象的输入数据中包含参数的值。有关更多信息，请参阅 [在您的输入 JSON 中提供筛选器值](filter-batch.md#providing-filter-values)。 + 我们建议您使用与输入数据不同的位置来存储输出数据（文件夹或其他 Amazon S3 存储桶）。 # 为用户细分准备输入数据 批量细分作业使用解决方案版本，根据您在输入 JSON 文件中提供的数据进行用户细分。在获取用户细分之前，您必须准备好 JSON 文件并将其上传到 Amazon S3 存储桶。我们建议您在 Amazon S3 存储桶中创建输出文件夹，或者使用单独的输出 Amazon S3 存储桶。然后，您可以使用相同的输入数据位置运行多个批量推理作业。 如果您使用带有占位符参数的筛选器（如 `$GENRE`），则必须在输入 JSON 的 `filterValues` 对象中提供参数的值。有关更多信息，请参阅 [在您的输入 JSON 中提供筛选器值](filter-batch.md#providing-filter-values)。 **准备和导入数据** 1. 根据您的解决方案使用的食谱，设置批量输入数据的格式。用新行分隔输入数据元素。您的输入数据是 itemIds 列表 (Item-Affinity) 或物品属性列表 (Item-Attribute-Affinity)。 + 对于物品属性，输入数据可以包括带有 `AND` 运算符的逻辑表达式，用于为每个查询获取多个物品或属性的用户。有关更多信息，请参阅 [为 Item-Attribute-Affinity 配方指定物品属性](#specifying-item-attributes)。 + 对于物品属性，使用 `\` 字符对输入数据中的任何特殊字符以及单引号或双引号进行转义。 + 有关这两个配方的输入数据示例，请参阅[批量细分作业输入和输出 JSON 示例](#batch-segment-job-json-examples)。 1. 将您的输入 JSON 上传到 Amazon S3 存储桶中的输入文件夹。有关更多信息，请参阅《Amazon Simple Storage Service 用户指南》**中的[使用拖放功能上传文件和文件夹](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/upload-objects.html)。 1. 为输出数据创建一个单独的位置，可以是文件夹，也可以是其他 Amazon S3 存储桶。通过为输出 JSON 创建单独的位置，您可以使用相同的输入数据位置运行多个批量细分作业。 准备好输入数据并将其上传到 Amazon S3 存储桶后，即可使用批量细分作业生成用户细分。有关更多信息，请参阅 [使用批量细分作业来获取用户细分](creating-batch-seg-job.md)。 **Topics** + [为 Item-Attribute-Affinity 配方指定物品属性](#specifying-item-attributes) + [批量细分作业输入和输出 JSON 示例](#batch-segment-job-json-examples) ## 为 Item-Attribute-Affinity 配方指定物品属性 如果您使用 Item-Attribute-Affinity 配方，则您的输入数据是物品属性列表。您可以混用不同列的元数据。例如，一行可能是数字列，下一行可能是类别列。不能使用非结构化文本物品元数据作为物品属性。 您的输入物品元数据可以包含带有 `AND` 运算符的逻辑表达式，用于获取多个属性的用户细分。例如，一行输入数据可能是 `{"itemAttributes": "ITEMS.genres = \"Comedy\" AND ITEMS.genres = \"Action\""}` 或 `{"itemAttributes": "ITEMS.genres = "\Comedy\" AND ITEMS.audience = "\teen\""}`。 当您将两个属性与 `AND` 运算符组合在一起时，您会根据用户交互历史记录创建用户细分，其中包含更有可能与同时具有这两个属性的物品进行交互的用户。与筛选器表达式（使用 `IN` 运算符表示字符串相等）不同，批量细分输入表达式仅支持字符串匹配的相等 `=` 符号。 ## 批量细分作业输入和输出 JSON 示例 对于批量细分作业，您的输入数据必须是 itemIds 列表（Item-Affinity 食谱）或物品属性列表 (Item-Attribute-Affinity)。每行输入数据都是一个单独的推理查询。根据每个用户与您库存物品交互的概率，按降序对每个用户细分进行排序。 如果您使用带有占位符参数的筛选器（如 `$GENRE`），则必须在输入 JSON 的 `filterValues` 对象中提供参数的值。有关更多信息，请参阅 [在您的输入 JSON 中提供筛选器值](filter-batch.md#providing-filter-values)。 以下是按食谱组织的批量细分作业格式正确的 JSON 输入和输出示例。 **Item-Affinity** ------ #### [ Input ] 您的输入数据最多可有 500 个物品。用新行分隔每个 `itemId`，如下所示。 ``` {"itemId": "105"} {"itemId": "106"} {"itemId": "441"} ... ``` ------ #### [ Output ] ``` {"input": {"itemId": "105"}, "output": {"recommendedUsers": ["106", "107", "49"]}} {"input": {"itemId": "106"}, "output": {"recommendedUsers": ["105", "107", "49"]}} {"input": {"itemId": "441"}, "output": {"recommendedUsers": ["2", "442", "435"]}} ... ``` ------ **Item-Attribute-Affinity** ------ #### [ Input ] 您的输入数据最多可以有 10 个查询，其中每个查询都是一个或多个非文本物品属性。用新行分隔每个属性或属性表达式，如下所示。 ``` {"itemAttributes": "ITEMS.genres = \"Comedy\" AND ITEMS.genres = \"Action\""} {"itemAttributes": "ITEMS.genres = \"Comedy\""} {"itemAttributes": "ITEMS.genres = \"Horror\" AND ITEMS.genres = \"Action\""} ... ``` ------ #### [ Output ] ``` {"itemAttributes": "ITEMS.genres = \"Comedy\" AND ITEMS.genres = \"Action\"", "output": {"recommendedUsers": ["25", "78", "108"]}} {"itemAttributes": "ITEMS.genres = \"Adventure\"", "output": {"recommendedUsers": ["87", "31", "129"]}} {"itemAttributes": "ITEMS.genres = \"Horror\" AND ITEMS.genres = \"Action\"", "output": {"recommendedUsers": ["8", "442", "435"]}} ... ``` ------ # 使用批量细分作业来获取用户细分 如果您使用了 USER\$1SEGMENTATION 食谱，则可以创建批量细分作业，以获取解决方案版本的用户细分。根据每个用户与您库存物品交互的概率，按降序对每个用户细分进行排序。根据食谱，您的输入数据必须是 JSON 格式的物品列表（[Item-Affinity 食谱](item-affinity-recipe.md)）或物品属性（[Item-Attribute-Affinity 食谱](item-attribute-affinity-recipe.md)）。您可以使用 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)。 **Topics** + [创建批量细分作业（控制台）](#batch-segment-console) + [创建批量细分作业 (AWS CLI)](#batch-segment-cli) + [创建批量细分作业 (AWS SDKs)](#batch-segment-sdk) ## 创建批量细分作业（控制台） 完成[为批量建议准备输入数据](batch-data-upload.md)后，就可以创建批量细分作业了。此过程假定您已通过 USER\$1SEGEMENTATION 食谱，创建了一个解决方案和一个解决方案版本（经过训练的模型）。 **创建批量细分作业（控制台）** 1. 在[https://console.aws.amazon.com/personalize/家](https://console.aws.amazon.com/personalize/home)中打开 Amazon Personalize 控制台并登录您的账户。 1. 在**数据集组**页面上，选择您的数据集组。 1. 在导航窗格中选择**批量细分作业**，然后选择**创建批量细分作业**。 1. 在**批量细分作业详细信息** 中，对于**批量细分作业名称**，为您的批量细分作业指定一个名称。 1. 对于**解决方案**，选择解决方案，然后选择要用于生成建议的**解决方案版本 ID**。只有使用了 USER\$1SEGEMENTATION 食谱，您才能创建批量细分作业。 1. 对于**用户数量**，可以选择指定 Amazon Personalize 为每个用户细分生成的用户数量。默认值为 25。最大值为 500 万。 1. 对于**输入源**，指定输入文件的 Amazon S3 路径，或者使用**浏览 S3** 选择您的 Amazon S3 存储桶。 使用以下语法：**s3://amzn-s3-demo-bucket//.json** 您的输入数据必须采用与您的解决方案使用的食谱对应的正确格式。有关输入数据的示例，请参阅[批量细分作业输入和输出 JSON 示例](prepare-input-data-user-segment.md#batch-segment-job-json-examples)。 1. 对于**输出目标**，指定输出位置的路径，或使用**浏览 S3** 选择您的 Amazon S3 存储桶。我们建议使用不同的输出数据位置（文件夹或其他 Amazon S3 存储桶）。 使用以下语法：**s3://amzn-s3-demo-bucket//** 1. 对于 **IAM 角色**，选择下列一个选项： + 选择**创建和使用新的服务角色**，然后输入**服务角色名称**以创建新角色，或者 + 如果您已经创建了具有正确权限的角色，请选择**使用现有服务角色**，并选择 IAM 角色。 您使用的角色必须分别对您的输入和输出 Amazon S3 存储桶具有读写权限。 1. 对于**筛选器配置**，可以选择一个过滤器，将筛选器应用于用户细分。如果您的筛选器使用占位符参数，请确保这些参数的值包含在您的输入 JSON 中。有关更多信息，请参阅 [在您的输入 JSON 中提供筛选器值](filter-batch.md#providing-filter-values)。 1. 对于**标签**，可以选择添加任何标签。有关标记 Amazon Personalize 资源的更多信息，请参阅[为 Amazon Personalize 资源添加标签](tagging-resources.md)。 1. 选择**创建批量细分作业**。此时将开始创建批量细分作业，**批量细分作业** 页面将显示，并显示**批量细分作业详细信息** 部分。 1. 当批量细分作业的状态更改为**活动** 时，您可以从指定的输出 Amazon S3 存储桶中检索作业的输出。输出文件的名称将采用 `input-name.out` 格式。 ## 创建批量细分作业 (AWS CLI) 完成[为批量建议准备输入数据](batch-data-upload.md)后，就可以使用以下 `create-batch-segment-job` 代码创建批量细分作业了。指定作业名称，将 `Solution version ARN` 替换为解决方案版本的 Amazon 资源名称 (ARN)，然后将 `IAM service role ARN` 替换为您在设置期间为 Amazon Personalize 创建的 IAM 服务角色的 ARN。此角色必须分别对您的输入和输出 Amazon S3 存储桶具有读写权限。对于 `num-results`，指定您希望 Amazon Personalize 为每行输入数据预测的用户数量。默认值为 25。最大值为 500 万。（可选）提供 `filter-arn` 来筛选用户细分。如果您的筛选器使用占位符参数，请确保这些参数的值包含在您的输入 JSON 中。有关更多信息，请参阅 [筛选批量建议和用户细分（自定义资源）](filter-batch.md)。 将 `S3 input path` 和 `S3 output path` 替换为指向您的输入文件和输出位置的 Amazon S3 路径。我们建议使用不同的输出数据位置（文件夹或其他 Amazon S3 存储桶）。对输入和输出位置使用以下语法：**s3://amzn-s3-demo-bucket//.json** 和 **s3://amzn-s3-demo-bucket//**。 ``` aws personalize create-batch-segment-job \ --job-name Job name \ --solution-version-arn Solution version ARN \ --num-results The number of predicted users \ --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 { "batchSegmentJobArn": "arn:aws:personalize:us-west-2:acct-id:batch-segment-job/batchSegmentJobName" } ``` ## 创建批量细分作业 (AWS SDKs) 完成[为批量建议准备输入数据](batch-data-upload.md)后，就可以通过 `CreateBatchSegmentJob` 操作创建批量细分作业了。以下代码展示了如何创建批量细分作业。为作业命名，指定要使用的解决方案版本的 Amazon 资源名称 (ARN)，为您的 Amazon Personalize IAM 角色指定 ARN，并指定您的输入文件和输出位置的 Amazon S3 路径。您的 IAM 服务角色必须分别对您的输入和输出 Amazon S3 存储桶具有读写权限。 我们建议使用不同的输出数据位置（文件夹或其他 Amazon S3 存储桶）。对输入和输出位置使用以下语法：**s3://amzn-s3-demo-bucket//.json** 和 **s3://amzn-s3-demo-bucket//**。 对于 `numResults`，指定您希望 Amazon Personalize 为每行输入数据预测的用户数量。默认值为 25。最大值为 500 万。（可选）提供 `filterArn` 来筛选用户细分。如果您的筛选器使用占位符参数，请确保这些参数的值包含在您的输入 JSON 中。有关更多信息，请参阅 [筛选批量建议和用户细分（自定义资源）](filter-batch.md)。 ------ #### [ SDK for Python (Boto3) ] ``` import boto3 personalize_rec = boto3.client(service_name='personalize') personalize_rec.create_batch_segment_job ( solutionVersionArn = "Solution version ARN", jobName = "Job name", numResults = 25, filterArn = "Filter ARN", roleArn = "IAM service role ARN", jobInput = {"s3DataSource": {"path": "s3://amzn-s3-demo-bucket//.json"}}, jobOutput = {"s3DataDestination": {"path": "s3://amzn-s3-demo-bucket//"}} ) ``` ------ #### [ SDK for Java 2.x ] ``` public static String createBatchSegmentJob(PersonalizeClient personalizeClient, String solutionVersionArn, String jobName, String filterArn, int numResults, String s3InputDataSourcePath, String s3DataDestinationPath, String roleArn, String explorationWeight, String explorationItemAgeCutOff) { long waitInMilliseconds = 60 * 1000; String status; String batchSegmentJobArn; try { // Set up data input and output parameters. S3DataConfig inputSource = S3DataConfig.builder() .path(s3InputDataSourcePath) .build(); S3DataConfig outputDestination = S3DataConfig.builder() .path(s3DataDestinationPath) .build(); BatchSegmentJobInput jobInput = BatchSegmentJobInput.builder() .s3DataSource(inputSource) .build(); BatchSegmentJobOutput jobOutputLocation = BatchSegmentJobOutput.builder() .s3DataDestination(outputDestination) .build(); CreateBatchSegmentJobRequest createBatchSegmentJobRequest = CreateBatchSegmentJobRequest.builder() .solutionVersionArn(solutionVersionArn) .filterArn(filterArn) .jobInput(jobInput) .jobOutput(jobOutputLocation) .jobName(jobName) .numResults(numResults) .roleArn(roleArn) .build(); batchSegmentJobArn = personalizeClient.createBatchSegmentJob(createBatchSegmentJobRequest) .batchSegmentJobArn(); DescribeBatchSegmentJobRequest describeBatchSegmentJobRequest = DescribeBatchSegmentJobRequest.builder() .batchSegmentJobArn(batchSegmentJobArn) .build(); long maxTime = Instant.now().getEpochSecond() + 3 * 60 * 60; // wait until the batch segment job is complete. while (Instant.now().getEpochSecond() < maxTime) { BatchSegmentJob batchSegmentJob = personalizeClient .describeBatchSegmentJob(describeBatchSegmentJobRequest) .batchSegmentJob(); status = batchSegmentJob.status(); System.out.println("batch segment 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 batchSegmentJobArn; } catch (PersonalizeException e) { System.out.println(e.awsErrorDetails().errorMessage()); } return ""; } ``` ------ #### [ SDK for JavaScript v3 ] ``` // Get service clients module and commands using ES6 syntax. import { CreateBatchSegmentJobCommand } 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 segment job's parameters. export const createBatchSegmentJobParam = { jobName: "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 CreateBatchSegmentJobCommand(createBatchSegmentJobParam), ); console.log("Success", response); return response; // For unit tests. } catch (err) { console.log("Error", err); } }; run(); ``` ------ 处理批处理作业可能需要一段时间才能完成。您可以通过调用 [DescribeBatchSegmentJob](API_DescribeBatchSegmentJob.md) 和传递 `batchSegmentJobArn` 作为输入参数来检查作业的状态。您也可以致电列出您 AWS 环境中的所有 Amazon Personalize 批量细分任务[ListBatchSegmentJobs](API_ListBatchSegmentJobs.md)。 # 批量细分作业输出格式示例 批量细分作业可从 Amazon S3 存储桶导入您的批量输入数据，使用通过 USER\$1SEGMENTATION 食谱训练的解决方案版本生成*用户细分*，并将细分导出到 Amazon S3 存储桶。 以下各节列出了按配方进行的批量细分作业的 JSON 输出示例。 **Topics** + [Item-Affinity](#batch-segment-output-item-affinity) + [Item-Attribute-Affinity](#batch-segment-output-item-attribute-affinity) ## Item-Affinity 以下示例显示了 Item-Affinity 食谱输出 JSON 文件的格式。 ``` {"input": {"itemId": "105"}, "output": {"recommendedUsers": ["106", "107", "49"]}} {"input": {"itemId": "106"}, "output": {"recommendedUsers": ["105", "107", "49"]}} {"input": {"itemId": "441"}, "output": {"recommendedUsers": ["2", "442", "435"]}} ... ``` ## Item-Attribute-Affinity 以下示例显示了 Item-Attribute-Affinity 食谱的输出 JSON 文件的格式。 ``` {"itemAttributes": "ITEMS.genres = \"Comedy\" AND ITEMS.genres = \"Action\"", "output": {"recommendedUsers": ["25", "78", "108"]}} {"itemAttributes": "ITEMS.genres = \"Adventure\"", "output": {"recommendedUsers": ["87", "31", "129"]}} {"itemAttributes": "ITEMS.genres = \"Horror\" AND ITEMS.genres = \"Action\"", "output": {"recommendedUsers": ["8", "442", "435"]}} ... ```