Register Model API

원문 보기 위키 갱신 2026.10.14

출처: 문서

본문

Register Model API

특정 모델의 모든 버전은 모델 그룹에 보관됩니다. 모델을 그룹에 등록하기 전에 모델 그룹을 등록하거나 모델의 첫 번째 버전을 등록하여 그룹을 생성할 수 있습니다. 클러스터의 각 모델 그룹 이름은 전역적으로 고유해야 합니다.

모델 그룹을 먼저 등록하지 않고 모델의 첫 번째 버전을 등록하는 경우, 새 모델 그룹이 다음 이름과 액세스 수준으로 자동 생성됩니다:

이름: 새 모델 그룹은 모델과 동일한 이름을 갖습니다. 모델 그룹 이름은 고유해야 하므로, 모델 이름이 클러스터의 다른 모델 그룹 이름과 동일하지 않도록 하세요.
액세스 수준: 새 모델 그룹의 액세스 수준은 요청에서 전달하는 access_mode, backend_roles, add_all_backend_roles 매개변수를 사용하여 결정됩니다. 세 매개변수 중 어느 것도 제공하지 않으면, 클러스터에서 모델 액세스 제어가 활성화된 경우 새 모델 그룹은 private이 되고, 모델 액세스 제어가 비활성화된 경우 public이 됩니다. 새로 등록된 모델은 해당 모델 그룹에 할당된 첫 번째 모델 버전입니다.

모델 그룹이 생성되면, 해당 model_group_id를 제공하여 모델 그룹에 새 모델 버전을 등록합니다. 이 경우 모델 이름은 고유할 필요가 없습니다.

OpenSearch에서 제공하는 사전 학습 모델을 사용하는 경우, 먼저 이러한 모델에 대해 고유한 이름의 모델 그룹을 등록하는 것이 좋습니다. 그런 다음 사전 학습 모델을 해당 모델 그룹의 버전으로 등록합니다. 이렇게 하면 모든 모델 그룹이 전역적으로 고유한 모델 그룹 이름을 갖게 됩니다. {: .tip}

이 API에 대한 사용자 액세스에 대한 자세한 내용은 모델 액세스 제어 고려 사항을 참조하세요.

모델 크기가 10MB를 초과하는 경우, ML Commons는 모델을 더 작은 청크로 분할하여 해당 청크를 모델의 인덱스에 저장합니다.

엔드포인트

POST /_plugins/_ml/models/_register

쿼리 매개변수

다음 표에서는 사용 가능한 쿼리 매개변수를 보여줍니다. 모든 쿼리 매개변수는 선택 사항입니다.

Parameter	Data type	Description
`deploy`	Boolean	모델을 등록한 후 배포할지 여부입니다. 배포 작업은 Deploy Model API를 호출하여 수행됩니다. 기본값은 `false`입니다.

요청 본문 필드

요청 본문 필드는 모델 유형에 따라 달라져요.

OpenSearch 제공 사전 훈련 모델 등록

OpenSearch는 여러 사전 훈련 모델을 제공해요. 자세한 내용은 OpenSearch-provided pretrained models를 참조하세요.

사전 훈련 텍스트 임베딩 모델 등록

사전 훈련 텍스트 임베딩 모델을 등록하려면 필수 매개변수는 name, version, model_format뿐이에요.

다음 표는 사용 가능한 요청 필드를 보여줘요.

사전 훈련 희소 인코딩 모델 등록

사전 훈련 희소 인코딩 모델을 등록하려면 함수 이름을 SPARSE_ENCODING 또는 SPARSE_TOKENIZE로 설정해야 해요.

다음 표는 사용 가능한 요청 필드를 보여줘요.

사용자 지정 모델 등록

OpenSearch 클러스터 내에서 사용자 지정 모델을 로컬로 사용하려면 해당 모델의 URL과 config 객체를 제공해야 해요. 자세한 내용은 Custom local models를 참조하세요.

다음 표는 사용 가능한 요청 필드를 보여줘요.

`model_config` 객체

