Docker & NVIDIA Container Toolkit: So reichst du deine GPU fehlerfrei an AI-Container weiter

Warum NVIDIA Container Toolkit?

KI- und Deep-Learning-Workloads wie PyTorch oder TensorFlow benötigen massiv parallele Rechenleistung. Eine GPU im Container nutzbar zu machen, ist jedoch nicht trivial, weil der Container-Sandbox standardmäßig keinen Zugriff auf das Host-Gerät hat. Hier kommt das NVIDIA Container Toolkit ins Spiel: Es stellt die NVIDIA-Treiber, CUDA-Bibliotheken und das GPU-Device transparent im Docker-Container bereit – ohne dass du die Abhängigkeiten manuell in jedes Image kopieren musst.

Voraussetzungen auf dem Host

Ein Linux-System (Ubuntu/Debian, RHEL/Rocky oder SUSE) mit installiertem Docker Engine – Version 19.03 oder neuer.
Ein NVIDIA-GPU-Treiber auf dem Host, der mit CUDA kompatibel ist. Prüfe das mit nvidia-smi – der Befehl sollte die GPU und die Treiberversion anzeigen.
Für AI-Container empfehlen wir mindestens 8 GB VRAM für Modelle wie YOLOv8 oder Stable Diffusion. Für größere LLMs (z. B. Llama-2-7B) solltest du 16 GB oder mehr einplanen.
Docker-Runtime mit nvidia-container-runtime – diese wird automatisch vom Toolkit konfiguriert.

NVIDIA Container Toolkit installieren

Die Installation erfolgt über das offizielle NVIDIA-Repository. Für Debian/Ubuntu führst du folgende Schritte aus:

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://nvidia.github.io/libnvidia-container/stable/deb/$(/etc/os-release | grep VERSION_ID | cut -d= -f2) /" | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit

Danach konfigurierst du die Docker-Runtime:

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

Bei RHEL/Rocky nutze entsprechend yum oder dnf, das Prinzip bleibt identisch.

GPU im Container testen

Der einfachste Test ist das Ausführen des NVIDIA-CUDA-Basisimages mit nvidia-smi:

docker run --rm --gpus all nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi

Siehst du die GPU-Informationen, ist die Durchreichung erfolgreich. Für einen AI-Container mit PyTorch kannst du folgendes Kommando verwenden:

docker run --gpus all -it --rm -v $(pwd):/workspace -w /workspace pytorch/pytorch:latest bash

Innerhalb des Containers kannst du mit nvidia-smi den VRAM beobachten. Für detaillierte Werte (z. B. frei und belegt) hilft:

nvidia-smi --query-gpu=memory.total,memory.free --format=csv

Ein Python-Check in PyTorch sieht so aus:

python -c "import torch; print(torch.cuda.is_available(), torch.cuda.device_count())"

Die Ausgabe sollte True 1 oder eine höhere Anzahl an GPUs zeigen.

Wichtige Docker-Optionen im Überblick

–gpus all: Reicht alle GPUs des Hosts an den Container weiter.
–gpus ‚“device=0,1″‚: Nur bestimmte GPUs auswählen.
–runtime=nvidia: Alternative zur --gpus-Syntax (ältere Docker-Versionen).
NVIDIA_VISIBLE_DEVICES: Umgebungsvariable zur Steuerung der GPU-Sichtbarkeit, z. B. -e NVIDIA_VISIBLE_DEVICES=0.
–shm-size=2g: Bei datenintensiven AI-Workloads den Shared Memory erhöhen, da Standard-64MB oft zu klein sind.

Häufige Fehler und Lösungen

docker: Error response from daemon: could not select device driver "gpu" with capabilities: [[gpu]]: Das Toolkit ist nicht installiert oder die Runtime wurde nicht konfiguriert. Prüfe docker info auf den Eintrag nvidia bei Runtimes.
Unknown runtime specified nvidia: Docker wurde nach der Konfiguration nicht neu gestartet. Führe sudo systemctl restart docker aus.
Failed to initialize NVML: Driver/library version mismatch: Dies passiert, wenn der Host-Treiber nach einem Update nicht neu geladen wurde. Ein Reboot des Hosts behebt das Problem.
CUDA error: no kernel image is available for execution on the device: Das Image passt nicht zur CUDA-Architektur deiner GPU. Wähle ein passendes Image, z. B. pytorch/pytorch:latest mit CUDA-Support für deine Architektur.
Container startet, aber nvidia-smi zeigt keine GPU: Stelle sicher, dass die GPU nicht von einem anderen Prozess exklusiv belegt ist (z. B. nvidia-smi auf dem Host prüfen).

Fazit

Mit dem NVIDIA Container Toolkit wird die GPU-Durchreichung an AI-Container zum Standardprozess: einmal installieren, Docker konfigurieren, und schon kannst du rechenintensive Modelle isoliert und reproduzierbar ausführen. Achte auf die Treiberversion und den VRAM-Bedarf deiner Modelle – so vermeidest du die typischen Stolperfallen. Gerade auf einem Dedicated Server oder einer Workstation kannst du damit mehrere AI-Jobs sauber voneinander trennen, ohne in die Host-Umgebung eingreifen zu müssen.