適用於第三方平台的 Amazon OpenSearch Service ML 連接器

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

當您搭配外部遠端模型使用 Amazon OpenSearch Service 機器學習 (ML) 連接器時，您需要將特定授權憑證存放在其中 AWS Secrets Manager。這可以是 API 金鑰或使用者名稱和密碼組合。這表示您也需要建立 IAM 角色，允許 OpenSearch Service 存取從 Secrets Manager 讀取。

主題

先決條件
建立 OpenSearch Service 連接器

先決條件

若要使用 OpenSearch Service 為 Cohere 或任何外部提供者建立連接器，您必須擁有 IAM 角色，將 OpenSearch Service 存取權授予您存放登入資料 AWS Secrets Manager的位置。您也必須將登入資料存放在 Secrets Manager 中。

建立 IAM 角色

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

將下列受管 IAM 政策連接至您的新角色，以允許 OpenSearch Service 存取您的 Secrets Manager 值。若要將政策連接至角色，請參閱新增 IAM Identity Permissions。


{
    "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 是屬於網域擁有者的 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 角色：


{
  "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 接受金鑰值對做為秘密後，您會收到格式為的 ARNarn:aws:secretsmanager:us-west-2:123456789012:secret:MySecret-a1b2c3。在下一個步驟中建立連接器時，請保留此 ARN 的記錄，當您使用該 ARN 和金鑰時。

在 OpenSearch Dashboards 中映射 ML 角色（如果使用精細存取控制）

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

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

建立 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欄位中，您會傳遞 IAM 角色的 ARN，該角色允許 OpenSearch Service 從 Secrets Manager 讀取，以及哪個秘密的 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 檔案。用戶端需要 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 範本整合