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 piattaforme di terze parti
In questo tutorial, spieghiamo come creare un connettore da OpenSearch Service a Cohere. Per ulteriori informazioni sui connettori, consulta [Connettori supportati](https://opensearch.org/docs/latest/ml-commons-plugin/remote-models/connectors/#supported-connectors).
Quando utilizzi un connettore di apprendimento automatico (ML) di Amazon OpenSearch Service con un modello remoto esterno, devi memorizzare le tue credenziali di autorizzazione specifiche in Gestione dei segreti AWS. Potrebbe trattarsi di una chiave API o di una combinazione di nome utente e password. Ciò significa che devi anche creare un ruolo IAM che consenta l'accesso al OpenSearch servizio per la lettura da Secrets Manager.
**Topics**
+ [Prerequisiti](#connector-external-prereq)
+ [Crea un connettore di servizio OpenSearch](#connector-external-create)
## Prerequisiti
Per creare un connettore per Cohere o per qualsiasi provider esterno con OpenSearch Service, devi disporre di un ruolo IAM che conceda l'accesso al OpenSearch Servizio Gestione dei segreti AWS, a cui archiviare le tue credenziali. È inoltre necessario memorizzare le credenziali in Secrets Manager.
### Creazione di un ruolo IAM
Imposta un ruolo IAM per delegare le autorizzazioni di Secrets Manager a OpenSearch Service. Puoi anche utilizzare il ruolo esistente`SecretManagerReadWrite`. Per creare un nuovo ruolo, consulta [Creating an IAM role (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html#roles-creatingrole-user-console) nella *IAM User Guide*. Se crei un nuovo ruolo invece di utilizzare un ruolo AWS gestito, `opensearch-secretmanager-role` sostituiscilo in questo tutorial con il nome del tuo ruolo.
1. Allega la seguente policy IAM gestita al tuo nuovo ruolo per consentire a OpenSearch Service di accedere ai tuoi valori di Secrets Manager. Per allegare una policy a un ruolo, consulta [Aggiungere autorizzazioni di identità IAM](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. Segui le istruzioni riportate in [Modifica della politica di fiducia di un ruolo](https://docs.aws.amazon.com/IAM/latest/UserGuide/roles-managingrole-editing-console.html#roles-managingrole_edit-trust-policy) per modificare la relazione di trust del ruolo. Nella seguente politica, sostituiscila {{service-principal}} con uno dei seguenti principali di servizio per OpenSearch Service o OpenSearch Serverless:
**Per Service OpenSearch **
`opensearchservice.amazonaws.com`
**Per OpenSearch Serverless**
`ml.opensearchservice.amazonaws.com`
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"sts:AssumeRole"
],
"Effect": "Allow",
"Principal": {
"Service": [
"{{service-principle}}"
]
}
}
]
}
```
------
Ti consigliamo di utilizzare i tasti `aws:SourceAccount` e `aws:SourceArn` condition per limitare l'accesso a un dominio specifico. `SourceAccount`è l' Account AWS ID che appartiene al proprietario del dominio e il `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 a OpenSearch Service. 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-secretmanager-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 trasferire il ruolo, potresti riscontrare un errore di autorizzazione quando tenti di registrare un repository nel passaggio successivo.
### Configurare Gestione dei segreti AWS
Per memorizzare le credenziali di autorizzazione in Secrets Manager, consulta [Creare un Gestione dei segreti AWS segreto](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html) nella *Guida per l'Gestione dei segreti AWS utente*.
Dopo che Secrets Manager ha accettato la coppia chiave-valore come segreta, riceverai un ARN con il formato:. `arn:aws:secretsmanager:us-west-2:123456789012:secret:MySecret-a1b2c3` Tieni traccia di questo ARN, così come lo usi, e della tua chiave quando crei un connettore nel passaggio successivo.
### Mappa il ruolo ML nelle OpenSearch dashboard (se utilizzi un controllo di accesso granulare)
Il controllo granulare degli accessi introduce un passaggio aggiuntivo per 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. Vai al plug-in OpenSearch Dashboards per il tuo dominio di servizio. OpenSearch Puoi trovare l'endpoint Dashboards nella dashboard del tuo dominio nella OpenSearch console di servizio.
1. Dal menu principale scegli **Sicurezza**, **Ruoli e seleziona il ruolo** **ml\_full\_access**.
1. Scegliere **Utenti mappati**, **Gestisci mappatura**.
1. In **Ruoli di backend**, aggiungi l'ARN del ruolo che ha le autorizzazioni da passare. `opensearch-sagemaker-role`
```
arn:aws:iam::{{account-id}}:role/{{role-name}}
```
1. 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 di OpenSearch servizio. 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": "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\" }"
}
]
}
```
Il corpo della richiesta per questa richiesta è diverso da quello di una richiesta di connettore open source in due modi. All'interno del `credential` campo, si passa l'ARN per il ruolo IAM che consente a OpenSearch Service di leggere da Secrets Manager, insieme all'ARN per il segreto what. Nel `headers` campo, si fa riferimento al segreto utilizzando la chiave segreta e al fatto che proviene da un ARN.
Se il dominio risiede all'interno di un cloud privato virtuale (VPC), il 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 di solito comporta la connessione a una VPN o a una rete aziendale. Per verificare di poter accedere al dominio del OpenSearch servizio, accedi a `https://{{your-vpc-domain}}.{{region}}.es.amazonaws.com` In un browser Web e verifica di ricevere la risposta JSON predefinita.
### Client Python di esempio
Il client Python è più semplice da automatizzare rispetto a una richiesta HTTP e ha una migliore riusabilità. 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)[https://requests.readthedocs.io/en/latest/](https://requests.readthedocs.io/en/latest/)](https://aws.amazon.com/sdk-for-python/), e [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)
```