Whisper Docker 설정: Docker에서 OpenAI Whisper를 실행하는 완전 가이드

소개

• 어디서나 동일하게 배포 – Docker를 지원하는 모든 플랫폼에서 같은 컨테이너 실행
• 의존성 격리 – 시스템 패키지와의 충돌 방지
• 쉬운 확장 – 여러 컨테이너로 병렬 처리
• 버전 관리 – 특정 Whisper 버전과 설정 고정
• 배포 단순화 – 한 번의 명령으로 전체 스택 실행

---

Whisper에 Docker를 쓰는 이유

컨테이너화의 이점

• 개발·스테이징·프로덕션에서 동일한 환경
• 의존성 충돌 없음
• 재현 가능한 빌드

• Docker가 있는 환경이면 어디서나 실행
• 서버 간 마이그레이션이 쉬움
• 특정 클라우드에 묶이지 않는 배포

• 호스트 시스템에 영향 최소화
• 제거가 간단(컨테이너만 삭제)
• 격리를 통한 보안 이점

• 수평 확장이 용이
• 컨테이너 간 로드 밸런싱
• 컨테이너별 리소스 제한

• CI/CD 파이프라인과 잘 맞음
• Kubernetes 배포에 적합
• 클라우드 컨테이너 서비스와 궁합이 좋음

---

사전 요구 사항

• Docker 설치(버전 20.10 이상)
• Docker Compose(선택, 다중 컨테이너 구성 시)
• NVIDIA Docker(선택, GPU 사용 시)
• Docker 명령에 대한 기본 지식

Docker 설치

# Install Docker Desktop from docker.com
# Or using Homebrew
brew install --cask docker

sudo apt update
sudo apt install docker.io docker-compose
sudo systemctl start docker
sudo systemctl enable docker

설치 확인

docker --version
docker-compose --version

---

Whisper용 기본 Dockerfile

FROM python:3.10-slim

