서드파티 플랫폼에 대한 Amazon OpenSearch Service ML 커넥터 - Amazon OpenSearch Service
사전 조건OpenSearch Service 커넥터 생성

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

서드파티 플랫폼에 대한 Amazon OpenSearch Service ML 커넥터

이 자습서에서는 OpenSearch Service에서 Cohere로 연결되는 커넥터를 생성하는 방법을 다룹니다. 커넥터에 대한 자세한 내용은 지원되는 커넥터를 참조하세요.

외부 원격 모델과 함께 Amazon OpenSearch Service 기계 학습(ML) 커넥터를 사용하는 경우 AWS Secrets Manager에 특정 권한 부여 자격 증명을 저장해야 합니다. 이는 API 키 또는 사용자 이름과 암호의 조합일 수 있습니다. 즉, OpenSearch Service가 Secrets Manager에서 읽을 수 있도록 허용하는 IAM 역할도 생성해야 합니다.

사전 조건

Cohere 또는 OpenSearch Service를 사용하는 외부 공급자에 대한 커넥터를 생성하려면 자격 증명을 저장하는에 대한 OpenSearch Service 액세스 권한을 부여하는 IAM 역할 AWS Secrets Manager이 있어야 합니다. 또한 보안 인증 정보는 반드시 Secrets Manager에 저장해야 합니다.

IAM 역할 생성

OpenSearch Service에 대한 Secrets Manager 권한을 위임할 IAM 역할을 설정합니다. 기존의 SecretManagerReadWrite 역할을 사용해도 됩니다. 새 역할을 생성하려면 IAM 사용 설명서의 IAM 역할 생성(콘솔)을 참조하세요. AWS 관리형 역할을 사용하는 대신 새 역할을 생성하는 경우이 자습서opensearch-secretmanager-role에서를 자신의 역할 이름으로 바꿉니다.

  1. 다음과 같은 관리형 IAM 정책을 새 역할에 연결하여 OpenSearch Service가 Secrets Manager 값에 액세스할 수 있도록 허용합니다.. 역할에 정책을 연결하는 방법은 IAM 자격 증명 권한 추가를 참조하세요.

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

  2. 역할 신뢰 정책 수정에 나와 있는 지침에 따라 역할의 신뢰 관계를 편집합니다. Principal 명령문에 OpenSearch Service를 지정해야 합니다.

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

    aws:SourceAccount 및 aws:SourceArn 조건 키를 사용하여 액세스 권한을 특정 도메인으로 제한하는 것이 좋습니다. SourceAccount는 도메인 소유자에 속하는 AWS 계정 ID이고 SourceArn는 도메인의 ARN입니다. 예를 들어 신뢰 정책에 다음 조건 블록을 추가할 수 있습니다.

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

권한 구성

커넥터를 생성하려면 IAM 역할을 OpenSearch Service에 전달할 수 있는 권한이 필요합니다. es:ESHttpPost 작업에도 액세스해야 합니다. 이러한 두 권한을 모두 부여하려면 요청에 서명하기 위해 자격 증명이 사용되는 IAM 역할에 다음 정책을 연결합니다.

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

사용자 또는 역할에 역할을 전달할 iam:PassRole 권한이 없는 경우 다음 단계에서 리포지토리를 등록하려고 할 때 권한 부여 오류가 발생할 수 있습니다.

설정 AWS Secrets Manager

인증 자격 증명을 Secrets Manager에 저장하려면 AWS Secrets Manager 사용 설명서의 AWS Secrets Manager 암호 만들기를 참조하세요.

Secrets Manager가 키-값 쌍을 암호로 수락하면 arn:aws:secretsmanager:us-west-2:123456789012:secret:MySecret-a1b2c3와 같은 형식의 ARN을 받게 됩니다. 사용할 때 이 ARN을 기록하고 다음 단계에서 커넥터를 만들 때 키를 기록해 두십시오.

세분화된 액세스 제어를 사용하는 경우 OpenSearch Dashboards에서 ML 역할을 매핑할 수 있습니다.

세분화된 액세스 제어를 사용하면 커넥터를 설정할 때 추가 단계가 있습니다. 다른 모든 목적으로 HTTP 기본 인증을 사용하더라도 opensearch-sagemaker-role을 전달할 iam:PassRole 권한이 있는 IAM 역할에 ml_full_access 역할을 매핑해야 합니다.

  1. OpenSearch Service 도메인에 대한 OpenSearch 대시보드 플러그인으로 이동합니다. OpenSearch Service 콘솔의 도메인 대시보드에서 Dashboards 엔드포인트를 찾을 수 있습니다.

  2. 주 메뉴에서 보안, 역할을 선택하고 ml_full_access 역할을 선택합니다.

  3. 매핑된 사용자(Mapped users), 매핑 관리(Manage mapping)를 차례로 선택합니다.

  4. 백엔드 역할에서 opensearch-sagemaker-role을 전달할 권한이 있는 역할의 ARN을 추가합니다.

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

  5. Map(맵)을 선택하고 Mapped users(매핑된 사용자)에 사용자 또는 역할이 나타나는지 확인합니다.

OpenSearch Service 커넥터 생성

커넥터를 생성하려면 OpenSearch Service 도메인 엔드포인트로 POST 요청을 보내세요. curl, 샘플 Python 클라이언트, Postman 또는 다른 메서드를 사용하여 서명된 요청을 보낼 수 있습니다. Kibana 콘솔에서는 POST 요청을 사용할 수 없습니다. 요청은 다음과 같은 형식을 사용합니다.

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\" }"
        }
    ]
}

이 요청의 요청 본문은 오픈 소스 커넥터 요청의 요청 본문과 두 가지 측면에서 다릅니다. credential 필드 내에서 OpenSearch Service가 Secrets Manager에서 읽을 수 있도록 허용하는 IAM 역할에 대한 ARN과 어떤 암호에 대한 ARN을 함께 전달합니다. headers 필드에서는 암호 키를 사용하고 ARN에서 가져온 정보라는 사실을 사용하여 암호를 참조합니다.

도메인이 Virtual Private Cloud(VPC)에 상주하는 경우, 요청이 스냅샷 리포지토리를 등록하려면 컴퓨터가 VPC에 연결되어야 합니다. VPC 액세스는 네트워크 구성에 따라 다르지만, 대개는 VPN 또는 회사 네트워크 연결이 필요합니다. OpenSearch Service 도메인에 도달할 수 있는지 알아보려면 웹 브라우저에서 https://your-vpc-domain.region.es.amazonaws.com으로 이동하여 기본 JSON 응답을 받을 수 있는지 확인합니다.

샘플 Python 클라이언트

Python 클라이언트는 HTTP 요청보다 자동화가 간단하고 재사용성이 뛰어납니다. Python 클라이언트로 AI 커넥터를 만들려면 다음 샘플 코드를 Python 파일에 저장하세요. 클라이언트에는 AWS SDK for Python (Boto3), requests, 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)