本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 從 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-v2、User-Personalization、Personalized-Ranking-v2、Personalized-Ranking 和 PersonalIZED\$1ACTIONS 配方建立的自訂解決方案，Amazon Personalize 會在建議中包含每個項目的分數。這些分數代表 Amazon Personalize 對於使用者接下來將選取哪些項目或動作的相對確定性。分數越高代表確定性越高。 + 如需 User-Personalization-v2 和 User-Personalization 分數的資訊，請參閱 [建議評分的運作方式 （自訂資源）](recommendations.md#how-recommendation-scoring-works)。 + 如需 PersonalIZED\$1ACTIONS 配方分數的相關資訊，請參閱 [動作建議評分的運作方式](get-action-recommendations.md#how-action-recommendation-scoring-works)。 + 如需 Personalized-Ranking-v2 和 Personalized-Ranking 建議的分數資訊，請參閱 [個人化排名評分的運作方式](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 不會顯示網域推薦者或相似項目、SIMS 或熱門計數配方的分數。如需個人化排名建議分數的資訊，請參閱 [個人化排名評分的運作方式](rankings.md#how-ranking-scoring-works)。 Amazon Personalize 會以 0 到 1 （均含） 的規模產生項目的相對分數。使用 User-Personalization-v2，Amazon Personalize 會為您的項目子集產生分數。透過使用者個人化，Amazon Personalize 會計算目錄中的所有項目。 如果您使用 User-Personalization-v2 並將篩選條件套用至建議，取決於篩選條件移除的建議數量，Amazon Personalize 可能會新增預留位置項目。這樣做是為了滿足您的建議請求`numResults`的 。這些項目是根據滿足篩選條件之互動資料量的熱門項目。他們沒有使用者的相關性分數。 對於 User-Personalization-v2 和 User-Personalization，所有分數的總計等於 1。例如，如果您收到使用者的電影建議，並且有三部電影顯示項目資料集和互動資料集，則他們的分數可能是 `0.6`、 `0.3`和 `0.1`。同樣地，如果您的庫存中有 10，000 部電影，最高評分的電影可能會有非常小的分數 （平均分數為 `.001`)，但由於評分是相對的，因此建議仍然有效。 在數學術語中，每個使用者項目對 (u，i) 的分數是根據下列公式計算，其中 `exp`是指數函數，wu̅ 和 wi/j 分別是使用者和項目內嵌，而希臘字母 sigma (Σ) 代表分數的所有項目總和： ![\[描述用於計算建議中每個項目分數的公式。\]](http://docs.aws.amazon.com/zh_tw/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 SDKs，從 Amazon Personalize 推薦者或自訂行銷活動取得即時項目建議。 **Topics** + [取得項目建議 （主控台）](#get-real-time-recommendations-console) + [取得項目建議 (AWS CLI)](#get-item-rec-cli) + [取得項目建議AWS SDKs)](#get-item-rec-sdk) ## 取得項目建議 （主控台） 若要取得 Amazon Personalize 主控台的建議，請在建議者 （網域資料集群組） 或自訂行銷活動的詳細資訊頁面上提供請求資訊。 **取得建議** 1. 在 [https://console.aws.amazon.com/personalize/home](https://console.aws.amazon.com/personalize/home)：// 開啟 Amazon Personalize 主控台並登入您的帳戶。 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. 選擇 **Get recommendations (取得建議)**。顯示包含使用者前 25 個建議項目的資料表。如果您使用 User-Personalization-v2，則每個建議項目都會包含項目包含在建議中的原因清單。如需詳細資訊，請參閱[User-Personalization-v2 的建議原因](recommendations.md#recommendation-reasons)。 ## 取得項目建議 (AWS CLI) 使用下列程式碼從行銷活動取得建議。若要從推薦者取得建議，請將 `campaign-arn` 參數取代為 `recommender-arn`。 指定您要取得建議的使用者 ID，以及行銷活動或建議者的 Amazon Resource Name (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 SDKs) 下列程式碼說明如何從具有 AWS SDKs行銷活動取得使用者的 Amazon Personalize 建議。若要從推薦者取得建議，請將 `campaignArn` 參數取代為 `recommenderArn`。 指定您要取得建議的使用者 ID，以及行銷活動或建議者的 Amazon Resource Name (ARN)。使用者前 10 個建議項目的清單隨即顯示。如果您使用 User-Personalization-v2，則每個建議項目都會包含項目包含在建議中的原因清單。如需詳細資訊，請參閱[User-Personalization-v2 的建議原因](recommendations.md#recommendation-reasons)。 若要變更建議項目的數量，請變更 的值`numResults`。預設為 25 個項目。上限為 500 個項目。如果您使用 RELATED\$1ITEMS 配方來訓練支援行銷活動的解決方案版本，請將 `userId` 參數取代為 ，`itemId`並指定項目 ID。 如果您在行銷活動或建議者的建議中啟用中繼資料，您可以指定要包含在回應中的項目資料集中繼資料欄。如需程式碼範例，請參閱 [包含項目中繼資料與建議AWS SDKs)](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 SDKs中的中繼資料欄。若要使用 Amazon Personalize 主控台執行此操作，您可以在測試行銷活動時指定資料欄。如需詳細資訊，請參閱[取得項目建議 （主控台）](getting-real-time-item-recommendations.md#get-real-time-recommendations-console)。 **Topics** + [包含項目中繼資料與建議 (AWS CLI)](#getting-recommendations-with-metadata-cli) + [包含項目中繼資料與建議AWS SDKs)](#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 SDKs) 如果您在行銷活動或建議者的建議中啟用中繼資料，您可以指定要包含在回應中的項目資料集中繼資料欄。下列程式碼範例示範如何在建議請求中指定中繼資料資料欄。 ``` 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 SDKs將提升套用至建議。 **Topics** + [支援促銷的使用案例和配方](#promotion-use-case-recipes) + [提升篩選條件](#promotion-filters) + [提升新項目](#promoting-new-items) + [提升項目 （主控台）](#promoting-items-console) + [提升項目 (AWS CLI)](#promoting-items-cli) + [提升項目AWS SDKs)](#promoting-items-sdk) ## 支援促銷的使用案例和配方 所有使用案例都支援促銷。下列自訂配方支援促銷： + [User-Personalization-v2](native-recipe-user-personalization-v2.md) 和 [使用者個人化](native-recipe-new-item-USER_PERSONALIZATION.md)配方 + [類似項目](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. 在 [https://console.aws.amazon.com/personalize/home](https://console.aws.amazon.com/personalize/home)：// 開啟 Amazon Personalize 主控台並登入您的帳戶。 1. 選擇包含您正在使用的行銷活動或建議程式的資料集群組。 1. 如果您尚未建立篩選條件，請建立指定提升條件的篩選條件。您建立提升篩選條件的方式與建立請求篩選條件的方式相同。如需建立和管理篩選條件的資訊，請參閱 [篩選結果](filter.md)。 1. 在導覽窗格中，選擇**建議者**或**行銷活動**。 1. 選擇目標行銷活動或推薦者。 1. 對於行銷活動，在**測試行銷活動結果**下，根據您使用的配方輸入您的建議請求詳細資訊。對於建議者，請選擇**測試建議者**，然後輸入您的建議請求詳細資訊。 1. 選擇性地選擇請求的篩選條件。此篩選條件僅適用於非提升的項目。如需建立和管理篩選條件的資訊，請參閱 [篩選結果](filter.md)。 1. 如果您使用內容中繼資料，請提供每個內容的資料。針對每個內容，針對**金鑰**輸入中繼資料欄位。針對**值**，輸入內容資料。如需詳細資訊，請參閱[提高與內容中繼資料的建議相關性](contextual-metadata.md)。 1. 針對**提升**，請指定下列項目： + **提升項目百分比**：輸入要套用提升的建議項目百分比。 + **篩選條件**：選擇指定提升條件的篩選條件。此篩選條件適用於提升的項目，而不是您在步驟 7 中指定的任何請求篩選條件。 + **篩選條件參數**：如果您的提升使用具有預留位置參數的篩選條件，請針對每個參數輸入值來設定篩選條件。若要對一個參數使用多個值，請以逗號分隔每個值。 1. 選擇 **Get recommendations (取得建議)**。顯示包含使用者前 25 個建議項目的資料表。升級**項目**欄指出該項目是否因為您的提升而包含在內。提升項目會相對於其他建議項目隨機放置，但會相對於其他提升項目按排序排列。根據您的使用案例或配方，不屬於提升一部分的建議項目會依與使用者、熱門度或類似度的相關性排序。如果沒有足夠的項目符合提升條件，結果將包含盡可能多的提升項目。 ## 提升項目 (AWS CLI) 下列程式碼說明如何使用 AWS CLI 和自訂行銷活動提升建議中的項目。若要使用建議程式提升項目，請以 取代 `campaign-arn` 參數，`recommender-arn`並指定建議程式的 Amazon Resource Name (ARN)。針對提升欄位，指定下列項目： + 名稱：為提升命名。建議回應使用 名稱來識別提升的項目。 + percent-promoted-items：要套用提升的建議項目百分比。在此範例中，將提升 50% 的項目。 + filterArn：指定定義提升條件之篩選條件的 Amazon Resource Name (ARN)。如需詳細資訊，請參閱[提升篩選條件](#promotion-filters)。 + 參數名稱和值：如果您的篩選條件表達式有任何參數，請提供參數名稱 （區分大小寫） 和值。例如，如果您的篩選條件表達式有 `$GENRE` 參數，請提供 GENRE 做為索引鍵，並提供類型或類型，例如 *Comedy* 做為值。使用逗號分隔多個值。當您使用 時 AWS CLI，對於每個值，您必須使用 `/` 字元來逸出引號和`/`字元。下列程式碼範例示範如何格式化值。 此程式碼說明如何同時使用請求篩選條件和提升篩選條件。提升篩選條件僅適用於提升的項目，而請求篩選條件僅適用於剩餘的建議項目。如需詳細資訊，請參閱[提升篩選條件](#promotion-filters)。 如需其他欄位的資訊，請參閱 [取得項目建議AWS SDKs)](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 SDKs) 下列程式碼說明如何使用適用於 Python 的 SDK (Boto3) 和適用於 Java 的 SDK 2.x 和自訂行銷活動提升建議中的項目。若要使用建議程式提升項目，請將 `campaignArn` 參數取代為 ，`recommenderArn`並指定建議程式的 Amazon Resource Name (ARN)。針對提升欄位，指定下列項目： + name：指定提升的名稱。建議回應包含識別提升項目的名稱。 + percentPromotedItems：要套用提升的建議項目百分比。 + promotionFilterARN：定義提升條件之篩選條件的 Amazon Resource Name (ARN)。如需詳細資訊，請參閱[提升篩選條件](#promotion-filters)。 + 任何參數名稱和值：如果您的篩選條件表達式有任何參數，請為篩選條件表達式中的每個參數提供參數名稱 （區分大小寫） 和值。例如，如果您的篩選條件表達式有 `$GENRE` 參數，請提供 `"GENRE"`做為索引鍵，以及類型或類型，例如 "\$1"Comedy"\$1" 做為值。使用逗號分隔多個值。例如 `"\"comedy\",\"drama\",\"horror"\"`。 下列程式碼示範如何使用請求篩選條件和提升篩選條件。提升篩選條件僅適用於提升的項目，而請求篩選條件僅適用於剩餘的建議項目。如需詳細資訊，請參閱[提升篩選條件](#promotion-filters)。 如需其他欄位的資訊，請參閱 [取得項目建議AWS SDKs)](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 SDKs取得動作建議。 **Topics** + [動作建議評分的運作方式](#how-action-recommendation-scoring-works) + [取得動作建議 （主控台）](#get-action-recommendations-console) + [取得動作建議 (AWS CLI)](#get-action-recommendations-cli-example) + [取得動作建議AWS SDKs)](#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. 在 [https://console.aws.amazon.com/personalize/home](https://console.aws.amazon.com/personalize/home)：// 開啟 Amazon Personalize 主控台並登入您的帳戶。 1. 選擇包含您正在使用之行銷活動的資料集群組。 1. 在導覽窗格的**自訂資源**下，選擇**行銷活動**。 1. 選擇目標行銷活動。 1. 在**測試行銷活動結果**下，輸入您的建議請求詳細資訊。 如果您在使用者登入之前為他們記錄事件 （匿名使用者），您可以從這些事件提供 `sessionId` 來取得此使用者的建議，就好像是他們的 一樣`userId`。如需記錄匿名使用者事件的詳細資訊，請參閱 [記錄匿名使用者的事件](recording-events.md#recording-anonymous-user-events)。 1. 選擇性地選擇篩選條件。如需詳細資訊，請參閱[篩選建議和使用者客群](filter.md)。 1. 選擇 **Get recommendations (取得建議)**。顯示包含使用者前 5 個建議動作的資料表。 ## 取得動作建議 (AWS CLI) 使用下列程式碼從行銷活動取得動作建議。指定您要取得建議的使用者 ID，以及行銷活動的 Amazon Resource Name (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 SDKs) 下列程式碼說明如何從行銷活動取得使用者的 Amazon Personalize 建議。指定您要取得建議的使用者 ID，以及行銷活動的 Amazon Resource Name (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 SDKs)](get-personalized-rankings-sdk.md) + [個人化執行範例筆記本](#real-time-recommendations-personalized-ranking-example) ## 個人化排名評分的運作方式 就像 `GetRecommendations`操作針對使用 User-Personalization-v2 和 User-Personalization 配方建立的解決方案傳回的分數一樣，`GetPersonalizedRanking`分數總和為 1，但只有輸入項目會收到分數和建議分數通常較高。如果項目在最新的訓練期間不存在，則會獲得 0 分。 在數學上，GetPersonalizedRanking 的評分函數與 `GetRecommendations` 相同，不同之處在於它只考慮輸入項目。這意味著分數接近 1 的可能性越高，因為提高分數的其他選擇較少： ![\[描述用來計算排名中每個項目分數的公式。\]](http://docs.aws.amazon.com/zh_tw/personalize/latest/dg/images/get_personalized_ranking.png) # 取得個人化排名 （主控台） 若要從 Amazon Personalize 主控台取得使用者的個人化排名，請選擇您正在使用的行銷活動，然後提供其使用者 ID、指定您要為使用者排名的項目清單、選擇性選擇篩選條件，以及選擇性提供任何內容資料。 **取得使用者的個人化排名** 1. 在 [https://console.aws.amazon.com/personalize/home](https://console.aws.amazon.com/personalize/home)：// 開啟 Amazon Personalize 主控台並登入您的帳戶。 1. 選擇包含您正在使用之行銷活動的資料集群組。 1. 在導覽窗格中，選擇**行銷活動**。 1. 在**行銷活動**頁面上，選擇目標行銷活動。 1. 在**測試行銷活動結果**下，輸入您要取得建議之使用者的使用者 **ID**。 1. 針對**項目 IDs**，輸入要為使用者排名的項目清單。 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 Resource Name (ARN)、使用者的 User ID，並提供要為使用者排名的項目 IDs 清單 （各自以空格分隔）。要排名的項目必須位於您用來訓練解決方案版本的資料中。隨即顯示排名建議清單。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 SDKs) 下列程式碼範例示範如何使用 AWS SDKs 取得個人化排名的不同變化。 **Topics** + [取得個人化排名](#personalized-ranking-sdk-sample) + [在個人化排名中包含項目中繼資料](#getting-personalized-ranking-with-metadata-sdk) + [使用內容中繼資料取得個人化排名](#personalized-ranking-contextual-metadata-example) ## 取得個人化排名 下列程式碼說明如何取得使用者的個人化排名。指定使用者的 ID 和要為使用者排名的項目 IDs 清單。項目 IDs 必須在您用來訓練解決方案版本的資料中。會傳回排名建議清單。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`請變更為您用來訓練解決方案的資料中的項目 IDs 清單。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']) ``` ## 個人化執行範例筆記本 如需示範如何使用個人化排名配方的範例 Jupyter 筆記本，請參閱[個人化排名範例](https://github.com/aws-samples/amazon-personalize-samples/blob/master/next_steps/core_use_cases/personalized_ranking/personalize_ranking_example.ipynb)。 # 提高與內容中繼資料的建議相關性 為了提高建議相關性，當您取得項目建議或取得個人化排名時，請包含使用者的內容中繼資料，例如其裝置類型或當日時間。 若要使用內容中繼資料，項目互動資料集的結構描述必須具有內容資料的中繼資料欄位。例如，裝置欄位 （請參閱 [為 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) 和 [使用者個人化](native-recipe-new-item-USER_PERSONALIZATION.md) + [Personalized-Ranking-v2](native-recipe-personalized-ranking-v2.md) 和 [個人化排名](native-recipe-search.md) 如需內容資訊的詳細資訊，請參閱下列AWSMachine 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']) ``` # 使用自訂資源取得批次項目建議 透過自訂資源，您可以使用非同步批次流程取得項目建議。例如，您可能會取得電子郵件清單上所有使用者的產品建議，或跨庫存[item-to-item相似性](native-recipe-similar-items.md)。 若要取得項目的批次建議，您可以使用批次推論任務。*批次推論任務*是一種工具，可從 Amazon S3 儲存貯體匯入批次輸入資料、使用您的自訂解決方案版本產生*項目建議*，然後將項目建議匯出至 Amazon S3 儲存貯體。根據配方，您的輸入資料是使用者或項目的清單，或每個項目都有項目集合的使用者清單。 如果您的解決方案使用類似項目配方，而且您有包含文字資料和項目標題資料的項目資料集，您可以為每個項目群組產生具有主題的批次建議。如需詳細資訊，請參閱[來自 Content Generator 的具有主題的批次建議](themed-batch-recommendations.md)。 建立自訂解決方案版本後，新資料如何影響批次項目建議取決於其類型、匯入方法，以及您使用的自訂配方。如需新資料如何影響批次建議的資訊，請參閱 [新資料如何影響批次建議 （自訂資源）](how-new-data-influences-batch-recommendations.md)。 **Topics** + [批次工作流程](#batch-worfklow-steps) + [指導方針和要求](#batch-permissions-req) + [批次工作流程評分](#batch-scoring) + [來自 Content Generator 的具有主題的批次建議](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 行銷活動。如果您建立了網域資料集群組，您仍然可以建立自訂資源。 + 若要產生具有建議的佈景主題，您必須使用類似項目配方。而且，您必須擁有包含文字資料和項目標題資料的項目資料集。如需主題建議的詳細資訊，請參閱 [來自 Content Generator 的具有主題的批次建議](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 分鐘考慮可用的資料。 ## 批次工作流程評分 批次建議包括分數，如下所示： + 透過使用者個人化和個人化執行配方，Amazon Personalize 會計算批次推論任務建議分數，如 [建議評分的運作方式 （自訂資源）](recommendations.md#how-recommendation-scoring-works)和 中所述[個人化排名評分的運作方式](rankings.md#how-ranking-scoring-works)。您可以在批次推論任務的輸出 JSON 檔案中檢視分數。 + 使用類似項目配方，如果您取得主題批次建議，Amazon Personalize 會根據主題對每個項目的相關性，對每個相關項目進行排名。每個項目都包含 0 到 1 的分數。分數越高，項目與佈景主題的關係就越密切。如需 佈景主題建議的詳細資訊，請參閱 [來自 Content Generator 的具有主題的批次建議](themed-batch-recommendations.md)。 # 來自 Content Generator 的具有主題的批次建議 **重要** 當您取得主題的批次建議時，會產生額外費用。如需詳細資訊，請參閱 [Amazon Personalize 定價](https://aws.amazon.com/personalize/pricing/)。 如果您使用 [類似項目配方](native-recipe-similar-items.md)，Amazon Personalize Content Generator 可以將描述性主題新增至批次建議。*Content Generator* 是由 Amazon Personalize 管理的生成式人工智慧 （生成式 AI) 功能。 當您使用主題取得批次建議時，Amazon Personalize Content Generator 會為每個類似的項目集新增描述性主題。佈景主題是以項目描述和項目資料集中的項目名稱資料為基礎。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 Content Generator 僅適用於下列 AWS 區域： + 美國東部 (維吉尼亞北部) + 美國西部 (奧勒岡) + 亞太區域 (東京) ## 準則和要求 以下是使用主題產生建議的指導方針和要求： + 您的輸入檔案最多可有 100 個項目。如需批次建議的輸入資料資訊，請參閱 [準備批次建議的輸入資料](batch-data-upload.md)。 + 您的解決方案必須使用 [類似項目配方](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)、巧克力 （分數 .17664525)、蘋果 （分數 .08994528)、冰棒 （分數 .14294521)、甜洋芋 （分數 .07794527) 和紅根 （分數 .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 配方和熱門計數配方，您的輸入資料是具有 userIds清單的 JSON 檔案 + 對於 RELATED\$1ITEMS 配方，您的輸入資料是 itemIds的清單 + 對於個人化\$1RANKING 配方，您的輸入資料是 userIds 的清單，每個都與 itemIds 的集合配對 使用新行分隔每一列。如需輸入資料範例，請參閱 [批次推論任務輸入和輸出 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 配方 （僅限opularity-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 配方 （僅限opularity-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 ] 使用新行分隔`itemIds`要排名的每個 `userId`和 清單，如下所示。 ``` {"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"]}} ... ``` ------ 以下顯示具有主題的相似項目配方的正確格式 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/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//.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//** 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) 完成 後[準備批次建議的輸入資料](batch-data-upload.md)，您就可以使用 [CreateBatchInferenceJob](API_CreateBatchInferenceJob.md)操作建立批次推論任務。 **Topics** + [建立批次推論任務](#batch-cli-code-sample) + [建立產生佈景主題的批次推論任務](#batch-cli-themes) ### 建立批次推論任務 您可以使用 `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//.json**和 **s3://amzn-s3-demo-bucket//**。 此範例包含選用的使用者個人化配方特定`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\"}}" ``` ### 建立產生佈景主題的批次推論任務 若要產生類似項目的主題，您必須使用類似項目配方，且您的項目資料集必須具有文字欄位和項目名稱資料欄。如需 佈景主題建議的詳細資訊，請參閱 [來自 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) 完成 後[準備批次建議的輸入資料](batch-data-upload.md)，您就可以使用 [CreateBatchInferenceJob](API_CreateBatchInferenceJob.md)操作建立批次推論任務。 **Topics** + [建立批次推論任務](#batch-sdk-code-sample) + [建立產生佈景主題的批次推論任務](#batch-sdk-themes) ### 建立批次推論任務 您可以使用下列程式碼來建立批次推論任務。指定任務名稱、解決方案版本的 Amazon Resource Name (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) ] 此範例包含選用的使用者個人化配方特定`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//.json"}}, jobOutput = {"s3DataDestination": {"path": "s3:/amzn-s3-demo-bucket//"}} ) ``` ------ #### [ 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 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)。 ### 建立產生佈景主題的批次推論任務 若要產生類似項目的主題，您必須使用類似項目配方，且您的項目資料集必須具有文字欄位和項目名稱資料欄。如需 佈景主題建議的詳細資訊，請參閱 [來自 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//.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 配方 下列範例顯示熱門計數配方的輸出 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"]}} ... ``` 下列範例顯示具有主題的類似項目配方的輸出 JSON 檔案格式。如需 佈景主題建議的詳細資訊，請參閱 [來自 Content Generator 的具有主題的批次建議](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 輸入和輸出範例。 **項目親和性** ------ #### [ 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-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/home](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 Resource Name (ARN)，並將 取代`IAM service role ARN`為您在設定期間為 Amazon Personalize 建立的 IAM 服務角色的 ARN。此角色必須分別具有輸入和輸出 Amazon S3 儲存貯體的讀取和寫入存取權。對於 `num-results` ，指定您希望 Amazon Personalize 針對每一行輸入資料預測的使用者數量。預設為 25。上限為 500 萬。選擇性地提供 `filter-arn`來篩選使用者客群。如果您的篩選條件使用預留位置參數，請確定參數的值包含在您的輸入 JSON 中。如需詳細資訊，請參閱[篩選批次建議和使用者區段 （自訂資源）](filter-batch.md)。 `S3 output path` 使用輸入檔案`S3 input 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 Resource Name (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** + [項目親和性](#batch-segment-output-item-affinity) + [Item-Attribute-Affinity](#batch-segment-output-item-attribute-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"]}} ... ```