Docker Model Runner: Guia de Configuração do Tamanho do Contexto

Configure tamanhos de contexto no Docker Model Runner com soluções alternativas

Conteúdo da página

Configurar tamanhos de contexto no Docker Model Runner é mais complexo do que deveria ser.

Embora o parâmetro context_size exista na configuração do docker-compose, muitas vezes é ignorado pela imagem docker/model-runner:latest-cuda, que define hardcoded um tamanho de contexto de 4096 tokens. Este guia explora as limitações e fornece soluções práticas.

configurando carro Esta imagem foi gerada por Flux 1 dev.

Entendendo o Problema

Ao usar Docker Model Runner com docker-compose, você pode configurar o tamanho do contexto da seguinte forma:

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

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

No entanto, verificando os logs, você verá o tamanho real do contexto sendo usado:

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

Você verá uma saída como:

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

A imagem docker/model-runner:latest-cuda está definindo hardcoded --ctx-size 4096 ao chamar o llama.cpp, ignorando completamente sua configuração context_size: 10240.

Por Que Isso Acontece

O tamanho do contexto (n_ctx) é definido no momento da inicialização do modelo no llama.cpp, o motor de inferência subjacente usado pelo Docker Model Runner. Isso acontece durante a fase de construção do contexto do modelo, antes de qualquer solicitação de API ser processada. A integração do Docker Model Runner com o docker-compose parece ter um bug onde não passa corretamente o parâmetro context_size da seção models para o processo underlying llama.cpp. Em vez disso, ele usa padrão 4096 tokens, independentemente da sua configuração.

Essa limitação significa que, embora o Docker Compose reconheça o parâmetro context_size em sua configuração YAML, a imagem docker/model-runner:latest-cuda não o respeita ao construir os argumentos da linha de comando do llama.cpp. A flag hardcoded --ctx-size 4096 tem precedência sobre qualquer configuração que você especifique.

Soluções e Trabalhos em Torno

O que fazer? Os métodos 1-2-3 funcionarão, mas têm limitações.

Método 1. ad-hoc, funcionará. Método 2. hardcoded no modelo. Método 3. requer containerização e colocar seu próprio app na composição. Isso está mais próximo da produção.

Método 1: Use docker model configure (Limitado)

Você pode configurar o tamanho do contexto usando o CLI do Docker Model, que armazena a configuração nos metadados do Docker:

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

Este comando atualiza a configuração do modelo, mas a implementação tem limitações significativas. A configuração é armazenada, mas nem sempre é aplicada corretamente.

Limitações:

  • Não funciona ao usar docker model run diretamente, apenas via curl para o ponto de extremidade da API
  • Você não pode usar docker model run após configurar - ele ignorará a configuração
  • A configuração é ignorada ao usar docker-compose com a imagem docker/model-runner:latest-cuda
  • A configuração pode ser perdida ao atualizar ou puxar novamente o modelo

Este método funciona melhor para testes com chamadas de API diretas, mas não é adequado para implantações de produção usando docker-compose.

Método 2: Empacote Seu Próprio Modelo

A maneira mais confiável de definir um tamanho de contexto personalizado é empacotar seu próprio modelo com o tamanho de contexto desejado usando docker model package. Isso grava o tamanho do contexto nos metadados do modelo durante o empacotamento:

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

Isso cria um novo artefato OCI (similar a uma imagem Docker) com o tamanho do contexto configurado permanentemente. O modelo empacotado pode então ser enviado para o Docker Hub ou qualquer registro compatível com OCI e puxado como qualquer outro modelo do Docker Model Runner.

No entanto, esta abordagem exige:

  • Acesso ao arquivo GGUF original (o formato quantizado usado pelo llama.cpp)
  • Reempacotamento sempre que quiser mudar o tamanho do contexto, o que pode ser demorado
  • Gerenciamento de seu próprio registro de modelos ou conta no Docker Hub
  • Conhecimento sobre o fluxo de trabalho de empacotamento do Docker Model Runner

