Learn AI with Python · 강의

Docker로 머신러닝 모델 컨테이너화하기

다단계 Dockerfile, CUDA 기본 이미지, 모델 아티팩트 COPY, 상태 확인 엔드포인트를 다룹니다.

Docker로 머신러닝 모델 컨테이너화하기은(는) CoddyKit의 무료 Learn AI with Python 강의입니다. 이것은 4개 중 1번째 강의입니다. 아래에서 전체 강의를 무료로 읽을 수 있으며, 내장 코드 에디터와 24/7 AI 튜터와 함께 브라우저에서 직접 실습할 수 있습니다. 이 강의는 Learn AI with Python 학습 경로의 일부이며, 진행 상황이 웹과 CoddyKit 앱에 동기화됩니다. Learn AI with Python 강의에는 총 4개의 강의가 포함되어 있습니다.

머신러닝 모델을 컨테이너화하는 이유

머신러닝 모델은 특정 Python 버전, 시스템 라이브러리, 고정된 패키지 버전에 의존합니다. Docker는 이 모든 것을 하나의 변경 불가능한 이미지로 묶어 모델이 노트북, CI 실행기, 운영 클러스터에서 동일하게 실행되도록 합니다.

머신러닝에서 가장 큰 문제는 의존성 버전이 어긋나는 것입니다. numpy 1.24를 기준으로 학습한 모델이 numpy 2.0에서 아무런 표시 없이 잘못 작동할 수 있습니다. 컨테이너는 이러한 버전을 고정합니다.

단순한 단일 단계 이미지

첫 번째 시도에서는 모든 것을 하나의 단계에 설치합니다. 작동하기는 하지만 컴파일러, 캐시, 개발 헤더와 같은 빌드 도구가 최종 이미지에 포함되어 이미지가 커지고 공격 표면도 넓어집니다.

FROM python:3.11
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["python", "serve.py"]

다단계 빌드의 개념

다단계 빌드는 한 단계에서 의존성을 컴파일하고 설치한 다음(이 단계를 빌더라고 합니다), 완성된 산출물만 깨끗한 최종 단계로 복사합니다. 빌드에만 필요한 도구는 운영 환경에 도달하지 않습니다.

빌더 단계: 전체 기반 이미지에서 pip install 실행
최종 단계: 경량 기반 이미지에 설치된 패키지 복사

빌더 단계: pip install

빌더는 패키지를 알려진 접두 경로에 설치하므로 쉽게 복사해 올 수 있습니다. --user를 사용하면 패키지가 /root/.local 아래에 저장되므로 나중에 하나의 디렉터리만 가져오면 됩니다.

FROM python:3.11 AS builder
WORKDIR /app
COPY requirements.txt .
RUN pip install --user --no-cache-dir -r requirements.txt

최종 경량 단계

최종 단계는 python:3.11-slim에서 시작하고 빌더에서 설치된 패키지를 복사합니다. 경량 이미지에는 빌드 도구 모음이 포함되지 않으므로 이미지 크기를 수백 메가바이트 줄일 수 있습니다.

FROM python:3.11-slim
WORKDIR /app
COPY --from=builder /root/.local /root/.local
ENV PATH=/root/.local/bin:$PATH
COPY . .

모델 가중치 복사

대형 모델 가중치는 도커가 캐시할 수 있도록 별도 계층으로 복사해야 합니다. 코드만 변경하면 가중치 계층을 재사용하므로 다시 빌드하는 작업이 빠릅니다.

COPY model/ /app/model/
COPY src/ /app/src/

EXPOSE로 제공 포트 노출

추론 서버(FastAPI, 트라이톤, TorchServe)는 포트에서 요청을 수신합니다. EXPOSE 8000은 컨테이너가 8000 포트에서 서비스를 제공한다는 사실을 문서화합니다. 이 명령만으로 포트가 게시되는 것은 아니므로 실행할 때 -p 8000:8000으로 포트를 매핑해야 합니다.

EXPOSE 8000
CMD ["uvicorn", "src.serve:app", "--host", "0.0.0.0", "--port", "8000"]

HEALTHCHECK 기초

오케스트레이터는 모델 서버가 실행 중인지 확인해야 합니다. HEALTHCHECK 명령은 일정한 간격으로 명령을 실행합니다. 0이 아닌 종료 코드는 컨테이너를 비정상 상태로 표시하므로 컨테이너를 다시 시작하거나 부하 분산기에서 제외할 수 있습니다.

curl을 사용한 HEALTHCHECK

