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

A configuração de tamanhos de contexto no Docker Model Runner é mais complexa do que deveria.

Embora o parâmetro context_size exista na configuração do docker-compose, ele é frequentemente ignorado pela imagem docker/model-runner:latest-cuda, que define um tamanho de contexto de 4096 tokens de forma estática. Este guia explora as limitações e oferece soluções práticas. Para uma comparação mais ampla do Docker Model Runner com Ollama, vLLM, LocalAI e provedores de nuvem — incluindo compensações de configuração e infraestrutura — consulte Hospedagem de LLM: Infraestrutura Local, Auto-hospedada e em Nuvem Comparadas.

configurando carro Esta imagem foi gerada por Flux 1 dev.

Compreendendo o Problema

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

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

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

No entanto, ao verificar os logs, revela-se o tamanho de contexto real sendo utilizado:

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

Você verá uma saída como esta:

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

A imagem docker/model-runner:latest-cuda está definindo --ctx-size 4096 de forma estática 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 utilizado pelo Docker Model Runner. Isso ocorre durante a fase de construção do contexto do modelo, antes que qualquer solicitação de API seja processada. A integração do compose do Docker Model Runner parece ter um bug onde não passa corretamente o parâmetro context_size da seção de modelos para o processo subjacente do llama.cpp. Em vez disso, ele define como padrão 4096 tokens, independentemente da sua configuração.

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

Soluções e Contornar

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. Definido de forma estática no modelo. Método 3. Requer containerização e a inclusão da sua própria aplicação na composição. Isso está mais próximo de produção.

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

Você pode configurar o tamanho do contexto usando a CLI do Docker Model, que armazena a configuração nos metadados do modelo 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:

  • Isso não funciona ao usar docker model run diretamente, apenas via curl para o endpoint da API
  • Você não pode usar docker model run após a configuração — 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 quando o modelo for atualizado ou puxado novamente

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

Método 2: Empacotar 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 incorpora o tamanho do contexto nos metadados do modelo no momento do 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 requer:

  • Acesso ao arquivo de modelo GGUF original (o formato quantizado usado pelo llama.cpp)
  • Reempacotamento sempre que você quiser alterar o tamanho do contexto, o que pode ser demorado
  • Gerenciamento do seu próprio registro de modelos ou conta no Docker Hub
  • Compreensão do 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 reproduzíveis entre implantações.

Método 3: Docker Compose

Isso está atualmente quebrado para docker/model-runner:latest-cuda

Mas para a sua própria aplicação 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á realmente sendo 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 esta:

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

Se você vir 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 de 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 de contexto está funcionando:

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

# Teste 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 tokens
python3 << 'PYTHON'
import json
with open('response.json') as f:
    r = json.load(f)
    if 'usage' in r:
        print(f"Tokens do prompt: {r['usage']['prompt_tokens']}")
        if r['usage']['prompt_tokens'] > 4096:
            print("✅ A janela de contexto é maior que 4096!")
        else:
            print("⚠️ A janela de contexto parece estar limitada a 4096")
PYTHON

Soluções Alternativas

Se você precisar de uma configuração de tamanho de contexto mais flexível, 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. O Ollama permite que você especifique o tamanho do contexto por modelo e não tem as mesmas limitações de docker-compose.

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

Para ver como o Docker Model Runner se encaixa com outras opções locais e em nuvem, consulte nosso guia Hospedagem de LLM: Infraestrutura Local, Auto-hospedada e em Nuvem Comparadas.

Recursos Relacionados

Docker Model Runner

Docker e Infraestrutura

Soluções Alternativas de LLM

Documentação Oficial

Conclusão

A configuração de tamanhos de contexto no Docker Model Runner é atualmente problemática 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 um tamanho de contexto de 4096 tokens de forma estática, independentemente da sua configuração.

O contorno 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 de modelo GGUF originais. Alternativamente, você pode usar docker model configure para acesso direto à API, mas isso não funciona com implantações docker-compose.

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

Você ainda pode otimizar o uso de VRAM através de outros meios, como quantização de modelo (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 os ajustes de tamanho de contexto de qualquer forma.

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

Assinar

Receba novos artigos sobre sistemas, infraestrutura e engenharia de IA.