# Set working directory
WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y \
    ffmpeg \
    git \
    && rm -rf /var/lib/apt/lists/*

# Install Python dependencies
RUN pip install --no-cache-dir \
    openai-whisper \
    torch \
    torchaudio

# Copy application code (if you have custom scripts)
# COPY . .

# Set default command
CMD ["whisper", "--help"]

이미지 빌드

docker build -t whisper:latest .

기본 컨테이너 실행

docker run --rm whisper:latest whisper --version

---

API 서버가 포함된 Dockerfile

FROM python:3.10-slim

WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y \
    ffmpeg \
    git \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Install Python dependencies
RUN pip install --no-cache-dir \
    openai-whisper \
    torch \
    torchaudio \
    fastapi \
    uvicorn \
    python-multipart

# Create directories for audio and output
RUN mkdir -p /app/audio /app/output

# Copy application code
COPY app.py .
COPY requirements.txt .

# Expose API port
EXPOSE 8000

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

# Run API server
CMD ["uvicorn", "app.py:app", "--host", "0.0.0.0", "--port", "8000"]

API 서버 예시(app.py)

from fastapi import FastAPI, File, UploadFile
from fastapi.responses import JSONResponse
import whisper
import os

app = FastAPI()

# Load Whisper model (can be configured via env)
model_name = os.getenv("WHISPER_MODEL", "base")
model = whisper.load_model(model_name)

@app.get("/health")
def health():
    return {"status": "healthy"}

@app.post("/transcribe")
async def transcribe(file: UploadFile = File(...)):
    # Save uploaded file
    file_path = f"/app/audio/{file.filename}"
    with open(file_path, "wb") as f:
        content = await file.read()
        f.write(content)
    
    # Transcribe
    result = model.transcribe(file_path)
    
    # Clean up
    os.remove(file_path)
    
    return JSONResponse(content={
        "text": result["text"],
        "language": result["language"]
    })

requirements.txt

fastapi==0.104.1
uvicorn[standard]==0.24.0
python-multipart==0.0.6
openai-whisper
torch
torchaudio

---

Docker Compose 설정

docker-compose.yml

version: '3.8'

services:
  whisper-api:
    build: .
    container_name: whisper-api
    ports:
      - "8000:8000"
    volumes:
      - ./audio:/app/audio
      - ./output:/app/output
    environment:
      - WHISPER_MODEL=base
      - CUDA_VISIBLE_DEVICES=0
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

  # Optional: Redis for queue management
  redis:
    image: redis:7-alpine
    container_name: whisper-redis
    ports:
      - "6379:6379"
    volumes:
      - redis-data:/data
    restart: unless-stopped

volumes:
  redis-data:

Docker Compose로 실행

# Start services
docker-compose up -d

# View logs
docker-compose logs -f whisper-api

# Stop services
docker-compose down

---

Docker에서 GPU 지원

NVIDIA Docker 설치

# Add NVIDIA Docker repository
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | \
    sudo tee /etc/apt/sources.list.d/nvidia-docker.list

# Install
sudo apt-get update
sudo apt-get install -y nvidia-docker2
sudo systemctl restart docker

GPU 지원 Dockerfile

FROM nvidia/cuda:11.8.0-cudnn8-runtime-ubuntu22.04

WORKDIR /app

# Install Python
RUN apt-get update && apt-get install -y \
    python3.10 \
    python3-pip \
    ffmpeg \
    git \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Install Python dependencies with CUDA support
RUN pip3 install --no-cache-dir \
    openai-whisper \
    torch \
    torchaudio \
    --index-url https://download.pytorch.org/whl/cu118

# Install API dependencies
RUN pip3 install --no-cache-dir \
    fastapi \
    uvicorn \
    python-multipart

COPY app.py .
EXPOSE 8000

CMD ["uvicorn", "app.py:app", "--host", "0.0.0.0", "--port", "8000"]

GPU로 실행

# Using docker run
docker run --gpus all -p 8000:8000 whisper-gpu:latest

# Using docker-compose

GPU용 docker-compose.yml

version: '3.8'

services:
  whisper-api:
    build: .
    container_name: whisper-api-gpu
    runtime: nvidia
    environment:
      - NVIDIA_VISIBLE_DEVICES=all
    ports:
      - "8000:8000"
    volumes:
      - ./audio:/app/audio
      - ./output:/app/output
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

---

프로덕션용 최적화 Dockerfile

# Multi-stage build for smaller image
FROM python:3.10-slim as builder

WORKDIR /app

# Install build dependencies
RUN apt-get update && apt-get install -y \
    gcc \
    g++ \
    git \
    && rm -rf /var/lib/apt/lists/*

# Install Python packages
COPY requirements.txt .
RUN pip install --user --no-cache-dir -r requirements.txt

# Final stage
FROM python:3.10-slim

WORKDIR /app

# Install runtime dependencies only
RUN apt-get update && apt-get install -y \
    ffmpeg \
    curl \
    && rm -rf /var/lib/apt/lists/* \
    && apt-get clean

# Copy Python packages from builder
COPY --from=builder /root/.local /root/.local

# Make sure scripts in .local are usable
ENV PATH=/root/.local/bin:$PATH

# Create non-root user for security
RUN useradd -m -u 1000 whisper && \
    mkdir -p /app/audio /app/output && \
    chown -R whisper:whisper /app

USER whisper

# Copy application code
COPY --chown=whisper:whisper app.py .
COPY --chown=whisper:whisper requirements.txt .

EXPOSE 8000

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

CMD ["uvicorn", "app.py:app", "--host", "0.0.0.0", "--port", "8000"]

멀티 스테이지 빌드의 이점

• 더 작은 이미지 – 최종 이미지에는 런타임 의존성만 포함
• 더 빠른 빌드 – 빌드 의존성을 별도로 캐시
• 보안 강화 – 비 root 사용자, 공격 표면 축소

---

환경 변수 구성

Dockerfile

FROM python:3.10-slim

WORKDIR /app

RUN apt-get update && apt-get install -y \
    ffmpeg \
    git \
    curl \
    && rm -rf /var/lib/apt/lists/*

RUN pip install --no-cache-dir \
    openai-whisper \
    torch \
    torchaudio \
    fastapi \
    uvicorn \
    python-multipart

COPY app.py .

# Environment variables with defaults
ENV WHISPER_MODEL=base
ENV MAX_FILE_SIZE=100MB
ENV LOG_LEVEL=INFO

EXPOSE 8000

CMD ["uvicorn", "app.py:app", "--host", "0.0.0.0", "--port", "8000"]

환경 변수가 포함된 docker-compose.yml

version: '3.8'

services:
  whisper-api:
    build: .
    ports:
      - "8000:8000"
    volumes:
      - ./audio:/app/audio
      - ./output:/app/output
    environment:
      - WHISPER_MODEL=small
      - MAX_FILE_SIZE=200MB
      - LOG_LEVEL=DEBUG
      - CUDA_VISIBLE_DEVICES=0
    env_file:
      - .env
    restart: unless-stopped

.env 파일

WHISPER_MODEL=small
MAX_FILE_SIZE=200MB
LOG_LEVEL=INFO
CUDA_VISIBLE_DEVICES=0

---

볼륨 관리

볼륨이 포함된 docker-compose.yml

version: '3.8'

services:
  whisper-api:
    build: .
    ports:
      - "8000:8000"
    volumes:
      # Bind mount for development
      - ./audio:/app/audio
      - ./output:/app/output
      
      # Named volume for model cache (persists across containers)
      - whisper-models:/root/.cache/whisper
      
      # Config volume
      - ./config:/app/config:ro
    environment:
      - WHISPER_MODEL=base

volumes:
  whisper-models:
    driver: local

이점

• 모델 캐시 – 한 번 다운로드하면 컨테이너 간 재사용
• 데이터 지속성 – 컨테이너를 재시작해도 출력 파일 유지
• 구성 유연성 – 이미지를 다시 빌드하지 않고 설정 변경

---

헬스 체크와 모니터링

헬스 체크가 포함된 Dockerfile

FROM python:3.10-slim

WORKDIR /app

RUN apt-get update && apt-get install -y \
    ffmpeg \
    curl \
    && rm -rf /var/lib/apt/lists/*

RUN pip install --no-cache-dir \
    openai-whisper \
    fastapi \
    uvicorn

COPY app.py .

# Health check endpoint
HEALTHCHECK --interval=30s \
            --timeout=10s \
            --start-period=40s \
            --retries=3 \
            CMD curl -f http://localhost:8000/health || exit 1

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

헬스 체크 엔드포인트

from fastapi import FastAPI
import whisper

app = FastAPI()
model = whisper.load_model("base")

@app.get("/health")
def health():
    try:
        # Quick test transcription
        return {"status": "healthy", "model": "base"}
    except Exception as e:
        return {"status": "unhealthy", "error": str(e)}, 503

---

일반적인 사용 사례

사용 사례 1: 개발 환경

version: '3.8'

services:
  whisper-dev:
    build:
      context: .
      dockerfile: Dockerfile.dev
    volumes:
      - .:/app
      - /app/__pycache__
    ports:
      - "8000:8000"
    environment:
      - WHISPER_MODEL=tiny
      - DEBUG=true
    command: uvicorn app.py:app --reload --host 0.0.0.0 --port 8000

사용 사례 2: 큐가 있는 프로덕션

version: '3.8'

services:
  whisper-api:
    build: .
    ports:
      - "8000:8000"
    environment:
      - REDIS_URL=redis://redis:6379
      - WHISPER_MODEL=small
    depends_on:
      - redis
      - worker

  worker:
    build: .
    command: python worker.py
    environment:
      - REDIS_URL=redis://redis:6379
      - WHISPER_MODEL=small
    volumes:
      - ./audio:/app/audio
    depends_on:
      - redis

  redis:
    image: redis:7-alpine
    volumes:
      - redis-data:/data

volumes:
  redis-data:

사용 사례 3: 다중 모델 구성

version: '3.8'

services:
  whisper-fast:
    build: .
    ports:
      - "8001:8000"
    environment:
      - WHISPER_MODEL=tiny
      - PORT=8000

  whisper-balanced:
    build: .
    ports:
      - "8002:8000"
    environment:
      - WHISPER_MODEL=base
      - PORT=8000

  whisper-accurate:
    build: .
    ports:
      - "8003:8000"
    environment:
      - WHISPER_MODEL=large
      - PORT=8000

---

모범 사례

1. 구체적인 베이스 이미지 사용

FROM python:latest

FROM python:3.10-slim

2. 레이어 최소화

RUN apt-get update
RUN apt-get install -y ffmpeg
RUN apt-get install -y git

RUN apt-get update && apt-get install -y \
    ffmpeg \
    git \
    && rm -rf /var/lib/apt/lists/*

3. .dockerignore 사용

__pycache__
*.pyc
*.pyo
*.pyd
.Python
.env
.venv
venv/
.git
.gitignore
README.md
*.md
.DS_Store

4. 리소스 제한 설정

services:
  whisper-api:
    build: .
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 4G
        reservations:
          cpus: '1'
          memory: 2G

5. 헬스 체크 사용

HEALTHCHECK --interval=30s --timeout=10s CMD curl -f http://localhost:8000/health || exit 1

6. 비 root 사용자

RUN useradd -m -u 1000 whisper
USER whisper

7. 모델 캐시

volumes:
  - whisper-models:/root/.cache/whisper

---

일반적인 문제 해결

문제 1: 컨테이너가 즉시 종료됨

# Check logs
docker logs <container-id>

# Run interactively to debug
docker run -it whisper:latest /bin/bash

문제 2: GPU를 사용할 수 없음

# Verify NVIDIA Docker
docker run --rm --gpus all nvidia/cuda:11.8.0-base-ubuntu22.04 nvidia-smi

# Check runtime
docker info | grep -i runtime

문제 3: 메모리 부족

# Increase memory limit
deploy:
  resources:
    limits:
      memory: 8G

문제 4: 모델 다운로드가 느리거나 매번 발생

# Use volume for model cache
volumes:
  - whisper-models:/root/.cache/whisper

문제 5: 권한 거부

# Fix permissions in Dockerfile
RUN chown -R whisper:whisper /app

---

성능 최적화

1. 모델 사전 로드

# Download model during build
RUN python -c "import whisper; whisper.load_model('base')"

2. faster-whisper 사용

RUN pip install --no-cache-dir faster-whisper

3. 멀티스레딩

CMD ["uvicorn", "app.py:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "4"]

4. 리소스 할당

deploy:
  resources:
    limits:
      cpus: '4'
      memory: 8G

---

보안 고려 사항

1. 공식 베이스 이미지 사용

FROM python:3.10-slim  # Official Python image

2. 취약점 스캔

docker scan whisper:latest

3. 이미지 업데이트

FROM python:3.10-slim  # Use latest patch version
RUN pip install --upgrade pip

4. 네트워크 접근 제한

services:
  whisper-api:
    build: .
    networks:
      - internal
    # No external ports if accessed via reverse proxy

---

결론

1. 단순하게 시작 – 기본 Dockerfile부터
2. Docker Compose 활용 – 다중 서비스 스택 단순화
3. GPU 활성화 – 프로덕션 성능이 필요할 때
4. 모범 사례 준수 – 보안, 최적화, 모니터링
5. 충분히 테스트 – 프로덕션 배포 전

---

다음 단계

• 첫 컨테이너 빌드 – 기본 Dockerfile로 시작
• GPU 지원 추가 – NVIDIA GPU가 있는 경우
• Docker Compose 구성 – 전체 애플리케이션 스택용
• 클라우드 배포 – ECS, GKE, AKS 등 컨테이너 서비스