OpenSearch-provided pretrained models

원문 보기 위키 갱신 2026.10.14

출처: 문서

본문

OpenSearch 제공 사전 훈련 모델

2.9에서 도입됨 {: .label .label-purple }

OpenSearch는 다양한 오픈소스 사전 훈련 모델을 제공하여 머신러닝(ML) 검색 및 분석 사용 사례를 지원합니다. 지원되는 모든 모델을 OpenSearch 클러스터에 업로드하여 로컬에서 사용할 수 있습니다.

지원되는 사전 학습 모델

OpenSearch는 유형별로 분류된 다음 모델들을 지원해요. 텍스트 임베딩 모델은 Hugging Face에서 가져오고, 스파스 인코딩 모델은 OpenSearch에서 학습시켰어요. 같은 유형의 모델은 비슷한 사용 사례를 가지지만, 각 모델마다 크기가 다르고 클러스터 설정에 따라 성능이 달라져요. 일부 사전 학습 모델의 성능 비교는 SBERT 문서를 참고하세요.

CentOS 7 운영 체제에서 로컬 모델을 실행하는 것은 지원되지 않아요. 또한 모든 로컬 모델이 모든 하드웨어와 운영 체제에서 실행될 수 있는 것은 아니에요. {: .important}

문장 변환기

문장 변환기 모델은 문장과 단락을 차원 밀집 벡터 공간에 매핑해요. 벡터의 개수는 모델 유형에 따라 달라져요. 클러스터링이나 의미 검색과 같은 사용 사례에 이 모델들을 사용할 수 있어요.

다음 표는 다운로드할 수 있는 문장 변환기 모델과 아티팩트 링크 목록을 제공해요. 모델 이름 앞에 huggingface/를 접두사로 붙여야 한다는 점을 기억하세요. 모델 이름 열에 표시된 대로요.

토큰 제한 및 잘림: 텍스트 임베딩 모델에는 최대 토큰 제한이 있어요 (보통 BERT 기반 모델의 경우 512 토큰). 문서가 이 제한을 초과하면 모델이 자동으로 텍스트를 자르고, 잘린 내용은 임베딩에 포함되지 않아요. 이는 검색 관련성에 큰 영향을 줄 수 있는데, 관련 내용이 잘렸을 경우 문서가 검색 결과에 반환되지 않을 수 있기 때문이에요. 이 문제를 피하려면 긴 문서를 임베딩 생성 전에 더 작은 청크로 나누세요. {: .warning}

모델 이름	버전	벡터 차원	자동 잘림	TorchScript 아티팩트	ONNX 아티팩트
`huggingface/sentence-transformers/all-distilroberta-v1`	1.0.2	768차원 밀집 벡터 공간.	예	- model_url - config_url	- model_url - config_url
`huggingface/sentence-transformers/all-MiniLM-L6-v2`	1.0.2	384차원 밀집 벡터 공간.	예	- model_url - config_url	- model_url - config_url
`huggingface/sentence-transformers/all-MiniLM-L12-v2`	1.0.2	384차원 밀집 벡터 공간.	예	- model_url - config_url	- model_url - config_url
`huggingface/sentence-transformers/all-mpnet-base-v2`	1.0.2	768차원 밀집 벡터 공간.	예	- model_url - config_url	- model_url - config_url
`huggingface/sentence-transformers/msmarco-distilbert-base-tas-b`	1.0.3	768차원 밀집 벡터 공간. 의미 검색에 최적화되었어요.	예	- model_url - config_url	- model_url - config_url
`huggingface/sentence-transformers/multi-qa-MiniLM-L6-cos-v1`	1.0.2	384차원 밀집 벡터 공간. 의미 검색을 위해 설계되었고 2억 1500만 개의 질문/답변 쌍으로 학습되었어요.	예	- model_url - config_url	- model_url - config_url
`huggingface/sentence-transformers/multi-qa-mpnet-base-dot-v1`	1.0.2	768차원 밀집 벡터 공간.	예	- model_url - config_url	- model_url - config_url
`huggingface/sentence-transformers/paraphrase-MiniLM-L3-v2`	1.0.2	384차원 밀집 벡터 공간.	예	- model_url - config_url	- model_url - config_url
`huggingface/sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2`	1.0.2	384차원 밀집 벡터 공간.	예	- model_url - config_url	- model_url - config_url
`huggingface/sentence-transformers/paraphrase-mpnet-base-v2`	1.0.1	768차원 밀집 벡터 공간.	예	- model_url - config_url	- model_url - config_url
`huggingface/sentence-transformers/distiluse-base-multilingual-cased-v1`	1.0.2	512차원 밀집 벡터 공간.	예	- model_url - config_url	사용 불가

