ClearML은 실험 추적 (experiment tracking), 파이프라인 (pipelines), 하이퍼파라미터 최적화 (hyperparameter optimisation), 그리고 모델 서빙 (model serving)을 결합한 오픈 소스 MLOps 플랫폼으로, AWS SageMaker의 셀프 호스팅 (self-hosted) 대안입니다. 이 가이드는 Docker Compose를 사용하여 ClearML 서버를 배포하고, Traefik을 통해 웹 (web), API, 파일 서버 (file servers)를 세 개의 서브도메인 (subdomains)으로 전면에 배치하며, 에이전트 (agent)를 등록하고, 샘플 실험을 실행하고, 파이프라인을 구축하고, HPO 스윕 (HPO sweep)을 실행하며, 서빙 스택 (serving stack)을 배포합니다. 이 과정을 마치면 여러분의 도메인에서 보안이 유지된 상태로 전체 ML 라이프사이클 (ML lifecycle)을 커버하는 ClearML을 갖게 될 것입니다.

전제 조건 (Prerequisite): Docker + Compose가 설치된 Ubuntu 호스트, app.clearml.example.com, api.clearml.example.com, files.clearml.example.com에 대한 DNS A 레코드. GPU 워크로드 (GPU workloads)를 실행할 계획이라면 호스트에 NVIDIA Container Toolkit이 설치되어 있어야 합니다.

호스트 준비 (Prepare the Host)

1. Elasticsearch의 가상 메모리 제한(virtual memory limit) 높이기:

$ echo "vm.max_map_count=524288" | sudo tee /etc/sysctl.d/99-clearml.conf
$ sudo sysctl --system
$ sudo systemctl restart docker

2. 예상되는 소유권(ownership)을 가진 데이터 디렉토리 생성:

$ sudo mkdir -p /opt/clearml/{data/elastic_7,data/mongo_4/db,data/mongo_4/configdb,data/redis,data/fileserver,logs,config}
$ sudo chown -R 1000:1000 /opt/clearml

ClearML 서버 배포 (Deploy the ClearML Server)

1. 프로젝트 디렉토리 생성:

$ mkdir -p ~/clearml && cd ~/clearml

2. 공식 Compose 파일 다운로드:

$ curl -fsSL https://raw.githubusercontent.com/clearml/clearml-server/master/docker/docker-compose.yml -o docker-compose.yml

3. docker-compose.yml 수정:

• apiserver, webserver, fileserver 아래의 ports: 블록을 주석 처리합니다 (Traefik이 이를 게시할 것입니다).
• networks: 섹션을 이름이 지정된 외부 네트워크 (named external networks)로 교체합니다:

networks:
  backend:
    name: clearml_backend
...

4. 공개 호스트네임 (public hostnames)이 포함된 env 파일 생성:

$ nano .env

CLEARML_WEB_HOST=https://app.clearml.example.com
CLEARML_API_HOST=https://api.clearml.example.com
CLEARML_FILES_HOST=https://files.clearml.example.com

5. 스택 시작하기 (Start the stack):

$ docker compose up -d
$ docker compose ps
$ docker compose logs --tail 50

Traefik으로 스택 프론트엔드 구성하기 (Front the Stack with Traefik)

1. Traefik 프로젝트 디렉터리 생성:

$ mkdir -p ~/clearml/traefik && cd ~/clearml/traefik
$ mkdir -p letsencrypt && touch letsencrypt/acme.json && chmod 600 letsencrypt/acme.json

2. .env 파일 생성:

LETSENCRYPT_EMAIL=admin@example.com

3. Traefik Compose 파일 생성:

$ nano docker-compose.yml

services:
  traefik:
    image: traefik:v3.6
...

4. 라우팅 파일 생성:

$ nano dynamic_conf.yml

http:
  routers:
    clearml-web:
...

5. Traefik 시작하기:

$ docker compose up -d
$ docker logs traefik 2>&1 | grep -i certificate

관리자 및 API 자격 증명 생성 (Create an Admin and API Credentials)

