本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 適用於第三方平台的 Amazon OpenSearch Service ML 連接器
<a name="ml-external-connector"></a>

在本教學課程中，我們將介紹如何從 OpenSearch Service 建立連接器到 Cohere。如需連接器的詳細資訊，請參閱[支援的連接器](https://opensearch.org/docs/latest/ml-commons-plugin/remote-models/connectors/#supported-connectors)。

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

**Topics**
+ [先決條件](#connector-external-prereq)
+ [建立 OpenSearch Service 連接器](#connector-external-create)

## 先決條件
<a name="connector-external-prereq"></a>

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

### 建立 IAM 角色
<a name="connector-external-iam"></a>

設定 IAM 角色將 Secrets Manager 許可委派給 OpenSearch Service。您也可以使用現有的 `SecretManagerReadWrite` 角色。若要建立新角色，請參閱《[IAM 使用者指南》中的建立 IAM 角色 （主控台）](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html#roles-creatingrole-user-console)。 **如果您確實建立新的角色，而不是使用 AWS 受管角色，請在本教學`opensearch-secretmanager-role`課程中將 取代為您自己的角色名稱。

1. 將下列受管 IAM 政策連接至您的新角色，以允許 OpenSearch Service 存取您的 Secrets Manager 值。若要將政策連接至角色，請參閱[新增 IAM Identity Permissions](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html#add-policies-console)。

------
#### [ JSON ]

****  

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

------

1. 遵循[修改角色信任政策](https://docs.aws.amazon.com/IAM/latest/UserGuide/roles-managingrole-editing-console.html#roles-managingrole_edit-trust-policy)中的指示來編輯角色的信任關係。在下列政策中，將 *service-principal* 取代為下列其中一個適用於 OpenSearch Service 或 OpenSearch Serverless 的服務主體：  
**對於 OpenSearch Service**  
`opensearchservice.amazonaws.com`  
**對於 OpenSearch Serverless**  
`ml.opensearchservice.amazonaws.com`

------
#### [ JSON ]

****  

   ```
   {
       "Version":"2012-10-17",		 	 	 
       "Statement": [
           {
               "Action": [
                   "sts:AssumeRole"
               ],
               "Effect": "Allow",
               "Principal": {
                   "Service": [
                       "service-principle"
                   ]
               }
           }
       ]
   }
   ```

------

   我們建議您使用 `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"
       }
   }
   ```

### 設定 許可
<a name="connector-external-permissions"></a>

若要建立連接器，您需要將 IAM 角色傳遞至 OpenSearch Service 的許可。您也需要存取 `es:ESHttpPost` 動作。若要授予這兩個許可，請將下列政策連接至其憑證用於簽署請求的 IAM 角色：

------
#### [ JSON ]

****  

```
{
  "Version":"2012-10-17",		 	 	 
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "iam:PassRole",
      "Resource": "arn:aws:iam::111122223333:role/opensearch-secretmanager-role"
    },
    {
      "Effect": "Allow",
      "Action": "es:ESHttpPost",
      "Resource": "arn:aws:es:us-east-1:111122223333:domain/domain-name/*"
    }
  ]
}
```

------

如果您的使用者或角色沒有傳遞角色的`iam:PassRole`許可，當您在下一個步驟嘗試註冊儲存庫時，可能會遇到授權錯誤。

### 設定 AWS Secrets Manager
<a name="connector-external-sm"></a>

若要在 Secrets Manager 中存放授權憑證，請參閱*AWS Secrets Manager 《 使用者指南*》中的[建立 AWS Secrets Manager 秘密](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)。

在 Secrets Manager 接受金鑰/值對做為秘密後，您會收到格式為 的 ARN`arn:aws:secretsmanager:us-west-2:123456789012:secret:MySecret-a1b2c3`。保留此 ARN 的記錄，當您在下一個步驟中建立連接器時使用該 ARN 和金鑰。

### 在 OpenSearch Dashboards 中映射 ML 角色 （如果使用精細存取控制）
<a name="connector-external-fgac"></a>

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

1. 導覽至 OpenSearch Service 網域的 OpenSearch Dashboards 外掛程式。您可以在 OpenSearch Service 主控台的網域儀表板上找到 Dashboards 端點。

1. 從主選單選擇**安全性**、**角色**，然後選取 **ml\$1full\$1access** 角色。

1. 選擇 **Mapped users** (已映射的使用者)、**Manage mapping** (管理映射)。

1. 在**後端角色**下，新增具有傳遞 許可之角色的 ARN`opensearch-sagemaker-role`。

   ```
   arn:aws:iam::account-id:role/role-name
   ```

1. 選擇 **Map** (映射)，並確認使用者或角色顯示在 **Mapped users** (已映射的使用者) 中。

## 建立 OpenSearch Service 連接器
<a name="connector-external-create"></a>

若要建立連接器，請將`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 用戶端範例
<a name="connector-external-python"></a>

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)

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)
```