適用於第三方平台的 Amazon OpenSearch 服務 ML

在本教程中，我們將介紹如何創建從 OpenSearch 服務到 Cohere 的連接器。如需連接器的詳細資訊，請參閱支援的連接器。

當您將 Amazon Ser OpenSearch vice 機器學習 (ML) 連接器與外部遠端模型搭配使用時，您需要將特定的授權登入資料存放在中 AWS Secrets Manager。這可能是 API 密鑰，也可以是用戶名和密碼的組合。這意味著您還需要創建一個 IAM 角色，以允許從 Secrets Manager 讀取 OpenSearch 服務訪問權限。

主題

必要條件
建立 OpenSearch 服務連接器

必要條件

若要為 Cohere 或任何具有服務的外部提供者建立連接器，您必須具有可授與 OpenSearch 服 OpenSearch 務存取權的 IAM 角色 AWS Secrets Manager，並在其中儲存您的登入資料。您也必須將您的認證儲存在 Secrets Manager 中。

建立 IAM 角色

設定 IAM 角色以將 Secrets Manager 權限委派給 OpenSearch 服務。您也可以使用現有的SecretManagerReadWrite角色。若要建立新角色，請參閱 IAM 使用者指南中的建立 IAM 角色 (主控台)。如果您確實建立新角色而不是使用 AWS 受管理的角色，請將本教學課程opensearch-secretmanager-role中的角色名稱取代為您自己的角色名稱。

將下列受管身分與存取權管理政策附加到您的新角色，以允許 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是屬於網域擁有者的 AWS 帳戶 ID，而且SourceArn是網域的 ARN。例如，您可以將下列條件區塊新增至信任原則：


"Condition": {
    "StringEquals": {
        "aws:SourceAccount": "account-id"
    },
    "ArnLike": {
        "aws:SourceArn": "arn:aws:es:region:account-id:domain/domain-name"
    }
}

設定許可

若要建立連接器，您需要將 IAM 角色傳遞給 OpenSearch 服務的權限。您也需要存取 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權限，則在下一個步驟中嘗試註冊存放庫時可能會遇到授權錯誤。

設定 AWS Secrets Manager

若要將您的授權認證儲存在 Secrets Manager 中，請參閱AWS Secrets Manager 使用者指南中的建立密 AWS Secrets Manager 碼。

當 Secrets Manager 接受您的鍵值對作為密碼之後，您會收到一個 ARN，格式為：。arn:aws:secretsmanager:us-west-2:123456789012:secret:MySecret-a1b2c3在下一個步驟中建立連接器時，請記錄此 ARN 以及您的金鑰。

在 OpenSearch 儀表板中對應 ML 角色 (如果使用精細的存取控制)

精細的存取控制會在設定連接器時引入額外的步驟。即使您將 HTTP 基本身分驗證用於所有其他目的，您也需要將 ml_full_access 角色映射至擁有 iam:PassRole 許可能夠傳遞 opensearch-sagemaker-role 的 IAM 角色。

導覽至 OpenSearch 服務網域的 OpenSearch 儀表板外掛程式。您可以在 OpenSearch 服務主控台上的網域儀表板上找到儀表板端點。
從主功能表中選擇安全性、角色，然後選取 ml_full_ access 角色。
選擇 Mapped users (已映射的使用者)、Manage mapping (管理映射)。
在後端角色下，新增具有通過opensearch-sagemaker-role權限之角色的 ARN。
```
arn:aws:iam::account-id:role/role-name
```
選擇 Map (映射)，並確認使用者或角色顯示在 Mapped users (已映射的使用者) 中。

建立 OpenSearch 服務連接器

若要建立連接器，請將要POST求傳送至 OpenSearch 服務網域端點。您可以使用 curl、Python 用戶端範例、郵遞員或其他方法來傳送已簽署的要求。請注意，您無法在 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欄位內，您會傳遞 IAM 角色的 ARN，該角色允許 OpenSearch 服務從 Secrets Manager 讀取，以及 ARN 以取得什麼秘密。在該headers字段中，您可以使用秘密密鑰以及其來自 ARN 的事實來參考秘密。

如果您的網域位於虛擬私有雲 (VPC) 內，您的電腦必須連線至 VPC，才能成功建立 AI 連接器的要求。存取 VPC 會因網路組態而異，但通常涉及連線至 VPN 或公司網路。要檢查您是否可以訪問 OpenSearch 服務域，請https://your-vpc-domain.region.es.amazonaws.com在 Web 瀏覽器中導航到並確認您收到默認的 JSON 響應。

示例 Python 客戶端

Python 客戶端比 HTTP 請求更容易自動化，並且具有更好的可重用性。若要使用 Python 用戶端建立 AI 連接器，請將下列範例程式碼儲存至 Python 檔案。用戶端需要AWS 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。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

用於連接器 AWS 服務

CloudFormation 模板集成