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.

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

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 --name my-llm ai/llama2

# Esegui con porta personalizzata
docker model run -p 8080:8080 ai/llama2

# Esegui con specifica GPU
docker model run --gpus 0,1 ai/llama2

# Esegui con limite di memoria
docker model run --memory 8g ai/llama2

# Esegui con variabili ambiente
docker model run -e MODEL_CONTEXT=4096 ai/llama2

# Esegui con montaggio del volume per dati persistenti
docker model run -v model-data:/data ai/llama2

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 --all --format json

# Filtra per nome
docker model ls --filter "name=llama"

Arrestare i Modelli

Arresta le istanze dei modelli in esecuzione:

# Arresta un modello specifico
docker model stop my-llm

# Arresta tutti i modelli in esecuzione
docker model stop $(docker model ps -q)

# Arresta con timeout
docker model stop --time 30 my-llm

Rimuovere i 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)

Confezionamento di Modelli Personalizzati

Crea un Articolo OCI da GGUF

Confeziona i tuoi 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 i 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 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_CONTEXT=4096
      - MODEL_TEMPERATURE=0.7
    volumes:
      - model-data:/root/.cache
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

volumes:
  model-data:

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 ulteriori configurazioni avanzate di Docker Compose e comandi, consulta il nostro Foglio di riferimento Docker Compose che copre rete, volumi e modelli di orchestrazione.

Variabili di Ambiente

Configura il comportamento del modello con le variabili di ambiente:

# Dimensione finestra contesto
MODEL_CONTEXT=4096

# 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 batch
MODEL_BATCH_SIZE=512

# Conteggio thread (CPU)
MODEL_THREADS=8

# Abilita log dettagliati
MODEL_VERBOSE=true

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

Esegui con variabili di ambiente:

docker model run \
  -e MODEL_CONTEXT=8192 \
  -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 sulla 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 e i metadati del modello
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 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 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 Practice

Selezione Modello

# Usa modelli quantizzati per 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 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

Controlli di 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 Produzione

Per distribuzioni in produzione con Kubernetes, i contenitori Docker Model Runner possono essere orchestrati utilizzando manifest Kubernetes standard. 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 su 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 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 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 di sistema
docker model system info

# Utilizzo del 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 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 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

Fogli di Riferimento Correlati

Articoli di Confronto