Docker Model Runner Cheatsheet: Comandi & Esempi

Riferimento rapido per i comandi di Docker Model Runner

Docker Model Runner (DMR) è la soluzione ufficiale di Docker per eseguire modelli AI localmente, introdotta ad aprile 2025. Questa guida rapida fornisce un riferimento veloce per tutti i comandi essenziali, le configurazioni e le best practice.

elenco dei modelli gemma disponibili in docker model runner

Installazione

Docker Desktop

Abilita Docker Model Runner tramite l’interfaccia grafica:

  1. Apri Docker Desktop
  2. Vai a Impostazioni → AI tab
  3. Clicca su Abilita Docker Model Runner
  4. Riavvia Docker Desktop

/home/rg/prj/hugo-pers/content/post/2025/10/docker-model-runner-cheatsheet/docker-model-runner_w678.jpg interfaccia docker model runner

Docker Engine (Linux)

Installa il pacchetto del plugin:

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install docker-model-plugin

# Fedora/RHEL
sudo dnf install docker-model-plugin

# Arch Linux
sudo pacman -S docker-model-plugin

Verifica l’installazione:

docker model --help

Supporto NVIDIA RTX per Docker

Per abilitare l’esecuzione di LLM su GPU invece che su CPU, installa nvidia-container-toolkit:

distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker

poi puoi eseguire i container con --gpus all

docker run --rm --gpus all <image> <command>

verifica che il container possa vedere la GPU:

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

Aggiungere il supporto NVIDIA per Docker Model Runner

Docker Model Runner richiede una configurazione esplicita della GPU. A differenza dei comandi standard docker run, docker model run non supporta i flag --gpus o -e. Invece, devi:

  1. Configura il demone Docker per utilizzare il runtime NVIDIA per default

Prima, verifica dove è installato nvidia-container-runtime:

which nvidia-container-runtime

Questo output sarà tipicamente /usr/bin/nvidia-container-runtime. Usa questo percorso nella configurazione seguente.

Crea o aggiorna /etc/docker/daemon.json:

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

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

Riavvia Docker:

sudo systemctl restart docker

Verifica la configurazione:

docker info | grep -i runtime

Dovresti vedere Default Runtime: nvidia nell’output.

  1. Riinstalla Docker Model Runner con supporto GPU

Docker Model Runner deve essere installato/riinstallato con supporto GPU esplicito:

# Ferma il runner corrente
docker model stop-runner

# Riinstalla con supporto CUDA
docker model reinstall-runner --gpu cuda

Questo scaricherà la versione abilitata per CUDA (docker/model-runner:latest-cuda) invece della versione solo CPU.

  1. Verifica l’accesso alla GPU

Controlla che il container Docker Model Runner possa accedere alla GPU:

docker exec docker-model-runner nvidia-smi
  1. Testa un modello con GPU

Esegui un modello e controlla i log per confermare l’utilizzo della GPU:

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

Controlla i log per la conferma della GPU:

docker model logs | grep -i cuda

Dovresti vedere messaggi come:

  • using device CUDA0 (NVIDIA GeForce RTX 4080)
  • offloaded 41/41 layers to GPU
  • CUDA0 model buffer size = 10946.13 MiB

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 deve essere la versione abilitata per CUDA.

Backend GPU disponibili:

  • cuda - NVIDIA CUDA (più comune)
  • rocm - AMD ROCm
  • musa - Moore Threads MUSA
  • cann - Huawei CANN
  • auto - Rilevamento automatico (predefinito)
  • none - Solo CPU

Comandi Principali

Scaricare Modelli

Scarica modelli preimballati da Docker Hub:

# Scaricamento base
docker model pull ai/llama2

# Scarica una versione specifica
docker model pull ai/llama2:7b-q4

# Scarica da un registro personalizzato
docker model pull myregistry.com/models/mistral:latest

# Elenco dei modelli disponibili in uno spazio dei nomi
docker search ai/

Eseguire Modelli

Avvia un modello con servizio API automatico:

# Esecuzione base (interattiva)
docker model run ai/llama2 "Cosa è Docker?"

# Esegui come servizio (in background)
docker model run -d

in generale non abbiamo molte opzioni per l’esecuzione dei modelli tramite CLI:

docker model run --help
Usage:  docker model run MODEL [PROMPT]

