Docker Model Runner: Guida alla configurazione della dimensione del contesto

Configurare le dimensioni del contesto in Docker Model Runner con soluzioni alternative

Indice

Configurazione delle dimensioni del contesto in Docker Model Runner è più complessa di quanto dovrebbe essere.

Sebbene il parametro context_size esista nella configurazione docker-compose, spesso viene ignorato dall’immagine docker/model-runner:latest-cuda, che imposta in modo hardcoded una dimensione del contesto di 4096 token. Questa guida esplora le limitazioni e fornisce soluzioni pratiche. Per un confronto più ampio tra Docker Model Runner e Ollama, vLLM, LocalAI e i provider cloud – incluso il confronto tra configurazione e trade-off infrastrutturali – vedi LLM Hosting: Local, Self-Hosted & Cloud Infrastructure Compared.

configurazione auto Questa immagine è stata generata da Flux 1 dev.

Comprendere il problema

Utilizzando Docker Model Runner con docker-compose, potresti configurare la dimensione del contesto in questo modo:

services:
  llm:
    image: docker/model-runner:latest-cuda
    models:
      - llm_model

models:
  llm_model:
    model: ai/gemma3-qat:4B
    context_size: 10240

Tuttavia, controllando i log si osserva la dimensione del contesto effettivamente utilizzata:

docker compose logs 2>&1 | grep -i "n_ctx"

Vedrai un output simile a:

llamaCppArgs: [... --ctx-size 4096 ...]
llama_context: n_ctx = 4096

L’immagine docker/model-runner:latest-cuda imposta in modo hardcoded --ctx-size 4096 quando chiama llama.cpp, ignorando completamente la tua configurazione context_size: 10240.

Perché succede

La dimensione del contesto (n_ctx) viene impostata durante l’inizializzazione del modello in llama.cpp, l’engine di inferenza sottostante utilizzato da Docker Model Runner. Questo avviene durante la fase di costruzione del contesto del modello, prima che vengano processate le richieste API. L’integrazione di Docker Model Runner con docker-compose sembra presentare un bug in cui non viene correttamente passato il parametro context_size dalla sezione models al processo sottostante llama.cpp. Invece, si imposta di default su 4096 token, indipendentemente dalla tua configurazione.

Questo limite significa che, anche se Docker Compose riconosce il parametro context_size nella tua configurazione YAML, l’immagine docker/model-runner:latest-cuda non lo rispetta quando costruisce gli argomenti della riga di comando per llama.cpp. L’indicazione hardcoded --ctx-size 4096 ha la precedenza su qualsiasi configurazione specificata.

Soluzioni e workaround

Cosa fare? I metodi 1-2-3 funzioneranno, ma hanno limitazioni.

Metodo 1. ad-hoc, funzionerà. Metodo 2. hardcoded nel modello. Metodo 3. richiede la containerizzazione e l’inserimento nel composition del proprio app. Questo è più vicino alla produzione.

Metodo 1: Utilizzare docker model configure (Limitato)

Puoi configurare la dimensione del contesto utilizzando il CLI di Docker Model, che memorizza la configurazione nei metadati del modello di Docker:

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

Questo comando aggiorna la configurazione del modello, ma l’implementazione presenta significative limitazioni. La configurazione viene memorizzata ma non sempre applicata correttamente.

Limitazioni:

  • Non funziona quando si utilizza docker model run direttamente, solo tramite curl all’endpoint API
  • Non è possibile utilizzare docker model run dopo la configurazione – la ignorerà
  • La configurazione viene ignorata quando si utilizza docker-compose con l’immagine docker/model-runner:latest-cuda
  • La configurazione potrebbe essere persa quando il modello viene aggiornato o richiamato nuovamente

Questo metodo funziona meglio per i test con chiamate API dirette, ma non è adatto per le distribuzioni in produzione utilizzando docker-compose.

Metodo 2: Pacchettizzare il proprio modello

Il modo più affidabile per impostare una dimensione del contesto personalizzata è pacchettizzare il proprio modello con la dimensione desiderata utilizzando docker model package. Questo imposta la dimensione del contesto nei metadati del modello durante la fase di pacchettizzazione:

docker model package \
  --gguf /path/to/model.gguf \
  --context-size 10240 \
  --name my-model:custom-context

Questo crea un nuovo artefatto OCI (simile a un’immagine Docker) con la dimensione del contesto configurata in modo permanente. Il modello pacchettizzato può quindi essere spedito su Docker Hub o qualsiasi registro compatibile con OCI e richiamato come qualsiasi altro modello Docker Model Runner.

Tuttavia, questo approccio richiede:

  • Accesso al file GGUF originale (il formato quantizzato utilizzato da llama.cpp)
  • Ripacchettizzazione ogni volta che si desidera modificare la dimensione del contesto, che può essere tempo consumante
  • Gestione del proprio registro dei modelli o di un account Docker Hub
  • Conoscenza del flusso di lavoro di pacchettizzazione di Docker Model Runner

Questo metodo è adatto per ambienti di produzione dove si necessita di dimensioni del contesto coerenti e riproducibili in ogni distribuzione.

Metodo 3: Docker Compose

Questo è attualmente rotto per docker/model-runner:latest-cuda

Ma per il proprio app nell’immagine potrebbe funzionare :)

Sebbene la sintassi esista in docker-compose.yml:

