适用于第三方平台的 Amazon OpenSearch 服务 ML 连接器

在本教程中，我们将介绍如何创建从 Service 到 Coh OpenSearch ere 的连接器。有关连接器的更多信息，请参阅受支持的连接器。

当您将 Amazon S OpenSearch ervice 机器学习 (ML) 连接器与外部远程模型一起使用时，您需要在中存储您的特定授权凭证 Amazon Secrets Manager。这可能是 API 密钥，也可以是用户名和密码组合。这意味着你还需要创建一个 IAM 角色，允许 OpenSearch 服务访问权限从 Secrets Manager 读取。

主题

先决条件
创建 OpenSearch 服务连接器

先决条件

要使用 S OpenSearch ervice 为 Cohere 或任何外部提供商创建连接器，您必须拥有一个 IAM 角色来授予 OpenSearch 服务访问权限 Amazon Secrets Manager，您可以在其中存储您的证书。您还必须将凭证存储在 Secrets Manager 中。

创建 IAM 角色

设置一个 IAM 角色以将 Secrets Manager 权限委派给 OpenSearch 服务。您也可以使用现有 SecretManagerReadWrite 角色。要创建新角色，请参阅 IAM 用户指南中的创建 IAM 角色（控制台）。如果您确实创建了新角色而不是使用 Amazon 托管角色，请将本教程opensearch-secretmanager-role中的角色名称替换为您自己的角色名称。

将以下托管 IAM 策略附加到您的新角色，以允许 OpenSearch 服务访问您的 Secrets Manager 值。要将策略附加到角色，请参阅添加 IAM 身份权限。


{
    "Version": "2012-10-17",
    "Statement": [
        {   
            "Action": [
                "secretsmanager:GetSecretValue"
            ],
            "Effect": "Allow",
            "Resource": "*"
        }
    ]
}

按照修改角色信任策略中的说明编辑角色的信任关系。您必须在Principal语句中指定 “ OpenSearch 服务”：


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": [
                "sts:AssumeRole"
            ],
            "Effect": "Allow",
            "Principal": {
                "Service": [
                    "opensearchservice.amazonaws.com"
                ]
            }
        }
    ]
}

建议您使用aws:SourceAccount和aws:SourceArn条件密钥来限制对特定域的访问。SourceAccount是属于域名所有者的 Amazon Web Services 账户 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 角色，该角色的凭据用于签署请求：


{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "iam:PassRole",
      "Resource": "arn:aws:iam::account-id:role/opensearch-secretmanager-role"
    },
    {
      "Effect": "Allow",
      "Action": "es:ESHttpPost",
      "Resource": "arn:aws:es:region:account-id:domain/domain-name/*"
    }
  ]
}

如果您的用户或角色没有 iam:PassRole 权限传递您的角色，则在下一步骤中尝试注册存储库时，您可能会遇到授权错误：

设置 Amazon Secrets Manager

要将您的授权凭证存储在 Secrets Manager 中，请参阅 Amazon Secrets Manager 用户指南中的创建 Amazon Secrets Manager 密钥。

在 Secrets Manager 接受您的键值对作为密钥后，您会收到一个格式为 arn:aws:secretsmanager:us-west-2:123456789012:secret:MySecret-a1b2c3 的 ARN。请记录此 ARN 和密钥，您在下一步创建连接器时会用到。

在 OpenSearch 仪表板中映射 ML 角色（如果使用精细的访问控制）

设置连接器时，精细访问控制会引入额外的步骤。即使将 HTTP 基本身份验证用于所有其他目的，也需要将 ml_full_access 角色映射到具有传递 opensearch-sagemaker-role 的 iam:PassRole 权限的 IAM 角色。

导航到您的 OpenSearch 服务域的 OpenSearch 仪表板插件。您可以在 OpenSearch 服务控制台的域控制面板上找到控制面板终端节点。
从主菜单中选择安全、角色，然后选择 ml_full_access 角色。
选择映射的用户、管理映射。
在后端角色下，添加具有传递 opensearch-sagemaker-role 权限的角色的 ARN。
```
arn:aws:iam::account-id:role/role-name
```
选择映射并确认在映射的用户下显示的用户或角色。

创建 OpenSearch 服务连接器

要创建连接器，请向 OpenSearch 服务域终端节点发送POST请求。您可以使用 curl、示例 Python 客户端、Postman 或其他方法来发送已签名的请求。请注意，您无法在 Kibana 控制台中使用 POST 请求。此请求采用以下形式：


POST domain-endpoint/_plugins/_ml/connectors/_create
{
    "name": "Cohere Connector: embedding",
    "description": "The connector to cohere embedding model",
    "version": 1,
    "protocol": "http",
    "credential": {
        "secretArn": "arn:aws:secretsmanager:region:account-id:secret:cohere-key-id",
        "roleArn": "arn:aws:iam::account-id:role/opensearch-secretmanager-role"
    },
    "actions": [
        {
            "action_type": "predict",
            "method": "POST",
            "url": "https://api.cohere.ai/v1/embed",
            "headers": {
                "Authorization": "Bearer ${credential.secretArn.cohere-key-used-in-secrets-manager}"
            },
            "request_body": "{ \"texts\": ${parameters.texts}, \"truncate\": \"END\" }"
        }
    ]
}

此请求的请求正文在两个方面与开源连接器请求的请求正文不同。在credential字段内，您可以传递允许 OpenSearch 服务从 Secrets Manager 读取的 IAM 角色的 ARN，以及针对什么秘密的 ARN。在 headers 字段中，您使用密钥来引用密钥以及它来自 ARN 的事实。

如果域位于某个虚拟私有云 (VPC) 中，则必须将您的电脑连接到该 VPC，请求才能成功创建 AI 连接器。访问 VPC 因网络配置而异，但通常包括连接到 VPN 或企业网络。要检查您是否可以访问您的 OpenSearch 服务域，请在 Web 浏览器https://your-vpc-domain.region.es.amazonaws.com中导航到并确认收到默认 JSON 响应。

示例 Python 客户端

Python 客户端比 HTTP 请求更容易自动化，并且具有更好的可重用性。要使用 Python 客户端创建 AI 连接器，请将以下示例代码保存到 Python 文件中。客户端需要 Amazon SDK for Python (Boto3)、requests 和 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)

path = '_plugins/_ml/connectors/_create'
url = host + path

payload = {
    "name": "Cohere Connector: embedding",
    "description": "The connector to cohere embedding model",
    "version": 1,
    "protocol": "http",
    "credential": {
        "secretArn": "arn:aws:secretsmanager:region:account-id:secret:cohere-key-id",
        "roleArn": "arn:aws:iam::account-id:role/opensearch-secretmanager-role"
    },
    "actions": [
        {
            "action_type": "predict",
            "method": "POST",
            "url": "https://api.cohere.ai/v1/embed",
            "headers": {
                "Authorization": "Bearer ${credential.secretArn.cohere-key-used-in-secrets-manager}"
            },
            "request_body": "{ \"texts\": ${parameters.texts}, \"truncate\": \"END\" }"
        }
    ]
}

headers = {"Content-Type": "application/json"}

r = requests.post(url, auth=awsauth, json=payload, headers=headers)
print(r.status_code)
print(r.text)

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

连接器适用于 Amazon Web Services

CloudFormation 模板集成