翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # OpenSearch からの検索結果のパーソナライズ Amazon Personalize を使用すると、オープンソースの OpenSearch または Amazon OpenSearch Service からの結果をユーザー向けにパーソナライズできます。 [OpenSearch](https://opensearch.org/docs/latest) は Apache 2.0 ライセンスに基づく自己管理型のオープンソース検索サービスです。[Amazon OpenSearch Service](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/what-is.html) は、AWS クラウドにおける OpenSearch クラスターのデプロイ、オペレーション、スケーリングを容易にするマネージドサービスです。Amazon OpenSearch Serviceを使用すると、OpenSearch は結果を取得してランク付けします。 クエリ結果をランク付けする際に、OpenSearch は、[BM-25](https://en.wikipedia.org/wiki/Okapi_BM25) と呼ばれる確率的ランキングフレームワークを使用して、関連性スコアを計算します。特定のキーワードがドキュメント内で頻繁に表示される場合、BM-25 はそのドキュメントに対して高い関連性スコアを割り当てます。OpenSearch ランキングでは、クリックスルーデータなどのユーザーの行動は考慮されません。 Amazon Personalize を OpenSearch と一緒に使用すると、Amazon Personalize は、ユーザーの過去の行動、アイテムに関するメタデータ、およびユーザーに関するメタデータに基づいて OpenSearch の結果を再ランク付けします。OpenSearch は、検索レスポンスをアプリケーションに返す前に、再ランク付けを組み込んでいます。OpenSearch の結果にランキングを適用するときに、Amazon Personalize のランキングにどの程度の重みを与えるかを制御できます。 この再ランク付けにより、結果がより魅力的になり、ユーザーの興味に関連性の高いものになります。これにより、アプリケーションのクリックスルー率とコンバージョン率が向上する可能性があります。パーソナライズした検索によって eコマースアプリケーションの結果がどのように改善されるかを説明するユースケース例については、「[ユースケースの例](#opensearch-use-case-example)」を参照してください。 OpenSearch の結果をパーソナライズする前に、「[Amazon Personalize Search Ranking プラグインの要件](plugin-requirements.md)」に記載されている要件を確認してください。 **Topics** + [ ## ユースケースの例 ](#opensearch-use-case-example) + [ ## Amazon Personalize Search Ranking プラグインの仕組み ](#opensearch-plugin-how-it-works) + [ ## 追加情報 ](#open-search-plugin-additional-info) + [ # Amazon Personalize Search Ranking プラグインの要件 ](plugin-requirements.md) + [ # Amazon Personalize を使用した Amazon OpenSearch Service の結果のパーソナライズ ](opensearch-service.md) + [ # Amazon Personalize を使用したオープンソースの Open Search の結果のパーソナライズ ](opensearch-open-source.md) + [ # `personalized_search_ranking` レスポンスプロセッサのフィールド ](opensearch-plugin-pipeline-fields.md) + [ # パイプラインメトリクスの例 ](monitor-response.md) ## ユースケースの例 Amazon Personalize を使用して OpenSearch の結果を再ランク付けすると、検索結果がユーザーにとってより関連性の高いものになります。例えば、自動車を販売する eコマースアプリケーションがあるとします。ユーザーがトヨタ車に関するクエリを入力し、結果をパーソナライズしない場合、OpenSearch はデータ内のキーワードに基づいてトヨタ製自動車のリストを返します。このリストは、すべてのユーザーに対して同じ順序でランク付けされます。 ただし、Amazon Personalize を使用して結果をパーソナライズすると、OpenSearch は特定のユーザーの行動 (クリック数など) に基づいて、これらの車を特定のユーザーに関連性の高い順に再ランク付けします。ユーザーがクリックする可能性が最も高い車が最初にランク付けされます。 OpenSearch の結果をパーソナライズする場合、OpenSearch が Amazon Personalize のランキングに与える重み (強度) を制御できます。この例を続けて、ユーザーが特定の年の特定のタイプの車 (2008 年製のトヨタのプリウスなど) を検索する場合、OpenSearch の元のランキングにさらに重点を置く必要があるかもしれません。 ただし、結果が広範囲に及ぶ一般的なクエリ (トヨタの全車両を検索する場合など) では、パーソナライゼーションに重点を置くことがあります。これにより、リスト上部にある車が、特定のユーザーにとってより関連性の高いものになります。 ## Amazon Personalize Search Ranking プラグインの仕組み 次の図は、Amazon Personalize Search Ranking プラグインの動作を示しています。 ![\[プラグインを使用して OpenSearch の結果をパーソナライズするときの動作を示しています。\]](http://docs.aws.amazon.com/ja_jp/personalize/latest/dg/images/opensearch-plugin-how-it-works.png) 1. 顧客のクエリを OpenSearch サービスドメインまたはオープンソースの OpenSearch クラスターに送信します。 1. OpenSearch は、クエリレスポンス (クエリに関連する項目のリスト) とユーザーの ID を Amazon Personalize Search Ranking プラグインに送信します。 1. プラグインは、レスポンス内のアイテムとユーザーを Amazon Personalize キャンペーンに送信してランキングを求めます。検索パイプライン内のレシピとキャンペーンの Amazon リソースネーム (ARN) の値を使用して、ユーザーごとにカスタマイズされたランキングを取得します。レコメンデーションには GetPersonalizedRanking API オペレーションを使用します。リクエストでは、クエリを実行したユーザーの userId と、`inputList` の OpenSearch クエリから返されたアイテムを渡します。 1. Amazon Personalize は、再ランク付けされた結果をプラグインに返します。 1. プラグインは検索結果を並べ替え、お使いの OpenSearch Service ドメインまたはオープンソースの OpenSearch クラスターに返します。Amazon Personalize キャンペーンからの反応と、設定時に指定したパーソナライゼーションの強調に基づいて、結果が再ランク付けされます。 1. オープンソースの OpenSearch クラスターまたは OpenSearch Service ドメインは、最終結果をアプリケーションに返します。 ## 追加情報 次のリソースでは、OpenSearch の使用に関する追加情報を提供します。 + OpenSearch の開始方法については、「[クイックスタート](https://opensearch.org/docs/quickstart)」を参照してください。 + OpenSearch Service の使用を開始する方法については、**「Amazon OpenSearch Service デベロッパーガイド」の「[Amazon OpenSearch Service の開始](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/gsg.html)」を参照してください。 + Amazon Personalize の Personalized-Ranking レシピの詳細については、「[Personalized-Ranking-v2 レシピ](native-recipe-personalized-ranking-v2.md)」または「[Personalized-Ranking レシピ](native-recipe-search.md)」を参照してください。 # Amazon Personalize Search Ranking プラグインの要件 OpenSearch の結果をパーソナライズする前に、Amazon Personalize Search Ranking プラグインに関する以下のガイドラインと要件に注意してください。 + OpenSearch のバージョン 2.9.0 以降を使用する必要があります。Amazon OpenSearch Service を使用する場合、ドメインにはバージョン 2.9 以降を使用する必要があります。 + お持ちでない場合は、[アクセス許可のセットアップ](aws-personalize-set-up-permissions.md) の手順を完了して Amazon Personalize にアクセスする許可をユーザーに与え、Amazon Personalize のリソースにアクセスする許可を Amazon Personalize に与えます。 + お使いの OpenSearch Service ドメインまたはオープンソースの OpenSearch クラスターから Amazon Personalize リソースにアクセスできる必要があります。 + OpenSearch Service ドメインへのアクセス許可を付与する方法については、「[Amazon OpenSearch Service の設定](opensearch-granting-access-managed.md)」を参照してください。 + OpenSearch クラスターへのアクセス許可の付与については、「[オープンソースの OpenSearch アクセス許可のセットアップ](opensearch-granting-access.md)」を参照してください。 + Amazon Personalize のカスタムリソースのみを使用できます。ドメインデータセットグループを作成した場合でも、カスタムリソースを追加できます。 + カスタムレシピ [Personalized-Ranking-v2 レシピ](native-recipe-personalized-ranking-v2.md) または [Personalized-Ranking レシピ](native-recipe-search.md) のみを使用できます。 + Amazon Personalize でアイテムインタラクションデータセットを作成する必要があります。アイテムデータセットとユーザーデータセットはオプションです。 + Amazon Personalize Search Ranking プラグインを使用している場合、Amazon Personalize フィルターを適用することはできません。 + デフォルトでは、プラグインは OpenSearch のインデックス付きドキュメントの `_id` が Amazon Personalize データの itemId と一致することを前提としています。OpenSearch データが Amazon Personalize の itemId に対応する別のフィールドを使用している場合は、プラグインを設定するときにフィールドの名前を指定する必要があります。 + クエリを実行するユーザーに使用するユーザー userId は、Amazon Personalize にインポートするデータのuserId と一致する必要があります。 + このプラグインは OpenSearch からの検索結果の上位 500 件のみを再ランク付けします。残りのアイテムは再ランク付けされず、リスト末尾に表示されます。 # Amazon Personalize を使用した Amazon OpenSearch Service の結果のパーソナライズ Amazon OpenSearch Service からの OpenSearch の結果をパーソナライズするには、次の操作を行います。 1. **Amazon Personalize のセットアップ** — まだセットアップをしていない場合は、[Amazon Personalize の設定](setup.md) のステップを実行して認証情報を設定し、Amazon Personalize のアクセス権限を設定します。OpenSearch の結果をパーソナライズするために AWS SDKs を設定する必要はありません。 1. **Amazon Personalize ワークフローの完了** – Amazon Personalize ワークフローを完了すると、データのインポート、Personalized-Ranking-v2 を使ったソリューションの作成、カスタムソリューションバージョンのトレーニング、キャンペーンへのデプロイが可能になります。アイテムインタラクションデータセットを作成する必要があります。ユーザーデータセットとアイテムデータセットはオプションです。詳細については、「[Amazon Personalize のワークフローの詳細](personalize-workflow.md)」を参照してください。 1. **アクセス許可の設定** — OpenSearch Service ドメインから Amazon Personalize リソースにアクセスできるようにアクセス許可を設定します。詳細については、「[アクセス許可のセットアップ](opensearch-granting-access-managed.md)」を参照してください。 1. **Amazon Personalize Search Ranking プラグインをインストールする** — このプラグインは、Amazon Personalize との通信と結果の再ランク付けを処理します。OpenSearch Service ドメインにプラグインをインストールする方法については、「[プラグインのインストール](open-search-install-managed.md)」を参照してください。 1. **Amazon Personalize Search Ranking プラグインの設定** — プラグインを設定するには、検索パイプラインを作成します。*検索パイプライン*は、リクエストプロセッサとレスポンスプロセッサのセットです。プラグインのパイプラインを作成するときは、`personalized_search_ranking` レスポンスプロセッサで Amazon Personalize リソースを指定します。また、プラグインが結果を再ランク付けするときに Amazon Personalize からの結果に与える重みも設定します。詳細については、「[パイプラインの作成](managed-opensearch-plugin-pipeline-example.md)」を参照してください。 1. **Amazon Personalize Search Ranking プラグインを OpenSearch クエリに適用する** — `personalized_search_ranking` レスポンスプロセッサを使用して検索パイプラインを設定し、Amazon Personalize Search Ranking プラグインを OpenSearch クエリに適用すると、再ランク付けされた結果を表示できるようになります。OpenSearch Service クエリにプラグインを適用する方法については、「[プラグインの適用](managed-apply-plugin.md)」を参照してください。 1. **結果の比較** — Amazon Personalize Search Ranking プラグインは、OpenSearch クエリレスポンス内の検索結果をランク付けし直します。Amazon Personalize のランキングと OpenSearch のランキングの両方が考慮されます。結果がどのように再ランク付けされるかを理解するには、パーソナライゼーションを使用するクエリと使用しないクエリの結果を比較できます。結果を OpenSearch Service と比較する方法については、「[結果の比較](managed-comparing-results.md)」を参照してください。 1. **Amazon Personalize Search Ranking プラグインの監視** — Amazon Personalize Search Ranking プラグインを検索クエリに適用すると、検索パイプラインのメトリクスを取得してプラグインを監視できます。OpenSearch Service でプラグインをモニタリングする方法については、「[プラグインの監視](managed-monitor.md)」を参照してください。 **Topics** + [ # Amazon OpenSearch Service の設定 ](opensearch-granting-access-managed.md) + [ # OpenSearch Service ドメインで Amazon Personalize Search Ranking プラグインをインストールする ](open-search-install-managed.md) + [ # Amazon OpenSearch Service のパイプラインを作成する ](managed-opensearch-plugin-pipeline-example.md) + [ # Amazon OpenSearch Service クエリへのプラグインの適用 ](managed-apply-plugin.md) + [ # パーソナライズされた Amazon OpenSearch Service の結果をパーソナライズされていない結果と比較する ](managed-comparing-results.md) + [ # Amazon OpenSearch Service の監視 ](managed-monitor.md) # Amazon OpenSearch Service の設定 Amazon OpenSearch Service を使用する場合は、OpenSearch Service ドメインから Amazon Personalize リソースにアクセスできる必要があります。 **アクセス許可を設定するには** 1. リソースが同じアカウントにあるか異なるアカウントにあるかに応じて、リソースにアクセスするアクセス許可を持つ 1 つ以上の IAM サービスロールを作成します。 + OpenSearch Service リソースと Amazon Personalize リソースが同じアカウントにある場合、OpenSearch Service 用の IAM サービスロールを作成し、Amazon Personalize キャンペーンからパーソナライズされたランキングを取得するアクセス許可を付与します。詳細については、「[リソースが同じアカウントにある場合のアクセス許可の設定](service-role-managed.md)」を参照してください。 + OpenSearch Service リソースと Amazon Personalize リソースが別々のアカウントにある場合は、2 つの IAM サービスロールを作成します。OpenSearch Service リソースを使用してアカウント内に 1 つを作成し、OpenSearch Service リソースへのアクセスを許可します。また、Amazon Personalize リソースを使用してアカウント内に 1 つを作成し、Amazon Personalize キャンペーンからパーソナライズされたランキングを取得するアクセス許可を付与します。詳細については、「[リソースが異なるアカウントにある場合のアクセス許可の設定](configuring-multiple-accounts.md)」を参照してください。 1. OpenSearch Service ドメインにアクセスするユーザーまたはロールに、OpenSearch Service 用に作成した IAM サービスロールの `PassRole` アクセス許可を付与します。詳細については、「[Amazon OpenSearch Service のドメインセキュリティの設定](domain-user-managed.md)」を参照してください。 アクセス許可を設定したら、ドメインにプラグインをインストールする準備が整います。詳細については、「[プラグインのインストール](open-search-install-managed.md)」を参照してください。 **Topics** + [ # リソースが同じアカウントにある場合のアクセス許可の設定 ](service-role-managed.md) + [ # リソースが異なるアカウントにある場合のアクセス許可の設定 ](configuring-multiple-accounts.md) + [ # Amazon OpenSearch Service のドメインセキュリティの設定 ](domain-user-managed.md) # リソースが同じアカウントにある場合のアクセス許可の設定 OpenSearch Service リソースと Amazon Personalize リソースが同じアカウントにある場合、OpenSearch Service 用の IAM サービスロールを作成する必要があります。このロールには、Amazon Personalize キャンペーンからパーソナライズされたランキングを取得するためのアクセス許可が必要です。Amazon Personalize キャンペーンからパーソナライズされたランキングを取得する許可を OpenSearch Service サービスロールに付与するには、以下が必要です。 + ロールの信頼ポリシーは OpenSearch Service への `AssumeRole` アクセス許可を付与する必要があります。信頼ポリシーの例については、「[信頼ポリシーの例](#opensearch-granting-access-managed-trust-policy)」を参照してください。 + ロールには、Amazon Personalize キャンペーンからパーソナライズされたランキングを取得する許可が必要です。ポリシーの例については「[アクセス許可ポリシーの例](#opensearch-granting-access-managed-permissions-policy)」を参照してください。 IAM ロールの作成の詳細については、「*IAM ユーザーガイド*」の「[IAM ロールを作成する](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html)」を参照してください。ロールへの IAM ポリシーのアタッチについては、**「IAM ユーザーガイド」の「[IAM ID のアクセス許可の追加および削除](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html)」を参照してください。 OpenSearch Service 用の IAM サービスロールを作成したら、OpenSearch Service ドメインにアクセスするユーザーまたはロールに、OpenSearch Service サービスロールの `PassRole` アクセス許可を付与する必要があります。詳細については、「[Amazon OpenSearch Service のドメインセキュリティの設定](domain-user-managed.md)」を参照してください。 **Topics** + [ ## 信頼ポリシーの例 ](#opensearch-granting-access-managed-trust-policy) + [ ## アクセス許可ポリシーの例 ](#opensearch-granting-access-managed-permissions-policy) ## 信頼ポリシーの例 以下の信頼ポリシーの例では、OpenSearch Service に `AssumeRole` アクセス許可を付与しています。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [{ "Sid": "", "Effect": "Allow", "Action": "sts:AssumeRole", "Principal": { "Service": [ "es.amazonaws.com" ] } }] } ``` ------ ## アクセス許可ポリシーの例 次のポリシー例では、Amazon Personalize キャンペーンからパーソナライズされたランキングを取得するための最低限のアクセス許可をロールに付与しています。`Campaign ARN` には、Amazon Personalize キャンペーンの Amazon リソースネーム (ARN) を指定します。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "personalize:GetPersonalizedRanking" ], "Resource": "arn:aws:personalize:us-east-1:111122223333:campaign/YourResourceId" } ] } ``` ------ # リソースが異なるアカウントにある場合のアクセス許可の設定 OpenSearch Service リソースと Amazon Personalize リソースが別々のアカウントにある場合は、各アカウントに IAM ロールを作成し、そのロールにアカウントのリソースへのアクセスを許可します。 **複数のアカウントのアクセス許可を設定するには** 1. Amazon Personalize キャンペーンが存在するアカウントで、Amazon Personalize キャンペーンからパーソナライズされたランキングを取得するアクセス許可を持つ IAM ロールを作成します。プラグインを設定するときは、`personalized_search_ranking` レスポンスプロセッサの `external_account_iam_role_arn` パラメータでこのロールの ARN を指定します。詳細については、「[Amazon OpenSearch Service のパイプラインを作成する](managed-opensearch-plugin-pipeline-example.md)」を参照してください。 ポリシーの例については「[アクセス許可ポリシーの例](service-role-managed.md#opensearch-granting-access-managed-permissions-policy)」を参照してください。 1. OpenSearch Service ドメインが存在するアカウントで、OpenSearch Service の `AssumeRole` アクセス許可を付与する信頼ポリシーを持つロールを作成します。プラグインを設定するときは、`personalized_search_ranking` レスポンスプロセッサの `iam_role_arn` パラメータでこのロールの ARN を指定します。詳細については、「[Amazon OpenSearch Service のパイプラインを作成する](managed-opensearch-plugin-pipeline-example.md)」を参照してください。 信頼ポリシーの例については、「[信頼ポリシーの例](service-role-managed.md#opensearch-granting-access-managed-trust-policy)」を参照してください。 1. 各ロールを変更して、他のロールの `AssumeRole` アクセス許可を付与します。例えば、Amazon Personalize リソースにアクセスできるロールの場合、その IAM ポリシーは OpenSearch Service ドメインのアカウントのロールに、次のようにロール継承アクセス許可を付与します。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [{ "Sid": "", "Effect": "Allow", "Action": "sts:AssumeRole", "Resource": "arn:aws:iam::111122223333:role/roleName" }] } ``` ------ 1. OpenSearch Service ドメインが存在するアカウントで、OpenSearch Service ドメインにアクセスするユーザーまたはロールに、先ほど作成した OpenSearch Service サービスロールの `PassRole` アクセス許可を付与します。詳細については、「[Amazon OpenSearch Service のドメインセキュリティの設定](domain-user-managed.md)」を参照してください。 # Amazon OpenSearch Service のドメインセキュリティの設定 OpenSearch Service でプラグインを使用するには、ドメインにアクセスするユーザーまたはロールが、先ほど作成した [OpenSearch Service 用の IAM サービスロール](service-role-managed.md)に対する `PassRole` アクセス許可を持っている必要があります。また、ユーザーまたはロールには、`es:ESHttpGet` および `es:ESHttpPut` アクションを実行するためのアクセス許可が必要です。 OpenSearch Service へのアクセス許可の設定については、**「Amazon OpenSearch Service デベロッパーガイド」の「[Amazon OpenSearch Service のセキュリティ](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/security.html)」を参照してください。IAM ポリシーの例については、「[OpenSearch Service のユーザーまたはロールのポリシー例](#opensearch-domain-user-policy-examples)」を参照してください。 ## OpenSearch Service のユーザーまたはロールのポリシー例 次の IAM ポリシーの例では、[リソースが同じアカウントにある場合のアクセス許可の設定](service-role-managed.md) で作成した OpenSearch Service 用の IAM サービスロールの `PassRole` アクセス許可をユーザーまたはロールに付与します。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Action": "iam:PassRole", "Resource": "arn:aws:iam::111122223333:role/aws-service-role/opensearchservice.amazonaws.com/AWSServiceRoleForAmazonOpenSearchService" } ] } ``` ------ 次の IAM ポリシーは、OpenSearch Service でパイプラインと検索クエリを作成するための最低限の許可を付与します。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Action": [ "es:ESHttpGet", "es:ESHttpPut" ], "Effect": "Allow", "Resource": "*", "Condition": { "ForAnyValue:StringEquals": { "aws:ResourceTag/environment": [ "production" ] } } } ] } ``` ------ # OpenSearch Service ドメインで Amazon Personalize Search Ranking プラグインをインストールする Amazon Personalize ワークフローを完了し、[プラグインの要件](plugin-requirements.md) に記載されている要件を満たしたら、ドメインでプラグインをインストールする準備が整います。 プラグインを使用するには、`Amazon_Personalize_Search_Ranking_Plugin` プラグインをドメインに関連付けます。プラグインはプリインストールされており、Amazon S3 からインポートする必要はありません。OpenSearch Service パッケージを関連付けるのと同じ方法でプラグインを関連付けます。OpenSearch Service パッケージの関連付けについては、「[Amazon OpenSearch Serviceのカスタムパッケージ](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/custom-packages.html#custom-packages-assoc)」を参照してください。 プラグインをドメインに関連付けると、プラグインを設定する準備が整います。検索パイプラインを作成し、`personalized_search_ranking` レスポンスプロセッサを指定して設定します。詳細については、「[パイプラインの作成](managed-opensearch-plugin-pipeline-example.md)」を参照してください。 ## Amazon OpenSearch Service ドメインに関する追加情報 次のリソースでは、Amazon OpenSearch Service ドメインの使用に関する追加情報を提供します。 + テストドメインを設定するための簡潔なチュートリアルについては、**「Amazon OpenSearch Service デベロッパーガイド」の「はじめに」セクションの「[ステップ 1: Amazon OpenSearch Service ドメインを作成する](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/gsg.html#gsgcreate-domain)」を参照してください。 + OpenSearch Service ドメイン設定の詳細なステップについては、「[Amazon OpenSearch Service ドメインの作成と管理](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/createupdatedomains.html)」を参照してください。 + 少量のテストデータを OpenSearch Service にアップロードするための簡潔なチュートリアルについては、**「Amazon OpenSearch Service デベロッパーガイド」の「はじめに」セクションの「[ステップ 2: Amazon OpenSearch Service にデータをアップロードしてインデックスを作成する](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/gsg.html#gsgupload-data)」を参照してください。 + データの取り込みについての詳細は、**「Amazon OpenSearch Serviceデベロッパーガイド」の「[Amazon OpenSearch Service におけるデータのインデックス作成](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/indexing.html)」を参照してください。 # Amazon OpenSearch Service のパイプラインを作成する [Amazon Personalize Search Ranking プラグインをインストール](open-search-install-managed.md)したら、OpenSearch 検索パイプラインを作成して設定する準備が整います。 *検索パイプライン*は、作成した順序で順番に実行されるリクエストプロセッサとレスポンスプロセッサのセットです。プラグインの検索パイプラインを作成するときは、`personalized_search_ranking` レスポンスプロセッサを指定します。検索パイプラインについて詳しくは、「[検索パイプライン](https://opensearch.org/docs/latest/search-plugins/search-pipelines/index/)」を参照してください。 `personalized_search_ranking` レスポンスプロセッサを含む検索パイプラインを作成したら、OpenSearch クエリにプラグインを適用する準備が整います。このプラグインを OpenSearch インデックスに適用することも、個々の OpenSearch クエリに適用することもできます。詳細については、「[プラグインの適用](managed-apply-plugin.md)」を参照してください。 次の Python コードを使用して、OpenSearch Service ドメインに `personalized_search_ranking` レスポンスプロセッサを備えた検索パイプラインを作成できます。`domain endpoint` をドメインのエンドポイント URL に置き換えます。例: `https://..es-staging.amazonaws.com`。各 `personalized_search_ranking` パラメータの詳細については、「[`personalized_search_ranking` レスポンスプロセッサのフィールド](opensearch-plugin-pipeline-fields.md)」を参照してください。 ``` import requests from requests_auth_aws_sigv4 import AWSSigV4 domain_endpoint = 'domain endpoint' pipeline_name = 'pipeline name' url = f'{domain_endpoint}/_search/pipeline/{pipeline_name}' auth = AWSSigV4('es') headers = {'Content-Type': 'application/json'} body = { "description": "A pipeline to apply custom re-ranking from Amazon Personalize", "response_processors": [ { "personalized_search_ranking" : { "campaign_arn" : "Amazon Personalize Campaign ARN", "item_id_field" : "productId", "recipe" : "aws-personalized-ranking-v2", "weight" : "0.3", "tag" : "personalize-processor", "iam_role_arn": "Role ARN", "aws_region": "AWS region", "ignore_failure": true } ] } try: response = requests.put(url, auth=auth, json=body, headers=headers, verify=False) print(response.text) except Exception as e: print(f"Error: {e}") ``` # Amazon OpenSearch Service クエリへのプラグインの適用 [パイプラインを作成](managed-opensearch-plugin-pipeline-example.md)したら、Amazon Personalize Search Ranking プラグインをクエリに適用する準備が整います。Amazon Personalize Search Ranking プラグインは、インデックスのすべてのクエリとレスポンスに適用できます。このプラグインは個々のクエリとレスポンスにも適用できます。 + 次の Python コードを使用して、検索パイプラインをインデックスに適用できます。この方法では、このインデックスを使用するすべての検索で、プラグインを使用して検索結果にパーソナライゼーションを適用します。 ``` import requests from requests_auth_aws_sigv4 import AWSSigV4 domain_endpoint = 'domain endpoint' index = 'index name' url = f'{domain_endpoint}/{index}/_settings/' auth = AWSSigV4('es') headers = {'Content-Type': 'application/json'} body = { "index.search.default_pipeline": "pipeline name" } try: response = requests.put(url, auth=auth, json=body, headers=headers) print(response.text) except Exception as e: print(f"Error: {e}") ``` + 次の Python コードを使用して、トヨタブランドの自動車の個別のクエリに検索パイプラインを適用できます。 コードを更新して、ドメインエンドポイント、OpenSearch Service インデックス、パイプラインの名前、クエリを指定します。`user_id` には、検索結果を取得するユーザーの ID を指定します。Amazon Personalize ソリューションバージョンの作成に使用したデータに、このユーザーが存在する必要があります。ユーザーが不在の場合、Amazon Personalize は人気に基づいてアイテムをランク付けします。 `context` には、コンテキストメタデータを使用する場合は、デバイスタイプなどのユーザーのコンテキストメタデータを提供してください。`context` フィールドはオプションです。詳細については、「[コンテキストメタデータを使用したレコメンデーションの関連性の向上](contextual-metadata.md)」を参照してください。 ``` import requests from requests_auth_aws_sigv4 import AWSSigV4 domain_endpoint = 'domain endpoint' index = 'index name' url = f'{domain_endpoint}/{index}/_search/' auth = AWSSigV4('es') headers = {'Content-Type': 'application/json'} params = {"search_pipeline": "pipeline-name"} body = { "query": { "multi_match": { "query": "Toyota", "fields": ["BRAND"] } }, "ext": { "personalize_request_parameters": { "user_id": "USER ID", "context": { "DEVICE" : "mobile phone" } } } } try: response = requests.post(url, auth=auth, params=params, json=body, headers=headers, verify=False) print(response) except Exception as e: print(f"Error: {e}") ``` # パーソナライズされた Amazon OpenSearch Service の結果をパーソナライズされていない結果と比較する Amazon Personalize Search Ranking プラグインは、Amazon Personalize のランキングと OpenSearch のランキングの両方に基づいて検索結果を再配置します。プラグインが結果を再ランク付けする方法は、パイプラインで `personalized_search_ranking` レスポンスプロセッサをどのように設定したかによって異なります。 結果のランク付け方法を理解するには、パーソナライゼーションの有無にかかわらずクエリを実行し、結果を比較できます。次の Python コードを使用して 2 つの異なるクエリを実行し、結果を 2 つの JSON ファイルに出力できます。1 つ目の方法は、プラグインを使用して結果をランク付けし直すクエリを実行します。2 つ目は、パーソナライズせずに結果を生成するメソッドを実行します。 ``` import json import requests from requests_auth_aws_sigv4 import AWSSigV4 # Returns re-ranked OpenSearch results using the Amazon Personalize Search Ranking plugin. def get_personalized_results(pipeline_name): url = f'{domain}/{index}/_search/' auth = AWSSigV4('es') headers = {'Content-Type': 'application/json'} params = {"search_pipeline": pipeline_name} body = { "query": { "multi_match": { "query": "Toyota", "fields": ["BRAND"] } }, "ext": { "personalize_request_parameters": { "user_id": "1" } } } try: response = requests.post(url, auth=auth, params=params, json=body, headers=headers, verify=False) except Exception as e: return f"Error: {e}" return response.text # Returns OpenSearch results without personalization. def get_opensearch_results(): url = f'{domain}/{index}/_search/' auth = AWSSigV4('es') headers = {'Content-Type': 'application/json'} body = { "query": { "multi_match": { "query": "Toyota", "fields": ["BRAND"] } } } try: response = requests.post(url, auth=auth, json=body, headers=headers, verify=False) except Exception as e: return f"Error: {e}" return response.text def print_results(file_name, results): results_file = open(file_name, 'w') results_file.write(json.dumps(results, indent=4)) results_file.close() # specify domain endpoint domain = "DOMAIN_ENDPOINT" # specify the region where you created your Amazon Personalize resources and Amazon OpenSearch domain aws_region = "REGION" # specify the name of the pipeline that uses the Amazon Personalize plugin pipeline_name = "PIPELINE_NAME" # specify your Amazon OpenSearch index index = "INDEX" # specify names for json files for comparison personalized_results_file = "personalized_results.json" opensearch_results_file = "opensearch_results.json" # get personalized results personalized_results = json.loads(get_personalized_results(pipeline_name)) # get OpenSearch results without personalization opensearch_results = json.loads(get_opensearch_results()) # print results to files print_results(personalized_results_file, personalized_results) print_results(opensearch_results_file, opensearch_results) ``` # Amazon OpenSearch Service の監視 Amazon Personalize Search Ranking プラグインを OpenSearch クエリに適用すると、検索パイプラインのメトリックスを取得してプラグインを監視できます。パイプラインメトリックスには、`personalized_search_ranking` レスポンスプロセッサの失敗したリクエスト数などの統計が含まれます。 OpenSearch Service を使用している場合は、Amazon CloudWatch のメトリクスを通じてプラグインをモニタリングできます。詳細については、「[Amazon OpenSearch Service ドメインのモニタリング](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/monitoring.html)」を参照してください。 次の Python コードを使用して、すべてのパイプラインメトリクスを取得できます。パイプラインの例については、「[パイプラインメトリクスの例](monitor-response.md)」を参照してください。 ``` import requests from requests_auth_aws_sigv4 import AWSSigV4 domain_endpoint = 'domain endpoint' url = f'{domain_endpoint}/_nodes/stats/search_pipeline' auth = AWSSigV4('es') headers = {'Content-Type': 'application/json'} try: response = requests.get(url, auth=auth, headers=headers, verify=False) print(response.text) except Exception as e: print(f"Error: {e}") ``` # Amazon Personalize を使用したオープンソースの Open Search の結果のパーソナライズ オープンソースの OpenSearch の結果をパーソナライズするには、次の操作を行います。 1. **Amazon Personalize のセットアップ** — まだセットアップをしていない場合は、[Amazon Personalize の設定](setup.md) のステップを実行して認証情報を設定し、Amazon Personalize のアクセス権限を設定します。OpenSearch の結果をパーソナライズするために AWS SDKs を設定する必要はありません。 1. **Amazon Personalize ワークフローの完了** – Amazon Personalize ワークフローを完了すると、データのインポート、Personalized-Ranking-v2 または Personalized-Ranking レシピを使ったソリューションの作成、カスタムソリューションバージョンのトレーニング、キャンペーンへのデプロイが可能になります。アイテムインタラクションデータセットを作成する必要があります。ユーザーデータセットとアイテムデータセットはオプションです。詳細については、「[Amazon Personalize のワークフローの詳細](personalize-workflow.md)」を参照してください。 1. **アクセス許可の設定** — OpenSearch クラスターから Amazon Personalize リソースにアクセスできるようにアクセス許可を設定します。詳細については、「[アクセス許可のセットアップ](opensearch-granting-access.md)」を参照してください。 1. **Amazon Personalize Search Ranking プラグインをインストールする** — Amazon Personalize Search Ranking プラグインは、Amazon Personalize との通信と結果の再ランク付けを処理します。 + OpenSearch クラスターが既に実行されている場合は、プラグインを手動でインストールできます。詳細については、「[既存の OpenSearch クラスターにプラグインを手動でインストールします。](opensearch-manual-install.md)」を参照してください。 + OpenSearch クラスターをまだ作成していない場合は、クイックスタート bash スクリプトを使用してクラスターを作成できます。詳細については、「[新しいクラスターを作成し、スクリプトを使用してプラグインをインストールする](opensearch-install-with-script.md)」を参照してください。 1. **Amazon Personalize Search Ranking プラグインの設定** — プラグインを設定するには、検索パイプラインを作成します。*検索パイプライン*は、リクエストプロセッサとレスポンスプロセッサのセットです。プラグインのパイプラインを作成するときは、`personalized_search_ranking` レスポンスプロセッサで Amazon Personalize リソースを指定します。また、プラグインが結果を再ランク付けするときに Amazon Personalize からの結果に与える重みも設定します。詳細については、「[パイプラインの作成](opensearch-plugin-pipeline-example.md)」を参照してください。 1. **Amazon Personalize Search Ranking プラグインを OpenSearch クエリに適用** — Amazon Personalize Search Ranking プラグインを OpenSearch インデックスのすべてのクエリとレスポンスに適用できます。このプラグインは個々の OpenSearch クエリとレスポンスに適用することもできます。オープンソースの OpenSearch にプラグインを適用する方法については、「[プラグインの適用](opensource-apply-plugin.md)」を参照してください。 1. **結果の比較** — Amazon Personalize Search Ranking プラグインは、OpenSearch クエリレスポンス内の検索結果をランク付けし直します。Amazon Personalize のランキングと OpenSearch のランキングの両方が考慮されます。結果がどのように再ランク付けされるかを理解するには、パーソナライゼーションを使用するクエリと使用しないクエリの結果を比較できます。結果をオープンソースの OpenSearch と比較する方法については、「[結果の比較](opensource-comparing-results.md)」を参照してください。 1. **Amazon Personalize Search Ranking プラグインの監視** — Amazon Personalize Search Ranking プラグインを検索クエリに適用すると、検索パイプラインのメトリクスを取得してプラグインを監視できます。オープンソースの OpenSearch クラスターでプラグインをモニタリングする方法については、「[オープンソースの OpenSearch によるプラグインの監視](opensource-monitor.md)」を参照してください。OpenSearch から返されるパイプラインメトリクスの例については、「[パイプラインメトリクスの例](monitor-response.md)」を参照してください。 **Topics** + [ # オープンソースの OpenSearch アクセス許可のセットアップ ](opensearch-granting-access.md) + [ # 既存の OpenSearch クラスターに Amazon Personalize Search Ranking プラグインを手動でインストールする ](opensearch-manual-install.md) + [ # 新しいクラスターを作成し、スクリプトを使用してプラグインをインストールする ](opensearch-install-with-script.md) + [ # オープンソース OpenSearch でパイプラインを作成する ](opensearch-plugin-pipeline-example.md) + [ # オープンソースの OpenSearch のクエリに Amazon Personalize Search Ranking プラグインを適用する ](opensource-apply-plugin.md) + [ # パーソナライズされた OpenSearch の結果を、パーソナライズされていない結果と比較する ](opensource-comparing-results.md) + [ # オープンソースの OpenSearch によるプラグインの監視 ](opensource-monitor.md) # オープンソースの OpenSearch アクセス許可のセットアップ オープンソースの OpenSearch を使用する場合は、オープンサーチクラスターから Amazon Personalize リソースにアクセスできる必要があります。アクセス許可を付与するには、次の手順を実行します。 + OpenSearch を最初からセットアップする場合は、[クイックスタート Bash スクリプト](https://github.com/opensearch-project/search-processor/blob/main/helpers/personalized_search_ranking_quickstart.sh)を使用して OpenSearch クラスターを Docker コンテナで実行できます。スクリプトは、 AWS プロファイルのデフォルトの認証情報を使用します。スクリプトを実行するときに、代替プロファイルを指定できます。 これらの認証情報は、Amazon Personalize キャンペーンの GetPersonalizedRanking アクションを実行するアクセス許可を持つユーザーまたはロールに関連付けられている必要があります。IAM ポリシーの例については、「[IAM ポリシーの例](#opensearch-role-policy-example)」を参照してください。または、認証情報にはこれらのアクセス許可を持つロールを引き受けるアクセス許可が必要です。Amazon Personalize Search Ranking プラグインのパイプラインを作成するときに、このロールの Amazon リソースネーム (ARN) を指定できます。 + [クイックスタート Bash スクリプト](https://github.com/opensearch-project/search-processor/blob/main/helpers/personalized_search_ranking_quickstart.sh)を使用しない場合は、OpenSearch キーストアに認証情報を手動で追加できます。これらの認証情報は、Amazon Personalize キャンペーンの GetPersonalizedRanking アクションを実行する権限を持つユーザーまたはロールと一致している必要があります。 OpenSearch キーストアに AWS 認証情報を手動で追加するには、OpenSearch クラスターが実行されている (Docker コンテナなど) 次のコマンドを実行します。次に、各認証情報を入力します。セッショントークンを使用しない場合は、コマンドの最後の行を省略できます。 ``` opensearch-keystore add \ personalized_search_ranking.aws.access_key \ personalized_search_ranking.aws.secret_key \ personalized_search_ranking.aws.session_token ``` + Amazon EC2 インスタンスで OpenSearch クラスターを実行する場合、IAM インスタンスプロファイルを使用してアクセス許可を付与できます。ロールにアタッチされたポリシーは、Amazon Personalize キャンペーンの GetPersonalizedRanking アクションを実行するアクセス許可をロールに付与する必要があります。また、ロールを引き受けるためのアクセス許可を Amazon EC2 に付与する必要があります｡ Amazon EC2 インスタンスプロファイルについては、「[インスタンスプロファイルの使用](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2_instance-profiles.html)」を参照してください。ポリシーの例については「[IAM ポリシーの例](#opensearch-role-policy-example)」を参照してください。 ## IAM ポリシーの例 次のポリシー例では、Amazon Personalize キャンペーンからパーソナライズされたランキングを取得するための最低限のアクセス許可をユーザーまたはロールに付与します。`Campaign ARN` には、Amazon Personalize キャンペーンの Amazon リソースネーム (ARN) を指定します。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "personalize:GetPersonalizedRanking" ], "Resource": "arn:aws:personalize:us-east-1:111122223333:campaign/YourResourceId" } ] } ``` ------ さらに、OpenSearch クラスターを Amazon EC2 インスタンスで実行し、IAM インスタンスプロファイルを使用してアクセス許可を付与する場合、ロールの信頼ポリシーは、次のように Amazon EC2 に `AssumeRole` アクセス許可を付与する必要があります。Amazon EC2 インスタンスプロファイルについては、「[インスタンスプロファイルの使用](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2_instance-profiles.html)」を参照してください。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "ec2.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` ------ # 既存の OpenSearch クラスターに Amazon Personalize Search Ranking プラグインを手動でインストールする すでに OpenSearch クラスターがある場合は、OpenSearch GitHub リポジトリから直接クラスターにプラグインを手動でインストールできます。 **プラグインを手動でインストールするには** 1. OpenSearch クラスターを起動するには、以下のコマンドを使用します。 ``` bin/opensearch ``` 1. カタログデータを OpenSearch クラスターにまだアップロードしていない場合は、OpenSearch クラスターにアップロードします。データをアップロードするときは、OpenSearch インデックスを作成し、フィールドマッピングを定義します。次に、そのインデックスにデータをアップロードします。例については、「[サンプルデータを使用してインデックスとフィールドマッピングを作成する](https://opensearch.org/docs/latest/quickstart/#create-an-index-and-field-mappings-using-sample-data)」を参照してください。 1. プラグインをインストールするには、次のコマンドを使用します。 ``` bin/opensearch-plugin install https://github.com/opensearch-project/search-processor/releases/download/2.9.0/opensearch-search-processor-2.9.0.0.zip ``` プラグインのインストールについての詳細は、「[プラグインのインストール](https://opensearch.org/docs/latest/install-and-configure/plugins/)」を参照してください。 Amazon Personalize Search Ranking プラグインをインストールしたら、設定する準備が整います。プラグインを設定するには、検索パイプラインを作成し、`personalized_search_ranking` レスポンスプロセッサを指定します。詳細については、「[パイプラインの作成](opensearch-plugin-pipeline-example.md)」を参照してください。 # 新しいクラスターを作成し、スクリプトを使用してプラグインをインストールする OpenSearch クラスターをまだ作成していない場合は、クイックスタート bash スクリプトを使用してクラスターを作成できます。このスクリプトは、Docker コンテナに OpenSearch クラスターをセットアップし、AWSデフォルトプロファイルを使用して認証情報を設定し、Amazon Personalize Search Ranking プラグインをインストールします。 OpenSearch クラスターを手動で作成する方法については、OpenSearch ドキュメントの「[クイックスタート](https://opensearch.org/docs/quickstart)」の説明を参照してください。 **クイックスタート Bash スクリプトを使用してプラグインをインストールするには** 1. スクリプトを実行する前に、ご使用のオペレーティングシステム用の [Docker Desktop](https://docs.docker.com/get-docker/) をダウンロードしてインストールします。 1. [クイックスタート Bash スクリプト](https://github.com/opensearch-project/search-processor/blob/main/helpers/personalized_search_ranking_quickstart.sh)を GitHub からダウンロードします。 1. ワーキングディレクトリで、次のコマンドを使用してスクリプトを実行します。 ``` sh personalized_search_ranking_quickstart.sh ``` このコマンドでは、スクリプトはデフォルト AWS プロファイルの認証情報を使用します。代替プロファイルを指定するには、デフォルトの `--profile` 引数を使用します。 ``` sh personalized_search_ranking_quickstart.sh --profile profile-name ``` スクリプトを実行すると、スクリプトによって作成された固有のディレクトリにある README ファイルに、そのスクリプトに関する詳細情報が記載されます。このディレクトリには、スクリプトが使用する Dockerfile ファイルと docker-compose.yml ファイルが格納されます。例: `../opensearch-personalize-intelligent-ranking-docker.1234/README`。 1. カタログデータを OpenSearch クラスターにアップロードします。データをアップロードする際は、OpenSearch インデックスを作成し、フィールドマッピングを定義します。次に、そのインデックスにデータをアップロードします。例については、「[サンプルデータを使用してインデックスとフィールドマッピングを作成する](https://opensearch.org/docs/latest/quickstart/#create-an-index-and-field-mappings-using-sample-data)」を参照してください。 OpenSearch をセットアップして Amazon Personalize Search Ranking プラグインをインストールしたら、設定する準備は完了です。プラグインを設定するには、検索パイプラインを作成し、`personalized_search_ranking` レスポンスプロセッサを指定します。詳細については、「[パイプラインの作成](opensearch-plugin-pipeline-example.md)」を参照してください。 # オープンソース OpenSearch でパイプラインを作成する クラスターにプラグインをインストールしたら、OpenSearch 検索パイプラインを作成して設定する準備が整います。 *検索パイプライン*は、作成した順序で順番に実行されるリクエストプロセッサとレスポンスプロセッサのセットです。プラグインの検索パイプラインを作成するときは、`personalized_search_ranking` レスポンスプロセッサを指定します。検索パイプラインについて詳しくは、「[検索パイプライン](https://opensearch.org/docs/latest/search-plugins/search-pipelines/index/)」を参照してください。 `personalized_search_ranking` レスポンスプロセッサを含むパイプラインを作成したら、クエリにプラグインを適用する準備が整います。詳細については、「[プラグインの適用](opensource-apply-plugin.md)」を参照してください。 次の curl コマンドを使用して、オープンソースの OpenSearch クラスター上に `personalized_search_ranking` レスポンスプロセッサーを備えた検索パイプラインを作成できます。各 `personalized_search_ranking` パラメータの詳細については、「[`personalized_search_ranking` レスポンスプロセッサのフィールド](opensearch-plugin-pipeline-fields.md)」を参照してください。 ``` curl -X PUT "http://localhost:9200/_search/pipeline/pipeline-name" -ku 'admin:admin' --insecure -H 'Content-Type: application/json' -d' { "description": "A pipeline to apply custom re-ranking from Amazon Personalize", "response_processors" : [ { "personalized_search_ranking" : { "campaign_arn" : "Amazon Personalize Campaign ARN", "item_id_field" : "productId", "recipe" : "aws-personalized-ranking-v2", "weight" : "0.3", "tag" : "personalize-processor", "iam_role_arn": "Role ARN", "aws_region": "AWS region", "ignore_failure": true } } ] }' ``` `personalized_search_ranking` レスポンスプロセッサを含む検索パイプラインを作成したら、OpenSearch クエリにプラグインを適用する準備が整います。このプラグインを OpenSearch インデックスに適用することも、個々の OpenSearch クエリに適用することもできます。詳細については、「[オープンソースの OpenSearch のクエリに Amazon Personalize Search Ranking プラグインを適用する](opensource-apply-plugin.md)」を参照してください。 # オープンソースの OpenSearch のクエリに Amazon Personalize Search Ranking プラグインを適用する Amazon Personalize Search Ranking プラグインは、OpenSearch インデックスのすべてのクエリとレスポンスに適用できます。このプラグインは個々の OpenSearch クエリとレスポンスに適用することもできます。 + 次の curl コマンドは、ローカルで実行されているオープンソース OpenSearch クラスター内の OpenSearch インデックスに検索パイプラインを適用します。この方法では、このインデックスでのすべての検索がプラグインを使用して検索結果にパーソナライゼーションを適用します。 ``` curl -XGET "https://localhost:9200/index/_settings" -ku 'admin:admin' --insecure -H 'Content-Type: application/json' -d' { "index.search.default_pipeline": "pipeline-name" } ' ``` + 次の curl コマンドは、ローカルで実行されているオープンソース OpenSearch クラスター内のインデックスで Toyota ブランド車を対象とする個別のクエリに検索パイプラインを適用します。 `user_id` には、検索結果を取得するユーザーの ID を指定します。Amazon Personalize ソリューションバージョンの作成に使用したデータに、このユーザーが存在する必要があります。ユーザーが不在の場合、Amazon Personalize は人気に基づいてアイテムをランク付けします。`context` には、コンテキストメタデータを使用する場合は、デバイスタイプなどのユーザーのコンテキストメタデータを提供してください。`context` フィールドはオプションです。詳細については、「[コンテキストメタデータを使用したレコメンデーションの関連性の向上](contextual-metadata.md)」を参照してください。 ``` curl -XGET "http://localhost:9200/index/_search?search_pipeline=pipeline-name" -ku 'admin:admin' --insecure -H 'Content-Type: application/json' -d' { "query": { "multi_match": { "query": "Toyota", "fields": ["BRAND"] } }, "ext": { "personalize_request_parameters": { "user_id": "USER ID", "context": { "DEVICE": "mobile phone" } } } } ' ``` 結果がどのように再ランク付けされるかを理解するには、OpenSearch Dashboards を使用して OpenSearch の結果をプラグインで再ランク付けした結果と比較できます。詳細については、「[パーソナライズされた OpenSearch の結果を、パーソナライズされていない結果と比較する](opensource-comparing-results.md)」を参照してください。 OpenSearch クエリにプラグインを適用すると、OpenSearch パイプラインのメトリクスを取得してプラグインを監視できます。詳細については、「[オープンソースの OpenSearch によるプラグインの監視](opensource-monitor.md)」を参照してください。 # パーソナライズされた OpenSearch の結果を、パーソナライズされていない結果と比較する 結果がどのように再ランク付けされるかを理解するために、2 つのブラウザウィンドウで[開発ツールコンソール](https://opensearch.org/docs/latest/dashboards/dev-tools/run-queries)を使用してクエリを実行できます。そうすれば、パーソナライゼーションの有無にかかわらずクエリの結果を比較できます。 **Dev Tools コンソールと結果を比較するには** 1. OpenSearch Dashboards がインストールされていることを確認してください。クイックスタート Bash スクリプトは OpenSearch ダッシュボードをインストールします。このスクリプトを使用しない場合や、すでにクラスターを実行している場合は、OpenSearch Dashboards をインストールする必要があります。詳細については、「[OpenSearch Dashboards のインストール](https://opensearch.org/docs/latest/install-and-configure/install-dashboards/index/)」を参照してください。 1. OpenSearch Dashboards を起動します。ブラウザから `http://localhost:5601` を開き、OpenSearch Dashboards にサインインします。デフォルトの認証情報は、ユーザー名は「admin」、パスワードは「admin」です。 1. OpenSearch Dashboards ホームページの「管理」メニューで**[開発ツール]** を選択します。 1. 別のブラウザウィンドウを開き、Dev Tools コンソールをもう一度開きます。前のウィンドウの URL を使用できます。 1. 1 つのウィンドウに、パーソナライゼーションのための再ランク付けを一切使用しないクエリを入力します。もう一方のウィンドウでは、`personalized_search_ranking` レスポンスプロセッサのパイプラインを使用する curl コマンドを入力します。curl コマンドをコンソールに直接貼り付けると、コマンドはコンソールが使用する形式に自動的に変換されます。コマンドの例については、「[オープンソースの OpenSearch のクエリに Amazon Personalize Search Ranking プラグインを適用する](opensource-apply-plugin.md)」を参照してください。 1. 両方のクエリを実行し、結果を比較します。 # オープンソースの OpenSearch によるプラグインの監視 Amazon Personalize Search Ranking プラグインを OpenSearch クエリに適用すると、検索パイプラインのメトリックスを取得してプラグインを監視できます。パイプラインメトリックスには、`personalized_search_ranking` レスポンスプロセッサの失敗したリクエスト数などの統計が含まれます。 次のコードを使用して、すべてのパイプラインのメトリクスを取得できます。レスポンスにはすべての検索パイプラインの統計が含まれます。パイプラインメトリクスの例については、「[パイプラインメトリクスの例](monitor-response.md)」を参照してください。 ``` curl -XGET "https://localhost:9200/_nodes/stats/search_pipeline?pretty" -ku 'admin:admin' ``` # `personalized_search_ranking` レスポンスプロセッサのフィールド Amazon Personalize Search Ranking プラグインの検索パイプラインを作成するときは、以下のフィールドを使用して `personalized_search_ranking` レスポンスプロセッサを指定します。 + **campaign\$1arn (必須)** — 結果のパーソナライズに使用する Amazon Personalize キャンペーンのAmazon リソースネーム (ARN) を指定します。 + **item\$1id\$1field (オプション)** — OpenSearch のインデックス付きドキュメントの `_id` フィールドが Amazon Personalize の itemId と一致しない場合は、一致するフィールドの名前を指定します。デフォルトでは、プラグインは `_id` データが Amazon Personalize データの itemId と一致すると仮定します。 + **レシピ (必須)** — 使用する Amazon Personalize レシピの名前を指定します。プラグインを使用するには、`aws-personalized-ranking-v2` または `aws-personalized-ranking` を指定できます。 + **重み (必須)** — レスポンスプロセッサが結果を再ランク付けする際にパーソナライゼーションを重視することを指定します。0.0 ～ 1.0 の範囲内の値を指定します。`1.0` に近いほど、Amazon Personalize の結果が上位にランクされる可能性が高くなります。`0.0` を指定した場合、パーソナライズは行われず、OpenSearch が優先されます。 + **タグ (オプション)** — プロセッサの識別子を指定します。 + **iam\$1role\$1arn (OpenSearch Service の場合は必須、オープンソース OpenSearch の場合はオプション)** — OpenSearch Service の場合は、Amazon Personalize リソースにアクセスするための OpenSearch Service の[アクセス許可を設定する](opensearch-granting-access-managed.md)ときに作成したロールの Amazon リソースネーム (ARN) を指定します。OpenSearch Service リソースと Amazon Personalize リソースが異なるアカウントに存在する場合は、OpenSearch Service の `AssumeRole` アクセス許可を付与するロールを指定します。詳細については、「[リソースが異なるアカウントにある場合のアクセス許可の設定](configuring-multiple-accounts.md)」を参照してください。 オープンソース OpenSearch の場合、複数のロールを使用して組織内のさまざまなユーザーグループのアクセス許可を制限する場合は、Amazon Personalize へのアクセス許可を持つロールの ARN を指定します。OpenSearch AWS キーストア内の 認証情報のみを使用する場合は、このフィールドを省略できます。 + **aws\$1region (必須)** — Amazon Personalize キャンペーンを作成した AWS リージョン。 + **ignore\$1failure (オプション)** — プラグインがプロセッサ障害を無視するかどうかを指定します。値には、`true` または `false` を指定します。本番環境では、クエリ応答が中断されないように `true` を指定することをお勧めします。テスト環境では、プラグインが生成するエラーをすべて表示するように `false` を指定できます。 + **external\$1account\$1iam\$1role\$1arn** — OpenSearch Service を使用し、Amazon Personalize リソースと OpenSearch Service リソースが異なるアカウントに存在する場合は、Amazon Personalize リソースにアクセスするアクセス許可を持つロールの ARN を指定します。このロールは、Amazon Personalize リソースと同じアカウントに存在する必要があります。詳細については、「[リソースが異なるアカウントにある場合のアクセス許可の設定](configuring-multiple-accounts.md)」を参照してください。 OpenSearch Service のコードサンプルについては、「[Amazon OpenSearch Service のパイプラインを作成する](managed-opensearch-plugin-pipeline-example.md)」を参照してください。オープンソースの OpenSearch の例については、「[オープンソース OpenSearch でパイプラインを作成する](opensearch-plugin-pipeline-example.md)」を参照してください。 # パイプラインメトリクスの例 Amazon Personalize Search Ranking プラグインを OpenSearch クエリに適用すると、検索パイプラインのメトリックスを取得してプラグインを監視できます。パイプラインメトリックスには、`personalized_search_ranking` レスポンスプロセッサの失敗したリクエスト数などの統計が含まれます。 次のコードは、OpenSearch から返されるパイプラインメトリクスを抜粋したものです。2 つの異なるパイプラインの統計を含む `pipelines` オブジェクトのみが表示されます。パイプラインごとに、Amazon Personalize Search Ranking プラグインのメトリックスが `personalized_search_ranking` レスポンスプロセッサリストに表示されます。すべてのメトリクスの詳細な例については、「[検索パイプラインメトリクス](https://opensearch.org/docs/latest/search-plugins/search-pipelines/search-pipeline-metrics/)」を参照してください。 ``` { .... .... "pipelines": { "pipelineA": { "request": { "count": 0, "time_in_millis": 0, "current": 0, "failed": 0 }, "response": { "count": 6, "time_in_millis": 2246, "current": 0, "failed": 0 }, "request_processors": [], "response_processors": [ { personalized_search_ranking": { "type": "personalized_search_ranking", "stats": { "count": , "time_in_millis":