스파스 인코딩 모델

Introduced 2.11 {: .label .label-purple }

스파스 인코딩 모델은 텍스트를 스파스 벡터로 변환하고, 그 벡터를 텍스트 항목과 해당 가중치를 나타내는 <token: weight> 쌍의 목록으로 변환해요. 클러스터링이나 스파스 신경 검색과 같은 사용 사례에 이 모델들을 사용할 수 있어요.

최적의 성능을 위해 다음 조합을 권장해요:

인덱싱과 검색 모두에서 amazon/neural-sparse/opensearch-neural-sparse-encoding-v2-distill 모델을 사용하세요.
인덱싱 시 amazon/neural-sparse/opensearch-neural-sparse-encoding-doc-v3-gte 모델을 사용하고, 검색 시 amazon/neural-sparse/opensearch-neural-sparse-tokenizer-v1 토크나이저를 사용하세요.

amazon/neural-sparse/opensearch-neural-sparse-encoding-doc-v3-distill과 amazon/neural-sparse/opensearch-neural-sparse-encoding-doc-v3-gte는 모두 최대 값 비율 0.1로 가지치기되어 검색 성능과 인덱스 크기 간의 개선된 균형을 제공해요.

신경 스파스 검색 실행을 위한 앞의 옵션에 대한 자세한 내용은 스파스 벡터 임베딩 자동 생성을 참조하세요.

다음 표는 다운로드할 수 있는 스파스 인코딩 모델과 아티팩트 링크 목록을 제공해요.