Este método é mais adequado para ambientes de produção onde você precisa de tamanhos de contexto consistentes e reprodutíveis em todas as implantações.

Método 3: Docker Compose

Este método está quebrado atualmente para docker/model-runner:latest-cuda

Mas para seu próprio app na imagem pode funcionar :)

Embora a sintaxe exista no 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

Isso não funciona - o parâmetro context_size é reconhecido pelo docker-compose, mas não é aplicado. O modelo ainda usa 4096 tokens.

Método 4: Variáveis de Ambiente (Também Quebrado)

Tentando usar a variável de ambiente MODEL_CONTEXT:

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

Isso também não funciona - a variável de ambiente não é respeitada ao usar docker-compose.

Verificando o Tamanho do Contexto

Para verificar qual tamanho de contexto está sendo realmente usado, examine os logs:

# Verificar argumentos do llama.cpp
docker compose logs 2>&1 | grep "llamaCppArgs"

# Verificar tamanho de contexto real
docker compose logs 2>&1 | grep -i "n_ctx" | tail -10

Você verá uma saída como:

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

Se você ver n_ctx = 4096 apesar de configurar um valor diferente, sua configuração está sendo ignorada.

Testando o Tamanho do Contexto

Para verificar se sua configuração de tamanho do contexto está realmente sendo aplicada, você precisa testar com prompts que excedam o limite padrão de 4096 tokens. Aqui está um script prático usando Python para testar se sua configuração de tamanho do contexto está funcionando:

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

# Testar com 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

# Verificar uso de 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("✅ Janela de contexto é maior que 4096!")
        else:
            print("⚠️ Janela de contexto parece estar limitada a 4096")
PYTHON

Soluções Alternativas

Se você precisa de uma configuração mais flexível de tamanho de contexto, considere estas alternativas:

  • Ollama - Uma solução alternativa de hospedagem de LLM que oferece melhor controle sobre tamanhos de contexto e configuração mais simples. Ollama permite que você especifique o tamanho do contexto por modelo e não tem as mesmas limitações de docker-compose.

  • Comparação entre Docker Model Runner e Ollama - Uma comparação detalhada das duas soluções, incluindo capacidades de configuração de tamanho de contexto, desempenho e quando escolher cada plataforma.

Recursos Relacionados

Docker Model Runner

Docker e Infraestrutura

Soluções Alternativas de LLM

Documentação Oficial

Conclusão

Configurar tamanhos de contexto no Docker Model Runner está atualmente problemático ao usar docker-compose. Embora a sintaxe de configuração exista na especificação do Docker Compose, ela não é implementada corretamente na imagem docker/model-runner:latest-cuda, que define hardcoded um tamanho de contexto de 4096 tokens, independentemente da sua configuração.

A solução mais confiável é empacotar seus próprios modelos com o tamanho de contexto desejado usando docker model package, embora isso adicione complexidade ao seu fluxo de trabalho e exija acesso aos arquivos GGUF originais. Alternativamente, você pode usar docker model configure para acesso direto à API, mas isso não funciona com implantações de docker-compose.

Para a maioria dos casos de uso, o tamanho padrão de contexto de 4096 tokens é suficiente para aplicações típicas de IA conversacional. Se você precisar de janelas de contexto maiores ou de configuração mais flexível, considere usar Ollama como alternativa, que oferece melhor controle sobre tamanhos de contexto sem as limitações de docker-compose.

Você ainda pode otimizar o uso de VRAM por meio de outros meios, como quantização de modelos (Q4, Q6, Q8) e configuração de camadas de GPU (MODEL_GPU_LAYERS), que são mais eficazes para reduzir o consumo de memória do que ajustes no tamanho do contexto.

Para mais detalhes sobre otimização de GPU e gerenciamento de VRAM, veja nosso guia sobre configurar suporte a GPU NVIDIA.