Semantic search using AWS CloudFormation and Amazon SageMaker

원문 보기 위키 갱신 2026.10.14

출처: 문서

본문

AWS CloudFormation과 Amazon SageMaker를 사용한 시맨틱 검색

이 튜토리얼에서는 AWS CloudFormation과 Amazon SageMaker를 사용해 Amazon OpenSearch Service에서 시맨틱 검색을 구현하는 방법을 소개해요. 자세한 내용은 시맨틱 검색을 참고하세요.

Amazon OpenSearch Service 대신 셀프 관리형 OpenSearch를 사용하는 경우에는 블루프린트를 사용해 Amazon SageMaker 모델에 연결하는 커넥터를 만드세요. 커넥터 생성에 대한 자세한 내용은 Connectors를 참고하세요.

CloudFormation 통합은 Semantic Search with SageMaker Embedding Model 튜토리얼의 단계를 자동화해요. CloudFormation 템플릿은 IAM 역할을 생성하고, AWS Lambda 함수를 호출해 AI 커넥터와 모델을 설정해요.

your_ 접두사로 시작하는 플레이스홀더는 여러분의 값으로 바꾸세요. {: .note}

모델 입력 및 출력 요구 사항

Amazon SageMaker 모델의 입력이 기본 전처리 함수에서 요구하는 형식을 따르는지 확인하세요.

모델 입력은 문자열 배열이어야 해요:

["hello world", "how are you"]

또한 모델 출력이 기본 후처리 함수에서 요구하는 형식을 따르는지 확인하세요. 모델 출력은 배열의 배열이어야 하고, 각 내부 배열은 입력 문자열 하나의 임베딩에 해당해요:

[
  [
    -0.048237994,
    -0.07612697,
    ...
  ],
  [
    0.32621247,
    0.02328475,
    ...
  ]
]

모델의 입력/출력이 요구되는 기본 형식과 다르다면, Painless 스크립트를 사용해 직접 전처리/후처리 함수를 만들 수 있어요.

예시: Amazon Bedrock Titan 임베딩 모델

예를 들어 Amazon Bedrock Titan 임베딩 모델(블루프린트)의 입력은 다음과 같아요:

{ "inputText": "your_input_text" }

OpenSearch에서 기대하는 입력 형식은 다음과 같아요:

{ "text_docs": [ "your_input_text1", "your_input_text2"] }

text_docs를 inputText로 변환하려면 다음 전처리 함수를 정의해야 해요:

"pre_process_function": """
    StringBuilder builder = new StringBuilder();
    builder.append("\"");
    String first = params.text_docs[0];// Get the first doc, ml-commons will iterate all docs
    builder.append(first);
    builder.append("\"");
    def parameters = "{" +"\"inputText\":" + builder + "}"; // This is the Bedrock Titan embedding model input
    return  "{" +"\"parameters\":" + parameters + "}";"""

{% include copy.html %}

기본 Amazon Bedrock Titan 임베딩 모델의 출력은 다음 형식이에요:

{
  "embedding": <float_array>
}

하지만 OpenSearch에서 기대하는 형식은 다음과 같아요:

{
  "name": "sentence_embedding",
  "data_type": "FLOAT32",
  "shape": [ <embedding_size> ],
  "data": <float_array>
}

Amazon Bedrock Titan 임베딩 모델의 출력을 OpenSearch에서 기대하는 형식으로 변환하려면 다음 후처리 함수를 정의해야 해요:

"post_process_function": """
      def name = "sentence_embedding";
      def dataType = "FLOAT32";
      if (params.embedding == null || params.embedding.length == 0) {
        return params.message;
      }
      def shape = [params.embedding.length];
      def json = "{" +
                 "\"name\":\"" + name + "\"," +
                 "\"data_type\":\"" + dataType + "\"," +
                 "\"shape\":" + shape + "," +
                 "\"data\":" + params.embedding +
                 "}";
      return json;
    """

{% include copy.html %}

사전 준비: OpenSearch 클러스터 생성

Amazon OpenSearch Service 콘솔로 이동해 OpenSearch 도메인을 생성하세요.

도메인의 Amazon Resource Name(ARN)을 기록해 두세요. 이후 단계에서 사용하게 돼요.

1단계: 백엔드 역할 매핑

OpenSearch CloudFormation 템플릿은 Lambda 함수를 사용해 AWS Identity and Access Management(IAM) 역할이 연결된 AI 커넥터를 생성해요. 필요한 권한을 부여하려면 IAM 역할을 ml_full_access에 매핑해야 해요. 백엔드 역할을 매핑하려면 Semantic Search with SageMaker Embedding Model 튜토리얼의 2.2단계를 따르세요.