모델 이름	버전	자동 절단	TorchScript 아티팩트	설명
`amazon/neural-sparse/opensearch-neural-sparse-encoding-v1`	1.0.1	예	- model_url - config_url	신경 희소 인코딩 모델이에요. 이 모델은 텍스트를 희소 벡터로 변환하고, 벡터에서 0이 아닌 요소의 인덱스를 식별한 다음, 벡터를 `<entry, weight>` 쌍으로 변환해요. 여기서 각 항목은 0이 아닌 요소 인덱스에 해당해요. transformers 및 PyTorch API를 사용하여 이 모델을 실험하려면 Hugging Face 문서를 참조하세요.
`amazon/neural-sparse/opensearch-neural-sparse-encoding-v2-distill`	1.0.0	예	- model_url - config_url	신경 희소 인코딩 모델이에요. 이 모델은 텍스트를 희소 벡터로 변환하고, 벡터에서 0이 아닌 요소의 인덱스를 식별한 다음, 벡터를 `<entry, weight>` 쌍으로 변환해요. 여기서 각 항목은 0이 아닌 요소 인덱스에 해당해요. transformers 및 PyTorch API를 사용하여 이 모델을 실험하려면 Hugging Face 문서를 참조하세요.
`amazon/neural-sparse/opensearch-neural-sparse-encoding-doc-v1`	1.0.1	예	- model_url - config_url	신경 희소 인코딩 모델이에요. 이 모델은 텍스트를 희소 벡터로 변환하고, 벡터에서 0이 아닌 요소의 인덱스를 식별한 다음, 벡터를 `<entry, weight>` 쌍으로 변환해요. 여기서 각 항목은 0이 아닌 요소 인덱스에 해당해요. transformers 및 PyTorch API를 사용하여 이 모델을 실험하려면 Hugging Face 문서를 참조하세요.
`amazon/neural-sparse/opensearch-neural-sparse-encoding-doc-v2-distill`	1.0.0	예	- model_url - config_url	신경 희소 인코딩 모델이에요. 이 모델은 텍스트를 희소 벡터로 변환하고, 벡터에서 0이 아닌 요소의 인덱스를 식별한 다음, 벡터를 `<entry, weight>` 쌍으로 변환해요. 여기서 각 항목은 0이 아닌 요소 인덱스에 해당해요. transformers 및 PyTorch API를 사용하여 이 모델을 실험하려면 Hugging Face 문서를 참조하세요.
`amazon/neural-sparse/opensearch-neural-sparse-encoding-doc-v2-mini`	1.0.0	예	- model_url - config_url	신경 희소 인코딩 모델이에요. 이 모델은 텍스트를 희소 벡터로 변환하고, 벡터에서 0이 아닌 요소의 인덱스를 식별한 다음, 벡터를 `<entry, weight>` 쌍으로 변환해요. 여기서 각 항목은 0이 아닌 요소 인덱스에 해당해요. transformers 및 PyTorch API를 사용하여 이 모델을 실험하려면 Hugging Face 문서를 참조하세요.
`amazon/neural-sparse/opensearch-neural-sparse-encoding-doc-v3-distill`	1.0.0	예	- model_url - config_url	신경 희소 인코딩 모델이에요. 이 모델은 텍스트를 희소 벡터로 변환하고, 벡터에서 0이 아닌 요소의 인덱스를 식별한 다음, 벡터를 `<entry, weight>` 쌍으로 변환해요. 여기서 각 항목은 0이 아닌 요소 인덱스에 해당해요. transformers 및 PyTorch API를 사용하여 이 모델을 실험하려면 Hugging Face 문서를 참조하세요.
`amazon/neural-sparse/opensearch-neural-sparse-encoding-doc-v3-gte`	1.0.0	예	- model_url - config_url	신경 희소 인코딩 모델이에요. 이 모델은 텍스트를 희소 벡터로 변환하고, 벡터에서 0이 아닌 요소의 인덱스를 식별한 다음, 벡터를 `<entry, weight>` 쌍으로 변환해요. 여기서 각 항목은 0이 아닌 요소 인덱스에 해당해요. transformers 및 PyTorch API를 사용하여 이 모델을 실험하려면 Hugging Face 문서를 참조하세요.
`amazon/neural-sparse/opensearch-neural-sparse-encoding-multilingual-v1`	1.0.0	예	- model_url - config_url	다국어 신경 희소 인코딩 모델이에요. 이 모델은 텍스트를 희소 벡터로 변환하고, 벡터에서 0이 아닌 요소의 인덱스를 식별한 다음, 벡터를 `<entry, weight>` 쌍으로 변환해요. 여기서 각 항목은 0이 아닌 요소 인덱스에 해당해요. transformers 및 PyTorch API를 사용하여 이 모델을 실험하려면 Hugging Face 문서를 참조하세요.
`amazon/neural-sparse/opensearch-neural-sparse-tokenizer-v1`	1.0.1	예	- model_url - config_url	신경 희소 토크나이저예요. 이 토크나이저는 텍스트를 토큰으로 분할하고 각 토큰에 미리 정의된 가중치(토큰의 역문서 빈도(IDF))를 할당해요. IDF 파일이 제공되지 않으면 가중치는 기본적으로 1이 돼요. 자세한 내용은 모델 준비를 참조하세요.
`amazon/neural-sparse/opensearch-neural-sparse-tokenizer-multilingual-v1`	1.0.0	예	- model_url - config_url	다국어 신경 희소 토크나이저예요. 이 토크나이저는 텍스트를 토큰으로 분할하고 각 토큰에 미리 정의된 가중치(토큰의 역문서 빈도(IDF))를 할당해요. IDF 파일이 제공되지 않으면 가중치는 기본적으로 1이 돼요. 자세한 내용은 모델 준비를 참조하세요.

Cross-encoder 모델

2.12에서 도입됨 {: .label .label-purple }

Cross-encoder 모델은 쿼리 재순위화를 지원해요.

다음 표는 다운로드할 수 있는 cross-encoder 모델 및 아티팩트 링크 목록을 제공해요. 모델 이름 열에 표시된 대로 모델 이름 앞에 huggingface/cross-encoders를 접두사로 붙여야 해요.

