Google Vertex AI는 실험 추적(experiment tracking), 학습 작업(training jobs), 파이프라인(pipelines), 모델 레지스트리(model registry) 및 엔드포인트(endpoints)를 갖춘 Google Cloud의 관리형 ML 플랫폼이지만, GCP 전용 API와 사용량 기반 과금 방식에 종속된다는 단점이 있습니다. ClearML은 모든 Docker 호스트 또는 Kubernetes 클러스터에서 동일한 기능을 수행하는 오픈 소스 MLOps 플랫폼으로, 코드 변경 없이 학습 메트릭(training metrics)을 자동으로 캡처하며 모든 데이터를 사용자가 제어하는 인프라에 보관합니다. 이 가이드는 Docker Compose와 Traefik을 사용하여 ClearML Server를 배포하고, 에이전트(agent)를 등록하며, 실험을 실행하고, 파이프라인을 구축하고, 하이퍼파라미터 스윕(hyperparameter sweep)을 수행하며, Triton으로 서빙되는 모델을 배포하는 과정을 다룹니다. 이 과정을 마치면 전체 ML 라이프사이클(ML lifecycle)을 아우르는 셀프 호스팅 방식의 Vertex AI 대체제를 갖게 될 것입니다.

Vertex AI → ClearML 매핑

GCP Vertex AI	ClearML 대응 기능	목적
Vertex AI Workbench	ClearML Web UI	브라우저 기반 모니터링 및 구성
...

전제 조건: Docker + Compose가 설치된 Ubuntu 호스트, app.clearml.example.com, api.clearml.example.com, files.clearml.example.com에 대한 DNS A 레코드. GPU 에이전트를 실행할 경우 NVIDIA Container Toolkit 필요.

ClearML Server 배포

1. Elasticsearch의 가상 메모리 제한을 높이고 Docker를 재시작합니다:

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

2. 올바른 소유권을 가진 영구 데이터 디렉토리를 생성합니다:

$ 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

3. 공식 Compose 파일을 다운로드합니다:

$ mkdir -p ~/clearml && cd ~/clearml
$ curl -fsSL https://raw.githubusercontent.com/clearml/clearml-server/master/docker/docker-compose.yml -o docker-compose.yml

4. 수정하기: apiserver, webserver, fileserver 아래의 ports: 블록을 주석 처리하고 (Traefik이 외부 라우팅을 처리할 것입니다), networks: 섹션을 이름이 지정된 브리지(named bridges)로 교체합니다:

networks:
  backend:
    name: clearml_backend
...

5. 퍼블릭 호스트네임(public hostnames) 설정:

$ 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

6. 스택 시작:

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

Traefik을 사용하여 스택 전면에 배치하기

1. Traefik 디렉토리 및 인증서 저장소 생성:

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

2. ACME 이메일 설정:

$ nano .env

LETSENCRYPT_EMAIL=admin@example.com

3. Traefik Compose 파일 생성:

$ nano docker-compose.yml

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

4. 각 서브도메인을 해당 ClearML 서비스로 라우팅:

$ nano dynamic_conf.yml

http:
  routers:
    clearml-web:
...

5. Traefik을 시작하고 인증서 발급 확인:

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

관리자 계정 및 API 자격 증명(Credentials) 생성

1. https://app.clearml.example.com을 열고, 사용자 이름과 회사 이름을 입력한 후 Create Account를 클릭합니다.
2. Settings → Workspace → Create new credentials로 이동합니다.
3. 생성된 블록을 복사합니다 — 에이전트(agent)와 SDK에서 사용해야 합니다:

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

ClearML 에이전트 등록

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

요청 시 인증 정보(credentials) 블록을 붙여넣으세요. 나머지는 기본값을 수락하려면 Enter를 누르면 됩니다. 그런 다음 데몬(daemon)을 시작합니다:

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

GPU 워크로드(workloads)의 경우:

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

Workers & Queues → Workers에서 등록을 확인합니다.

SDK 설치 및 첫 번째 실험 실행

$ source ~/clearml-agent/clearml_venv/bin/activate
$ pip install clearml scikit-learn joblib pandas
$ clearml-init

요청 시 인증 정보(credentials) 블록을 다시 붙여넣으세요.

$ mkdir -p ~/clearml/experiments && cd ~/clearml/experiments
$ nano 01_first_experiment.py

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

$ python3 01_first_experiment.py

출력 결과에 태스크(task) URL이 표시됩니다. 해당 URL을 열면 ClearML Tutorial 프로젝트 아래에서 실행 세부 정보, 하이퍼파라미터 (hyperparameters), 아티팩트 (artifacts), 콘솔 출력 및 스칼라 차트 (scalar charts)를 확인할 수 있습니다.

파이프라인 (Pipeline) 구축

$ nano 02_pipeline.py

from clearml import PipelineController

def step_one(pickle_data_url):
...

$ python3 02_pipeline.py

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

$ nano 03_hpo.py

from clearml import Task
from clearml.automation import HyperParameterOptimizer, DiscreteParameterRange, UniformIntegerParameterRange, RandomSearch

...

$ python3 03_hpo.py

Web UI의 ClearML Tutorial에서 진행 상황을 모니터링합니다.

ClearML Serving으로 모델 배포하기

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

서빙(serving)용 .env 파일을 설정합니다:

$ nano clearml-serving/docker/.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"
...

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

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

샘플 모델 학습 및 등록:

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

작업의 Artifacts 탭에서 모델 ID를 복사한 후, 엔드포인트를 추가합니다:

$ clearml-serving --id SERVING_SERVICE_ID model add \
    --engine triton \
    --endpoint "test_model_pytorch" \
...

추론 테스트:

$ 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"}'

모든 것 확인하기

$ curl -s https://api.clearml.example.com/debug.ping | head -c 100
$ curl -s -o /dev/null -w "%{http_code}" https://files.clearml.example.com/

웹 UI에서 에이전트가 Workers & Queues 아래에 표시되는지, 첫 번째 실험에 메트릭/아티팩트가 있는지, 그리고 실험을 복제(cloning)하고 재대기열화(re-enqueuing)했을 때 에이전트에 의해 처리되는지 확인합니다.

Vertex AI에서 마이그레이션하기

Vertex AI 개념	ClearML 대체 기능
google.cloud.aiplatform 실험 추적	clearml.Task — Git 상태, 종속성(deps), 커밋되지 않은 변경 사항 자동 캡처
...

다음 단계

ClearML은 트래킹, 에이전트, 파이프라인, HPO (Hyperparameter Optimization), 그리고 Triton 서빙과 함께 실행됩니다. 여기서부터는 다음 작업을 수행할 수 있습니다:

• GPU 에이전트를 추가하고 하드웨어 프로필별 전용 대기열(dedicated queues) 설정하기
• ClearML Data의 명시적 버전 관리 기능을 사용하여 GCS 기반 데이터셋 마이그레이션하기
• CI에 ClearML을 연결하여 모든 학습 실행이 자동으로 추적되도록 하기

추가 팁이 포함된 전체 가이드는 **Vultr Docs**의 원본 기사를 방문하세요.