IAM 역할은 CloudFormation 템플릿의 Lambda Invoke OpenSearch ML Commons Role Name 필드에 지정돼요. 기본 IAM 역할은 LambdaInvokeOpenSearchMLCommonsRole이므로, arn:aws:iam::your_aws_account_id:role/LambdaInvokeOpenSearchMLCommonsRole 백엔드 역할을 ml_full_access에 매핑해야 해요.

더 넓은 범위로 매핑하려면 와일드카드를 사용해 모든 역할에 ml_full_access를 부여할 수 있어요:

arn:aws:iam::your_aws_account_id:role/*

all_access는 ml_full_access보다 더 많은 권한을 포함하기 때문에, 백엔드 역할을 all_access에 매핑하는 것도 괜찮아요.

2단계: CloudFormation 템플릿 실행

CloudFormation 템플릿 통합은 Amazon OpenSearch Service 콘솔에서 사용할 수 있어요. 왼쪽 탐색 창에서 다음 이미지와 같이 Integrations를 선택하세요.

Amazon SageMaker에 모델을 배포하려면 다음 옵션 중 하나를 선택하세요.

옵션 1: 사전 학습된 모델을 Amazon SageMaker에 배포

다음 이미지와 같이 Deep Java Library 모델 저장소에서 사전 학습된 Hugging Face sentence transformer 임베딩 모델을 배포할 수 있어요.

다음 필드를 작성하고, 나머지 필드는 모두 기본값으로 두세요:

Amazon OpenSearch Endpoint를 입력하세요.
빠르게 시작하려면 기본 SageMaker Configuration을 사용하고, 필요에 따라 수정할 수도 있어요. 지원되는 Amazon SageMaker 인스턴스 유형은 Amazon SageMaker 문서를 참고하세요.
SageMaker Endpoint Url 필드는 비워 두세요. URL을 입력하면 모델이 Amazon SageMaker에 배포되지 않고, 새 추론 엔드포인트도 생성되지 않아요.
Custom Image 필드는 비워 두세요. 기본 이미지는 djl-inference:0.22.1-cpu-full이에요. 사용 가능한 이미지는 AWS Deep Learning Containers를 참고하세요.
Custom Model Data Url 필드는 비워 두세요.
Custom Model Environment 필드의 기본값은 djl://ai.djl.huggingface.pytorch/sentence-transformers/all-MiniLM-L6-v2예요. 지원되는 모델 목록은 지원되는 모델을 참고하세요.

옵션 2: 기존 SageMaker 추론 엔드포인트 사용

이미 SageMaker 추론 엔드포인트가 있다면, 다음 이미지와 같이 해당 엔드포인트를 사용해 모델을 구성할 수 있어요.

다음 필드를 작성하고, 나머지는 모두 기본값으로 두세요:

Amazon OpenSearch Endpoint를 입력하세요.
SageMaker Endpoint Url을 입력하세요.
Custom Image, Custom Model Data Url, Custom Model Environment 필드는 비워 두세요.

출력

배포가 끝나면 CloudFormation 스택의 Outputs에서 OpenSearch AI 커넥터와 모델 ID를 확인할 수 있어요.

오류가 발생하면 다음 단계에 따라 로그를 확인하세요:

Amazon SageMaker 콘솔을 열어요.
CloudWatch Logs 섹션으로 이동해요.
CloudFormation 스택 이름을 포함하거나 그와 연관된 Log Groups를 검색해요.

지원되는 모델

다음 Hugging Face sentence transformer 임베딩 모델을 Deep Java Library 모델 저장소에서 사용할 수 있어요:

djl://ai.djl.huggingface.pytorch/sentence-transformers/LaBSE/
djl://ai.djl.huggingface.pytorch/sentence-transformers/all-MiniLM-L12-v1/
djl://ai.djl.huggingface.pytorch/sentence-transformers/all-MiniLM-L12-v2/
djl://ai.djl.huggingface.pytorch/sentence-transformers/all-MiniLM-L6-v1/
djl://ai.djl.huggingface.pytorch/sentence-transformers/all-MiniLM-L6-v2/
djl://ai.djl.huggingface.pytorch/sentence-transformers/all-distilroberta-v1/
djl://ai.djl.huggingface.pytorch/sentence-transformers/all-mpnet-base-v1/
djl://ai.djl.huggingface.pytorch/sentence-transformers/all-mpnet-base-v2/
djl://ai.djl.huggingface.pytorch/sentence-transformers/all-roberta-large-v1/
djl://ai.djl.huggingface.pytorch/sentence-transformers/allenai-specter/
djl://ai.djl.huggingface.pytorch/sentence-transformers/bert-base-nli-cls-token/
djl://ai.djl.huggingface.pytorch/sentence-transformers/bert-base-nli-max-tokens/
djl://ai.djl.huggingface.pytorch/sentence-transformers/bert-base-nli-mean-tokens/
djl://ai.djl.huggingface.pytorch/sentence-transformers/bert-base-nli-stsb-mean-tokens/
djl://ai.djl.huggingface.pytorch/sentence-transformers/bert-base-wikipedia-sections-mean-tokens/
djl://ai.djl.huggingface.pytorch/sentence-transformers/bert-large-nli-cls-token/
djl://ai.djl.huggingface.pytorch/sentence-transformers/bert-large-nli-max-tokens/
djl://ai.djl.huggingface.pytorch/sentence-transformers/bert-large-nli-mean-tokens/
djl://ai.djl.huggingface.pytorch/sentence-transformers/bert-large-nli-stsb-mean-tokens/
djl://ai.djl.huggingface.pytorch/sentence-transformers/clip-ViT-B-32-multilingual-v1/
djl://ai.djl.huggingface.pytorch/sentence-transformers/distilbert-base-nli-mean-tokens/
djl://ai.djl.huggingface.pytorch/sentence-transformers/distilbert-base-nli-stsb-mean-tokens/
djl://ai.djl.huggingface.pytorch/sentence-transformers/distilbert-base-nli-stsb-quora-ranking/
djl://ai.djl.huggingface.pytorch/sentence-transformers/distilbert-multilingual-nli-stsb-quora-ranking/
djl://ai.djl.huggingface.pytorch/sentence-transformers/distiluse-base-multilingual-cased-v1/
djl://ai.djl.huggingface.pytorch/sentence-transformers/facebook-dpr-ctx_encoder-multiset-base/
djl://ai.djl.huggingface.pytorch/sentence-transformers/facebook-dpr-ctx_encoder-single-nq-base/
djl://ai.djl.huggingface.pytorch/sentence-transformers/facebook-dpr-question_encoder-multiset-base/
djl://ai.djl.huggingface.pytorch/sentence-transformers/facebook-dpr-question_encoder-single-nq-base/
djl://ai.djl.huggingface.pytorch/sentence-transformers/msmarco-MiniLM-L-12-v3/
djl://ai.djl.huggingface.pytorch/sentence-transformers/msmarco-MiniLM-L-6-v3/
djl://ai.djl.huggingface.pytorch/sentence-transformers/msmarco-MiniLM-L12-cos-v5/
djl://ai.djl.huggingface.pytorch/sentence-transformers/msmarco-MiniLM-L6-cos-v5/
djl://ai.djl.huggingface.pytorch/sentence-transformers/msmarco-bert-base-dot-v5/
djl://ai.djl.huggingface.pytorch/sentence-transformers/msmarco-bert-co-condensor/
djl://ai.djl.huggingface.pytorch/sentence-transformers/msmarco-distilbert-base-dot-prod-v3/
djl://ai.djl.huggingface.pytorch/sentence-transformers/msmarco-distilbert-base-tas-b/
djl://ai.djl.huggingface.pytorch/sentence-transformers/msmarco-distilbert-base-v2/
djl://ai.djl.huggingface.pytorch/sentence-transformers/msmarco-distilbert-base-v3/
djl://ai.djl.huggingface.pytorch/sentence-transformers/msmarco-distilbert-base-v4/
djl://ai.djl.huggingface.pytorch/sentence-transformers/msmarco-distilbert-cos-v5/
djl://ai.djl.huggingface.pytorch/sentence-transformers/msmarco-distilbert-dot-v5/
djl://ai.djl.huggingface.pytorch/sentence-transformers/msmarco-distilbert-multilingual-en-de-v2-tmp-lng-aligned/
djl://ai.djl.huggingface.pytorch/sentence-transformers/msmarco-distilbert-multilingual-en-de-v2-tmp-trained-scratch/
djl://ai.djl.huggingface.pytorch/sentence-transformers/msmarco-distilroberta-base-v2/
djl://ai.djl.huggingface.pytorch/sentence-transformers/msmarco-roberta-base-ance-firstp/
djl://ai.djl.huggingface.pytorch/sentence-transformers/msmarco-roberta-base-v2/
djl://ai.djl.huggingface.pytorch/sentence-transformers/msmarco-roberta-base-v3/
djl://ai.djl.huggingface.pytorch/sentence-transformers/multi-qa-MiniLM-L6-cos-v1/
djl://ai.djl.huggingface.pytorch/sentence-transformers/multi-qa-MiniLM-L6-dot-v1/
djl://ai.djl.huggingface.pytorch/sentence-transformers/multi-qa-distilbert-cos-v1/
djl://ai.djl.huggingface.pytorch/sentence-transformers/multi-qa-distilbert-dot-v1/
djl://ai.djl.huggingface.pytorch/sentence-transformers/nli-bert-base/
djl://ai.djl.huggingface.pytorch/sentence-transformers/nli-bert-large-max-pooling/
djl://ai.djl.huggingface.pytorch/sentence-transformers/nli-distilbert-base/
djl://ai.djl.huggingface.pytorch/sentence-transformers/nli-distilroberta-base-v2/
djl://ai.djl.huggingface.pytorch/sentence-transformers/nli-roberta-base-v2/
djl://ai.djl.huggingface.pytorch/sentence-transformers/nli-roberta-large/
djl://ai.djl.huggingface.pytorch/sentence-transformers/nq-distilbert-base-v1/
djl://ai.djl.huggingface.pytorch/sentence-transformers/paraphrase-MiniLM-L12-v2/
djl://ai.djl.huggingface.pytorch/sentence-transformers/paraphrase-MiniLM-L3-v2/
djl://ai.djl.huggingface.pytorch/sentence-transformers/paraphrase-MiniLM-L6-v2/
djl://ai.djl.huggingface.pytorch/sentence-transformers/paraphrase-TinyBERT-L6-v2/
djl://ai.djl.huggingface.pytorch/sentence-transformers/paraphrase-albert-base-v2/
djl://ai.djl.huggingface.pytorch/sentence-transformers/paraphrase-albert-small-v2/
djl://ai.djl.huggingface.pytorch/sentence-transformers/paraphrase-distilroberta-base-v2/
djl://ai.djl.huggingface.pytorch/sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2/
djl://ai.djl.huggingface.pytorch/sentence-transformers/paraphrase-multilingual-mpnet-base-v2/
djl://ai.djl.huggingface.pytorch/sentence-transformers/paraphrase-xlm-r-multilingual-v1/
djl://ai.djl.huggingface.pytorch/sentence-transformers/quora-distilbert-base/
djl://ai.djl.huggingface.pytorch/sentence-transformers/quora-distilbert-multilingual/
djl://ai.djl.huggingface.pytorch/sentence-transformers/roberta-base-nli-mean-tokens/
djl://ai.djl.huggingface.pytorch/sentence-transformers/roberta-base-nli-stsb-mean-tokens/
djl://ai.djl.huggingface.pytorch/sentence-transformers/roberta-large-nli-mean-tokens/
djl://ai.djl.huggingface.pytorch/sentence-transformers/roberta-large-nli-stsb-mean-tokens/
djl://ai.djl.huggingface.pytorch/sentence-transformers/stsb-bert-base/
djl://ai.djl.huggingface.pytorch/sentence-transformers/stsb-bert-large/
djl://ai.djl.huggingface.pytorch/sentence-transformers/stsb-distilbert-base/
djl://ai.djl.huggingface.pytorch/sentence-transformers/stsb-distilroberta-base-v2/
djl://ai.djl.huggingface.pytorch/sentence-transformers/stsb-roberta-base-v2/
djl://ai.djl.huggingface.pytorch/sentence-transformers/stsb-roberta-base/
djl://ai.djl.huggingface.pytorch/sentence-transformers/stsb-roberta-large/
djl://ai.djl.huggingface.pytorch/sentence-transformers/stsb-xlm-r-multilingual/
djl://ai.djl.huggingface.pytorch/sentence-transformers/use-cmlm-multilingual/
djl://ai.djl.huggingface.pytorch/sentence-transformers/xlm-r-100langs-bert-base-nli-stsb-mean-tokens/
djl://ai.djl.huggingface.pytorch/sentence-transformers/xlm-r-bert-base-nli-stsb-mean-tokens/
djl://ai.djl.huggingface.pytorch/sentence-transformers/xlm-r-distilroberta-base-paraphrase-v1/

더 알아보기 (Learn more)

원문 전체: https://docs.opensearch.org/latest/tutorials/vector-search/semantic-search/semantic-search-cfn-sagemaker/