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 nel aprile 2025. Questo foglio di riferimento fornisce un rapido riferimento per tutti i comandi essenziali, le configurazioni e le best practice.

Per un confronto più ampio tra Docker Model Runner e Ollama, vLLM, LocalAI e provider cloud—inclusi i compromessi di costo e infrastruttura—vedi LLM Hosting: Local, Self-Hosted & Cloud Infrastructure Compared.

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 docker model runner windows

Docker Engine (Linux)

Installa il pacchetto 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 di 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 GPU CUDA
docker model reinstall-runner --gpu cuda

Questo installerà 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. Test del 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:

# Scarica 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 inviato 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à 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 solo, 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:

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 hardcoded del contesto 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

Confezionamento di modelli personalizzati

Creare un’artefatto OCI da GGUF

Confeziona i tuoi propri modelli GGUF:

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

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

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

# Confezionamento con dimensione 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 API

Endpoint compatibili con OpenAI

Docker Model Runner espone automaticamente endpoint API 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": "C'era una volta",
    "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 il nostro Foglio di riferimento Docker Compose che copre rete, volumi e modelli di orchestrazione.

Variabili ambiente

Configura il comportamento del modello con variabili 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 il logging dettagliato
MODEL_VERBOSE=true

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

Esegui con variabili 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 quando la GPU è disponibile:

docker model run --no-gpu ai/llama2

Parallelismo tensoriale multi-GPU

Distribuisci modelli grandi su più GPU:

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

Ispezione e debug

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 prestazioni

# Utilizzo delle risorse
docker model stats

# Statistiche per 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

# Connetti 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 rete

# Crea rete personalizzata
docker network create llm-network

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

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

Sicurezza

Controllo 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 registro

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

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

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

Best Practices

Selezione modello

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

# Controlla le varianti del modello
docker search ai/llama2

Gestione 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 memoria GPU
docker model run --gpus all --gpu-memory 8g ai/llama2

Controllo salute

# Esegui con controllo 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 distribuzioni con limiti di risorse, autoscaling e bilanciamento del carico. Per un riferimento completo ai comandi Kubernetes e modelli di distribuzione, consulta il nostro Foglio di riferimento Kubernetes.

# Esempio: Distribuisci in 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 problemi

Problemi comuni

Il modello non parte:

# Controlla lo spazio disponibile sul disco
df -h

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

# Verifica disponibilità GPU
nvidia-smi  # Per 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'uso 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 diagnostici

# Informazioni di sistema
docker model system info

# Utilizzo disco
docker model system df

# Pulizia delle risorse non utilizzate
docker model system prune

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

Esempi di integrazione

Integrazione 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 la 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 parta..."
    sleep 10
fi

# Fai 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 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);

Per vedere come Docker Model Runner si adatta a Ollama, vLLM, LocalAI e provider cloud, consulta la nostra guida LLM Hosting: Local, Self-Hosted & Cloud Infrastructure Compared.

Documentazione ufficiale

Articoli correlati