Field	Data type	Description
`model_type`	String	모델 유형이에요(예: `bert`). Hugging Face 모델의 경우 모델 유형이 `config.json`에 지정돼요. 예를 들어 `all-MiniLM-L6-v2` Hugging Face model `config.json`을 참조하세요. 필수예요.
`embedding_dimension`	Integer	모델이 생성하는 밀집 벡터의 차원이에요. Hugging Face 모델의 경우 모델 카드에 차원이 지정돼요. 예를 들어 `all-MiniLM-L6-v2` Hugging Face model card에서 `384 dimensional dense vector space`라는 문장이 임베딩 차원을 384로 지정해요. 필수예요.
`framework_type`	String	모델이 사용하는 프레임워크예요. OpenSearch는 `sentence_transformers`와 `huggingface_transformers` 프레임워크를 지원해요. `sentence_transformers` 모델은 텍스트 임베딩을 직접 출력하므로 ML Commons가 후처리를 수행하지 않아요. `huggingface_transformers`의 경우 ML Commons가 평균 풀링을 적용하여 텍스트 임베딩을 얻는 후처리를 수행해요. 자세한 내용은 `all-MiniLM-L6-v2` Hugging Face model 예제를 참조하세요. 필수예요.
`all_config`	String	이 필드는 참조 용도로 사용돼요. 이 필드에 모든 모델 구성을 지정할 수 있어요. 예를 들어 Hugging Face 모델을 사용하는 경우 `config.json` 파일을 한 줄로 축소하고 그 내용을 `all_config` 필드에 저장할 수 있어요. 모델이 업로드되면 get model API 작업을 사용하여 이 필드에 저장된 모든 모델 구성을 가져올 수 있어요. 선택 사항이에요.
`additional_config`	Object	추가 모델 구성이에요. k-NN 검색의 거리 측정항목을 지정하는 `space_type`을 포함해요. OpenSearch 제공 사전 훈련 모델의 경우 이 값이 자동으로 해당 측정항목으로 설정돼요(예: `huggingface/sentence-transformers/all-distilroberta-v1`의 경우 `l2`). 사용자 지정 모델의 경우 원하는 공간 유형을 지정해요. 선택 사항이에요. Space types를 참조하세요.

model_config 객체의 다음 선택적 필드를 사용하여 사전 훈련된 sentence transformer 모델의 후처리 로직을 추가로 사용자 지정할 수 있어요.

Field	Data type	Description
`pooling_mode`	String	후처리 모델 출력이에요. `mean`, `mean_sqrt_len`, `max`, `weightedmean`, `cls`, `lasttoken`, `none` 중 하나예요. 디코더 전용 모델(예: Qwen3-Embedding)의 경우 `lasttoken`을 사용해요. 이 모델에서는 최종 비패딩 토큰이 인과적 주의를 통해 누적 컨텍스트를 캡처해요. 이미 사전 풀링된 출력(예: `sentence_embedding` 또는 `pooler_output`)을 제공하는 모델의 경우 추가 풀링을 건너뛰기 위해 `none`을 사용해요.
`normalize_result`	Boolean	`true`로 설정하면 모델 출력을 정규화하여 모델의 표준 범위로 조정해요.

타사 플랫폼에 호스팅된 모델 등록

타사 플랫폼에 호스팅된 모델을 등록하려면 먼저 독립형 커넥터를 생성하고 해당 커넥터의 ID를 제공하거나 모델에 대한 내부 커넥터를 지정할 수 있어요. 자세한 내용은 Creating connectors for third-party ML platforms를 참조하세요.

다음 표는 사용 가능한 요청 필드를 보여줘요.

`guardrails` 매개변수

가드레일은 대규모 언어 모델(LLM)의 안전 조치예요. LLM의 동작 방식과 생성하는 출력 종류를 제어하는 일련의 규칙과 경계를 제공해요.

가드레일과 함께 외부 호스팅 모델을 등록하려면 guardrails 매개변수를 제공해요. 이 매개변수는 다음 필드를 지원해요. 모든 필드는 선택 사항이에요.