Esegui un modello e interagisci con esso utilizzando un prompt fornito o in modalità chat

Opzioni:
      --color string                  Utilizza l'output colorato (auto|yes|no) (default "auto")
      --debug                         Abilita il logging di debug
  -d, --detach                        Carica il modello in background senza interazione
      --ignore-runtime-memory-check   Non bloccare il pull se la memoria stimata per il modello supera le risorse del sistema.

Elenco dei Modelli

Visualizza i modelli scaricati e in esecuzione:

# Elenco di tutti i modelli scaricati
docker model ls

# Elenco dei modelli in esecuzione
docker model ps

# Elenco con informazioni dettagliate
docker model ls --json

# Elenco con informazioni dettagliate
docker model ls --openai

# Restituirà solo gli hashcodes
docker model ls -q

Rimozione dei Modelli

Elimina i modelli dallo storage locale:

# Rimuovi un modello specifico
docker model rm ai/llama2

# Rimuovi con forza (anche se in esecuzione)
docker model rm -f ai/llama2

# Rimuovi i modelli non utilizzati
docker model prune

# Rimuovi tutti i modelli
docker model rm $(docker model ls -q)

Configurazione delle Dimensioni del Contesto del Modello

Non possiamo utilizzare il CLI per specificare la dimensione del contesto per una richiesta specifica.

In generale possiamo controllare la dimensione del contesto del modello solo in tre modi:

  1. Pacchettizza il modello da soli, specificando la dimensione del contesto hardcoded desiderata (vedi la sezione successiva per maggiori informazioni.)

  2. Quando si utilizza docker model runner, configura il comando con il parametro –context-size come segue:

docker model configure --context-size=10000 ai/gemma3-qat:4B

Poi puoi chiamare curl su di esso, ma non puoi fare docker model run... - questo ignorerà la configurazione.

  1. Nel file docker-compose.yaml, ma non possiamo utilizzare l’immagine docker-model-runner in questo modo, perché passa al modello una dimensione del contesto hardcoded di 4096
...
models:
  llm_model:
    model: ai/gemma3-qat:4B
    context_size: 10240
...

Per maggiori dettagli, vedi il post dedicato su questo argomento: Specificare la dimensione del contesto in DMR

Pacchettizzazione di Modelli Personalizzati

Creare un Articolo OCI da GGUF

Pacchettizza i tuoi propri modelli GGUF:

# Pacchettizzazione base
docker model package --gguf /path/to/model.gguf myorg/mymodel:latest

# Pacchettizza con metadati
docker model package \
  --gguf /path/to/model.gguf \
  --label "description=Modello Llama personalizzato" \
  --label "versione=1.0" \
  myorg/mymodel:v1.0

# Pacchettizza e push in un unico comando
docker model package --gguf /path/to/model.gguf --push myorg/mymodel:latest

# Pacchettizza con dimensione del contesto personalizzata
docker model package \
  --gguf /path/to/model.gguf \
  --context 8192 \
  myorg/mymodel:latest

Pubblicare Modelli

Pubblica i modelli nei registri:

# Accedi a Docker Hub
docker login

# Pubblica su Docker Hub
docker model push myorg/mymodel:latest

# Pubblica su registro privato
docker login myregistry.com
docker model push myregistry.com/models/mymodel:latest

# Etichetta e pubblica
docker model tag mymodel:latest myorg/mymodel:v1.0
docker model push myorg/mymodel:v1.0

Utilizzo dell’API

Endpoint compatibili con OpenAI

Docker Model Runner espone automaticamente endpoint compatibili con OpenAI:

# Avvia il modello con API
docker model run -d -p 8080:8080 --name llm ai/llama2

# Completamento chat
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama2",
    "messages": [{"role": "user", "content": "Ciao!"}]
  }'

# Generazione testo
curl http://localhost:8080/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama2",
    "prompt": "Un tempo",
    "max_tokens": 100
  }'

# Risposta streaming
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama2",
    "messages": [{"role": "user", "content": "Raccontami una storia"}],
    "stream": true
  }'

# Elenco dei modelli disponibili tramite API
curl http://localhost:8080/v1/models

# Informazioni sul modello
curl http://localhost:8080/v1/models/llama2

Configurazione Docker Compose

File Compose Base

version: '3.8'

