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

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

표준 docker run 명령과 달리 docker model run은 --gpus 또는 -e 플래그를 지원하지 않으므로, GPU 지원은 Docker 데몬 수준에서 설정해야 하며, 러너 설치 시에도 설정해야 합니다.

GPU 설정이 더 간단한 대안적인 LLM 호스팅 솔루션을 찾고 있다면, 내장된 GPU 지원과 간단한 설정을 제공하는 Ollama를 고려해 보세요. 그러나 Docker Model Runner는 Docker 생태계와 OCI 아티팩트 분배와의 더 나은 통합을 제공합니다.

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

사전 조건

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

• NVIDIA GPU와 호환되는 드라이버가 설치되어 있습니다. AI 워크로드에 적합한 GPU를 선택하는 방법은 NVIDIA GPU 사양의 AI 적합성 비교 가이드를 참조하세요.
• NVIDIA Container Toolkit이 설치되어 있습니다 (NVIDIA RTX 지원 섹션을 참조하십시오: NVIDIA RTX 지원 for 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 지원을 포함한 명시적인 설치 또는 재설치가 필요합니다. 러너 컨테이너 자체는 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 사용량 모니터링: 모델 추론 중 nvidia-smi를 사용하여 GPU 메모리와 활용도를 모니터링하세요. 더 고급의 모니터링 도구에 대해서는 Linux / Ubuntu에서의 GPU 모니터링 앱 가이드를 참조하세요.

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

5. 적절한 모델 크기 사용: GPU에 충분한 메모리가 있는지 확인하세요. GPU 메모리 효율성을 위해 양자화된 모델(Q4, Q5, Q6, Q8)을 사용하세요. AI 워크로드에 적합한 GPU를 선택하는 방법은 NVIDIA GPU 사양의 AI 적합성 비교 가이드를 참조하세요.

유용한 링크

• Docker Model Runner Cheatsheet
• Docker Model Runner 공식 문서
• NVIDIA Container Toolkit 설치 가이드
• Docker Model Runner vs Ollama 비교
• Ollama Cheatsheet - 내장 GPU 지원을 갖춘 대안적인 LLM 호스팅 솔루션
• Docker Cheatsheet - Docker 명령어 및 설정에 대한 완전한 참조
• Linux / Ubuntu에서의 GPU 모니터링 앱 - NVIDIA GPU 모니터링 도구 목록 및 비교
• NVIDIA GPU 사양의 AI 적합성 비교 - AI 워크로드에 적합한 GPU 선택 가이드