View a markdown version of this page

Connettori Amazon OpenSearch Service ML per Servizi AWS - OpenSearch Servizio Amazon
PrerequisitiCrea un connettore di servizio OpenSearch

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Connettori Amazon OpenSearch Service ML per Servizi AWS

Quando utilizzi i connettori di machine learning (ML) di Amazon OpenSearch Service con un altro Servizio AWS, devi configurare un ruolo IAM per connettere OpenSearch in modo sicuro il servizio a quel servizio. Servizi AWS che puoi configurare un connettore per includere Amazon SageMaker AI e Amazon Bedrock. In questo tutorial, spieghiamo come creare un connettore da OpenSearch Service a SageMaker Runtime. Per ulteriori informazioni sui connettori, consulta Connettori supportati.

Prerequisiti

Per creare un connettore, devi disporre di un endpoint di dominio Amazon SageMaker AI e di un ruolo IAM che conceda l'accesso OpenSearch al servizio.

Configura un dominio Amazon SageMaker AI

Consulta Deploy a Model in Amazon SageMaker AI nella Amazon SageMaker AI Developer Guide per implementare il tuo modello di machine learning. Annota l'URL dell'endpoint del tuo modello, necessario per creare un connettore AI.

Creazione di un ruolo IAM

Configura un ruolo IAM per delegare le autorizzazioni SageMaker di runtime al servizio. OpenSearch Per creare un nuovo ruolo, consulta Creazione di un ruolo IAM (console) nella IAM User Guide. Facoltativamente, puoi utilizzare un ruolo esistente purché abbia lo stesso set di privilegi. Se crei un nuovo ruolo invece di usare un ruolo AWS gestito, sostituiscilo opensearch-sagemaker-role in questo tutorial con il nome del tuo ruolo.

  1. Allega la seguente policy IAM gestita al tuo nuovo ruolo per consentire al OpenSearch Service di accedere al tuo endpoint SageMaker AI. Per allegare una policy a un ruolo, consulta Aggiungere autorizzazioni di identità IAM.

    JSON
    {
    "Version":"2012-10-17",
    "Statement": [
        {   
            "Action": [
                "sagemaker:InvokeEndpointAsync",
                "sagemaker:InvokeEndpoint"
            ],
            "Effect": "Allow",
            "Resource": "*"
        }
    ]
}

  2. Segui le istruzioni in Modifica della politica di fiducia di un ruolo per modificare la relazione di fiducia del ruolo. Nella seguente politica, sostituiscila service-principal con uno dei seguenti principi di servizio per OpenSearch Service o OpenSearch Serverless:

    Per l'assistenza OpenSearch

    opensearchservice.amazonaws.com o es.amazonaws.com

    Per OpenSearch Serverless

    ml.opensearchservice.amazonaws.com

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

    Ti consigliamo di utilizzare le chiavi di aws:SourceArn condizione aws:SourceAccount e per limitare l'accesso a un dominio specifico. SourceAccountÈ l' Account AWS ID che appartiene al proprietario del dominio e SourceArn è l'ARN del dominio. Ad esempio, puoi aggiungere il seguente blocco di condizioni alla politica di fiducia: 

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

Configurazione delle autorizzazioni

Per creare il connettore, è necessaria l'autorizzazione per passare il ruolo IAM al OpenSearch servizio. Devi inoltre disporre dell'accesso all'operazione es:ESHttpPost. Per concedere entrambe queste autorizzazioni, collega la policy seguente al ruolo IAM le cui credenziali vengono utilizzate per firmare la richiesta:

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

Se il tuo utente o ruolo non dispone iam:PassRole delle autorizzazioni per passare il tuo ruolo, potresti riscontrare un errore di autorizzazione quando provi a registrare un repository nella fase successiva.

Mappate il ruolo ML in OpenSearch Dashboards (se utilizzate un controllo di accesso granulare)

Fine-grained il controllo degli accessi introduce un passaggio aggiuntivo durante la configurazione di un connettore. Anche se si utilizza l'autenticazione di base HTTP per tutti gli altri scopi, è necessario mappare il ruolo ml_full_access al ruolo IAM che dispone delle autorizzazioni iam:PassRole per inviare opensearch-sagemaker-role.

  1. Accedi al plug-in OpenSearch Dashboards per il tuo dominio di OpenSearch servizio. Puoi trovare l'endpoint Dashboards nella dashboard del tuo dominio nella console del OpenSearch servizio.

  2. Dal menu principale scegli Sicurezza, Ruoli e seleziona il ruolo ml_full_access.

  3. Scegliere Utenti mappati, Gestisci mappatura.

  4. In Ruoli di backend, aggiungete l'ARN del ruolo che dispone delle autorizzazioni da passare. opensearch-sagemaker-role

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

  5. Selezionare Mappa e confermare che l'utente o il ruolo venga visualizzato in Utenti mappati.

