Docker 모델 러너에 NVIDIA GPU 지원 추가

Docker Model Runner은 AI 모델을 로컬에서 실행하는 Docker의 공식 도구이지만,
Docker Model Runner에서 NVidia GPU 가속 기능 활성화
은 특정 설정이 필요합니다.

표준 docker run 명령어와 달리 docker model run은 --gpus 또는 -e 플래그를 지원하지 않기 때문에, GPU 지원은 Docker 데몬 수준에서 그리고 러너 설치 시에 구성해야 합니다.

GPU 설정이 더 간단한 대안 LLM 호스팅 솔루션을 찾고 있다면, Ollama를 고려해 보세요. Ollama는 내장 GPU 지원과 간단한 설정을 제공합니다. 그러나 Docker Model Runner는 Docker 생태계와 OCI 아티팩트 분배와의 더 나은 통합을 제공합니다. Docker Model Runner와 Ollama, vLLM, LocalAI 및 클라우드 제공업체에 대한 비교—비용과 인프라 트레이드오프를 포함하여—LLM 호스팅: 로컬, 자가호스팅 및 클라우드 인프라 비교를 참조하세요.

이 아름다운 이미지는 AI 모델 Flux 1 dev에 의해 생성되었습니다.

사전 조건

GPU 지원을 구성하기 전에 다음 사항을 확인하세요:

• NVIDIA GPU와 호환되는 드라이버가 설치되어 있습니다. AI 워크로드에 적합한 GPU를 선택하는 데 도움이 되는 가이드는 NVIDIA GPU 사양의 AI 적합성 비교를 참조하세요.
• NVIDIA Container Toolkit이 설치되어 있습니다. (NVIDIA RTX 지원 섹션을 참조하세요: NVIDIA RTX 지원을 위한 Docker)
• Docker Model Runner가 설치되어 있습니다. (GPU 지원을 포함한 재설치가 가능합니다)

GPU가 접근 가능한지 확인하세요:

nvidia-smi

Docker의 GPU 접근을 테스트하세요:

docker run --rm --gpus all nvidia/cuda:12.2.2-base-ubi8 nvidia-smi

더 많은 Docker 명령어와 구성 옵션은 Docker Cheatsheet를 참조하세요.

단계 1: NVIDIA 런타임을 위한 Docker 데몬 구성

Docker Model Runner는 Docker 데몬 구성에서 NVIDIA 런타임을 기본 런타임으로 설정해야 합니다.

NVIDIA Container Runtime 경로 찾기

먼저 nvidia-container-runtime이 설치된 위치를 확인하세요:

which nvidia-container-runtime

이 명령어는 일반적으로 /usr/bin/nvidia-container-runtime를 출력합니다. 다음 단계에서 이 경로를 기억하세요.

Docker 데몬 구성

/etc/docker/daemon.json을 생성하거나 업데이트하여 NVIDIA를 기본 런타임으로 설정하세요:

sudo tee /etc/docker/daemon.json > /dev/null << 'EOF'
{
  "default-runtime": "nvidia",
  "runtimes": {
    "nvidia": {
      "path": "/usr/bin/nvidia-container-runtime",
      "runtimeArgs": []
    }
  }
}
EOF

중요: which nvidia-container-runtime이 다른 경로를 반환했다면 JSON 구성 파일에서 "path" 값을 적절히 수정하세요.

Docker 서비스 재시작

구성을 적용하려면 Docker를 재시작하세요:

sudo systemctl restart docker

구성 확인

NVIDIA 런타임이 구성되었는지 확인하세요:

docker info | grep -i runtime

출력 결과에 Default Runtime: nvidia가 포함되어 있어야 합니다.

단계 2: GPU 지원을 포함한 Docker Model Runner 설치

GPU 지원을 포함한 Docker Model Runner를 설치하거나 재설치해야 합니다. 러너 컨테이너 자체는 CUDA 지원 버전이어야 합니다.

현재 러너 중지 (실행 중인 경우)

Docker Model Runner가 이미 설치되어 있다면 먼저 중지하세요:

docker model stop-runner

CUDA 지원으로 설치/재설치

CUDA GPU 지원을 포함한 Docker Model Runner를 설치하거나 재설치하세요:

docker model reinstall-runner --gpu cuda

이 명령어는 다음과 같은 작업을 수행합니다:

• CPU 전용 버전 대신 CUDA 지원 버전(docker/model-runner:latest-cuda)을 풀어냅니다.
• 러너 컨테이너가 NVIDIA 런타임을 사용하도록 구성합니다.
• 모든 모델에 대한 GPU 가속을 활성화합니다.

참고: 이미 GPU 지원 없이 Docker Model Runner를 설치했다면 --gpu cuda 플래그를 사용하여 다시 설치해야 합니다. Docker 데몬만 구성하는 것만으로는 충분하지 않습니다—러너 컨테이너 자체는 CUDA 지원 버전이어야 합니다.

사용 가능한 GPU 백엔드

Docker Model Runner는 여러 GPU 백엔드를 지원합니다:

• cuda - NVIDIA CUDA (NVIDIA GPU에서 가장 일반적)
• rocm - AMD ROCm (AMD GPU에서)
• musa - Moore Threads MUSA
• cann - Huawei CANN
• auto - 자동 감지 (기본값, 올바르게 작동하지 않을 수 있음)
• none - CPU 전용

NVIDIA GPU를 사용하는 경우 항상 --gpu cuda를 명시적으로 사용하세요.

단계 3: GPU 접근 확인

설치 후 Docker Model Runner가 GPU에 접근할 수 있는지 확인하세요.

