AWS 서비스에 대한 Amazon OpenSearch Service ML 커넥터

Amazon OpenSearch Service 기계 학습(ML) 커넥터를 다른 AWS 서비스와 함께 사용하는 경우, OpenSearch Service를 해당 서비스에 안전하게 연결할 수 있도록 IAM 역할을 설정해야 합니다. AWS 서비스 Amazon SageMaker와 Amazon Bedrock을 포함하도록 커넥터를 설정할 수 있습니다. 이 자습서에서는 OpenSearch Service에서 SageMaker 런타임으로 커넥터를 생성하는 방법을 다룹니다. 커넥터에 대한 자세한 내용은 지원되는 커넥터를 참조하세요.

사전 조건

커넥터를 생성하려면 Amazon SageMaker 도메인 엔드포인트와 OpenSearch Service에 액세스 권한을 부여하는 IAM 역할이 있어야 합니다.

Amazon SageMaker 도메인 설정

기계 학습 모델을 배포하려면 Amazon SageMaker 개발자 안내서의 Amazon SageMaker에 모델 배포를 참조하세요. AI 커넥터를 생성하는 데 필요한 모델의 엔드포인트 URL을 기록하세요.

IAM 역할 생성

OpenSearch Service에 대한 SageMaker 런타임 권한을 위임할 IAM 역할을 설정합니다. 새 역할을 생성하려면 IAM 사용 설명서의 IAM 역할 생성(콘솔)을 참조하세요. 원하는 경우, 권한이 동일하다면 기존 역할을 사용할 수도 있습니다. AWS 관리형 역할을 사용하는 대신 새 역할을 생성하는 경우 이 자습서의 opensearch-sagemaker-role을 자신의 역할 이름으로 바꾸세요.

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


{
    "Version": "2012-10-17",
    "Statement": [
        {   
            "Action": [
                "sagemaker:InvokeEndpointAsync",
                "sagemaker:InvokeEndpoint"
            ],
            "Effect": "Allow",
            "Resource": "*"
        }
    ]
}

역할 신뢰 정책 수정에 나와 있는 지침에 따라 역할의 신뢰 관계를 편집합니다. 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-sagemaker-role"
    },
    {
      "Effect": "Allow",
      "Action": "es:ESHttpPost",
      "Resource": "arn:aws:es:region:account-id:domain/domain-name/*"
    }
  ]
}

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

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

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

OpenSearch Service 도메인에 대한 OpenSearch 대시보드 플러그인으로 이동합니다. OpenSearch Service 콘솔의 도메인 대시보드에서 Dashboards 엔드포인트를 찾을 수 있습니다.
주 메뉴에서 보안, 역할을 선택하고 ml_full_access 역할을 선택합니다.
매핑된 사용자(Mapped users), 매핑 관리(Manage mapping)를 차례로 선택합니다.
백엔드 역할에서 opensearch-sagemaker-role을 전달할 권한이 있는 역할의 ARN을 추가합니다.
```
arn:aws:iam::account-id:role/role-name
```
Map(맵)을 선택하고 Mapped users(매핑된 사용자)에 사용자 또는 역할이 나타나는지 확인합니다.

OpenSearch Service 커넥터 생성

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


POST domain-endpoint/_plugins/_ml/connectors/_create
{
   "name": "sagemaker: embedding",
   "description": "Test connector for Sagemaker embedding model",
   "version": 1,
   "protocol": "aws_sigv4",
   "credential": {
      "roleArn": "arn:aws:iam::account-id:role/opensearch-sagemaker-role"
   },
   "parameters": {
      "region": "region",
      "service_name": "sagemaker"
   },
   "actions": [
      {
         "action_type": "predict",
         "method": "POST",
         "headers": {
            "content-type": "application/json"
         },
         "url": "https://runtime.sagemaker.region.amazonaws.com/endpoints/endpoint-id/invocations",
         "request_body": "{ \"inputs\": { \"question\": \"${parameters.question}\", \"context\": \"${parameters.context}\" } }"
      }
   ]
}

도메인이 Virtual Private Cloud(VPC)에 상주하는 경우, 요청이 AI 커넥터를 생성하려면 컴퓨터가 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)

# Register repository
path = '_plugins/_ml/connectors/_create'
url = host + path

payload = {
   "name": "sagemaker: embedding",
   "description": "Test connector for Sagemaker embedding model",
   "version": 1,
   "protocol": "aws_sigv4",
   "credential": {
      "roleArn": "arn:aws:iam::account-id:role/opensearch-sagemaker-role"
   },
   "parameters": {
      "region": "region",
      "service_name": "sagemaker"
   },
   "actions": [
      {
         "action_type": "predict",
         "method": "POST",
         "headers": {
            "content-type": "application/json"
         },
         "url": "https://runtime.sagemaker.region.amazonaws.com/endpoints/endpoint-id/invocations",
         "request_body": "{ \"inputs\": { \"question\": \"${parameters.question}\", \"context\": \"${parameters.context}\" } }"
      }
   ]
}
headers = {"Content-Type": "application/json"}

r = requests.post(url, auth=awsauth, json=payload, headers=headers)
print(r.status_code)
print(r.text)

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

기계 학습

외부 플랫폼용 커넥터