필드	데이터 타입	설명
`type`	String	가드레일 유형이에요. 유효한 값은 `local_regex`와 `model`이에요. `local_regex`를 사용하면 정규 표현식 또는 중지 단어를 지정할 수 있어요. `model`을 사용하면 가드레일 모델을 지정할 수 있어요. 자세한 내용은 Guardrails를 참조하세요.
`input_guardrail`	Object	모델 입력에 대한 가드레일이에요.
`output_guardrail`	Object	모델 출력에 대한 가드레일이에요.
`stop_words`	Object	모델 입력/출력 검증에 사용되는 중지 단어가 포함된 인덱스 목록이에요. 모델 프롬프트/응답에 인덱스에 포함된 중지 단어가 있으면 모델에 대한 예측 요청이 거부돼요.
`index_name`	Object	중지 단어를 저장하는 인덱스의 이름이에요.
`source_fields`	Object	중지 단어를 저장하는 필드의 이름이에요.
`regex`	Object	입력/출력 검증에 사용되는 정규 표현식이에요. 모델 프롬프트/응답이 정규 표현식과 일치하면 모델에 대한 예측 요청이 거부돼요.
`model_id`	String	사용자 입력과 LLM 출력을 검증하는 데 사용되는 가드레일 모델이에요.
`response_filter`	String	가드레일 모델 응답이 포함된 필드의 점 경로(dot path)예요.
`response_validation_regex`	String	가드레일 모델 응답을 검증하는 데 사용되는 정규 표현식이에요.

`interface` 매개변수

모델 인터페이스는 JSON schema 구문을 사용하여 모든 로컬 딥 러닝 모델 및 외부 호스팅 모델에 임의의 메타데이터 주석을 추가할 수 있는 매우 유연한 방법을 제공해요. 이 주석은 모델 호출 중에 모델의 입력 및 출력 필드에 대한 유효성 검사를 시작해요. 유효성 검사는 모델이 추론을 수행하기 전후에 입력 및 출력 필드가 올바른 형식인지 확인해요.

모델 인터페이스로 모델을 등록하려면 interface 매개변수를 제공하세요. 이 매개변수는 다음 필드를 지원해요.

필드	데이터 타입	설명
`input`	Object	모델 입력에 대한 JSON schema예요.
`output`	Object	모델 출력에 대한 JSON schema예요.

입력 및 출력 필드는 제공된 JSON schema를 기준으로 평가돼요. 두 필드를 동시에 제공할 필요는 없어요.

커넥터 모델 인터페이스

워크플로를 간소화하기 위해 커넥터 블루프린트 형식 중 하나로 커넥터를 사용하여 외부 호스팅 모델을 등록할 수 있어요. 이렇게 하면 모델 등록 중에 이 커넥터에 대한 사전 정의된 모델 인터페이스가 자동으로 생성돼요. 사전 정의된 모델 인터페이스는 커넥터 블루프린트와 모델의 메타데이터를 기반으로 생성되므로, 오류를 방지하려면 커넥터를 생성할 때 블루프린트를 엄격히 따라야 해요.

Amazon Comprehend
Amazon Textract (사전 정의된 모델 인터페이스는 DetectDocumentText API에만 사용할 수 있으며, DetectEnities API는 지원되지 않아요.)
Amazon Bedrock AI21 Labs Jurassic
Amazon Bedrock Anthropic Claude 3
Amazon Bedrock Anthropic Claude
Amazon Bedrock Cohere Embed English v3
Amazon Bedrock Cohere Embed Multilingual v3
Amazon Bedrock Titan Text Embeddings
Amazon Bedrock Titan Multimodal Embeddings

커넥터 블루프린트에 대한 자세한 내용은 Connector blueprints를 참조하세요.

`batch_inference_config` 매개변수

batch_inference_config 매개변수를 사용하여 OpenSearch가 한 번의 호출로 모델에 보내는 입력 문자열의 수와 크기를 제한함으로써 각 호출이 외부 호스팅 모델의 제한 내에 머물도록 할 수 있어요. 또한 개별 요청을 결합하여 전체 처리량을 향상시키는 동적 배치를 활성화할 수 있어요. max_items_per_request와 max_bytes_per_request 중 적어도 하나는 양수 값으로 설정해야 해요.

다음 표는 batch_inference_config 필드를 나열해요.