모델 이름	버전	TorchScript 아티팩트	ONNX 아티팩트
`huggingface/cross-encoders/ms-marco-MiniLM-L-6-v2`	1.0.2	- model_url - config_url	- model_url - config_url
`huggingface/cross-encoders/ms-marco-MiniLM-L-12-v2`	1.0.2	- model_url - config_url	- model_url - config_url

시맨틱 문장 하이라이팅 모델

3.0에서 도입됨 {: .label .label-purple }

시맨틱 문장 하이라이팅 모델은 semantic 하이라이터와 함께 작동하도록 특별히 설계되었어요. 이 모델은 문서 텍스트를 분석하고 검색 쿼리와 가장 의미론적으로 관련된 문장을 식별해요.

이 모델을 semantic 하이라이터와 함께 사용하는 방법에 대한 튜토리얼은 시맨틱 하이라이팅 사용을 참조하세요.

다음 표는 다운로드할 수 있는 시맨틱 문장 하이라이팅 모델 및 아티팩트 링크 목록을 제공해요. 모델 이름 열에 표시된 대로 모델 이름 앞에 opensearch/를 접두사로 붙여야 해요.

모델 이름	버전	TorchScript 아티팩트	설명
`amazon/sentence-highlighting/opensearch-semantic-highlighter-v1`	1.0.0	- model_url - config_url	하이라이팅할 의미론적으로 관련된 문장을 식별하도록 최적화된 모델이에요.

전제 조건

전용 ML 노드가 있는 클러스터에서는 성능 향상을 위해 "only_run_on_ml_node": "true"를 지정하세요. 자세한 내용은 ML Commons 클러스터 설정을 참조하세요.

이 예제는 전용 ML 노드가 없는 간단한 설정을 사용하고, 비ML 노드에서 모델을 실행할 수 있어요. 이 기본 로컬 설정이 제대로 작동하도록 하려면 다음 클러스터 설정을 지정하세요.

PUT _cluster/settings
{
  "persistent": {
    "plugins.ml_commons.only_run_on_ml_node": "false",
    "plugins.ml_commons.model_access_control_enabled": "true",
    "plugins.ml_commons.native_memory_threshold": "99"
  }
}

{% include copy-curl.html %}

1단계: 모델 그룹 등록

모델을 등록하려면 다음 옵션이 있어요:

model_group_id를 사용하여 기존 모델 그룹에 모델 버전을 등록할 수 있어요.
model_group_id를 사용하지 않으면 ML Commons가 새 모델 그룹으로 모델을 생성해요.

모델 그룹을 등록하려면 다음 요청을 전송하세요.

POST /_plugins/_ml/model_groups/_register
{
  "name": "local_model_group",
  "description": "A model group for local models"
}

{% include copy-curl.html %}

응답에는 이 모델 그룹에 모델을 등록하는 데 사용할 모델 그룹 ID가 포함돼요.

{
 "model_group_id": "wlcnb4kBJ1eYAeTMHlV6",
 "status": "CREATED"
}

모델 그룹에 대한 자세한 내용은 모델 액세스 제어를 참조하세요.

2단계: 로컬 OpenSearch 제공 모델 등록

1단계에서 생성한 모델 그룹에 OpenSearch 제공 모델을 등록하려면 다음 요청에 1단계의 모델 그룹 ID를 제공하세요.

사전 학습된 모델은 ML Commons 모델 저장소에서 제공되므로 등록 API 요청에 name, version, model_group_id, model_format만 제공하면 돼요.

POST /_plugins/_ml/models/_register
{
  "name": "huggingface/sentence-transformers/msmarco-distilbert-base-tas-b",
  "version": "1.0.3",
  "model_group_id": "Z1eQf4oB5Vm0Tdw8EIP2",
  "model_format": "TORCH_SCRIPT"
}

{% include copy-curl.html %}

OpenSearch가 등록 작업의 태스크 ID를 반환해요.

{
  "task_id": "cVeMb4kBJ1eYAeTMFFgj",
  "status": "CREATED"
}

작업 상태를 확인하려면 Get ML Task API에 태스크 ID를 제공하세요.

GET /_plugins/_ml/tasks/cVeMb4kBJ1eYAeTMFFgj

{% include copy-curl.html %}

작업이 완료되면 상태가 COMPLETED로 변경돼요.