러너 컨테이너의 GPU 접근 확인

Docker Model Runner 컨테이너 내부에서 GPU 접근을 테스트하세요:

docker exec docker-model-runner nvidia-smi

이 명령어는 컨테이너가 GPU에 접근하고 있음을 확인하는 GPU 정보를 표시해야 합니다.

러너 상태 확인

Docker Model Runner가 실행 중인지 확인하세요:

docker model status

러너가 활성화되고 llama.cpp 지원이 있는지 확인하세요.

단계 4: GPU를 사용한 모델 테스트

모델을 실행하고 GPU가 사용되고 있는지 확인하세요.

모델 실행

모델 추론을 시작하세요:

docker model run ai/qwen3:14B-Q6_K "who are you?"

로그에서 GPU 사용 확인

Docker Model Runner 로그에서 GPU 사용 여부를 확인하세요:

docker model logs | grep -i cuda

다음과 같은 메시지가 표시되어야 합니다:

• using device CUDA0 (NVIDIA GeForce RTX 4080) - GPU 장치 감지
• offloaded 41/41 layers to GPU - 모델 레이어가 GPU에 로드됨
• CUDA0 model buffer size = 10946.13 MiB - GPU 메모리 할당
• CUDA0 KV buffer size = 640.00 MiB - GPU에 저장된 키-값 캐시
• CUDA0 compute buffer size = 306.75 MiB - GPU에 저장된 계산 버퍼

GPU 사용 모니터링

다른 터미널에서 GPU 사용량을 실시간으로 모니터링하세요:

nvidia-smi -l 1

모델이 실행 중일 때 GPU 메모리 사용량과 활용도가 증가하는 것을 확인하세요.

더 고급의 GPU 모니터링 옵션과 도구에 대해서는 Linux / Ubuntu에서의 GPU 모니터링 앱 가이드를 참조하세요.

문제 해결

모델이 여전히 CPU를 사용 중

모델이 여전히 CPU를 사용 중이라면:

1. Docker 데몬 구성 확인:

   docker info | grep -i runtime
   

   Default Runtime: nvidia가 표시되어야 합니다.

2. 러너 컨테이너 런타임 확인:

   docker inspect docker-model-runner | grep -A 2 '"Runtime"'
   

   "Runtime": "nvidia"가 표시되어야 합니다.

3. GPU 지원으로 러너 재설치:

   docker model reinstall-runner --gpu cuda
   

4. 로그에서 오류 확인:

   docker model logs | tail -50
   

GPU 감지 실패

GPU가 감지되지 않는다면:

1. NVIDIA Container Toolkit 설치 확인:

   dpkg -l | grep nvidia-container-toolkit
   

2. 표준 Docker로 GPU 접근 테스트:

   docker run --rm --gpus all nvidia/cuda:12.2.2-base-ubi8 nvidia-smi
   

   Docker 문제 해결을 위해 Docker Cheatsheet를 참조하세요.

3. NVIDIA 드라이버 확인:

   nvidia-smi
   

성능 문제

GPU 성능이 낮다면:

1. GPU 활용도 확인:

   nvidia-smi
   

   높은 GPU 활용도 퍼센트를 확인하세요.

2. 모델 레이어가 GPU에 로드되었는지 확인:

   docker model logs | grep "offloaded.*layers to GPU"
   

   모든 레이어가 GPU로 이전되어야 합니다.

3. 메모리 문제 확인:

   nvidia-smi
   

   GPU 메모리가 고갈되지 않았는지 확인하세요.

최고의 실천 방법

1. GPU 백엔드를 명시적으로 지정하세요: NVIDIA GPU를 사용할 경우 --gpu auto 대신 --gpu cuda를 사용하여 올바른 구성이 보장되도록 하세요.

2. 변경 후 구성 확인: Docker 데몬 설정을 변경한 후 항상 docker info | grep -i runtime을 확인하세요.

3. GPU 사용 모니터링: 모델 추론 중 GPU 메모리와 활용도를 nvidia-smi로 모니터링하세요. 더 고급의 모니터링 도구에 대해서는 Linux / Ubuntu에서의 GPU 모니터링 앱 가이드를 참조하세요.

4. 정기적으로 로그 확인: docker model logs를 확인하여 모델이 GPU 가속을 사용하고 있는지 확인하세요.

5. 적절한 모델 크기 사용: GPU에 충분한 메모리가 있는지 확인하세요. Q4, Q5, Q6, Q8 등 양자화된 모델을 사용하여 GPU 메모리 효율성을 높이세요. AI 워크로드에 적합한 GPU를 선택하는 데 도움이 되는 가이드는 NVIDIA GPU 사양의 AI 적합성 비교를 참조하세요.

GPU 지원이 활성화되면 Docker Model Runner는 로컬에서 LLM을 실행하는 방법 중 하나입니다. Ollama, vLLM, 클라우드 API 및 기타 옵션과의 관계를 확인하려면 LLM 호스팅: 로컬, 자가호스팅 및 클라우드 인프라 비교 가이드를 참조하세요.

유용한 링크

• Docker Model Runner Cheatsheet
• Docker Model Runner 공식 문서
• NVIDIA Container Toolkit 설치 가이드
• Docker Model Runner vs Ollama 비교
• Docker Cheatsheet - Docker 명령어 및 구성에 대한 완전한 참조
• Linux / Ubuntu에서의 GPU 모니터링 앱 - NVIDIA GPU 모니터링 도구 목록 및 비교
• NVIDIA GPU 사양의 AI 적합성 비교 - AI 워크로드에 적합한 GPU 선택 가이드