템플릿 이미지 업로드

관리자가 학습에 사용할 베이스 이미지(template image)를 직접 빌드하여 업로드하는 방법을 안내합니다.

관리자 전용

이 기능은 플랫폼 관리자만 사용할 수 있습니다. 일반 사용자가 학습용 이미지를 업로드하려면 학습 이미지 업로드: CLI 방식 또는 학습 이미지 업로드: Docker 방식을 사용하세요.

개요

템플릿 이미지는 사용자들이 학습 시 선택할 수 있는 베이스 이미지입니다. 관리자는 다양한 환경(PyTorch, TensorFlow, CUDA 버전 등)의 템플릿 이미지를 미리 준비하여 제공할 수 있습니다.

템플릿 이미지 워크플로우:

1. 관리자가 베이스 이미지를 빌드
2. Harbor의 템플릿 이미지 저장소에 push
3. Platform이 webhook으로 이미지 등록 감지
4. DB에 자동 등록
5. 사용자가 학습 시 사용 가능한 템플릿 확인 가능

자동 감지

템플릿 이미지를 Harbor에 push하면 Platform이 webhook을 통해 자동으로 감지하여 DB에 등록합니다. 별도의 등록 작업은 필요하지 않습니다.

사전 요구사항

• Docker가 설치되어 있어야 합니다
• 템플릿 이미지 저장소 push 권한이 있는 Harbor 계정 (관리자에게 문의)
• Platform 관리자 권한

템플릿 이미지란?

템플릿 이미지는 사용자가 학습 코드를 작성할 때 베이스로 사용할 수 있는 사전 구성된 Docker 이미지입니다.

일반적인 템플릿 이미지 예시:

• pytorch/pytorch:2.3.0-cuda12.1-cudnn8-runtime
• tensorflow/tensorflow:2.15.0-gpu
• nvcr.io/nvidia/pytorch:24.01-py3

템플릿 이미지에 포함되는 것:

• Base OS (Ubuntu, Alpine 등)
• Python 및 필수 라이브러리
• ML 프레임워크 (PyTorch, TensorFlow 등)
• CUDA, cuDNN (GPU 사용 시)
• 공통 의존성 패키지

사용자 학습 이미지와의 차이:

구분	템플릿 이미지	학습 이미지
제공자	관리자	사용자
목적	베이스 환경 제공	학습 코드 실행
포함 내용	프레임워크, 공통 라이브러리	사용자 코드, 커스텀 의존성
저장소	템플릿 이미지 저장소	사용자별 저장소

1. Harbor 로그인

템플릿 이미지 저장소에 push하기 위해 Harbor에 로그인합니다.

docker login harbor.aiplatform.re.kr

인증 정보 입력:

Username: <관리자 계정>
Password: <관리자 비밀번호>

로그인 성공

Login Succeeded

Harbor 도메인

현재 Harbor 도메인은 harbor.aiplatform.re.kr입니다. 이 도메인은 변경될 수 있으므로, 최신 도메인은 관리자에게 확인하세요.

2. 베이스 이미지 준비

템플릿으로 제공할 베이스 이미지를 준비합니다. 두 가지 방법이 있습니다:

방법 1: 기존 이미지 사용

공식 이미지를 그대로 사용하거나 태그만 변경하여 사용합니다.

# 공식 PyTorch 이미지 pull
docker pull pytorch/pytorch:2.3.0-cuda12.1-cudnn8-runtime

# 템플릿 저장소 태그로 변경
docker tag pytorch/pytorch:2.3.0-cuda12.1-cudnn8-runtime \
  harbor.aiplatform.re.kr/kitech-base-image/pytorch-2.3.0-cuda12.1:20250112

방법 2: 커스텀 이미지 빌드

공통 의존성을 추가한 커스텀 이미지를 빌드합니다.

Dockerfile 예시:

Dockerfile.pytorch-template

FROM pytorch/pytorch:2.3.0-cuda12.1-cudnn8-runtime

WORKDIR /workspace

# 공통 의존성 설치
RUN pip install --no-cache-dir \
    numpy==1.26.4 \
    pandas==2.0.3 \
    scikit-learn==1.3.0 \
    matplotlib==3.7.2 \
    seaborn==0.12.2 \
    mlflow==2.9.2

# 한국 시간대 설정
ENV TZ=Asia/Seoul
RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone

빌드:

docker build -f Dockerfile.pytorch-template \
  -t harbor.aiplatform.re.kr/kitech-base-image/pytorch-2.3.0-cuda12.1-kitech:20250112 .