{
  "model_id": "cleMb4kBJ1eYAeTMFFg4",
  "task_type": "REGISTER_MODEL",
  "function_name": "TEXT_EMBEDDING",
  "state": "COMPLETED",
  "worker_node": [
    "XPcXLV7RQoi5m8NI_jEOVQ"
  ],
  "create_time": 1689793598499,
  "last_update_time": 1689793598530,
  "is_async": false
}

반환된 model_id를 기록해 두세요. 모델을 배포할 때 필요해요.

3단계: 모델 배포

배포 작업은 모델 인덱스에서 모델의 청크를 읽은 다음 모델 인스턴스를 생성하여 메모리에 로드해요. 모델이 클수록 더 많은 청크로 분할되고 메모리에 로드하는 데 더 오래 걸려요.

등록된 모델을 배포하려면 다음 요청에 3단계의 모델 ID를 제공하세요.

POST /_plugins/_ml/models/cleMb4kBJ1eYAeTMFFg4/_deploy

{% include copy-curl.html %}

응답에는 배포 작업 상태를 확인하는 데 사용할 수 있는 태스크 ID가 포함돼요.

{
  "task_id": "vVePb4kBJ1eYAeTM7ljG",
  "status": "CREATED"
}

이전 단계와 마찬가지로 Get ML Task API를 호출하여 작업 상태를 확인하세요.

GET /_plugins/_ml/tasks/vVePb4kBJ1eYAeTM7ljG

{% include copy-curl.html %}

작업이 완료되면 상태가 COMPLETED로 변경돼요.

{
  "model_id": "cleMb4kBJ1eYAeTMFFg4",
  "task_type": "DEPLOY_MODEL",
  "function_name": "TEXT_EMBEDDING",
  "state": "COMPLETED",
  "worker_node": [
    "n-72khvBTBi3bnIIR8FTTw"
  ],
  "create_time": 1689793851077,
  "last_update_time": 1689793851101,
  "is_async": true
}

클러스터나 노드가 다시 시작되면 모델을 다시 배포해야 해요. 자동 재배포를 설정하는 방법은 모델 배포 설정을 참조하세요. {: .tip}

4단계(선택 사항): 모델 테스트

Predict API를 사용하여 모델을 테스트하세요.

텍스트 임베딩 모델

텍스트 임베딩 모델의 경우 다음 요청을 전송하세요.

POST /_plugins/_ml/_predict/text_embedding/cleMb4kBJ1eYAeTMFFg4
{
  "text_docs":[ "today is sunny"],
  "return_number": true,
  "target_response": ["sentence_embedding"]
}

{% include copy-curl.html %}

응답에는 제공된 문장에 대한 텍스트 임베딩이 포함돼요.

{
  "inference_results" : [
    {
      "output" : [
        {
          "name" : "sentence_embedding",
          "data_type" : "FLOAT32",
          "shape" : [
            768
          ],
          "data" : [
            0.25517133,
            -0.28009856,
            0.48519906,
            ...
          ]
        }
      ]
    }
  ]
}

스파스 인코딩 모델 또는 스파스 토크나이저

스파스 인코딩 모델 또는 스파스 토크나이저의 경우 다음 요청을 전송하세요.

POST /_plugins/_ml/_predict/sparse_encoding/cleMb4kBJ1eYAeTMFFg4
{
  "text_docs":[ "today is sunny"]
}

{% include copy-curl.html %}

응답에는 추출된 토큰과 해당 가중치가 포함돼요.

