本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 適用於 的 Amazon OpenSearch Service ML 連接器 AWS 服務
當您將 Amazon OpenSearch Service Machine Learning (ML) 連接器與另一個連接器搭配使用時 AWS 服務，您需要設定 IAM 角色，以安全地將 OpenSearch Service 連線至該服務。 AWS 服務 您可以設定連接器來包含 Amazon SageMaker AI 和 Amazon Bedrock。在本教學課程中，我們將介紹如何建立從 OpenSearch Service 到 SageMaker 執行期的連接器。如需連接器的詳細資訊，請參閱[支援的連接器](https://opensearch.org/docs/latest/ml-commons-plugin/remote-models/connectors/#supported-connectors)。
**Topics**
+ [先決條件](#connector-sagemaker-prereq)
+ [建立 OpenSearch Service 連接器](#connector-sagemaker-create)
## 先決條件
若要建立連接器，您必須擁有 Amazon SageMaker AI 網域端點和授予 OpenSearch Service 存取權的 IAM 角色。
### 設定 Amazon SageMaker AI 網域
請參閱《[Amazon SageMaker AI 開發人員指南》中的在](https://docs.aws.amazon.com/sagemaker/latest/dg/how-it-works-deployment.html) *Amazon SageMaker AI* 中部署模型，以部署您的機器學習模型。請注意模型的端點 URL，您需要此 URL 才能建立 AI 連接器。
### 建立 IAM 角色
設定 IAM 角色將 SageMaker 執行期許可委派給 OpenSearch Service。若要建立新的角色，請參閱《[IAM 使用者指南》中的建立 IAM 角色 （主控台）](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html#roles-creatingrole-user-console)。 **或者，只要現有角色具有相同的權限集，您就可以使用該角色。如果您確實建立新的角色，而不是使用 AWS 受管角色，請在本教學`opensearch-sagemaker-role`課程中將 取代為您自己的角色名稱。
1. 將下列受管 IAM 政策連接至您的新角色，以允許 OpenSearch Service 存取您的 SageMaker AI 端點。若要將政策連接至角色，請參閱[新增 IAM 身分許可](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html#add-policies-console)。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"sagemaker:InvokeEndpointAsync",
"sagemaker:InvokeEndpoint"
],
"Effect": "Allow",
"Resource": "*"
}
]
}
```
------
1. 遵循[修改角色信任政策](https://docs.aws.amazon.com/IAM/latest/UserGuide/roles-managingrole-editing-console.html#roles-managingrole_edit-trust-policy)中的指示來編輯角色的信任關係。在下列政策中，將 *service-principal* 取代為下列其中一個適用於 OpenSearch Service 或 OpenSearch Serverless 的服務主體：
**對於 OpenSearch Service**
`opensearchservice.amazonaws.com`
**對於 OpenSearch Serverless**
`ml.opensearchservice.amazonaws.com`
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"sts:AssumeRole"
],
"Effect": "Allow",
"Principal": {
"Service": [
"ml.opensearchservice.amazonaws.com"
]
}
}
]
}
```
------
建議您使用 `aws:SourceAccount`和 `aws:SourceArn`條件金鑰來限制對特定網域的存取。`SourceAccount` 是屬於網域擁有者的 AWS 帳戶 ID，而 `SourceArn`是網域的 ARN。例如，您可以將下列條件區塊新增至信任政策：
```
"Condition": {
"StringEquals": {
"aws:SourceAccount": "account-id"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:es:region:account-id:domain/domain-name"
}
}
```
### 設定 許可
若要建立連接器，您需要將 IAM 角色傳遞至 OpenSearch Service 的許可。您也需要存取 `es:ESHttpPost` 動作。若要授予這兩個許可，請將下列政策連接至其憑證用於簽署請求的 IAM 角色：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": "arn:aws:iam::111122223333:role/opensearch-sagemaker-role"
},
{
"Effect": "Allow",
"Action": "es:ESHttpPost",
"Resource": "arn:aws:es:us-east-1:111122223333:domain/domain-name/*"
}
]
}
```
------
如果您的使用者或角色沒有傳遞角色的`iam:PassRole`許可，當您在下一個步驟嘗試註冊儲存庫時，可能會遇到授權錯誤。
### 在 OpenSearch Dashboards 中映射 ML 角色 （如果使用精細存取控制）
精細存取控制會在設定連接器時引入額外的步驟。即使您將 HTTP 基本身分驗證用於所有其他目的，您也需要將 `ml_full_access` 角色映射至擁有 `iam:PassRole` 許可能夠傳遞 `opensearch-sagemaker-role` 的 IAM 角色。
1. 導覽至 OpenSearch Service 網域的 OpenSearch Dashboards 外掛程式。您可以在 OpenSearch Service 主控台的網域儀表板上找到 Dashboards 端點。
1. 從主選單選擇**安全性**、**角色**，然後選取 **ml\$1full\$1access** 角色。
1. 選擇 **Mapped users** (已映射的使用者)、**Manage mapping** (管理映射)。
1. 在**後端角色**下，新增具有傳遞 許可之角色的 ARN`opensearch-sagemaker-role`。
```
arn:aws:iam::account-id:role/role-name
```
1. 選擇 **Map** (映射)，並確認使用者或角色顯示在 **Mapped users** (已映射的使用者) 中。
## 建立 OpenSearch Service 連接器
若要建立連接器，請將`POST`請求傳送至 OpenSearch Service 網域端點。您可以使用 curl、範例 Python 用戶端、Postman 或其他方法來傳送已簽署的請求。請注意，您無法在 Kibana 主控台中使用`POST`請求。請求採用下列格式：
```
POST domain-endpoint/_plugins/_ml/connectors/_create
{
"name": "sagemaker: embedding",
"description": "Test connector for Sagemaker embedding model",
"version": 1,
"protocol": "aws_sigv4",
"credential": {
"roleArn": "arn:aws:iam::account-id:role/opensearch-sagemaker-role"
},
"parameters": {
"region": "region",
"service_name": "sagemaker"
},
"actions": [
{
"action_type": "predict",
"method": "POST",
"headers": {
"content-type": "application/json"
},
"url": "https://runtime.sagemaker.region.amazonaws.com/endpoints/endpoint-id/invocations",
"request_body": "{ \"inputs\": { \"question\": \"${parameters.question}\", \"context\": \"${parameters.context}\" } }"
}
]
}
```
如果您的網域位於虛擬私有雲端 (VPC) 中，您的電腦必須連接到 VPC，請求才能成功建立 AI 連接器。存取 VPC 因網路組態而異，但通常涉及連線到 VPN 或公司網路。若要檢查您是否可以連線到 OpenSearch Service 網域，請在 Web 瀏覽器`https://your-vpc-domain.region.es.amazonaws.com`中導覽至 ，並確認您收到預設的 JSON 回應。
### Python 用戶端範例
Python 用戶端比 HTTP 請求更易於自動化，且具有更佳的可重複使用性。若要使用 Python 用戶端建立 AI 連接器，請將下列範例程式碼儲存至 Python 檔案。用戶端需要 [適用於 Python (Boto3) 的 AWS SDK](https://aws.amazon.com/sdk-for-python/)、 [https://requests.readthedocs.io/en/latest/](https://requests.readthedocs.io/en/latest/)和 [https://pypi.org/project/requests-aws4auth/](https://pypi.org/project/requests-aws4auth/)套件。
```
import boto3
import requests
from requests_aws4auth import AWS4Auth
host = 'domain-endpoint/'
region = 'region'
service = 'es'
credentials = boto3.Session().get_credentials()
awsauth = AWS4Auth(credentials.access_key, credentials.secret_key, region, service, session_token=credentials.token)
# Register repository
path = '_plugins/_ml/connectors/_create'
url = host + path
payload = {
"name": "sagemaker: embedding",
"description": "Test connector for Sagemaker embedding model",
"version": 1,
"protocol": "aws_sigv4",
"credential": {
"roleArn": "arn:aws:iam::account-id:role/opensearch-sagemaker-role"
},
"parameters": {
"region": "region",
"service_name": "sagemaker"
},
"actions": [
{
"action_type": "predict",
"method": "POST",
"headers": {
"content-type": "application/json"
},
"url": "https://runtime.sagemaker.region.amazonaws.com/endpoints/endpoint-id/invocations",
"request_body": "{ \"inputs\": { \"question\": \"${parameters.question}\", \"context\": \"${parameters.context}\" } }"
}
]
}
headers = {"Content-Type": "application/json"}
r = requests.post(url, auth=awsauth, json=payload, headers=headers)
print(r.status_code)
print(r.text)
```