네이밍 규칙

템플릿 이미지 이름은 중복을 피하고 버전을 명확히 구분할 수 있도록 작성하는 것이 좋습니다.

권장 형식:

Repository 이름: <framework>-<version>[-<suffix>]

• pytorch-2.3.0-cuda12.1: 기본 PyTorch 이미지
• tensorflow-2.15.0-gpu-kitech: 조직명 suffix 추가
• vision-base-1.0: 특정 용도의 베이스 이미지

Tag: 빌드 날짜나 버전 번호 사용

• 20250112: 빌드 날짜 (YYYYMMDD)
• v1, v2: 시맨틱 버전
• latest: 가장 최신 버전 (권장하지 않음)

피해야 할 패턴:

• 너무 일반적인 이름: pytorch, base, ml-image
• 버전 정보 누락: pytorch-cuda (어떤 버전인지 불명확)
• Tag 없이 latest만 사용 (버전 추적 어려움)

3. 템플릿 저장소 구조

템플릿 이미지는 특정 project와 repository 구조를 따라야 합니다.

harbor.aiplatform.re.kr/kitech-base-image/<repository-name>:<tag>
                          └───────┬────────┘ └──────┬───────┘ └┬┘
                                Project         Repository    Tag

예시:

# PyTorch 템플릿
harbor.aiplatform.re.kr/kitech-base-image/pytorch-2.3.0-cuda12.1:20250112

# TensorFlow 템플릿
harbor.aiplatform.re.kr/kitech-base-image/tensorflow-2.15.0-gpu-kitech:20250112

# 커스텀 템플릿
harbor.aiplatform.re.kr/kitech-base-image/vision-training-base:v1

저장소 구조 준수

템플릿 이미지는 반드시 kitech-base-image project에 push해야 합니다. 다른 project에 push하면 Platform이 템플릿으로 인식하지 못합니다.

4. 이미지 Push

준비한 이미지를 템플릿 저장소에 push합니다.

docker push harbor.aiplatform.re.kr/kitech-base-image/pytorch-2.3.0-cuda12.1:20250112

Push 진행 상황

The push refers to repository [harbor.aiplatform.re.kr/kitech-base-image/pytorch-2.3.0-cuda12.1]
7e91ab813e95: Pushed
8d3ac3489996: Pushed
f1417ff83b31: Pushed
0e736609e8e5: Pushed
84e69331e841: Pushed
20250112: digest: sha256:abc123... size: 3245

M1/M2 Mac에서 빌드하는 경우

Ubuntu 환경에서 실행되도록 플랫폼을 지정해야 합니다:

# 플랫폼 지정하여 빌드
docker build --platform linux/amd64 \
  -t harbor.aiplatform.re.kr/kitech-base-image/pytorch-2.3.0-cuda12.1:20250112 .

# Push
docker push harbor.aiplatform.re.kr/kitech-base-image/pytorch-2.3.0-cuda12.1:20250112

5. Platform에서 확인

Push가 완료되면 Platform이 webhook을 통해 자동으로 감지합니다.

자동 등록 확인

등록 시간

Webhook 처리 시간으로 인해 몇 초에서 최대 1분 정도 소요될 수 있습니다. 이미지가 즉시 표시되지 않으면 잠시 기다린 후 새로고침하세요.

메타데이터 수정

Webhook으로 자동 등록된 템플릿 이미지는 기본 정보만 포함되어 있습니다. 관리자는 사용자가 이해하기 쉽도록 설명과 메타데이터를 추가할 수 있습니다.

사용자에게 제공

등록된 템플릿 이미지는 사용자가 학습 코드 작성 시 베이스 이미지로 선택할 수 있습니다.

사용자 코드 예시:

from keynet_train import trace_pytorch

@trace_pytorch(
    model_name="my-model",
    sample_input=torch.randn(1, 3, 224, 224),
    base_image="harbor.aiplatform.re.kr/kitech-base-image/pytorch-2.3.0-cuda12.1:20250112"
)
def train_model():
    # 훈련 코드...
    return model

다음 단계

템플릿 이미지를 업로드했다면:

1. 사용자 가이드 업데이트: 사용 가능한 템플릿 이미지 목록을 문서화
2. 학습 이미지 업로드: CLI 방식: 사용자가 템플릿을 활용하는 방법
3. 버전 관리: 템플릿 이미지 버전 업데이트 정책 수립