ML cluster settings
출처: 문서
본문
ML 클러스터 설정
다음 설정들은 ML Commons 플러그인을 구성해요. opensearch.yml 파일에서 지정하거나 Cluster Settings API를 사용해 업데이트할 수 있어요. 이 페이지의 모든 ML Commons 설정은 동적이에요.
정적 설정과 동적 설정에 대해 더 알아보려면 Configuring OpenSearch를 참고하세요.
ML 노드
기본적으로 ML 작업과 로컬 모델은 ML 노드에서만 실행돼요. data 노드 역할 없이 구성하면 ML 노드는 샤드를 저장하지 않고, 대신 런타임에 리소스 요구 사항을 계산해요. ML 노드를 사용하려면 opensearch.yml 파일에서 노드를 생성하세요. 노드에 커스텀 이름을 지정하고 노드 역할을 ml로 정의하세요:
node.roles: [ ml ]
{% include copy.html %}
전용 ML 노드가 있는 클러스터 예시는 예제 Docker Compose 파일을 참고하세요.
노드 선택 설정
ML Commons는 ML 작업과 모델이 실행될 노드를 선택하기 위한 다음 설정을 지원해요:
-
plugins.ml_commons.only_run_on_ml_node(Dynamic, Boolean):true이면 로컬 모델이 ML 노드에서만 실행돼요.false이면 로컬 모델이plugins.ml_commons.task_dispatcher.eligible_node_role.local_model에 나열된 역할을 가진 노드에서 실행돼요. 데이터 노드에서 모델을 테스트하려면false로 설정하세요. 기본값은true예요. -
plugins.ml_commons.task_dispatcher.eligible_node_role.local_model(Dynamic, list): 로컬 모델이 실행될 수 있는 노드 역할이에요. 이 설정은plugins.ml_commons.only_run_on_ml_node가false일 때만 적용돼요. 기본값은["data", "ml"]이에요. -
plugins.ml_commons.task_dispatcher.eligible_node_role.remote_model(Dynamic, list): 외부 호스팅 모델이 실행될 수 있는 노드 역할이에요. 예를 들어 외부 호스팅 모델을 ML 노드에서만 실행하려면["ml"]로 설정하세요. 기본값은["data", "ml"]이에요. -
plugins.ml_commons.task_dispatch_policy(Dynamic, string): ML 작업을 ML 노드에 분배하는 정책이에요. 유효한 값은 라운드 로빈 라우팅으로 작업을 분배하는round_robin과, 모든 ML 노드에서 JVM 힙 메모리 사용량이나 실행 중인 작업 같은 런타임 정보를 수집해 부하가 가장 낮은 노드에 작업을 분배하는least_load예요. 기본값은round_robin이에요. -
plugins.ml_commons.exclude_nodes._name(Dynamic, string): ML 작업이 실행되지 않을 노드 이름 또는node1, node2처럼 쉼표로 구분된 노드 이름 목록이에요. -
plugins.ml_commons.allow_custom_deployment_plan(Dynamic, Boolean):true이면 사용자가 자신의 권한에 따라 특정 ML 노드에 모델을 배포할 수 있어요. 기본값은false이에요.
프로덕션 클러스터에서는 plugins.ml_commons.only_run_on_ml_node를 true로 설정하는 것을 추천해요.
{: .tip}
작업 및 모델 제한 설정
ML Commons는 각 노드에서 ML 작업과 모델의 개수와 실행 시간을 제한하기 위한 다음 설정을 지원해요:
-
plugins.ml_commons.max_ml_task_per_node(Dynamic, integer): 각 ML 노드에서 실행할 수 있는 ML 작업의 최대 개수예요.0으로 설정하면 어떤 노드에서도 ML 작업이 실행되지 않아요. 유효한 값은 0--10,000이에요. 기본값은10이에요. -
plugins.ml_commons.max_model_on_node(Dynamic, integer): 각 ML 노드에 배포할 수 있는 모델의 최대 개수예요.0으로 설정하면 어떤 노드에도 모델을 배포할 수 없어요. 유효한 값은 0--10,000이에요. 기본값은10이에요. -
plugins.ml_commons.max_register_model_tasks_per_node(Dynamic, integer): 한 노드에서 병렬로 실행할 수 있는 모델 등록 작업의 최대 개수예요.0으로 설정하면 어떤 노드에서도 모델을 등록할 수 없어요. 유효한 값은 0--10이에요. 기본값은10이에요. -
plugins.ml_commons.max_deploy_model_tasks_per_node(Dynamic, integer): 한 노드에서 병렬로 실행할 수 있는 모델 배포 작업의 최대 개수예요.0으로 설정하면 어떤 노드에도 모델을 배포할 수 없어요. 유효한 값은 0--10이에요. 기본값은10이에요. -
plugins.ml_commons.ml_task_timeout_in_seconds(Dynamic, integer): ML 작업이 실행될 수 있는 시간(초)이에요. 시간이 초과되면 작업이 실패해요. 유효한 값은 1--86,400이에요. 기본값은600이에요. -
plugins.ml_commons.sync_up_job_interval_in_seconds(Dynamic, integer): ML Commons가 각 노드에서 새로 배포되거나 배포 해제된 모델을 동기화하는 작업을 실행하는 간격(초)이에요. 이 작업은 Profile API가 반환하는 런타임 정보를 최신 상태로 유지해요.0으로 설정하면 ML Commons가 동기화 작업을 중지해요. 유효한 값은 0--86,400이에요. 기본값은10이에요. -
plugins.ml_commons.monitoring_request_count(Dynamic, long): 각 노드에서 모니터링되는 예측 요청의 개수예요.0으로 설정하면 OpenSearch가 캐시에서 모니터링 중인 모든 예측 요청을 지우고 새 예측 요청 모니터링을 중지해요. 유효한 값은 0--10,000,000이에요. 기본값은100이에요.
모델 등록 설정
기본적으로 ML Commons는 OpenSearch 모델 저장소의 사전 훈련된 모델만 등록할 수 있어요. ML Commons는 다른 소스에서 모델을 등록하기 위한 다음 설정을 지원해요:
-
plugins.ml_commons.allow_registering_model_via_url(Dynamic, Boolean):true이면 사용자가 URL을 사용해 모델을 등록할 수 있어요. 기본값은false이에요. -
plugins.ml_commons.allow_registering_model_via_local_file(Dynamic, Boolean):true이면 사용자가 로컬 파일을 사용해 모델을 등록할 수 있어요. 기본값은false이에요. -
plugins.ml_commons.trusted_url_regex(Dynamic, string): 모델이 등록되려면 모델 URL이 일치해야 하는 Java 정규식이에요. 기본값은 HTTP, HTTPS, FTP 또는 로컬 파일 URL 어디서든 모델 파일을 등록할 수 있게 해줘요. 기본값은"^(https?|ftp|file)://[-a-zA-Z0-9+&@#/%?=~_|!:,.;]*[-a-zA-Z0-9+&@#/%=~_|]"이에요.
URL에서 모델을 등록할 때는 소스를 신뢰할 수 있는지 확인하세요. 신뢰할 수 없는 소스에서 모델을 로드하면 보안 위험이 발생할 수 있어요. 자세한 내용은 PyTorch security guidelines for untrusted models를 참고하세요. {: .warning}
plugins.ml_commons.trusted_url_regex의 기본값은 안전하지 않아요. 보안을 위해 모델이 있는 신뢰할 수 있는 저장소만 일치시키는 정규식으로 설정하세요. 예를 들어 https://github.com/opensearch-project/ml-commons/blob/2.x/ml-algorithms/src/test/resources/org/opensearch/ml/engine/algorithms/text_embedding/* 같은 식이에요.
{: .warning }
서킷 브레이커 설정
ML 작업을 실행하기 전에 ML Commons가 메모리와 디스크 사용량을 확인해요. 사용량이 임계값을 초과하면 OpenSearch가 서킷 브레이커를 작동시키고 예외를 던지며 작업을 실행하지 않아요. ML Commons는 다음 서킷 브레이커 설정을 지원해요:
-
plugins.ml_commons.native_memory_threshold(Dynamic, integer): ML 작업이 실행될 수 있는 네이티브 메모리 사용량의 최댓값으로, 전체 시스템 메모리 기준 백분율이에요. 이 서킷 브레이커는 너무 많은 모델이 로드될 때 out-of-memory 오류를 방지해요.0으로 설정하면 ML 작업이 실행되지 않아요.100으로 설정하면 서킷 브레이커가 비활성화돼요. 유효한 값은 0--100이에요. 기본값은90이에요. -
plugins.ml_commons.jvm_heap_memory_threshold(Dynamic, integer): ML 작업이 실행될 수 있는 JVM 힙 메모리 사용량의 최댓값으로, 전체 JVM 힙 기준 백분율이에요.0으로 설정하면 ML 작업이 실행되지 않아요.100으로 설정하면 서킷 브레이커가 비활성화돼요. 유효한 값은 0--100이에요. 기본값은85이에요. -
plugins.ml_commons.disk_free_space_threshold(Dynamic, byte size): ML 작업을 실행하는 데 필요한 최소 여유 디스크 공간이에요. 여유 디스크 공간이 이 값 아래로 떨어지면 서킷 브레이커가 작동해요. 서킷 브레이커를 비활성화하려면 이 값을-1로 설정하세요. 기본값은5gb예요.
모델 배포 설정
ML Commons는 모델을 자동으로 배포하고 재배포하기 위한 다음 설정을 지원해요:
-
plugins.ml_commons.model_auto_deploy.enable(Dynamic, Boolean):true이면 해당 모델에 대한 예측 요청을 받았는데 모델이 아직 배포되지 않은 경우 OpenSearch가 외부 호스팅 모델을 자동으로 배포해요. 기본값은true예요. -
plugins.ml_commons.model_auto_redeploy.enable(Dynamic, Boolean):true이면 클러스터 장애 이후 OpenSearch가 배포되었거나 부분적으로 배포된 모델을 자동으로 재배포해요. 클러스터의 모든 ML 노드가 실패하면 모델이DEPLOY_FAILED상태가 되고 수동으로 배포해야 해요. 기본값은true예요. -
plugins.ml_commons.model_auto_redeploy.lifetime_retry_times(Dynamic, integer): 클러스터의 ML 노드가 실패하거나 새 ML 노드가 클러스터에 합류할 때 OpenSearch가 배포되었거나 부분적으로 배포된 모델의 재배포를 시도하는 최대 횟수예요.0또는 음수로 설정하면 OpenSearch가 모델을 자동으로 재배포하지 않아요. 기본값은3이에요. -
plugins.ml_commons.model_auto_redeploy_success_ratio(Dynamic, float): 자동 재배포가 성공하려면 모델이 재배포되어야 하는 가용 ML 노드의 최소 비율이에요. 예를 들어 비율이0.7이고 모델이 가용 ML 노드의 70%에 재배포되면 재배포가 성공해요. 모델이 가용 ML 노드의 70% 미만에 재배포되면 OpenSearch가 재배포가 성공하거나plugins.ml_commons.model_auto_redeploy.lifetime_retry_times한도에 도달할 때까지 재배포를 재시도해요. 유효한 값은 0--1이에요. 기본값은0.8이에요.
동적 배칭 메모리 설정
노드의 모든 모델은 동적 배칭에 사용할 수 있는 메모리를 공유해요. 이 메모리가 고갈되면 OpenSearch가 새 큐 항목을 거부해요. 거부된 요청은 백오프를 사용해 재시도하거나 워크로드에 맞게 메모리 설정을 조정하세요. ML Commons는 이 메모리의 양을 제어하기 위한 다음 설정을 지원해요:
-
plugins.ml_commons.dynamic_batching.memory.fraction(Dynamic, double): 각 노드에서 동적 배칭에 사용할 수 있는 메모리 양을 계산할 때 사용하는 최대 JVM 힙의 비율이에요. 계산된 값은plugins.ml_commons.dynamic_batching.memory.min과plugins.ml_commons.dynamic_batching.memory.max사이로 제한돼요. 유효한 값은 0.0--0.1이에요. 기본값은0.01이에요. -
plugins.ml_commons.dynamic_batching.memory.min(Dynamic, byte size): 각 노드에서 동적 배칭에 사용할 수 있는 최소 메모리 양이에요. 기본값은64mb예요. -
plugins.ml_commons.dynamic_batching.memory.max(Dynamic, byte size): 각 노드에서 동적 배칭에 사용할 수 있는 최대 메모리 양이에요. 이 값은plugins.ml_commons.dynamic_batching.memory.min보다 크거나 같아야 해요. 기본값은512mb예요.
기능 설정
ML Commons는 기능을 활성화하거나 비활성화하는 데 사용할 수 있는 다음 설정을 지원해요:
-
plugins.ml_commons.remote_inference.enabled(Dynamic, Boolean):false이면 사용자가 커넥터를 만들거나 외부 호스팅 모델을 등록, 배포, 예측 실행할 수 없어요. 기본값은true예요. -
plugins.ml_commons.local_model.enabled(Dynamic, Boolean):false이면 사용자가 로컬 모델을 등록, 배포, 예측 실행할 수 없어요. 기본값은true예요. -
plugins.ml_commons.connector_access_control_enabled(Dynamic, Boolean):true이면 관리자가backend_roles를 사용해 Connector API 접근을 제어할 수 있어요. 기본값은false예요. -
plugins.ml_commons.connector.vertexai_enabled(Dynamic, Boolean):true이면 사용자가google_cloud프로토콜을 사용하는 커넥터를 만들 수 있어요. 자세한 내용은 Google Cloud 인증을 참고하세요. 기본값은false예요. -
plugins.ml_commons.safe_delete_model(Dynamic, Boolean):true이면 OpenSearch가 모델을 삭제하기 전에 다운스트림 의존성을 확인해요. 모델이 에이전트, 서치 파이프라인, 인제스트 파이프라인 또는 기타 다운스트림 작업에서 사용 중이라면 OpenSearch가 오류를 반환하고 모델을 삭제하지 않아요. 기본값은false예요. -
plugins.ml_commons.enable_inhouse_python_model(Dynamic, Boolean):true이면 사용자가 metrics correlation 같은 OpenSearch가 지원하는 Python 기반 모델을 실행할 수 있어요. 기본값은false예요. -
plugins.ml_commons.agent_framework_enabled(Dynamic, Boolean):true이면 에이전트와 도구를 포함한 에이전트 프레임워크가 활성화되고, 사용자가 에이전트를 등록, 실행, 삭제, 조회, 검색할 수 있어요. 기본값은true예요. -
plugins.ml_commons.memory_feature_enabled(Dynamic, Boolean):true이면 대화형 검색을 위해 대화의 모든 메시지를 저장하는 대화형 메모리가 활성화돼요. 기본값은true예요. -
plugins.ml_commons.agentic_memory_enabled(Dynamic, Boolean):true이면 agentic memory가 활성화돼요. 이 기능은 네임스페이스별로 구성된 세션 메모리, 작업 메모리, 장기 메모리, 메모리 히스토리를 포함해 AI 에이전트를 위한 메모리 관리를 제공해요. 기본값은true예요. -
plugins.ml_commons.rag_pipeline_feature_enabled(Dynamic, Boolean):true이면 검색 증강 생성(RAG)을 위한 서치 프로세서가 활성화돼요. RAG는 메모리와 이전 대화에서 관련 정보를 활용해 응답을 생성함으로써 쿼리 결과를 향상시켜요. 기본값은true예요.