Crea un connettore di servizio OpenSearch

Per creare un connettore, invia una POST richiesta all'endpoint del dominio OpenSearch Service. Puoi usare curl, il client Python di esempio, Postman o un altro metodo per inviare una richiesta firmata. Nota che non puoi usare una POST richiesta nella console Kibana. La richiesta ha il seguente formato:

POST domain-endpoint/_plugins/_ml/connectors/_create
{
   "name": "sagemaker: embedding",
   "description": "Test connector for Sagemaker embedding model",
   "version": 1,
   "protocol": "aws_sigv4",
   "credential": {
      "roleArn": "arn:aws:iam::account-id:role/opensearch-sagemaker-role"
   },
   "parameters": {
      "region": "region",
      "service_name": "sagemaker"
   },
   "actions": [
      {
         "action_type": "predict",
         "method": "POST",
         "headers": {
            "content-type": "application/json"
         },
         "url": "https://runtime.sagemaker.region.amazonaws.com/endpoints/endpoint-id/invocations",
         "request_body": "{ \"inputs\": { \"question\": \"${parameters.question}\", \"context\": \"${parameters.context}\" } }"
      }
   ]
}

Se il tuo dominio risiede in un cloud privato virtuale (VPC), il tuo computer deve essere connesso al VPC affinché la richiesta crei correttamente il connettore AI. L'accesso a un VPC varia in base alla configurazione di rete, ma in genere comporta la connessione a una VPN o a una rete aziendale. Per verificare di poter raggiungere il dominio del OpenSearch servizio, accedi a questo indirizzo https://your-vpc-domain.region.es.amazonaws.com in un browser Web e verifica di ricevere la risposta JSON predefinita.

Esempio di client Python

Il client Python è più semplice da automatizzare rispetto a una richiesta HTTP e ha una migliore riutilizzabilità. Per creare il connettore AI con il client Python, salva il seguente codice di esempio in un file Python. Il client richiede i pacchetti AWS SDK per Python (Boto3) requests, e 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)

# Register repository
path = '_plugins/_ml/connectors/_create'
url = host + path

payload = {
   "name": "sagemaker: embedding",
   "description": "Test connector for Sagemaker embedding model",
   "version": 1,
   "protocol": "aws_sigv4",
   "credential": {
      "roleArn": "arn:aws:iam::account-id:role/opensearch-sagemaker-role"
   },
   "parameters": {
      "region": "region",
      "service_name": "sagemaker"
   },
   "actions": [
      {
         "action_type": "predict",
         "method": "POST",
         "headers": {
            "content-type": "application/json"
         },
         "url": "https://runtime.sagemaker.region.amazonaws.com/endpoints/endpoint-id/invocations",
         "request_body": "{ \"inputs\": { \"question\": \"${parameters.question}\", \"context\": \"${parameters.context}\" } }"
      }
   ]
}
headers = {"Content-Type": "application/json"}

r = requests.post(url, auth=awsauth, json=payload, headers=headers)
print(r.status_code)
print(r.text)

Registra il modello per la ricerca semantica

Se intendete utilizzare il modello connesso per la ricerca semantica, dovete includere il model_config parametro al momento della registrazione del modello. Senza questo parametro, la creazione dell'indice dei campi semantici fallirà con l'errore «La configurazione del modello è nulla per il modello remoto []». model_id

Includi un model_config oggetto nella richiesta del modello di registro:

POST _plugins/_ml/models/_register
{
  "name": "Bedrock embedding model",
  "function_name": "remote",
  "connector_id": "connector_id",
  "model_config": {
    "model_type": "TEXT_EMBEDDING",
    "embedding_dimension": 1536,
    "framework_type": "SENTENCE_TRANSFORMERS",
    "additional_config": {
      "space_type": "l2"
    }
  }
}

Sostituiscilo embedding_dimension con la dimensione dell'output del tuo modello (ad esempio, 1536 per Amazon Titan Embeddings). Per informazioni sui tipi di spazio supportati, consulta la ricerca k-NN in Amazon Service. OpenSearch