翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

サードパーティプラットフォーム用の Amazon OpenSearch Service ML コネクタ

このチュートリアルでは、OpenSearch Service から Cohere へのコネクタを作成する方法について説明します。コネクタの詳細については、「Supported connectors」を参照してください。

Amazon OpenSearch Service 機械学習 (ML) コネクタを外部リモートモデルで使用する場合は、特定の権限がある認証情報を AWS Secrets Managerに保存する必要があります。これは API キーでも、ユーザー名とパスワードの組み合わせでもかまいません。つまり、OpenSearch Service のアクセスを Secrets Manager からの読み取りを許可する IAM ロールも作成する必要があるということです。

前提条件

Cohere または OpenSearch Service を使用する外部プロバイダーのコネクタを作成するには、認証情報 AWS Secrets Managerを保存する OpenSearch Service へのアクセスを許可する IAM ロールが必要です。また、認証情報は Secrets Manager に保存する必要があります。

IAM ロールを作成する

IAM ロールを設定して、OpenSearch Service に Secrets Manager のアクセス許可を委任します。既存の SecretManagerReadWrite ロールも使用できます。新しいロールを作成するには、IAM ユーザーガイドの「IAM ロール (コンソール) の作成」を参照してください。 AWS マネージドロールを使用する代わりに新しいロールを作成する場合は、このチュートリアルopensearch-secretmanager-roleの を独自のロールの名前に置き換えます。

アクセス許可の設定

コネクタを作成するには、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 User Guide」の「Create an AWS Secrets Manager secret」を参照してください。

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 ロールをマップする必要があります。

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