本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用 Amazon Personalize 個人化開放原始碼開放搜尋的結果
若要個人化結果開放原始碼 OpenSearch，請執行下列動作：
1. **設定 Amazon Personalize** – 如果您尚未設定，請完成 中的步驟[設定 Amazon Personalize](setup.md)，以設定您的登入資料並設定 Amazon Personalize 的許可。您不需要設定 AWS SDKs來個人化 OpenSearch 結果。
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)
+ [將 Amazon Personalize Search Ranking 外掛程式套用至開放原始碼 OpenSearch 中的查詢](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)在 Docker 容器中執行 OpenSearch 叢集。指令碼會在您的 AWS 設定檔中使用預設登入資料。您可以在執行指令碼時指定替代設定檔。
這些登入資料必須與具有為 Amazon Personalize 行銷活動執行 GetPersonalizedRanking 動作許可的使用者或角色相關聯。如需 IAM 政策的範例，請參閱 [IAM 政策範例](#opensearch-role-policy-example)。或者，登入資料必須具有許可，才能擔任具有這些許可的角色。您可以在建立 Amazon Personalize Search Ranking 外掛程式的管道時，提供此角色的 Amazon Resource Name (ARN)。
+ 如果您不使用[快速啟動 bash 指令碼](https://github.com/opensearch-project/search-processor/blob/main/helpers/personalized_search_ranking_quickstart.sh)，您可以手動將登入資料新增至 OpenSearch 金鑰存放區。這些登入資料必須與具有許可可為您的 Amazon Personalize 行銷活動執行 GetPersonalizedRanking 動作的使用者或角色對應。
若要手動將 AWS 登入資料新增至 OpenSearch 金鑰存放區，請執行下列執行 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 Resource Name (ARN)。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"personalize:GetPersonalizedRanking"
],
"Resource": "arn:aws:personalize:us-east-1:111122223333:campaign/YourResourceId"
}
]
}
```
------
此外，如果您在 Amazon EC2 執行個體上執行 OpenSearch 叢集，並使用 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 索引並定義欄位映射。然後，您將資料上傳到該索引。如需範例，請參閱[使用範例資料建立索引和欄位映射](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. 從 GitHub 下載[快速入門 bash 指令碼](https://github.com/opensearch-project/search-processor/blob/main/helpers/personalized_search_ranking_quickstart.sh)。
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 查詢。如需詳細資訊，請參閱[將 Amazon Personalize Search Ranking 外掛程式套用至開放原始碼 OpenSearch 中的查詢](opensource-apply-plugin.md)。
# 將 Amazon Personalize Search Ranking 外掛程式套用至開放原始碼 OpenSearch 中的查詢
您可以將 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 結果與結果進行比較，無需個人化
若要了解結果如何重新排名，您可以在兩個單獨的瀏覽器視窗中使用[開發工具主控台](https://opensearch.org/docs/latest/dashboards/dev-tools/run-queries)執行查詢。然後，您可以比較具有和不具有個人化之查詢的結果。
**將結果與開發工具主控台進行比較**
1. 確定已安裝 OpenSearch Dashboards。Quickstart bash 指令碼會安裝 OpenSearch Dashboards。如果您未使用指令碼或已執行叢集，則必須安裝 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. 開啟單獨的瀏覽器視窗，然後再次開啟開發工具主控台。您可以使用上一個視窗中的 URL。
1. 在一個視窗中，輸入未使用任何重新排名進行個人化的查詢。在另一個視窗中，輸入使用管道搭配`personalized_search_ranking`回應處理器的 curl 命令。如果您直接將 curl 命令貼到主控台，命令會自動轉換為主控台使用的格式。如需命令範例，請參閱 [將 Amazon Personalize Search Ranking 外掛程式套用至開放原始碼 OpenSearch 中的查詢](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'
```