Aggiungere il supporto per GPU NVIDIA a Docker Model Runner

Abilita l'accelerazione GPU per Docker Model Runner con supporto NVIDIA CUDA

Docker Model Runner è lo strumento ufficiale di Docker per eseguire modelli AI localmente, ma abilitare l’accelerazione GPU di NVidia in Docker Model Runner richiede una configurazione specifica.

A differenza dei comandi standard docker run, docker model run non supporta i flag --gpus o -e, quindi il supporto GPU deve essere configurato a livello del demone Docker e durante l’installazione del runner.

Se stai cercando una soluzione alternativa per l’hosting di LLM con una configurazione GPU più semplice, considera Ollama, che ha un supporto GPU integrato e un’installazione più semplice. Tuttavia, Docker Model Runner offre una migliore integrazione con l’ecosistema Docker e la distribuzione degli artifact OCI.

Docker Model Runner con supporto NVIDIA GPU Questa bella immagine è generata da AI model Flux 1 dev.

Prerequisiti

Prima di configurare il supporto GPU, assicurati di avere:

Verifica che la tua GPU sia accessibile:

nvidia-smi

Testa l’accesso GPU di Docker:

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

Per ulteriori comandi Docker e opzioni di configurazione, consulta la nostra Docker Cheatsheet.

Passo 1: Configura il demone Docker per il runtime NVIDIA

Docker Model Runner richiede che il runtime NVIDIA venga impostato come runtime predefinito nella configurazione del demone Docker.

Trova il percorso del runtime NVIDIA Container

Per prima cosa, trova dove è installato nvidia-container-runtime:

which nvidia-container-runtime

Questo output è tipicamente /usr/bin/nvidia-container-runtime. Nota questo percorso per il passo successivo.

Configura il demone Docker

Crea o aggiorna /etc/docker/daemon.json per impostare NVIDIA come runtime predefinito:

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

Importante: Se which nvidia-container-runtime ha restituito un percorso diverso, aggiorna il valore "path" nella configurazione JSON di conseguenza.

Riavvia il servizio Docker

Applica la configurazione riavviando Docker:

sudo systemctl restart docker

Verifica la configurazione

Conferma che il runtime NVIDIA sia configurato:

docker info | grep -i runtime

Dovresti vedere Default Runtime: nvidia nell’output.

Passo 2: Installa Docker Model Runner con supporto GPU

Docker Model Runner deve essere installato o reinstallato con supporto GPU esplicito. Il container runner stesso deve essere la versione abilitata per CUDA.

Ferma il runner corrente (se in esecuzione)

Se Docker Model Runner è già installato, fermalo prima:

docker model stop-runner

Installa/Reinstalla con supporto CUDA

Installa o reinstalla Docker Model Runner con supporto GPU CUDA:

docker model reinstall-runner --gpu cuda

Questo comando:

  • Scarica la versione abilitata per CUDA (docker/model-runner:latest-cuda) invece della versione solo CPU
  • Configura il container runner per utilizzare il runtime NVIDIA
  • Abilita l’accelerazione GPU per tutti i modelli

Nota: Se hai già installato Docker Model Runner senza supporto GPU, devi reinstallarlo con il flag --gpu cuda. Configurare solo il demone Docker non è sufficiente — il container runner stesso deve essere la versione abilitata per CUDA.

Backend GPU disponibili

Docker Model Runner supporta diversi backend GPU:

  • cuda - NVIDIA CUDA (più comune per le GPU NVIDIA)
  • rocm - AMD ROCm (per le GPU AMD)
  • musa - Moore Threads MUSA
  • cann - Huawei CANN
  • auto - Rilevamento automatico (predefinito, potrebbe non funzionare correttamente)
  • none - Solo CPU

Per le GPU NVIDIA, utilizza sempre --gpu cuda esplicitamente.

Passo 3: Verifica l’accesso alla GPU

Dopo l’installazione, verifica che Docker Model Runner possa accedere alla tua GPU.

Verifica l’accesso alla GPU dal container runner

Testa l’accesso alla GPU all’interno del container Docker Model Runner:

docker exec docker-model-runner nvidia-smi

Questo dovrebbe visualizzare le informazioni sulla tua GPU, confermando che il container ha accesso alla GPU.

