翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# サードパーティプラットフォーム用の Amazon OpenSearch Service ML コネクタ
このチュートリアルでは、OpenSearch Service から Cohere へのコネクタを作成する方法について説明します。コネクタの詳細については、「[Supported connectors](https://opensearch.org/docs/latest/ml-commons-plugin/remote-models/connectors/#supported-connectors)」を参照してください。
Amazon OpenSearch Service 機械学習 (ML) コネクタを外部リモートモデルで使用する場合は、特定の権限がある認証情報を AWS Secrets Managerに保存する必要があります。これは API キーでも、ユーザー名とパスワードの組み合わせでもかまいません。つまり、OpenSearch Service のアクセスを Secrets Manager からの読み取りを許可する IAM ロールも作成する必要があるということです。
**Topics**
+ [前提条件](#connector-external-prereq)
+ [OpenSearch Service コネクタを作成する](#connector-external-create)
## 前提条件
Cohere または OpenSearch Service を使用する外部プロバイダーのコネクタを作成するには、認証情報 AWS Secrets Managerを保存する OpenSearch Service へのアクセスを許可する IAM ロールが必要です。また、認証情報は Secrets Manager に保存する必要があります。
### IAM ロールを作成する
IAM ロールを設定して、OpenSearch Service に Secrets Manager のアクセス許可を委任します。既存の `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 ID アクセス許可の追加](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 の次のいずれかのサービスプリンシパルに置き換えます。
**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}}"
}
}
```
### アクセス許可の設定
コネクタを作成するには、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
認可の認証情報を Secrets Manager に保存するには、「*AWS Secrets Manager User Guide*」の「[Create an AWS Secrets Manager secret](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 はキーと使用するので記録しておいてください。
### OpenSearch Dashboards に ML ロールをマッピングします (きめ細かなアクセスコントロールを使用している場合)
きめ細かいアクセス制御では、コネクタの設定時に追加の手順が必要になります。HTTP 基本認証を他のすべての目的で使用する場合でも、`opensearch-sagemaker-role` を渡すための `iam:PassRole` 許可を持っている IAM ロールまたはユーザーに `ml_full_access` ロールをマップする必要があります。
1. OpenSearch Service ドメインの OpenSearch Dashboards プラグインに移動します。OpenSearch Service コンソールのドメインダッシュボードに Dashboards エンドポイントがあります。
1. メインメニューから [**セキュリティ**]、[**ロール**] を選択し、[**ml\_full\_access**] ロールを選択します。
1. **[マッピングされたユーザー]**、**[マッピングの管理]** を選択します。
1. **[バックエンドロール]** で、`opensearch-sagemaker-role` を渡すためのアクセス許可があるロールの ARN を追加します。
```
arn:aws:iam::{{account-id}}:role/{{role-name}}
```
1. **[マップ]** を選択し、ユーザーまたはロールが **[マッピングされたユーザー]** の下に表示されていることを確認します。
## OpenSearch Service コネクタを作成する
コネクタを作成するには、OpenSearch Service ドメインのエンドポイントに `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\" }"
}
]
}
```
このリクエストのリクエスト本文は、オープンソースのコネクタリクエストのリクエスト本文と 2 つの点で異なります。`credential` フィールド内では、OpenSearch Service が Secrets Manager から読み取ることを許可する IAM ロールの ARN と、シークレットの ARN を渡します。`headers` フィールドでは、シークレットキーとそれが ARN からのものであるという事実を用いてシークレットを参照します。
ドメインが仮想プライベートクラウド (VPC) に存在する場合は、リクエストが AI コネクタを正常に作成するには、コンピュータが VPC に接続されていることが必要です。VPC へのアクセスはネットワーク構成によって異なりますが、通常は VPN あるいは社内ネットワークへの接続が必要になります。OpenSearch Service ドメインにアクセスできるかを確認するには、ウェブブラウザで `https://{{your-vpc-domain}}.{{region}}.es.amazonaws.com` を開き、デフォルトの JSON 応答を受信していることを確認します。
### Python クライアントのサンプリング
Python クライアントは、HTTP リクエストよりも自動化が簡単で、再利用性も高いです。Python クライアントで AI コネクタを作成するには、以下のサンプルコードを Python ファイルに保存します。このクライアントには [AWS SDK for Python (Boto3)](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)
```