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.

configurazione auto Quest’immagine è stata generata da Flux 1 dev.

Comprensione del 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 scopre 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é accade

La dimensione del contesto (n_ctx) viene impostata durante l’inizializzazione del modello in llama.cpp, il motore di inferenza sottostante utilizzato da Docker Model Runner. Questo avviene durante la fase di costruzione del contesto del modello, prima che vengano elaborate qualsiasi richiesta API. L’integrazione di Docker Model Runner con docker-compose sembra avere un bug in cui non passa correttamente il parametro context_size dalla sezione models al processo sottostante llama.cpp. Invece, predefinito a 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’indicatore hardcoded --ctx-size 4096 ha la precedenza su qualsiasi configurazione specificata.

Soluzioni alternative

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 composto del tuo 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 di Docker:

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

Questo comando aggiorna la configurazione del modello, ma l’implementazione ha limitazioni significative. 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 puoi 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 i deployment in produzione utilizzando docker-compose.

Metodo 2: Pacchetto del proprio modello

Il modo più affidabile per impostare una dimensione del contesto personalizzata è di pacchettizzare il proprio modello con la dimensione del contesto 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 a Docker Hub o a 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 molto tempo consumante
  • Gestione del proprio registro dei modelli o di un account Docker Hub
  • Comprensione del flusso di lavoro di pacchettizzazione di Docker Model Runner

Questo metodo è adatto per ambienti di produzione in cui si necessita di dimensioni del contesto coerenti e riproducibili in tutti i deployment.

Metodo 3: Docker Compose

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

Ma per il tuo 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 di ambiente (Anche rotto)

Provando a utilizzare la variabile di ambiente MODEL_CONTEXT:

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

Questo non funziona nemmeno - la variabile di 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 del contesto effettiva
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 testare se la tua configurazione della dimensione del contesto funziona:

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

# Test con 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 per l’hosting di 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 ha le stesse limitazioni di docker-compose.

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

Risorse correlate

Docker Model Runner

Docker e infrastruttura

Soluzioni alternative 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 è di 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 diretto all’API, ma non funziona con i deployment 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 nel ridurre il consumo di memoria rispetto agli aggiustamenti delle dimensioni del contesto comunque.

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