Amazon OpenSearch Service ML-Konnektoren für Plattformen von Drittanbietern

In diesem Tutorial erfahren Sie, wie Sie einen Connector von OpenSearch Service zu Cohere erstellen. Weitere Informationen zu Konnektoren finden Sie unter Unterstützte Konnektoren.

Wenn Sie einen Amazon OpenSearch Service Machine Learning (ML) Connector mit einem externen Remote-Modell verwenden, müssen Sie Ihre spezifischen Autorisierungsdaten in speichern AWS Secrets Manager. Dies kann ein API-Schlüssel oder eine Kombination aus Benutzername und Passwort sein. Das bedeutet, dass Sie auch eine IAM-Rolle erstellen müssen, die es OpenSearch Service Access ermöglicht, aus Secrets Manager zu lesen.

Voraussetzungen

Um einen Connector für Cohere oder einen externen Anbieter mit OpenSearch Service zu erstellen, benötigen Sie eine IAM-Rolle, die dem OpenSearch Service Zugriff auf den Ort gewährt AWS Secrets Manager, an dem Sie Ihre Anmeldeinformationen speichern. Sie müssen Ihre Anmeldeinformationen auch in Secrets Manager speichern.

Erstellen einer IAM-Rolle

Richten Sie eine IAM-Rolle ein, um Secrets Manager Manager-Berechtigungen an den Service zu OpenSearch delegieren. Sie können auch die vorhandene SecretManagerReadWrite Rolle verwenden. Informationen zum Erstellen einer neuen Rolle finden Sie unter Erstellen einer IAM-Rolle (Konsole) im IAM-Benutzerhandbuch. Wenn Sie eine neue Rolle erstellen, anstatt eine AWS verwaltete Rolle zu verwenden, ersetzen Sie sie opensearch-secretmanager-role in diesem Tutorial durch den Namen Ihrer eigenen Rolle.

1. Fügen Sie Ihrer neuen Rolle die folgende verwaltete IAM-Richtlinie hinzu, damit OpenSearch Service auf Ihre Secrets Manager Manager-Werte zugreifen kann. Informationen zum Anhängen einer Richtlinie an eine Rolle finden Sie unter Hinzufügen von IAM-Identitätsberechtigungen.

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

2. Folgen Sie den Anweisungen unter Vertrauensrichtlinie für Rollen ändern, um die Vertrauensstellung der Rolle zu bearbeiten. Sie müssen OpenSearch Service in der Principal Erklärung angeben:

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Action": [
                   "sts:AssumeRole"
               ],
               "Effect": "Allow",
               "Principal": {
                   "Service": [
                       "opensearchservice.amazonaws.com"
                   ]
               }
           }
       ]
   }

   Es wird empfohlen, die Bedingungsschlüssel aws:SourceAccount und die aws:SourceArn Bedingungsschlüssel zu verwenden, um den Zugriff auf eine bestimmte Domäne zu beschränken. Das SourceAccount ist die AWS-Konto ID, die dem Besitzer der Domain gehört, und das SourceArn ist der ARN der Domain. Sie können der Vertrauensrichtlinie beispielsweise den folgenden Bedingungsblock hinzufügen:

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

Konfigurieren von Berechtigungen

Um den Connector zu erstellen, benötigen Sie die Erlaubnis, die IAM-Rolle an OpenSearch Service zu übergeben. Sie benötigen außerdem Zugriff auf die Aktion es:ESHttpPost. Um diese beiden Berechtigungen zu erteilen, fügen Sie die folgende Richtlinie an die IAM-Rolle an, deren Anmeldeinformationen zum Signieren der Anforderung verwendet werden:

{
  "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/*"
    }
  ]
}

Wenn Ihr Benutzer oder Ihre Rolle nicht iam:PassRole berechtigt ist, Ihre Rolle weiterzugeben, kann es sein, dass beim Versuch, ein Repository im nächsten Schritt zu registrieren, ein Autorisierungsfehler auftritt.

Richten Sie ein AWS Secrets Manager