services:
  llm:
    image: docker-model-runner
    model: ai/llama2:7b-q4
    ports:
      - "8080:8080"
    environment:
      - MODEL_TEMPERATURE=0.7
    volumes:
      - docker-model-runner-models:/models
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

volumes:
  docker-model-runner-models:
    external: true

Configurazione Multi-Modello

version: '3.8'

services:
  llama:
    image: docker-model-runner
    model: ai/llama2
    ports:
      - "8080:8080"
    
  mistral:
    image: docker-model-runner
    model: ai/mistral
    ports:
      - "8081:8080"
    
  embedding:
    image: docker-model-runner
    model: ai/nomic-embed-text
    ports:
      - "8082:8080"

Per configurazioni Docker Compose avanzate e comandi, vedi la nostra Guida rapida Docker Compose che copre rete, volumi e modelli di orchestrazione.

Variabili di Ambiente

Configura il comportamento del modello con variabili di ambiente:

# Temperatura (0.0-1.0)
MODEL_TEMPERATURE=0.7

# Campionamento top-p
MODEL_TOP_P=0.9

# Campionamento top-k
MODEL_TOP_K=40

# Token massimi
MODEL_MAX_TOKENS=2048

# Numero di strati GPU
MODEL_GPU_LAYERS=35

# Dimensione del batch
MODEL_BATCH_SIZE=512

# Conteggio thread (CPU)
MODEL_THREADS=8

# Abilita logging dettagliato
MODEL_VERBOSE=true

# Chiave API per l'autenticazione
MODEL_API_KEY=your-secret-key

Esegui con variabili di ambiente:

docker model run \
  -e MODEL_TEMPERATURE=0.8 \
  -e MODEL_API_KEY=secret123 \
  ai/llama2

Configurazione GPU

Rilevamento automatico GPU

DMR rileva automaticamente e utilizza le GPU disponibili:

# Usa tutte le GPU
docker model run --gpus all ai/llama2

# Usa una GPU specifica
docker model run --gpus 0 ai/llama2

# Usa più GPU specifiche
docker model run --gpus 0,1,2 ai/llama2

# GPU con limite di memoria
docker model run --gpus all --memory 16g ai/llama2

Modalità CPU solo

Forza l’inferenza su CPU anche se la GPU è disponibile:

docker model run --no-gpu ai/llama2

Parallelismo Tensor su Multi-GPU

Distribuisci modelli grandi su più GPU:

docker model run \
  --gpus all \
  --tensor-parallel 2 \
  ai/llama2-70b

Ispezione e Debugging

Visualizza Dettagli del Modello

# Ispeziona la configurazione del modello
docker model inspect ai/llama2

# Visualizza gli strati del modello
docker model history ai/llama2

# Controlla le dimensioni del modello e i metadati
docker model inspect --format='{{.Size}}' ai/llama2

Log e Monitoraggio

# Visualizza i log del modello
docker model logs llm

# Segui i log in tempo reale
docker model logs -f llm

# Visualizza le ultime 100 righe
docker model logs --tail 100 llm

# Visualizza i log con timestamp
docker model logs -t llm

Statistiche di Prestazione

# Utilizzo delle risorse
docker model stats

# Statistiche di un modello specifico
docker model stats llm

# Statistiche in formato JSON
docker model stats --format json

Rete

Esposizione API

# Porta predefinita (8080)
docker model run -p 8080:8080 ai/llama2

# Porta personalizzata
docker model run -p 3000:8080 ai/llama2

# Collega a un'interfaccia specifica
docker model run -p 127.0.0.1:8080:8080 ai/llama2

# Multiple porte
docker model run -p 8080:8080 -p 9090:9090 ai/llama2

Configurazione di Rete

# Crea una rete personalizzata
docker network create llm-network

# Esegui il modello su una rete personalizzata
docker model run --network llm-network --name llm ai/llama2

# Connetti a una rete esistente
docker model run --network host ai/llama2

Sicurezza

Controllo di Accesso

# Esegui con autenticazione API key
docker model run \
  -e MODEL_API_KEY=my-secret-key \
  ai/llama2

# Usa con autenticazione
curl http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer my-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"model": "llama2", "messages": [...]}'

Autenticazione del Registro

# Accedi a un registro privato
docker login myregistry.com -u username -p password

# Scarica da un registro privato
docker model pull myregistry.com/private/model:latest

# Usa un helper per le credenziali
docker login --password-stdin < token.txt

Best Practice