1. https://app.clearml.example.com에 접속하여 관리자(이름 + 회사)를 등록합니다.
2. Settings → Workspace → Create new credentials로 이동합니다.
3. 생성된 블록을 복사하여 에이전트 및 SDK 설정에 붙여넣습니다:

api {
  web_server: https://app.clearml.example.com
  api_server: https://api.clearml.example.com
...

ClearML 에이전트 등록하기 (Register a ClearML Agent)

$ mkdir -p ~/clearml-agent && cd ~/clearml-agent
$ sudo apt install python3.12-venv -y
$ python3 -m venv clearml_venv
...

프롬프트가 나타나면 자격 증명 블록을 붙여넣습니다. 그런 다음 에이전트를 시작합니다:

$ clearml-agent daemon --queue default --detached

GPU 호스트의 경우:

$ clearml-agent daemon --gpus 0,1 --queue default --detached

Web UI → Workers & Queues → Workers에서 확인합니다.

샘플 실험 실행하기 (Run a Sample Experiment)

1. 동일한 venv에 SDK 설치:

$ pip install clearml scikit-learn joblib pandas
$ clearml-init

2. 실험 저장:

$ nano 01_first_experiment.py

import joblib
from clearml import Task
from sklearn.datasets import load_iris
...

3. 실행:

$ python3 01_first_experiment.py

이제 Web UI의 ClearML Tutorial 프로젝트에 실행 메타데이터 (execution metadata), 하이퍼파라미터 (hyperparameters), 스칼라 (scalars), 그리고 업로드된 아티팩트 (artifact)가 표시됩니다.

파이프라인 구축하기 (Build a Pipeline)

$ nano 02_pipeline.py

from clearml import PipelineController

def step_one(pickle_data_url):
...

$ python3 02_pipeline.py

하이퍼파라미터 스윕 실행하기 (Run a Hyperparameter Sweep)

$ nano 03_hpo.py

from clearml import Task
from clearml.automation import (
    HyperParameterOptimizer, UniformIntegerParameterRange,
...

$ python3 03_hpo.py

ClearML Serving으로 모델 배포하기 (Deploy a Model with ClearML Serving)

$ cd ~/clearml
$ git clone https://github.com/clearml/clearml-serving.git
$ pip install clearml-serving
...

clearml-serving/docker/.env 파일에 자격 증명 (credentials)을 설정합니다:

CLEARML_WEB_HOST="https://app.clearml.example.com"
CLEARML_API_HOST="https://api.clearml.example.com"
CLEARML_FILES_HOST="https://files.clearml.example.com"
...

서빙 스택 (serving stack)을 시작합니다:

$ cd ~/clearml/clearml-serving/docker
$ docker compose --env-file .env -f docker-compose-triton.yml up -d

샘플 모델을 학습 및 등록한 후, 엔드포인트 (endpoint)를 추가합니다:

$ pip install -r ~/clearml/clearml-serving/examples/pytorch/requirements.txt
$ python3 ~/clearml/clearml-serving/examples/pytorch/train_pytorch_mnist.py

...

추론 (inference) 테스트:

$ curl -X POST "http://SERVER_IP:8080/serve/test_model_pytorch" \
    -H "Content-Type: application/json" \
    -d '{"url": "https://raw.githubusercontent.com/clearml/clearml-serving/main/examples/pytorch/5.jpg"}'

다음 단계 (Next Steps)

ClearML이 트래킹 (tracking), 에이전트 (agents), 파이프라인 (pipelines), HPO, 그리고 서빙 (serving)과 함께 실행되고 있습니다. 여기서 다음과 같은 작업을 수행할 수 있습니다:

• GPU 호스트에 더 많은 에이전트를 추가하고 전용 큐 (dedicated queues)에 할당하기
• 장기 보관을 위해 트래킹 데이터를 S3 호환 스토리지로 미러링하기
• 모든 학습 실행을 자동으로 기록하도록 ClearML을 CI에 연결하기

추가적인 팁이 포함된 전체 가이드를 확인하려면 **Vultr Docs**의 원문 기사를 방문하세요.