Verifica lo stato del runner

Conferma che Docker Model Runner sia in esecuzione:

docker model status

Dovresti vedere che il runner è attivo con il supporto llama.cpp.

Passo 4: Testa un modello con la GPU

Esegui un modello e verifica che stia utilizzando la GPU.

Esegui un modello

Avvia un’inferenza del modello:

docker model run ai/qwen3:14B-Q6_K "chi sei?"

Verifica l’utilizzo della GPU nei log

Controlla i log di Docker Model Runner per la conferma della GPU:

docker model logs | grep -i cuda

Dovresti vedere messaggi che indicano l’utilizzo della GPU:

  • using device CUDA0 (NVIDIA GeForce RTX 4080) - dispositivo GPU rilevato
  • offloaded 41/41 layers to GPU - strati del modello caricati sulla GPU
  • CUDA0 model buffer size = 10946.13 MiB - allocazione della memoria GPU
  • CUDA0 KV buffer size = 640.00 MiB - cache chiave-valore sulla GPU
  • CUDA0 compute buffer size = 306.75 MiB - buffer di calcolo sulla GPU

Monitora l’utilizzo della GPU

In un altro terminale, monitora l’utilizzo della GPU in tempo reale:

nvidia-smi -l 1

Dovresti vedere un aumento dell’utilizzo della memoria e della CPU quando il modello è in esecuzione.

Per ulteriori opzioni e strumenti avanzati di monitoraggio della GPU, consulta la nostra guida su Applicazioni di monitoraggio GPU in Linux / Ubuntu.

Risoluzione dei problemi

Il modello utilizza ancora la CPU

Se il modello continua a utilizzare la CPU:

  1. Verifica la configurazione del demone Docker:

    docker info | grep -i runtime

    Dovrebbe mostrare Default Runtime: nvidia

  2. Controlla il runtime del container runner:

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

    Dovrebbe mostrare "Runtime": "nvidia"

  3. Reinstalla il runner con supporto GPU:

    docker model reinstall-runner --gpu cuda

  4. Controlla i log per eventuali errori:

    docker model logs | tail -50

La GPU non è rilevata

Se la GPU non è rilevata:

  1. Verifica che il NVIDIA Container Toolkit sia installato:

    dpkg -l | grep nvidia-container-toolkit

  2. Testa l’accesso alla GPU con Docker standard:

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

    Per risolvere problemi con Docker, consulta la nostra Docker Cheatsheet.

  3. Verifica i driver NVIDIA:

    nvidia-smi

Problemi di prestazioni

Se le prestazioni della GPU sono scarse:

  1. Verifica l’utilizzo della GPU:

    nvidia-smi

    Cerca un alto percentuale di utilizzo della GPU

  2. Verifica che gli strati del modello siano sulla GPU:

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

    Tutti gli strati devono essere caricati sulla GPU

  3. Verifica eventuali problemi di memoria:

    nvidia-smi

    Assicurati che la memoria della GPU non sia esaurita

Linee guida per l’utilizzo

  1. Specifica sempre esplicitamente il backend GPU: Utilizza --gpu cuda invece di --gpu auto per le GPU NVIDIA per garantire una configurazione corretta.

  2. Verifica la configurazione dopo le modifiche: Controlla sempre docker info | grep -i runtime dopo aver modificato le impostazioni del demone Docker.

  3. Monitora l’utilizzo della GPU: Utilizza nvidia-smi per monitorare la memoria e l’utilizzo della GPU durante l’inferenza del modello. Per ulteriori strumenti avanzati di monitoraggio, consulta la nostra guida su Applicazioni di monitoraggio GPU in Linux / Ubuntu.

  4. Controlla regolarmente i log: Esamina docker model logs per assicurarti che i modelli utilizzino l’accelerazione GPU.

  5. Utilizza dimensioni di modello appropriate: Assicurati che la tua GPU abbia abbastanza memoria per il modello. Utilizza modelli quantizzati (Q4, Q5, Q6, Q8) per una maggiore efficienza della memoria GPU. Per aiuto nella scelta della giusta GPU per i carichi di lavoro AI, consulta la nostra guida su Confronto delle specifiche delle GPU NVIDIA adatte all’AI.