필드	데이터 타입	필수/선택	기본값	설명
`max_items_per_request`	Integer	선택 사항	`-1` (비활성화)	모델에 대한 한 번의 호출에서 입력 문자열의 최대 개수예요. 이 매개변수를 생략하거나 `-1`로 설정하면 이 제한이 비활성화돼요.
`max_bytes_per_request`	Long	선택 사항	`-1` (비활성화)	모델에 대한 단일 호출에서 입력 문자열의 최대 총 크기(바이트)예요. 이 제한은 커넥터 요청 본문의 다른 필드를 제외하므로, 엔드포인트의 페이로드 제한보다 낮은 값을 설정하여 다른 필드를 위한 공간을 확보하세요. 이 매개변수를 생략하거나 `-1`로 설정하면 이 제한이 비활성화돼요.
`dynamic_batching`	Object	선택 사항		동적 배치를 구성해요.
`dynamic_batching.enabled`	Boolean	선택 사항	`false`	`true`로 설정하면 OpenSearch가 모델에 요청을 보내기 전에 동적으로 배치해요. 동적 배치를 사용하려면 `max_items_per_request` 또는 `max_bytes_per_request`에 양수 값이 필요해요.
`dynamic_batching.flush_timeout_ms`	Long	선택 사항	`50`	첫 번째 요청이 모델이 배치로 호출되기 전에 추가 요청을 기다리는 최대 시간(밀리초)이에요. 유효한 값은 1~10,000이에요. 누적된 입력 문자열이 시간 초과 전에 `max_items_per_request` 또는 `max_bytes_per_request`에 도달하면 배치가 더 일찍 호출될 수 있어요.

요청 예시

다음 예시에서는 다양한 유형의 모델을 등록하는 방법을 보여줘요.

요청 예시: OpenSearch 제공 텍스트 임베딩 모델

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 제공 희소 인코딩 모델

POST /_plugins/_ml/models/_register
{
    "name": "amazon/neural-sparse/opensearch-neural-sparse-encoding-doc-v3-distill",
    "version": "1.0.0",
    "model_group_id": "Z1eQf4oB5Vm0Tdw8EIP2",
    "model_format": "TORCH_SCRIPT"
}

{% include copy-curl.html %}

요청 예시: 사용자 정의 모델

다음 요청 예시는 all-MiniLM-L6-v2라는 이름의 NLP 문장 변환 모델의 버전 1.0.0을 등록해요.

POST /_plugins/_ml/models/_register
{
    "name": "all-MiniLM-L6-v2",
    "version": "1.0.0",
    "description": "test model",
    "model_format": "TORCH_SCRIPT",
    "function_name": "TEXT_EMBEDDING",
    "model_group_id": "FTNlQ4gBYW0Qyy5ZoxfR",
    "model_content_hash_value": "c15f0d2e62d872be5b5bc6c84d2e0f4921541e29fefbef51d59cc10a8ae30e0f",
    "model_config": {
        "model_type": "bert",
        "embedding_dimension": 384,
        "framework_type": "sentence_transformers",
       "all_config": "{\"_name_or_path\":\"nreimers/MiniLM-L6-H384-uncased\",\"architectures\":[\"BertModel\"],\"attention_probs_dropout_prob\":0.1,\"gradient_checkpointing\":false,\"hidden_act\":\"gelu\",\"hidden_dropout_prob\":0.1,\"hidden_size\":384,\"initializer_range\":0.02,\"intermediate_size\":1536,\"layer_norm_eps\":1e-12,\"max_position_embeddings\":512,\"model_type\":\"bert\",\"num_attention_heads\":12,\"num_hidden_layers\":6,\"pad_token_id\":0,\"position_embedding_type\":\"absolute\",\"transformers_version\":\"4.8.2\",\"type_vocab_size\":2,\"use_cache\":true,\"vocab_size\":30522}"
    },
    "url": "https://artifacts.opensearch.org/models/ml-models/huggingface/sentence-transformers/all-MiniLM-L6-v2/1.0.1/torch_script/sentence-transformers_all-MiniLM-L6-v2-1.0.1-torch_script.zip"
}

{% include copy-curl.html %}

요청 예시: 독립형 커넥터를 사용한 외부 호스팅

