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

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

将 Amazon OpenSearch Service 机器学习（ML）连接器与外部远程模型结合使用时，您需要将具体的授权凭证存储到 Amazon Secrets Manager 中。这可能是 API 密钥，也可以是用户名和密码组合。这意味着您还需要创建一个 IAM 角色来允许 OpenSearch Service 从 Secrets Manager 中读取数据。

主题

先决条件
创建 OpenSearch Service 连接器

先决条件

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

创建 IAM 角色

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

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


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

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


{
    "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 角色传递给 OpenSearch Service。还需要对 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 Service 域的 OpenSearch 控制面板插件。您可以在 OpenSearch Service 控制台的域控制面板中找到控制面板端点。
从主菜单中选择安全、角色，然后选择 ml_full_access 角色。
选择映射的用户、管理映射。
在后端角色下，添加具有传递 opensearch-sagemaker-role 权限的角色的 ARN。
```
arn:aws:iam::account-id:role/role-name
```
选择映射并确认在映射的用户下显示的用户或角色。

创建 OpenSearch Service 连接器

要创建连接器，请将 POST 请求发送到 OpenSearch Service 域端点。您可以使用 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 Service 从 Secrets Manager 读取的 IAM 角色的 ARN 以及什么密文的 ARN。在 headers 字段中，您使用密钥来引用密钥以及它来自 ARN 的事实。

如果域位于某个虚拟私有云 (VPC) 中，则必须将您的电脑连接到该 VPC，请求才能成功创建 AI 连接器。访问 VPC 因网络配置而异，但通常包括连接到 VPN 或企业网络。要检查您是否可以访问 OpenSearch Service 域，请在 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 模板集成