본문으로 건너뛰기

학습 이미지 업로드: Docker 방식

Dockerfile을 직접 작성하고 Docker 명령어로 이미지를 빌드하여 Harbor registry에 업로드하는 과정을 안내합니다.

더 간단한 방법

Dockerfile 작성 없이 빠르게 시작하고 싶으시다면 학습 이미지 업로드: CLI 방식을 사용하세요. CLI가 Dockerfile 자동 생성부터 빌드, 업로드까지 모두 처리합니다.

이 페이지는 Dockerfile을 직접 작성하여 Docker 이미지를 완전히 제어하고 싶은 고급 사용자를 위한 가이드입니다.

사전 요구사항​

  • Docker가 설치되어 있어야 합니다
  • Harbor 계정이 있어야 합니다 (관리자에게 요청)
  • KeyNet Platform에서 프로젝트가 생성되어 있어야 합니다
  • Dockerfile이 준비되어 있어야 합니다

0. Dockerfile 작성​

먼저 학습용 Dockerfile을 작성해야 합니다.

기본 예시​

FROM pytorch/pytorch:2.8.0-cuda12.9-cudnn9-runtime

WORKDIR /app

# requirements 복사 및 설치
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 학습 코드 복사
COPY train.py .

# 컨테이너 실행 시 학습 시작
ENTRYPOINT ["python", "train.py"]

자세한 가이드​

Dockerfile 작성 방법, 베이스 이미지 선택, 의존성 관리, 레이어 캐싱 등에 대한 자세한 내용은 Docker 이미지 가이드를 참고하세요.

1. Harbor 로그인​

Docker 이미지를 push하기 위해 Harbor에 로그인합니다.

docker login harbor.aiplatform.re.kr

인증 정보 입력:

Username: <관리자에게 발급받은 계정>
Password: <관리자에게 발급받은 비밀번호>

로그인 성공​

Login Succeeded

Harbor 도메인​

Harbor 도메인

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

2. Repository Key 발급​

Platform의 모델 생성 화면에서 Harbor push용 repository 주소를 확인합니다.

Repository Key

발급 예시:

harbor.aiplatform.re.kr/kitech-model/orabz434x6oynnq2ls0y6:latest
중요

이 repository 주소는 모델마다 고유하게 생성됩니다. 반드시 이 주소로 이미지를 빌드하고 push해야 합니다.

Repository 주소 구조​

harbor.aiplatform.re.kr/kitech-model/orabz434x6oynnq2ls0y6:latest
                          └─────┬────┘ └─────────┬─────────┘ └─┬─┘
                             Project         Repository        Tag
  • Project: Platform 프로젝트 (고정: kitech-model)
  • Repository: 모델마다 고유한 식별자
  • Tag: 이미지 버전 (일반적으로 latest)

3. 이미지 빌드​

발급받은 repository 주소로 이미지를 빌드합니다.

기본 빌드​

# Platform에서 발급받은 repository로 빌드
docker build -t harbor.aiplatform.re.kr/kitech-model/orabz434x6oynnq2ls0y6:latest .

플랫폼 지정 (M1/M2 Mac)​

M1/M2 Mac에서 빌드하는 경우 반드시 플랫폼을 지정해야 합니다:

docker build --platform linux/amd64 -t harbor.aiplatform.re.kr/kitech-model/orabz434x6oynnq2ls0y6:latest .
M1/M2 Mac 사용자

Platform은 Ubuntu (linux/amd64) 환경에서 실행됩니다. --platform linux/amd64 옵션을 빠뜨리면 이미지가 Platform에서 실행되지 않습니다.

빌드 옵션 설명​

docker build [옵션] <컨텍스트>

필수 인자:

인자설명
컨텍스트빌드에 사용할 파일들이 있는 디렉토리 (.은 현재 디렉토리)

주요 옵션:

옵션설명
-t, --tag이미지 이름과 태그 (필수)
--platform대상 플랫폼 지정 (M1/M2 Mac에서 필수)
-f, --fileDockerfile 경로 (기본: ./Dockerfile)
빌드 컨텍스트

빌드 컨텍스트(.)는 Docker가 이미지 빌드 시 접근할 수 있는 파일 범위를 결정합니다. .dockerignore 파일로 불필요한 파일을 제외할 수 있습니다.

빌드 확인​

빌드가 완료되면 이미지 목록에서 확인합니다:

docker images | grep orabz434x6oynnq2ls0y6

출력 예시:

REPOSITORY                                                       TAG       IMAGE ID       CREATED         SIZE
harbor.aiplatform.re.kr/kitech-model/orabz434x6oynnq2ls0y6    latest    ac7910fd9ab7   5 minutes ago   8.5GB

빌드 시간 단축​