services:
  llm:
    image: docker/model-runner:latest-cuda
    models:
      - llm_model

models:
  llm_model:
    model: ai/gemma3-qat:4B
    context_size: 10240

Questo non funziona – il parametro context_size è riconosciuto da docker-compose ma non applicato. Il modello utilizza comunque 4096 token.

Metodo 4: Variabili d’ambiente (Anche rotto)

Provando a utilizzare la variabile d’ambiente MODEL_CONTEXT:

services:
  llm:
    image: docker/model-runner:latest-cuda
    environment:
      - MODEL_CONTEXT=10240

Questo non funziona nemmeno – la variabile d’ambiente non è rispettata quando si utilizza docker-compose.

Verifica della dimensione del contesto

Per controllare quale dimensione del contesto viene effettivamente utilizzata, esamina i log:

# Controlla gli argomenti di llama.cpp
docker compose logs 2>&1 | grep "llamaCppArgs"

# Controlla la dimensione effettiva del contesto
docker compose logs 2>&1 | grep -i "n_ctx" | tail -10

Vedrai un output simile a:

llamaCppArgs: [-ngl 999 --metrics --model /models/... --ctx-size 4096 ...]
llama_context: n_ctx = 4096
llama_context: n_ctx_per_seq = 4096

Se vedi n_ctx = 4096 nonostante tu abbia configurato un valore diverso, la tua configurazione viene ignorata.

Test della dimensione del contesto

Per verificare se la tua configurazione della dimensione del contesto viene effettivamente applicata, devi testare con prompt che superano il limite predefinito di 4096 token. Ecco uno script pratico utilizzando Python per verificare se la tua configurazione della dimensione del contesto funziona:

#!/bin/bash
MODEL="ai/gemma3-qat:4B"
PORT=8085

# Test con un prompt grande
python3 -c "print('test ' * 5000)" > large_prompt.txt

python3 << 'PYTHON' > request.json
import json
import os

with open('large_prompt.txt', 'r') as f:
    large_prompt = f.read().strip()

request = {
    "model": os.environ.get("MODEL", "ai/gemma3-qat:4B"),
    "messages": [{
        "role": "user",
        "content": large_prompt
    }]
}
print(json.dumps(request))
PYTHON

curl -s http://localhost:${PORT}/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d @request.json > response.json

# Controlla l'utilizzo dei token
python3 << 'PYTHON'
import json
with open('response.json') as f:
    r = json.load(f)
    if 'usage' in r:
        print(f"Prompt tokens: {r['usage']['prompt_tokens']}")
        if r['usage']['prompt_tokens'] > 4096:
            print("✅ La finestra del contesto è più grande di 4096!")
        else:
            print("⚠️ La finestra del contesto sembra limitata a 4096")
PYTHON

Soluzioni alternative

Se necessiti di una configurazione più flessibile delle dimensioni del contesto, considera queste alternative:

  • Ollama – Un’alternativa alla soluzione di hosting degli LLM che offre un controllo migliore sulle dimensioni del contesto e una configurazione più semplice. Ollama ti permette di specificare la dimensione del contesto per modello e non presenta le stesse limitazioni di docker-compose.

  • Confronto tra Docker Model Runner e Ollama – Un confronto dettagliato tra le due soluzioni, inclusi le capacità di configurazione delle dimensioni del contesto, le prestazioni e quando scegliere ciascuna piattaforma.

Per vedere come Docker Model Runner si adatta ad altre opzioni locali e cloud, consulta la nostra guida LLM Hosting: Local, Self-Hosted & Cloud Infrastructure Compared.

Risorse correlate

Docker Model Runner

Docker e infrastruttura

Soluzioni alternative per LLM

Documentazione ufficiale

Conclusione

La configurazione delle dimensioni del contesto in Docker Model Runner è attualmente problematica quando si utilizza docker-compose. Sebbene la sintassi di configurazione esista nella specifica di Docker Compose, non è implementata correttamente nell’immagine docker/model-runner:latest-cuda, che imposta in modo hardcoded una dimensione del contesto di 4096 token indipendentemente dalla tua configurazione.

La soluzione più affidabile è pacchettizzare i propri modelli con la dimensione del contesto desiderata utilizzando docker model package, anche se questo aggiunge complessità al tuo flusso di lavoro e richiede l’accesso ai file GGUF originali. Alternativamente, puoi utilizzare docker model configure per l’accesso API diretto, ma questa non funziona con le distribuzioni docker-compose.

Per la maggior parte dei casi d’uso, la dimensione predefinita del contesto di 4096 token è sufficiente per le applicazioni tipiche di AI conversazionale. Se necessiti di finestre del contesto più ampie o di una configurazione più flessibile, considera l’utilizzo di Ollama come alternativa, che offre un controllo migliore sulle dimensioni del contesto senza le limitazioni di docker-compose.

Puoi comunque ottimizzare l’utilizzo della VRAM attraverso altri mezzi, come la quantizzazione del modello (Q4, Q6, Q8) e la configurazione delle layer GPU (MODEL_GPU_LAYERS), che sono più efficaci per ridurre il consumo di memoria rispetto agli aggiustamenti delle dimensioni del contesto.

Per ulteriori dettagli sull’ottimizzazione della GPU e la gestione della VRAM, consulta la nostra guida su configurazione del supporto NVIDIA GPU.