Selezione del Modello

# Usa modelli quantizzati per un'inferenza più veloce
docker model pull ai/llama2:7b-q4     # Quantizzazione a 4 bit
docker model pull ai/llama2:7b-q5     # Quantizzazione a 5 bit
docker model pull ai/llama2:7b-q8     # Quantizzazione a 8 bit

# Controlla le varianti del modello
docker search ai/llama2

Gestione delle Risorse

# Imposta limiti di memoria
docker model run --memory 8g --memory-swap 16g ai/llama2

# Imposta limiti CPU
docker model run --cpus 4 ai/llama2

# Limita la memoria GPU
docker model run --gpus all --gpu-memory 8g ai/llama2

Verifica della Salute

# Esegui con verifica della salute
docker model run \
  --health-cmd "curl -f http://localhost:8080/health || exit 1" \
  --health-interval 30s \
  --health-timeout 10s \
  --health-retries 3 \
  ai/llama2

Orchestrazione in Produzione

Per distribuzioni in produzione con Kubernetes, i container Docker Model Runner possono essere orchestrati utilizzando manifesti standard Kubernetes. Definisci le distribuzioni con limiti di risorse, autoscaling e bilanciamento del carico. Per un riferimento completo ai comandi Kubernetes e ai modelli di distribuzione, consulta la nostra Guida rapida Kubernetes.

# Esempio: Distribuisci su un cluster Kubernetes
kubectl apply -f llm-deployment.yaml

# Scala la distribuzione
kubectl scale deployment llm --replicas=3

# Espone come servizio
kubectl expose deployment llm --type=LoadBalancer --port=8080

Risoluzione dei Problemi

Problemi Comuni

Il modello non si avvia:

# Controlla lo spazio disponibile sul disco
df -h

# Visualizza i log di errore dettagliati
docker model logs --tail 50 llm

# Verifica la disponibilità della GPU
nvidia-smi  # Per le GPU NVIDIA

Errori di memoria insufficiente:

# Usa un modello quantizzato più piccolo
docker model pull ai/llama2:7b-q4

# Riduci la dimensione del contesto
docker model run -e MODEL_CONTEXT=2048 ai/llama2

# Limita la dimensione del batch
docker model run -e MODEL_BATCH_SIZE=256 ai/llama2

Inferenza lenta:

# Controlla l'utilizzo della GPU
docker model stats llm

# Assicurati che la GPU venga utilizzata
docker model logs llm | grep -i gpu

# Aumenta il numero di strati GPU
docker model run -e MODEL_GPU_LAYERS=40 ai/llama2

Comandi di Diagnosi

# Informazioni del sistema
docker model system info

# Utilizzo del disco
docker model system df

# Pulisci le risorse non utilizzate
docker model system prune

# Pulizia completa (rimuovi tutti i modelli)
docker model system prune -a

Esempi di Integrazione

Integrazione con Python

import openai

# Configura il client per Docker Model Runner
client = openai.OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="not-needed"  # DMR non richiede una chiave per default
)

# Completamento chat
response = client.chat.completions.create(
    model="llama2",
    messages=[
        {"role": "user", "content": "Ciao!"}
    ]
)

print(response.choices[0].message.content)

# Streaming
stream = client.chat.completions.create(
    model="llama2",
    messages=[{"role": "user", "content": "Raccontami una storia"}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

Script Bash

#!/bin/bash

# Avvia il modello se non è in esecuzione
if ! docker model ps | grep -q "llm"; then
    docker model run -d --name llm -p 8080:8080 ai/llama2
    echo "Aspetto che il modello si avvii..."
    sleep 10
fi

# Effettua una chiamata API
curl -s http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama2",
    "messages": [{"role": "user", "content": "'"$1"'"}]
  }' | jq -r '.choices[0].message.content'

Integrazione con Node.js

import OpenAI from 'openai';

const client = new OpenAI({
    baseURL: 'http://localhost:8080/v1',
    apiKey: 'not-needed'
});

async function chat(message) {
    const completion = await client.chat.completions.create({
        model: 'llama2',
        messages: [{ role: 'user', content: message }]
    });
    
    return completion.choices[0].message.content;
}

// Utilizzo
const response = await chat('Cosa è Docker Model Runner?');
console.log(response);

Documentazione Ufficiale

Altri Fogli di Trucchi

Articoli di Confronto