빌드 시간을 단축하려면:

  1. .dockerignore 사용: 불필요한 파일 제외 (Docker 이미지 가이드 참고)
  2. 레이어 캐싱: requirements.txt를 먼저 복사하여 캐싱 활용
  3. 멀티스테이지 빌드: 빌드 도구와 런타임 분리

4. 이미지 Push​

빌드한 이미지를 Harbor에 업로드합니다:

docker push harbor.aiplatform.re.kr/kitech-model/orabz434x6oynnq2ls0y6:latest

Push 진행 상황​

The push refers to repository [harbor.aiplatform.re.kr/kitech-model/orabz434x6oynnq2ls0y6]
9e7b3cd4ea34: Pushed
7021d1b70935: Pushed
24ac5c944261: Pushed
0e736609e8e5: Pushed
84e69331e841: Pushed
0660c5415297: Pushed
4f4fb700ef54: Mounted from kitech-model/z9pqrfnilwvl5qclmj3yj
a84b49fe85c9: Pushed
f5ea56cf41c2: Pushed
c875434ab033: Pushed
latest: digest: sha256:32e07433676014d7ee963463c6044243d79114ad45771dcc754a325d34d7caca size: 856

Push 완료​

Push가 성공하면 Platform에서 자동으로 이미지를 감지합니다.

업로드된 모델 확인

자동 감지

Platform은 Harbor를 주기적으로 모니터링하여 새로운 이미지를 자동으로 감지합니다. 몇 초에서 최대 1분 정도 소요될 수 있습니다.

로컬 테스트 (선택사항)​

Platform에 push하기 전에 로컬에서 이미지를 테스트할 수 있습니다.

사전 요구사항

로컬 테스트를 위해서는 로컬 실험 환경이 구성되어 있어야 합니다. 특히 MLflow 연동 테스트를 하려면 MLflow 서버가 실행 중이어야 합니다.

기본 실행​

docker run --rm harbor.aiplatform.re.kr/kitech-model/orabz434x6oynnq2ls0y6:latest

GPU 사용​

docker run --rm --gpus all harbor.aiplatform.re.kr/kitech-model/orabz434x6oynnq2ls0y6:latest

Hyperparameter 전달​

docker run --rm harbor.aiplatform.re.kr/kitech-model/orabz434x6oynnq2ls0y6:latest --batch-size 32 --epochs 10

MLflow 연동 테스트​

로컬 MLflow 서버와 연동하여 테스트합니다.

MLflow 서버 실행 확인:

# MLflow 서버가 실행 중인지 확인
curl http://localhost:5000/health

Docker 컨테이너에서 MLflow 접근:

# --network host로 로컬 MLflow 서버에 접근
docker run --rm --network host harbor.aiplatform.re.kr/kitech-model/orabz434x6oynnq2ls0y6:latest

문제 해결​

Harbor 로그인 실패​

증상:

Error response from daemon: Get "https://harbor.aiplatform.re.kr/v2/": unauthorized

해결:

  1. Harbor 도메인 확인
  2. 계정 및 비밀번호 재확인
  3. 관리자에게 계정 활성화 상태 확인

Push 권한 오류​

증상:

denied: requested access to the resource is denied

해결:

  1. Harbor 로그인 상태 확인:

    docker login harbor.aiplatform.re.kr

  2. 계정에 push 권한이 있는지 관리자에게 확인

  3. Repository 주소가 Platform에서 발급받은 것과 정확히 일치하는지 확인

Platform 실행 오류​

증상:

exec /usr/bin/python: exec format error

원인:

M1/M2 Mac에서 --platform linux/amd64 옵션 없이 빌드한 경우

해결:

# 올바르게 다시 빌드
docker build --platform linux/amd64 -t harbor.aiplatform.re.kr/kitech-model/orabz434x6oynnq2ls0y6:latest .

# 다시 Push
docker push harbor.aiplatform.re.kr/kitech-model/orabz434x6oynnq2ls0y6:latest

대안: CLI로 빌드 (고급)​

Dockerfile은 직접 작성하되 빌드와 push는 CLI로 자동화할 수도 있습니다:

# keynet-train CLI 사용 (0.8.5 권장, 0.7.4 이상 호환)
keynet login https://gateway.aiplatform.re.kr
keynet-train push train.py --dockerfile ./Dockerfile

이 방법의 장점:

  • Dockerfile 작성: 직접 제어 (멀티스테이지 빌드, 레이어 최적화 등)
  • Harbor 로그인, 빌드, push: CLI가 자동 처리
  • Repository key 발급: CLI가 자동 처리

다음 단계​

이미지 push가 완료되었다면:

  1. Hyperparameter 설정: Platform에서 hyperparameter 등록
  2. MNIST 튜토리얼: 전체 워크플로우 예시
  3. YOLO 튜토리얼: 커스텀 데이터셋 사용 예시