Ubuntu에서 AWS SageMaker의 대안으로 ClearML 배포하기

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)

https://app.clearml.example.com에 접속하여 관리자(이름 + 회사)를 등록합니다.
Settings → Workspace → Create new credentials로 이동합니다.
생성된 블록을 복사하여 에이전트 및 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**의 원문 기사를 방문하세요.

Insights