Conectores Amazon OpenSearch Service ML para plataformas de terceiros

Neste tutorial, abordamos como criar um conector do OpenSearch Service ao Cohere. Para obter mais informações sobre conectores, consulte Conectores compatíveis.

Ao usar um conector de aprendizado de máquina (ML) do Amazon OpenSearch Service com um modelo remoto externo, você precisa armazenar suas credenciais de autorização específicas em AWS Secrets Manager. Isso pode ser uma chave de API ou uma combinação de nome de usuário e senha. Isso significa que você também precisa criar uma função do IAM que permita que o OpenSearch serviço acesse a leitura do Secrets Manager.

Pré-requisitos

Para criar um conector para o Cohere ou qualquer provedor externo com o OpenSearch Service, você deve ter uma função do IAM que conceda acesso ao OpenSearch Service AWS Secrets Manager, onde você armazena suas credenciais. Você também deve armazenar suas credenciais no Secrets Manager.

Criar um perfil do IAM

Configure uma função do IAM para delegar permissões do Secrets Manager ao OpenSearch Service. Você também pode usar a função SecretManagerReadWrite existente. Para criar um novo perfil, consulte Como criar um perfil do IAM (console) no Guia do usuário do IAM. Se você criar uma nova função em vez de usar uma função AWS gerenciada, substitua opensearch-secretmanager-role neste tutorial pelo nome da sua própria função.

1. Anexe a seguinte política gerenciada do IAM à sua nova função para permitir que o OpenSearch Service acesse seus valores do Secrets Manager. Para anexar uma política ao perfil, consulte Como adicionar permissões de identidade do IAM.

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

2. Siga as instruções em Modificação da política de confiança de um perfil para editar a relação de confiança do perfil. Você deve especificar OpenSearch Serviço na Principal declaração:

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

   Recomendamos que você use as chaves de condição aws:SourceAccount e aws:SourceArn para limitar o acesso a um domínio específico. SourceAccountÉ o Conta da AWS ID que pertence ao proprietário do domínio e SourceArn o ARN do domínio. Por exemplo, você pode adicionar o bloco de condições a seguir na política de confiança:

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

Configurar permissões do

Para criar o conector, você precisa de permissão para passar a função do IAM para o OpenSearch Serviço. Você também precisa de acesso à ação es:ESHttpPost. Para conceder ambas as permissões, anexe a seguinte política ao perfil do IAM cujas credenciais estão sendo usadas para assinar a solicitação:

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

Se seu usuário ou função não tiver permissões iam:PassRole para passar sua função, talvez você encontre o seguinte erro de autorização ao tentar registrar um repositório na próxima etapa.

Configurar AWS Secrets Manager

Para armazenar suas credenciais de autorização no Secrets Manager, consulte Como criar um segredo AWS Secrets Manager no Guia do usuário da AWS Secrets Manager .

Depois que o Secrets Manager aceitar seu par de valores-chave como segredo, você recebe um ARN com o formato: arn:aws:secretsmanager:us-west-2:123456789012:secret:MySecret-a1b2c3 Mantenha um registro desse ARN, conforme você o usa, e da sua chave ao criar um conector na próxima etapa.

Mapeie a função de ML em OpenSearch painéis (se estiver usando controle de acesso refinado)

O controle minucioso de acesso introduz uma etapa adicional ao configurar um conector. Mesmo que você use a autenticação básica HTTP para todos os outros fins, será necessário mapear o perfil ml_full_access para o seu perfil do IAM que tem permissões iam:PassRole para passar opensearch-sagemaker-role.

1. Navegue até o plug-in OpenSearch Dashboards do seu domínio OpenSearch de serviço. Você pode encontrar o endpoint Dashboards no painel do seu domínio no console de OpenSearch serviços.

2. No menu principal, escolha Segurança, Funções e selecione a função ml_full_access.

3. Escolha Usuários mapeados e Gerenciar mapeamento.

4. Em Funções de backend, adicione o ARN da função que tem permissão para aprovar opensearch-sagemaker-role.

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

5. Selecione Mapa e confirme se o usuário ou função aparece em Usuários mapeados.

Crie um conector OpenSearch de serviço

Para criar um conector, envie uma POST solicitação para o endpoint do domínio OpenSearch Service. Você pode usar curl, o cliente Python de amostra, o Postman ou outro método para enviar uma solicitação assinada. Você não pode usar uma solicitação POST no console do Kibana. O cabeçalho assume o seguinte 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\" }"
        }
    ]
}

De duas maneiras, o corpo dessa solicitação é diferente do de uma solicitação de conector de código aberto. Dentro do credential campo, você passa o ARN para a função do IAM que permite que o OpenSearch Service leia do Secrets Manager, junto com o ARN para o segredo de quê. No campo headers, você se refere ao segredo usando a chave secreta e o fato de ser proveniente de um ARN.

Se o domínio residir em uma nuvem privada virtual (VPC), seu computador deverá estar conectado à VPC para que a solicitação crie o conector de IA com êxito. O acesso a uma VPC varia de acordo com a configuração de rede, mas geralmente requer uma conexão com VPN ou rede corporativa. Para verificar se você pode acessar seu domínio OpenSearch de serviço, navegue até https://your-vpc-domain.region.es.amazonaws.com em um navegador da web e verifique se você recebeu a resposta JSON padrão.

Exemplo de cliente do Python

O cliente Python é mais simples de automatizar do que uma solicitação HTTP, além de ser mais fácil reutilizá-lo. Para criar o conector AI com o cliente Python, salve o código de exemplo a seguir em um arquivo Python. O cliente requer os pacotes AWS SDK for 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)

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)