Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
# Connecteurs Amazon OpenSearch Service ML pour plateformes tierces
Dans ce didacticiel, nous expliquons comment créer un connecteur de OpenSearch Service à Cohere. Pour plus d'informations sur les connecteurs, voir [Connecteurs pris en charge](https://opensearch.org/docs/latest/ml-commons-plugin/remote-models/connectors/#supported-connectors).
Lorsque vous utilisez un connecteur d'apprentissage automatique (ML) Amazon OpenSearch Service avec un modèle de télécommande externe, vous devez y stocker vos informations d'autorisation spécifiques AWS Secrets Manager. Il peut s'agir d'une clé API ou d'une combinaison de nom d'utilisateur et de mot de passe. Cela signifie que vous devez également créer un rôle IAM qui autorise l'accès au OpenSearch service à lire depuis Secrets Manager.
**Topics**
+ [Conditions préalables](#connector-external-prereq)
+ [Création d'un connecteur OpenSearch de service](#connector-external-create)
## Conditions préalables
Pour créer un connecteur pour Cohere ou tout autre fournisseur externe avec OpenSearch Service, vous devez disposer d'un rôle IAM qui accorde l'accès au OpenSearch Service AWS Secrets Manager, où vous stockez vos informations d'identification. Vous devez également enregistrer vos informations d'identification dans Secrets Manager.
### Créer un rôle IAM
Configurez un rôle IAM pour déléguer les autorisations de Secrets Manager au OpenSearch Service. Vous pouvez également utiliser le `SecretManagerReadWrite` rôle existant. Pour créer un nouveau rôle, consultez la section [Création d'un rôle IAM (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html#roles-creatingrole-user-console) dans le guide de l'*utilisateur IAM*. Si vous créez un nouveau rôle au lieu d'utiliser un rôle AWS géré, remplacez-le `opensearch-secretmanager-role` dans ce didacticiel par le nom de votre propre rôle.
1. Associez la politique IAM gérée suivante à votre nouveau rôle pour permettre au OpenSearch Service d'accéder aux valeurs de vos Secrets Manager. Pour associer une politique à un rôle, consultez la section [Ajout d'autorisations d'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. Suivez les instructions de la [section Modification d'une politique de confiance de rôle](https://docs.aws.amazon.com/IAM/latest/UserGuide/roles-managingrole-editing-console.html#roles-managingrole_edit-trust-policy) pour modifier la relation de confiance du rôle. Dans la politique suivante, remplacez-le *service-principal* par l'un des principes de service suivants pour OpenSearch Service ou OpenSearch Serverless :
**Pour le OpenSearch service**
`opensearchservice.amazonaws.com`
**Pour OpenSearch Serverless**
`ml.opensearchservice.amazonaws.com`
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"sts:AssumeRole"
],
"Effect": "Allow",
"Principal": {
"Service": [
"service-principle"
]
}
}
]
}
```
------
Nous vous recommandons d'utiliser les touches de `aws:SourceArn` condition `aws:SourceAccount` et pour limiter l'accès à un domaine spécifique. `SourceAccount`Il s'agit de l' Compte AWS ID qui appartient au propriétaire du domaine et de l'ARN du domaine. `SourceArn` Par exemple, vous pouvez ajouter le bloc de condition suivant à la politique de confiance :
```
"Condition": {
"StringEquals": {
"aws:SourceAccount": "account-id"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:es:region:account-id:domain/domain-name"
}
}
```
### Configurer les autorisations
Pour créer le connecteur, vous devez être autorisé à transmettre le rôle IAM au OpenSearch Service. Vous avez également besoin de l'accès à l'action `es:ESHttpPost`. Pour accorder ces deux autorisations, attachez la politique suivante au rôle IAM dont les informations d'identification sont utilisées pour signer la demande :
------
#### [ 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/*"
}
]
}
```
------
Si votre utilisateur ou votre rôle n'est pas `iam:PassRole` autorisé à transmettre votre rôle, il se peut que vous rencontriez une erreur d'autorisation lorsque vous tenterez d'enregistrer un référentiel à l'étape suivante.
### Configurez AWS Secrets Manager
Pour enregistrer vos informations d'autorisation dans Secrets Manager, consultez la section [Créer un AWS Secrets Manager secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html) dans le *Guide de AWS Secrets Manager l'utilisateur*.
Une fois que Secrets Manager a accepté votre paire clé-valeur en tant que secret, vous recevez un ARN au format :. `arn:aws:secretsmanager:us-west-2:123456789012:secret:MySecret-a1b2c3` Conservez un enregistrement de cet ARN, tel que vous l'utilisez, ainsi que de votre clé lorsque vous créerez un connecteur à l'étape suivante.
### Cartographier le rôle du machine learning dans OpenSearch les tableaux de bord (si vous utilisez un contrôle d'accès précis)
Le contrôle d'accès précis introduit une étape supplémentaire lors de la configuration d'un connecteur. Même si vous utilisez l'authentification de base HTTP à toutes les autres fins, vous devez mapper le rôle `ml_full_access` à votre rôle IAM qui a les autorisations `iam:PassRole` pour transmettre `opensearch-sagemaker-role`.
1. Accédez au plugin OpenSearch Dashboards correspondant à votre domaine OpenSearch de service. Vous pouvez trouver le point de terminaison Dashboards sur le tableau de bord de votre domaine sur la console OpenSearch de service.
1. Dans le menu principal, choisissez **Sécurité**, **Rôles**, puis sélectionnez le rôle **ml\$1full\$1access**.
1. Choisissez **Mapped users (Utilisateurs mappés)**, **Manage mapping (Gérer le mappage)**.
1. Sous **Rôles principaux**, ajoutez l'ARN du rôle autorisé à transmettre`opensearch-sagemaker-role`.
```
arn:aws:iam::account-id:role/role-name
```
1. Sélectionnez **Mapper** et vérifiez que l'utilisateur ou le rôle s'affiche sous **Utilisateurs mappés**.
## Création d'un connecteur OpenSearch de service
Pour créer un connecteur, envoyez une `POST` demande au point de terminaison du domaine de OpenSearch service. Vous pouvez utiliser curl, le client Python d'exemple, Postman ou une autre méthode pour envoyer une demande signée. Notez que vous ne pouvez pas utiliser de `POST` requête dans la console Kibana. La demande se présente au format suivant :
```
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\" }"
}
]
}
```
Le corps de la demande pour cette demande est différent de celui d'une demande de connecteur open source de deux manières. Dans le `credential` champ, vous transmettez l'ARN du rôle IAM qui permet au OpenSearch Service de lire depuis Secrets Manager, ainsi que l'ARN du secret quel. Dans le `headers` champ, vous faites référence au secret à l'aide de la clé secrète et du fait qu'il provient d'un ARN.
Si votre domaine réside dans un cloud privé virtuel (VPC), votre ordinateur doit être connecté au VPC pour que la demande puisse créer correctement le connecteur AI. L'accès à un VPC varie en fonction de la configuration réseau, mais implique généralement de se connecter à un VPN ou à un réseau d'entreprise. Pour vérifier que vous pouvez accéder à votre domaine de OpenSearch service, accédez `https://your-vpc-domain.region.es.amazonaws.com` à un navigateur Web et vérifiez que vous recevez la réponse JSON par défaut.
### Exemple de client Python
Le client Python est plus simple à automatiser qu'une requête HTTP et offre une meilleure réutilisabilité. Pour créer le connecteur AI avec le client Python, enregistrez l'exemple de code suivant dans un fichier Python. Le client a besoin des [https://pypi.org/project/requests-aws4auth/](https://pypi.org/project/requests-aws4auth/)packages [AWS SDK pour Python (Boto3)[https://requests.readthedocs.io/en/latest/](https://requests.readthedocs.io/en/latest/)](https://aws.amazon.com/sdk-for-python/),, et.
```
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)
```