Informationen zum Speichern Ihrer Autorisierungsdaten in Secrets Manager finden Sie unter Create an AWS Secrets Manager Secret im AWS Secrets Manager Benutzerhandbuch.

Nachdem Secrets Manager Ihr Schlüssel-Wert-Paar als Geheimnis akzeptiert hat, erhalten Sie einen ARN mit dem Format:. arn:aws:secretsmanager:us-west-2:123456789012:secret:MySecret-a1b2c3 Notieren Sie sich diesen ARN, wie Sie ihn verwenden, und Ihren Schlüssel, wenn Sie im nächsten Schritt einen Connector erstellen.

Ordnen Sie die ML-Rolle in OpenSearch Dashboards zu (wenn Sie eine differenzierte Zugriffskontrolle verwenden)

Durch eine differenzierte Zugriffskontrolle wird beim Einrichten eines Konnektors ein zusätzlicher Schritt eingeführt. Auch wenn Sie die HTTP-Basisauthentifizierung für alle anderen Zwecke verwenden, müssen Sie die ml_full_access-Rolle Ihrer IAM-Rolle mit iam:PassRole-Berechtigungen zuordnen, um opensearch-sagemaker-role zu übergeben.

1. Navigieren Sie zum OpenSearch Dashboards-Plugin für Ihre OpenSearch Service-Domain. Sie finden den Dashboards-Endpunkt in Ihrem Domain-Dashboard in der OpenSearch Service-Konsole.

2. Wählen Sie im Hauptmenü Sicherheit, Rollen und dann die Rolle ml_full_access aus.

3. Wählen Sie Zugeordnete Benutzer, Mapping verwalten.

4. Fügen Sie unter Backend-Rollen den ARN der Rolle hinzu, die über Berechtigungen zur Weitergabe opensearch-sagemaker-role verfügt.

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

5. Wählen Sie Zuordnen und bestätigen Sie, dass der Benutzer oder die Rolle unter Zugeordnete Benutzer angezeigt wird.

Erstellen Sie einen OpenSearch Service-Connector

Um einen Connector zu erstellen, senden Sie eine POST Anfrage an den Endpunkt der OpenSearch Service-Domäne. Sie können curl, den Python-Beispielclient, Postman oder eine andere Methode verwenden, um eine signierte Anfrage zu senden. Beachten Sie, dass Sie eine POST Anfrage in der Kibana-Konsole nicht verwenden können. Die Anfrage hat das folgende Format:

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\" }"
        }
    ]
}

Der Anfragetext für diese Anfrage unterscheidet sich in zweierlei Hinsicht von dem einer Open-Source-Connector-Anfrage. Innerhalb des credential Felds übergeben Sie den ARN für die IAM-Rolle, die es OpenSearch Service ermöglicht, aus Secrets Manager zu lesen, zusammen mit dem ARN für welches Geheimnis. In headers diesem Feld verweisen Sie auf das Geheimnis, indem Sie den geheimen Schlüssel und die Tatsache verwenden, dass es aus einem ARN stammt.

Wenn sich Ihre Domain in einer Virtual Private Cloud (VPC) befindet, muss Ihr Computer mit der VPC verbunden sein, damit die Anfrage den AI-Connector erfolgreich erstellen kann. Der Zugriff auf eine VPC hängt von der Netzwerkkonfiguration ab, beinhaltet jedoch in der Regel eine Verbindung zu einem VPN- oder Unternehmensnetzwerk. Um zu überprüfen, ob Sie Ihre OpenSearch Service-Domain erreichen können, navigieren Sie https://your-vpc-domain.region.es.amazonaws.com in einem Webbrowser zu und stellen Sie sicher, dass Sie die Standard-JSON-Antwort erhalten.

Beispiel für einen Python-Client

Der Python-Client ist einfacher zu automatisieren als eine HTTP-Anfrage und hat eine bessere Wiederverwendbarkeit. Um den AI-Konnektor mit dem Python-Client zu erstellen, speichern Sie den folgenden Beispielcode in einer Python-Datei. Der Client benötigt die requests-aws4authPakete AWS SDK for Python (Boto3)requests, und.

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)