POST /_plugins/_ml/models/_register
{
    "name": "openAI-gpt-4o-mini",
    "function_name": "remote",
    "model_group_id": "1jriBYsBq7EKuKzZX131",
    "description": "test model",
    "connector_id": "a1eMb4kBJ1eYAeTMAljY"
}

{% include copy-curl.html %}

요청 예시: 모델의 일부로 지정된 커넥터를 사용한 외부 호스팅

POST /_plugins/_ml/models/_register
{
    "name": "openAI-gpt-4o-mini: internal connector",
    "function_name": "remote",
    "model_group_id": "lEFGL4kB4ubqQRzegPo2",
    "description": "test model",
    "connector": {
        "name": "OpenAI Connector",
        "description": "The connector to public OpenAI model service for gpt-4o-mini",
        "version": 1,
        "protocol": "http",
        "parameters": {
            "endpoint": "api.openai.com",
            "max_tokens": 7,
            "temperature": 0,
            "model": "gpt-4o-mini"
        },
        "credential": {
            "openAI_key": "..."
        },
        "actions": [
            {
                "action_type": "predict",
                "method": "POST",
                "url": "https://${parameters.endpoint}/v1/chat/completions",
                "headers": {
                    "Authorization": "Bearer ${credential.openAI_key}"
                },
                "request_body": "{ \"model\": \"${parameters.model}\", \"messages\": [{\"role\": \"user\", \"content\": \"${parameters.prompt}\"}], \"max_tokens\": ${parameters.max_tokens}, \"temperature\": ${parameters.temperature} }"
            }
        ]
    }
}

{% include copy-curl.html %}

요청 예시: 정규식 및 중지 단어 검증

다음 예시에서는 정규식과 중지 단어 집합을 사용하여 LLM 응답을 검증해요:

POST /_plugins/_ml/models/_register
{
  "name": "openAI-gpt-4o-mini",
  "function_name": "remote",
  "model_group_id": "1jriBYsBq7EKuKzZX131",
  "description": "test model",
  "connector_id": "a1eMb4kBJ1eYAeTMAljY",
  "guardrails": {
    "type": "local_regex",
    "input_guardrail": {
      "stop_words": [
        {
          "index_name": "stop_words_input",
          "source_fields": ["title"]
        }
      ],
      "regex": ["regex1", "regex2"]
    },
    "output_guardrail": {
      "stop_words": [
        {
          "index_name": "stop_words_output",
          "source_fields": ["title"]
        }
      ],
      "regex": ["regex1", "regex2"]
    }
  }
}

{% include copy-curl.html %}

전체 예시는 중지 단어 및 정규식을 사용한 입력/출력 검증을 참조하세요.

요청 예시: 가드레일 모델 검증

다음 예시에서는 가드레일 모델을 사용하여 LLM 응답을 검증해요:

POST /_plugins/_ml/models/_register?deploy=true
{
    "name": "Bedrock Claude V2 model with guardrails model",
    "function_name": "remote",
    "model_group_id": "ppSmpo8Bi-GZ0tf1i7cD",
    "description": "Bedrock Claude V2 model with guardrails model",
    "connector_id": "xnJjDZABNFJeYR3IPvTO",
    "guardrails": {
        "input_guardrail": {
            "model_id": "o3JaDZABNFJeYR3I2fRV",
            "response_validation_regex": "^\\s*\"[Aa]ccept\"\\s*$"
        },
        "output_guardrail": {
            "model_id": "o3JaDZABNFJeYR3I2fRV",
            "response_validation_regex": "^\\s*\"[Aa]ccept\"\\s*$"
        },
        "type": "model"
    }
}

{% include copy-curl.html %}

전체 예시는 가드레일 모델을 사용한 입력/출력 검증을 참조하세요.

요청 예시: 인터페이스가 있는 외부 호스팅 모델

