Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
# Conectores Amazon OpenSearch Service ML para plataformas de terceros
En este tutorial, explicamos cómo crear un conector de OpenSearch Service a Cohere. Para obtener más información sobre los conectores, consulte [Conectores compatibles](https://opensearch.org/docs/latest/ml-commons-plugin/remote-models/connectors/#supported-connectors).
Cuando utilizas un conector de aprendizaje automático (ML) de Amazon OpenSearch Service con un modelo remoto externo, debes almacenar tus credenciales de autorización específicas en él AWS Secrets Manager. Puede ser una clave de API o una combinación de nombre de usuario y contraseña. Esto significa que también debe crear un rol de IAM que permita al OpenSearch Servicio acceder a Secrets Manager para leer.
**Topics**
+ [Requisitos previos](#connector-external-prereq)
+ [Crea un conector de OpenSearch servicio](#connector-external-create)
## Requisitos previos
Para crear un conector para Cohere o cualquier proveedor externo con el OpenSearch Servicio, debe tener un rol de IAM que le dé acceso al OpenSearch Servicio AWS Secrets Manager, donde almacene sus credenciales. También debe almacenar sus credenciales en Secrets Manager.
### Creación de un rol de IAM
Configure un rol de IAM para delegar los permisos de Secrets Manager a OpenSearch Service. También puede usar el rol de `SecretManagerReadWrite` existente. Para crear un rol nuevo, consulte [Creación de roles de IAM (consola)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html#roles-creatingrole-user-console) en la *Guía del usuario de IAM*. Si crea un nuevo rol en lugar de usar un rol AWS administrado, `opensearch-secretmanager-role` sustitúyalo en este tutorial por el nombre de su propio rol.
1. Adjunta la siguiente política de IAM gestionada a tu nueva función para permitir que OpenSearch Service acceda a tus valores de Secrets Manager. Para adjuntar una política a un rol, consulte [Adición de permisos de identidad de 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. Siga las instrucciones de [Modificación de una política de confianza de rol](https://docs.aws.amazon.com/IAM/latest/UserGuide/roles-managingrole-editing-console.html#roles-managingrole_edit-trust-policy) para editar la relación de confianza del rol. En la siguiente política, *service-principal* sustitúyala por uno de los siguientes principios de servicio para OpenSearch Service o OpenSearch Serverless:
**Para servicio OpenSearch **
`opensearchservice.amazonaws.com`
**Para sistemas OpenSearch sin servidor**
`ml.opensearchservice.amazonaws.com`
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"sts:AssumeRole"
],
"Effect": "Allow",
"Principal": {
"Service": [
"service-principle"
]
}
}
]
}
```
------
Le recomendamos que utilice las claves de condición `aws:SourceAccount` y `aws:SourceArn` para limitar el acceso a un dominio específico. `SourceAccount`Es el Cuenta de AWS ID que pertenece al propietario del dominio y `SourceArn` es el ARN del dominio. Por ejemplo, puede agregar el siguiente bloque de condición a la política de confianza:
```
"Condition": {
"StringEquals": {
"aws:SourceAccount": "account-id"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:es:region:account-id:domain/domain-name"
}
}
```
### Configuración de permisos
Para crear el conector, necesita permiso para transferir la función de IAM a OpenSearch Service. También necesita tener acceso a la acción `es:ESHttpPost`. Para conceder estos dos permisos, asocie la siguiente política al rol de IAM cuyas credenciales se utilicen para firmar la solicitud:
------
#### [ 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 su usuario o rol no tiene permisos de `iam:PassRole` para transferir su rol, puede que se produzca un error de autorización cuando intente registrar un repositorio en el siguiente paso.
### Configurar AWS Secrets Manager
Para almacenar sus credenciales de autorización en Secrets Manager, consulte [Create an AWS Secrets Manager secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html) en la *Guía del usuario de AWS Secrets Manager *.
Después de que Secrets Manager acepta su par clave-valor como secreto, recibirá un ARN con el formato: `arn:aws:secretsmanager:us-west-2:123456789012:secret:MySecret-a1b2c3`. Mantenga un registro de este ARN, a medida que lo usa y su clave cuando cree un conector en el siguiente paso.
### Asigne la función del aprendizaje automático en los OpenSearch paneles de control (si utiliza un control de acceso detallado)
El control de acceso detallado presenta un paso adicional al configurar un conector. Incluso si utiliza autenticación HTTP básica para todos los demás fines, debe asignar el rol `ml_full_access` al rol de IAM que tenga permisos `iam:PassRole` para transferir `opensearch-sagemaker-role`.
1. Navegue hasta el complemento OpenSearch Dashboards de su dominio de servicio. OpenSearch Puedes encontrar el punto de conexión de Dashboards en el panel de control de tu dominio, en la consola de OpenSearch servicio.
1. En el menú principal, seleccione **Seguridad**, **Roles** y seleccione el rol **ml\$1full\$1access**.
1. Seleccione **Usuarios asignados**, **Administrar mapeo**.
1. En **Roles de backend**, agregue el ARN del rol que tenga permisos para transferir `opensearch-sagemaker-role`.
```
arn:aws:iam::account-id:role/role-name
```
1. Seleccione **Asignar** y confirme que el usuario o el rol aparecen en **Usuarios asignados**.
## Crea un conector de OpenSearch servicio
Para crear un conector, envíe una `POST` solicitud al punto final del dominio de OpenSearch servicio. Puede usar curl, el cliente Python de muestra, Postman u otro método para enviar una solicitud firmada. Tenga en cuenta que no puede usar una solicitud `POST` en la consola de Kibana. La solicitud tiene el siguiente 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\" }"
}
]
}
```
El cuerpo de esta solicitud es diferente de una solicitud de conector de código abierto en dos aspectos. Dentro del `credential` campo, se pasa el ARN del rol de IAM que permite al OpenSearch Servicio leer Secrets Manager, junto con el ARN del secreto qué. En el campo `headers`, se hace referencia al secreto mediante la clave secreta y al hecho de que proviene de un ARN.
Si el dominio reside en una nube privada virtual (VPC), la computadora debe estar conectada a la VPC para que la solicitud cree correctamente el conector de IA. El acceso a una VPC depende de la configuración de red, pero generalmente implica conectarse a una VPN o una red corporativa. Para comprobar que puedes acceder a tu dominio de OpenSearch servicio, navega `https://your-vpc-domain.region.es.amazonaws.com` en un navegador web y comprueba que recibes la respuesta JSON predeterminada.
### Cliente Python de muestra
El cliente de Python es más simple de automatizar que una solicitud HTTP y tiene una mejor reutilización. Para crear el conector de IA con el cliente Python, guarde el siguiente código de ejemplo en un archivo Python. El cliente necesita los paquetes [AWS SDK para Python (Boto3)](https://aws.amazon.com/sdk-for-python/), [https://requests.readthedocs.io/en/latest/](https://requests.readthedocs.io/en/latest/) y [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)
```