{
  "inference_results": [
    {
      "output": [
        {
          "name": "output",
          "dataAsMap": {
            "response": [
              {
                "saturday": 0.48336542,
                "week": 0.1034762,
                "mood": 0.09698499,
                "sunshine": 0.5738209,
                "bright": 0.1756877,
                ...
              }
          }
        }
    }
}

앞의 예제는 기본 lexical 출력 형식을 사용하며, 문자열을 키로 반환해요. parameters.sparse_embedding_format을 lexical(문자열 토큰 반환) 또는 token_id(정수 토큰 ID 반환)로 설정하여 출력 키 형식을 제어할 수 있어요. 다음 예제는 sparse_embedding_format을 token_id로 설정해요.

POST /_plugins/_ml/_predict/sparse_encoding/cleMb4kBJ1eYAeTMFFg4
{
  "text_docs": ["hello world"],
  "parameters": {
    "sparse_embedding_format": "token_id"
  }
}

{% include copy-curl.html %}

응답에는 토큰 ID와 해당 토큰 가중치가 포함돼요.

{
  "inference_results": [
    {
      "output": [
        {
          "dataAsMap": {
            "response": [
              {
                "2088": 3.4208686,
                "7592": 6.9377565
              }
            ]
          }
        }
      ]
    }
  ]
}

크로스 인코더 모델

크로스 인코더 모델의 경우 다음 요청을 전송하세요.

POST _plugins/_ml/models/{model_id}/_predict
{
    "query_text": "today is sunny",
    "text_docs": [
        "how are you",
        "today is sunny",
        "today is july fifth",
        "it is winter"
    ]
}

{% include copy-curl.html %}

모델은 query_text와 text_docs의 각 문서 간 유사도 점수를 계산하고 text_docs에 제공된 순서대로 각 문서의 점수 목록을 반환해요.

{
  "inference_results": [
    {
      "output": [
        {
          "name": "similarity",
          "data_type": "FLOAT32",
          "shape": [
            1
          ],
          "data": [
            -6.077798
          ],
          "byte_buffer": {
            "array": "Un3CwA==",
            "order": "LITTLE_ENDIAN"
          }
        }
      ]
    },
    {
      "output": [
        {
          "name": "similarity",
          "data_type": "FLOAT32",
          "shape": [
            1
          ],
          "data": [
            10.223609
          ],
          "byte_buffer": {
            "array": "55MjQQ==",
            "order": "LITTLE_ENDIAN"
          }
        }
      ]
    },
    {
      "output": [
        {
          "name": "similarity",
          "data_type": "FLOAT32",
          "shape": [
            1
          ],
          "data": [
            -1.3987057
          ],
          "byte_buffer": {
            "array": "ygizvw==",
            "order": "LITTLE_ENDIAN"
          }
        }
      ]
    },
    {
      "output": [
        {
          "name": "similarity",
          "data_type": "FLOAT32",
          "shape": [
            1
          ],
          "data": [
            -4.5923924
          ],
          "byte_buffer": {
            "array": "4fSSwA==",
            "order": "LITTLE_ENDIAN"
          }
        }
      ]
    }
  ]
}

문서 점수가 높을수록 유사도가 높아요. 앞의 응답에서 문서는 쿼리 텍스트 today is sunny에 대해 다음과 같이 점수가 매겨져요.

문서 텍스트	점수
`how are you`	-6.077798
`today is sunny`	10.223609
`today is july fifth`	-1.3987057
`it is winter`	-4.5923924

쿼리와 동일한 텍스트를 포함하는 문서가 가장 높은 점수를 받고, 나머지 문서는 텍스트 유사도에 따라 점수가 매겨져요.

5단계: 검색에 모델 사용

벡터 인덱스를 설정하고 검색에 텍스트 임베딩 모델을 사용하는 방법은 시맨틱 검색을 참조하세요.

벡터 인덱스를 설정하고 검색에 스파스 인코딩 모델을 사용하는 방법은 신경 스파스 검색을 참조하세요.

재순위화에 크로스 인코더 모델을 사용하는 방법은 검색 결과 재순위화를 참조하세요.

더 알아보기 (Learn more)

원문 전체: https://docs.opensearch.org/latest/ml-commons-plugin/pretrained-models/

OpenSearch-provided pretrained models

본문

OpenSearch 제공 사전 훈련 모델

지원되는 사전 학습 모델

문장 변환기

스파스 인코딩 모델

Cross-encoder 모델

시맨틱 문장 하이라이팅 모델

전제 조건

1단계: 모델 그룹 등록

2단계: 로컬 OpenSearch 제공 모델 등록

3단계: 모델 배포

4단계(선택 사항): 모델 테스트

텍스트 임베딩 모델

스파스 인코딩 모델 또는 스파스 토크나이저

크로스 인코더 모델

5단계: 검색에 모델 사용

더 알아보기 (Learn more)

함께 읽는 실무 이야기