POST /_plugins/_ml/models/_register
{
    "name": "openAI-gpt-4o-mini",
    "function_name": "remote",
    "description": "test model",
    "connector_id": "A-j7K48BZzNMh1sWVdJu",
    "interface": {
        "input": {
            "properties": {
                "parameters": {
                    "properties": {
                        "messages": {
                            "type": "string",
                            "description": "This is a test description field"
                        }
                    }
                }
            }
        },
        "output": {
            "properties": {
                "inference_results": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
                            "output": {
                                "type": "array",
                                "items": {
                                    "properties": {
                                        "name": {
                                            "type": "string",
                                            "description": "This is a test description field"
                                        },
                                        "dataAsMap": {
                                            "type": "object",
                                            "description": "This is a test description field"
                                        }
                                    }
                                },
                                "description": "This is a test description field"
                            },
                            "status_code": {
                                "type": "integer",
                                "description": "This is a test description field"
                            }
                        }
                    },
                    "description": "This is a test description field"
                }
            }
        }
    }
}

{% include copy-curl.html %}

요청 예시: 배치 추론 구성

정확한 모델과 제공자에 대한 공식 문서에서 입력 문자열 개수(max_items_per_request) 및 페이로드(max_bytes_per_request) 제한을 확인하세요. 사용자 정의 엔드포인트의 경우 모델 서버에 구성된 제한을 사용하세요. 구성 지침은 외부 호스팅 모델에 대한 요청 배치를 참조하세요.

다음 요청은 크기 제한과 동적 배치가 활성화된 외부 호스팅 모델을 등록해요:

POST /_plugins/_ml/models/_register
{
  "name": "remote-embedding-model",
  "function_name": "remote",
  "connector_id": "<connector_id>",
  "batch_inference_config": {
    "max_items_per_request": 96,
    "max_bytes_per_request": 4000000,
    "dynamic_batching": {
      "enabled": true,
      "flush_timeout_ms": 50
    }
  }
}

{% include copy-curl.html %}

응답 예시

OpenSearch는 task_id, 작업 status, model_id로 응답해요:

{
  "task_id" : "ew8I44MBhyWuIwnfvDIH", 
  "status" : "CREATED",
  "model_id": "t8qvDY4BChVAiNVEuo8q"
}

모델 등록 상태 확인

모델 등록 상태를 확인하고 새 모델 버전에 대해 생성된 모델 ID를 검색하려면 task_id를 경로 매개변수로 Get ML Task API에 전달하세요:

GET /_plugins/_ml/tasks/{task_id}

{% include copy-curl.html %}

응답에는 모델 버전의 모델 ID가 포함돼요:

{
  "model_id": "Qr1YbogBYOqeeqR7sI9L",
  "task_type": "DEPLOY_MODEL",
  "function_name": "TEXT_EMBEDDING",
  "state": "COMPLETED",
  "worker_node": [
    "N77RInqjTSq_UaLh1k0BUg"
  ],
  "create_time": 1685478486057,
  "last_update_time": 1685478491090,
  "is_async": true
}

더 알아보기 (Learn more)

원문 전체: https://docs.opensearch.org/latest/ml-commons-plugin/api/model-apis/register-model/

Register Model API

본문

Register Model API

엔드포인트

쿼리 매개변수

요청 본문 필드

OpenSearch 제공 사전 훈련 모델 등록

사전 훈련 텍스트 임베딩 모델 등록

사전 훈련 희소 인코딩 모델 등록

사용자 지정 모델 등록

model_config 객체

타사 플랫폼에 호스팅된 모델 등록

guardrails 매개변수

interface 매개변수

커넥터 모델 인터페이스

batch_inference_config 매개변수

요청 예시

요청 예시: OpenSearch 제공 텍스트 임베딩 모델

요청 예시: OpenSearch 제공 희소 인코딩 모델

요청 예시: 사용자 정의 모델

요청 예시: 독립형 커넥터를 사용한 외부 호스팅

요청 예시: 모델의 일부로 지정된 커넥터를 사용한 외부 호스팅

요청 예시: 정규식 및 중지 단어 검증

요청 예시: 가드레일 모델 검증

요청 예시: 인터페이스가 있는 외부 호스팅 모델

요청 예시: 배치 추론 구성

응답 예시

모델 등록 상태 확인

더 알아보기 (Learn more)

함께 읽는 실무 이야기

`model_config` 객체

`guardrails` 매개변수

`interface` 매개변수

`batch_inference_config` 매개변수