本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 亚马逊 OpenSearch 服务 ML 连接器适用于 AWS 服务
当您将 Amazon S OpenSearch ervice 机器学习 (ML) 连接器与其他连接器一起使用时 AWS 服务，您需要设置一个 IAM 角色才能将 OpenSearch 服务安全地连接到该服务。 AWS 服务 你可以设置一个连接器来包含 Amazon A SageMaker I 和 Amazon Bedrock。在本教程中，我们将介绍如何创建从 OpenSearch 服务到 SageMaker 运行时的连接器。有关连接器的更多信息，请参阅[受支持的连接器](https://opensearch.org/docs/latest/ml-commons-plugin/remote-models/connectors/#supported-connectors)。
**Topics**
+ [先决条件](#connector-sagemaker-prereq)
+ [创建 OpenSearch 服务连接器](#connector-sagemaker-create)
## 先决条件
要创建连接器，您必须拥有 Amazon A SageMaker I 域终端节点和授予 OpenSearch 服务访问权限的 IAM 角色。
### 设置亚马逊 A SageMaker I 域名
要[部署您的机器学习模型，请参阅亚马逊 SageMaker A SageMaker I](https://docs.aws.amazon.com/sagemaker/latest/dg/how-it-works-deployment.html) *开发人员指南中的在 Ama* zon AI 中部署模型。记下模型的端点 URL，这是创建 AI 连接器所必需的。
### 创建一个 IAM 角色
设置 IAM 角色以向 OpenSearch 服务委派 SageMaker 运行时权限。要创建新角色，请参阅 *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 服务访问您的 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)中的说明编辑角色的信任关系。在以下策略中，将服务或 OpenSearch 无服务器的以下服务主体替换*service-principal*为以下 OpenSearch 服务主体之一：
**用于 OpenSearch 服务**
`opensearchservice.amazonaws.com`
**适用于 OpenSearch 无服务器**
`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 角色传递给 S OpenSearch ervice。还需要对 `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 仪表板中映射 ML 角色（如果使用精细的访问控制）
设置连接器时，精细访问控制会引入额外的步骤。即使将 HTTP 基本身份验证用于所有其他目的，也需要将 `ml_full_access` 角色映射到具有传递 `opensearch-sagemaker-role` 的 `iam:PassRole` 权限的 IAM 角色。
1. 导航到您的 OpenSearch 服务域的 OpenSearch 仪表板插件。您可以在 OpenSearch 服务控制台的域控制面板上找到控制面板终端节点。
1. 从主菜单中选择**安全**、**角色**，然后选择 **ml\$1full\$1access** 角色。
1. 选择**映射的用户**、**管理映射**。
1. 在**后端角色**下，添加具有传递 `opensearch-sagemaker-role` 权限的角色的 ARN。
```
arn:aws:iam::account-id:role/role-name
```
1. 选择**映射**并确认在**映射的用户**下显示的用户或角色。
## 创建 OpenSearch 服务连接器
要创建连接器，请向 OpenSearch 服务域终端节点发送`POST`请求。您可以使用 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 服务域，请在 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)
```