일반적인 패턴은 가벼운 /health 엔드포인트에 요청을 보내는 것입니다. curl -f는 HTTP 오류가 발생하면 모두 실패하고 0이 아닌 종료 코드를 반환하며, 이는 HEALTHCHECK가 요구하는 동작입니다.

HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
  CMD curl -f http://localhost:8000/health || exit 1

최소 상태 확인 엔드포인트

제공 애플리케이션은 전체 추론을 실행하지 않고도 모델이 로드되었는지 확인하는 빠른 엔드포인트를 노출해야 합니다.

from fastapi import FastAPI

app = FastAPI()
model = None  # loaded at startup

@app.get("/health")
def health():
    return {"status": "ok", "model_loaded": model is not None}

완성된 도커 파일

이제 모든 내용을 하나로 합치겠습니다. 빌드 단계에서 종속 항목을 설치하고, 최종 경량 단계에서 종속 항목과 모델을 복사한 다음 8000 포트를 노출하고 상태 확인을 선언합니다.

FROM python:3.11 AS builder
WORKDIR /app
COPY requirements.txt .
RUN pip install --user --no-cache-dir -r requirements.txt

FROM python:3.11-slim
WORKDIR /app
COPY --from=builder /root/.local /root/.local
ENV PATH=/root/.local/bin:$PATH
COPY model/ /app/model/
COPY src/ /app/src/
EXPOSE 8000
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD curl -f http://localhost:8000/health || exit 1
CMD ["uvicorn", "src.serve:app", "--host", "0.0.0.0", "--port", "8000"]

간단한 확인

다단계 빌드에 대한 이해도를 확인해 보세요.

복습

프로덕션 수준의 도커 파일로 머신러닝 모델을 컨테이너화하는 방법을 배웠습니다:

다단계 빌드: 빌드 단계에서 종속 항목을 설치하고 최종 경량 단계에서 복사합니다
EXPOSE 8000은 제공 포트를 문서화합니다
HEALTHCHECK CMD curl을 사용하면 오케스트레이터가 중단된 컨테이너를 감지할 수 있습니다
가중치를 별도의 캐시 가능한 계층으로 복사합니다

다음에는 컨테이너화한 모델을 관리형 클라우드 서비스에 배포합니다.

자주 묻는 질문

“Docker로 머신러닝 모델 컨테이너화하기” 강의는 무료인가요?

네 — “Docker로 머신러닝 모델 컨테이너화하기” 전체 내용을 이 웹사이트에서 무료로 읽을 수 있습니다. 인터랙티브하게 실습하려면(내장 코드 에디터와 24/7 AI 튜터), CoddyKit PRO로 업그레이드하면 Learn AI with Python 강의 전체를 잠금 해제할 수 있습니다. Learn AI with Python 강의에는 총 4개의 강의가 포함되어 있습니다.

“Docker로 머신러닝 모델 컨테이너화하기”에서 뭘 배우나요?

다단계 Dockerfile, CUDA 기본 이미지, 모델 아티팩트 COPY, 상태 확인 엔드포인트를 다룹니다. 브라우저에서 직접 실행하는 실습 코드로 Learn AI with Python을(를) 배우며, 24/7 AI 튜터가 강의를 진행하면서 질문에 답변해줍니다.

Learn AI with Python을(를) 시작하는 데 경험이 필요한가요?

사전 경험은 필요하지 않습니다. CoddyKit의 Learn AI with Python은(는) 초급자부터 고급 학습자까지를 위해 구성되어 있으므로, 여기서 시작하거나 처음부터 시작할 수 있으며 자신의 속도대로 진행할 수 있습니다. 이것은 4개 중 1번째 강의입니다.

“Docker로 머신러닝 모델 컨테이너화하기” 강의는 얼마나 걸리나요?

대부분의 CoddyKit 강의는 약 5~10분이 소요됩니다. 각 강의는 간결하고 인터랙티브하여 꾸준한 진행이 가능하며, 웹과 앱에서 중단한 부분부터 바로 시작할 수 있습니다.

이 Learn AI with Python 강의에서 코드를 작성하고 실행할 수 있나요?

네. 모든 Learn AI with Python 강의에는 내장 코드 에디터가 포함되어 있으므로, 브라우저에서 바로 실제 코드를 작성하고 실행한 후 즉시 AI 피드백을 받을 수 있습니다 — 로컬 설정이 필요 없습니다.

이 강의의 모든 강의

← Learn AI with Python(으)로 돌아가기