Docker 이미지
KeyNet Platform에 학습 모델을 업로드하려면 Docker 이미지를 빌드해야 합니다. 이 문서에서는 학습용 Docker 이미지 작성 방법과 주의사항을 설명합니다.
Dockerfile 기본 구조
학습용 Docker 이미지는 다음과 같은 구조를 가집니다:
# PyTorch 공식 이미지 사용
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"]
베이스 이미지 선택
PyTorch 이미지
PyTorch 공식 이미지는 이미 PyTorch가 설치되어 있어 의존성 관리가 간편합니다:
FROM pytorch/pytorch:2.8.0-cuda12.9-cudnn9-runtime
주요 고려사항:
- PyTorch 버전: keynet-train 은 PyTorch 2.8.0 이하만 지원
- CUDA 버전: GPU 환경에 맞는 CUDA 버전 선택
- 이미지 크기:
-runtime태그가-devel보다 가벼움
자세한 내용은 Docker로 첫 학습 실행을 참고하세요.
작업 디렉토리 설정
⚠️ 중요: /data 경로 금지
Platform은 /data 경로에 데이터셋을 마운트합니다. 절대로 /data를 WORKDIR로 사용하지 마세요:
# ✅ 올바른 예
WORKDIR /app
# ❌ 잘못된 예
WORKDIR /data # Platform 데이터셋 마운트 경로와 충돌!
권장 작업 디렉토리
/app(가장 일반적)/workspace/code
의존성 관리
requirements.txt
Python 패키지 의존성은 requirements.txt에 명시합니다:
keynet-train==0.8.5
ultralytics==8.3.223
opencv-python==4.8.0
캐싱 최적화
Docker 레이어 캐싱을 활용하여 빌드 시간을 단축합니다:
# ✅ 좋은 예: requirements 먼저 복사
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY train.py .
# ❌ 나쁜 예: 모든 파일 한 번에 복사
COPY . .
RUN pip install -r requirements.txt
이유:
train.py가 변경되어도 requirements.txt가 동일하면 의존성 설치 레이어는 캐시에서 재사용됩니다.
PyTorch 의존성
pytorch/pytorch 베이스 이미지를 사용하는 경우, PyTorch는 이미 설치되어 있습니다:
# PyTorch는 베이스 이미지에 포함되어 있으므로 불필요
keynet-train==0.8.5
# 필요한 추가 라이브러리만 명시
numpy
pandas
...
ENTRYPOINT vs CMD
ENTRYPOINT (권장)
학습 스크립트를 ENTRYPOINT로 지정하면 컨테이너가 항상 학습을 실행합니다:
ENTRYPOINT ["python", "train.py"]
Platform에서 hyperparameter를 전달하면 자동으로 인자로 추가됩니다:
# Platform이 실행하는 커맨드
python train.py --batch-size 64 --epochs 10
CMD
디버깅이 필요한 경우 CMD를 사용할 수 있습니다:
CMD ["python", "train.py"]
하지만 대부분의 경우 ENTRYPOINT가 더 명확합니다.
.dockerignore
불필요한 파일을 빌드 context에서 제외하여 빌드 시간과 이미지 크기를 줄입니다:
# Python
__pycache__/
*.pyc
*.pyo
*.pyd
.Python
*.so
*.egg
*.egg-info/
dist/
build/
# Virtual environments
venv/
.venv/
env/
ENV/
# 학습 결과물
*.pth
*.pt
*.onnx
runs/
mlruns/
# Git
.git/
.gitignore
.gitattributes
# IDE
.vscode/
.idea/
*.swp
*.swo
.DS_Store
# 문서
*.md
docs/
# 테스트
tests/
test_*.py
*_test.py
Platform 업로드 방식을 사용하는 경우에만 데이터를 제외하세요:
# 데이터 (Platform에서 /data에 마운트)
data/
dataset/
*.tar.gz
*.zip
이미지 내장 방식을 사용하는 경우 데이터를 .dockerignore에 추가하면 안 됩니다:
# ❌ 데이터를 제외하지 마세요!
# data/ # 주석 처리 또는 삭제
# dataset/ # 주석 처리 또는 삭제
자세한 내용은 데이터셋 사용 방식을 참고하세요.
자세한 내용은 Docker .dockerignore 공식 문서를 참고하세요.
플랫폼 지정
M1/M2 Mac에서 빌드하는 경우 플랫폼을 명시해야 합니다:
docker build --platform linux/amd64 -t my-image .
이유:
KeyNet Platform은 Ubuntu (linux/amd64) 환경에서 실행되므로, ARM 아키텍처(M1/M2)로 빌드하면 실행되지 않습니다.
다음 단계
Dockerfile 작성을 완료했다면:
- 학습 이미지 업로드: CLI 방식 또는 Docker 방식
- MNIST 튜토리얼: 처음부터 끝까지 완전한 예시
- YOLO 튜토리얼: 커스텀 데이터셋 사용 예시