Docker Model Runner: avviare LLM con Docker, senza Ollama

#Perché Docker Model Runner?

Docker Model Runner è la risposta di Docker a Ollama : un modo per eseguire dei LLM localmente senza lasciare l'ecosistema Docker. Non gestisci più un daemon separato né una cartella dedicata ai modelli — i modelli vengono distribuiti come artefatti OCI, recuperati da un registro esattamente come le immagini dei container, e gestiti da una nuova famiglia di comandi docker model.

Tecnicamente, il motore di inferenza di Model Runner è lo stesso di Ollama, di LM Studio o di Jan: llama.cpp. La differenza non è quindi la velocità bruta, ma l'integrazione. Se sul tuo computer o sul tuo server usi già Docker, Model Runner evita di aggiungere un altro strumento e permette ai tuoi container di comunicare in modo naturale con un modello locale.

Modelli in formato OCI

Un LLM si scarica, si gestisce in versioni e si carica nel registro come un'immagine Docker. Stesso registro, stessa autenticazione, stesse abitudini operative.

API compatibile con OpenAI

Endpoint /engines/v1/chat/completions, /completions, /models. Qualsiasi client OpenAI può connettersi cambiando l'URL di base.

Nessun strumento aggiuntivo necessario

Non serve installare anche Ollama. Basta la CLI docker e l'inferenza si integra con Compose.

GPU utilizzata direttamente

Il motore gira sull'host (Apple Silicon via Metal, NVIDIA via CUDA) e non all'interno di un container, per non perdere l'accelerazione.

#Prerequisiti

Docker Desktop recente

Model Runner è stato introdotto con Docker Desktop 4.40 (macOS Apple Silicon) e successivamente esteso a Windows con GPU NVIDIA. Aggiorna Docker Desktop all'ultima versione disponibile.

O Docker Engine su Linux

Su un server Linux senza Docker Desktop, Model Runner si installa tramite il pacchetto docker-model-plugin (vedi più avanti).

VRAM o memoria unificata

In Q4_K_M, considera circa 2 GB per un 3B, circa 5 GB per un 7B, circa 9 GB per un 14B, circa 19 GB per un 32B. Su Mac, la memoria unificata funge da VRAM.

Una GPU consigliata

RTX 3060 12 GB per iniziare, RTX 4070/4080 nella fascia media, RTX 4090 24 GB o un Mac M4 Pro (24-48 GB di memoria unificata) per i grandi modelli. Funziona anche con la sola CPU, ma lentamente.

#1. Attivare Docker Model Runner

La funzionalità non è sempre attiva di default. In Docker Desktop, si trova nelle impostazioni; dalla riga di comando, basta una singola istruzione.

1. 01
   Attraverso Docker Desktop

   Apri Settings → AI (o « Beta features » a seconda della versione), poi spunta « Enable Docker Model Runner ». Per chiamare l'API dall'host, attiva anche « Enable host-side TCP support » e annota la porta proposta (12434 per impostazione predefinita).
2. 02
   Via CLI

   Un comando attiva il servizio e, opzionalmente, apre la porta TCP sul lato host per raggiungere l'API dalla tua macchina senza passare attraverso un container.
3. 03
   Verificare

   docker model status confirme que le runner tourne. docker model version affiche la version du plugin installé.

# Activer Model Runner
docker desktop enable model-runner

# Activer + exposer l'API sur le port hôte 12434
docker desktop enable model-runner --tcp 12434

# Vérifier l'état
docker model status

Su un server Linux con Docker Engine (senza Docker Desktop), Model Runner si aggiunge come plugin. Su una distribuzione Debian/Ubuntu:

sudo apt-get update
sudo apt-get install docker-model-plugin

# Confirmer
docker model version

#2. Scaricare un modello in formato OCI

Docker ospita una libreria di modelli confezionati in formato OCI nel namespace ai/ di Docker Hub. Si scaricano esattamente come le immagini, con docker model pull. I tag codificano la dimensione e la quantizzazione del modello.

# Un petit modèle pour tester rapidement
docker model pull ai/smollm2

# Un modèle plus capable, tag explicite
docker model pull ai/qwen3.5

# Une variante quantifiée précise (taille + quantization)
docker model pull ai/gemma4:12B-Q4_K_M

# Lister ce qui est stocké localement
docker model ls

ai/smollm2

Modello molto piccolo, ideale per validare l'installazione in pochi secondi anche senza GPU.

ai/qwen3.5 · ai/gemma4 · ai/granite4.2

Modelli generalisti validi del 2026; scegli la dimensione in base alla tua VRAM (2B, 4B, 9B, 12B…). Qwen 3.5 9B (≈6,6 GB in Q4) è una buona scelta predefinita con 8 GB; tutti sono distribuiti con licenza Apache 2.0.

Tag di quantizzazione

Un tag come 9B-Q4_K_M specifica la dimensione e la compressione. Q4_K_M è il compromesso consigliato qualità/memoria; Q5_K_M e Q8_0 pesano di più.

Il formato OCI significa che questi modelli possono essere ospitati in qualsiasi registro compatibile: Docker Hub, ma anche un registro aziendale privato. Puoi quindi caricare un modello interno come carichi un'immagine, con la stessa autenticazione e le stesse politiche di accesso.

#3. Conversare con docker model run

Come docker run avvia un container, docker model run avvia una conversazione. Senza un messaggio passato come argomento, apre una chat interattiva nel terminale; con un prompt, risponde una volta e restituisce il controllo — perfetto per l'uso negli script.

# Chat interactif
docker model run ai/qwen3.5

# Prompt unique (mode « one-shot », scriptable)
docker model run ai/qwen3.5 "Explique le format OCI en une phrase."

La prima chiamata a un modello lo carica in memoria; le successive riutilizzano l'istanza caricata. Il motore rimuove automaticamente il modello dalla memoria dopo un periodo di inattività per liberare la VRAM, senza che tu debba gestire un daemon.

# Détails d'un modèle (taille, quantization, architecture)
docker model inspect ai/qwen3.5

# Logs du moteur d'inférence
docker model logs

# Supprimer un modèle pour récupérer de l'espace disque
docker model rm ai/smollm2

#4. API compatibile con OpenAI

Il vero punto di forza di Docker Model Runner, come di Ollama, è la sua API compatibile con quella di OpenAI. Ogni strumento progettato per l'API di OpenAI funziona semplicemente cambiando l'URL di base. Esistono due indirizzi a seconda di dove effettui la chiamata.

Dall'host (TCP)

http://localhost:12434/engines/v1/… si vous avez activé le support TCP côté hôte (port 12434 par défaut).

Da un container

http://model-runner.docker.internal/engines/v1/… — un nom DNS interne résolu automatiquement dans le réseau Docker.

Una chiamata chat diretta con curl dall'host, una volta attivata la porta TCP:

curl http://localhost:12434/engines/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ai/qwen3.5",
    "messages": [
      {"role": "system", "content": "Tu réponds en français, de façon concise."},
      {"role": "user", "content": "Qu'\''est-ce qu'\''un artefact OCI ?"}
    ]
  }'

Il campo model deve corrispondere a un modello scaricato localmente. Nell'SDK Python di OpenAI, basta reindirizzare base_url; la chiave API può essere qualsiasi stringa, Model Runner non la richiede in locale.

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:12434/engines/v1",
    api_key="docker",  # non vérifiée en local
)

resp = client.chat.completions.create(
    model="ai/qwen3.5",
    messages=[
        {"role": "user", "content": "Donne trois idées de noms pour un projet open source."}
    ],
)
print(resp.choices[0].message.content)

#5. Collegare un container al modello

Il vantaggio dell'integrazione Docker si vede qui: un container della tua applicazione può chiamare il modello tramite il DNS interno, senza esporre porte sull'host. Dal codice in esecuzione in un container, l'URL di base diventa model-runner.docker.internal.

curl http://model-runner.docker.internal/engines/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ai/qwen3.5",
    "messages": [{"role": "user", "content": "Bonjour"}]
  }'

In pratica, si passa l'URL tramite una variabile d'ambiente in modo che lo stesso codice funzioni localmente (porta 12434) e in un container (DNS interno). Un estratto di docker-compose.yml che inietta l'endpoint nel servizio applicativo:

services:
  app:
    build: .
    environment:
      OPENAI_BASE_URL: http://model-runner.docker.internal/engines/v1
      OPENAI_API_KEY: docker
      MODEL_NAME: ai/qwen3.5

#Docker Model Runner o Ollama, a seconda del tuo workflow

Entrambi eseguono llama.cpp ed espongono un'API compatibile con OpenAI. La scelta dipende dall'ecosistema in cui lavori, non dalle prestazioni pure.

Scegli Model Runner

Quando Docker è già la base della tua infrastruttura: vuoi che i tuoi container comunichino con il LLM tramite la rete Docker, vuoi distribuire modelli tramite un registro OCI privato ed evitare un altro strumento da installare e mantenere.

Scegli Model Runner

Per uno stack Compose in cui il modello è un servizio tra gli altri, versionato e distribuito con le stesse pratiche che usi per le tue immagini.

Resta su Ollama

Quando vuoi il catalogo di modelli più ampio e più aggiornato, una comunità numerosa e una documentazione ricca, e uno strumento che funziona allo stesso modo su Windows, macOS e Linux senza Docker Desktop.

Resta su Ollama

Per un uso semplice da ufficio, al di fuori di qualsiasi ambiente containerizzato, Ollama sulla porta 11434 resta la soluzione più diretta, con un ecosistema di interfacce (Open WebUI, LM Studio) già predisposto per collegarsi a Ollama.

#Risoluzione dei problemi

« docker: 'model' is not a docker command »

Il plugin non è installato o Model Runner non è attivato. Aggiorna Docker Desktop, attiva la funzionalità, o installa docker-model-plugin su Docker Engine.

L'API non risponde su localhost:12434

Il supporto TCP lato host non è attivo. Esegui di nuovo docker desktop enable model-runner --tcp 12434, oppure seleziona l'opzione in Settings → AI.

Un container non riesce a raggiungere il modello

Dall'interno di un contenitore, usa model-runner.docker.internal, non localhost: localhost punta sul contenitore stesso, non sull'host.

Caricamento lento o « out of memory »

Il modello supera la capacità della tua VRAM. Scarica una variante più leggera (tag Q4_K_M al posto di Q5/Q8) o un modello di dimensioni inferiori e verifica che la GPU venga rilevata correttamente.

La GPU non viene utilizzata (Windows)

Il supporto per le GPU NVIDIA su Windows è arrivato dopo la versione iniziale. Assicurati di usare una versione di Docker Desktop che lo supporti e che i tuoi driver siano aggiornati.

#Per approfondire

Docker Model Runner si apprezza meglio collegandolo agli altri componenti dell'IA locale già trattati sul sito:

Installare Ollama: Windows, macOS e Linux

Per fare un confronto concreto con l'alternativa di riferimento e la sua porta 11434, e decidere quale si adatta al tuo flusso di lavoro.

Q4, Q5, Q8: quale quantizzazione scegliere

Per leggere correttamente i tag dei modelli OCI (7B-Q4_K_M, ecc.) e valutare il compromesso tra qualità, velocità e memoria prima di scaricarli.

llama-server : un'API OpenAI locale con llama.cpp

Per vedere lo stesso motore esposto in altro modo, con un controllo più fine sull'offloading GPU.