Guía de configuración del tamaño de contexto del Docker Model Runner

Configure tamaños de contexto en Docker Model Runner con soluciones alternativas

Índice

Configuración de tamaños de contexto en Docker Model Runner es más compleja de lo que debería ser.

Aunque el parámetro context_size existe en la configuración de docker-compose, a menudo es ignorado por la imagen docker/model-runner:latest-cuda, que establece de forma predeterminada un tamaño de contexto de 4096 tokens. Esta guía explora las limitaciones y proporciona soluciones prácticas.

configurando coche Esta imagen fue generada por Flux 1 dev.

Entendiendo el problema

Al usar Docker Model Runner con docker-compose, podrías configurar el tamaño de contexto de esta manera:

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

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

Sin embargo, revisando los registros se revela el tamaño de contexto real que se está usando:

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

Verás una salida como:

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

La imagen docker/model-runner:latest-cuda está estableciendo de forma predeterminada --ctx-size 4096 al llamar a llama.cpp, ignorando completamente tu configuración context_size: 10240.

Por qué ocurre esto

El tamaño de contexto (n_ctx) se establece durante la inicialización del modelo en llama.cpp, el motor de inferencia subyacente que usa Docker Model Runner. Esto ocurre durante la fase de construcción del contexto del modelo, antes de que se procesen cualquier solicitud de API. La integración de Docker Model Runner con docker-compose parece tener un error donde no pasa correctamente el parámetro context_size desde la sección de modelos al proceso llama.cpp subyacente. En su lugar, se predetermina a 4096 tokens independientemente de tu configuración.

Esta limitación significa que, aunque Docker Compose reconoce el parámetro context_size en tu configuración YAML, la imagen docker/model-runner:latest-cuda no lo respeta al construir los argumentos de línea de comandos de llama.cpp. La bandera predeterminada --ctx-size 4096 tiene prioridad sobre cualquier configuración que especifiques.

Soluciones y alternativas

¿Qué hacer? Los métodos 1-2-3 funcionarán, pero tienen limitaciones.

Método 1. Ad-hoc, funcionará. Método 2. Establecido de forma predeterminada en el modelo. Método 3. Requerirá contenerización y poner tu propia aplicación en la composición. Eso está más cerca de la producción.

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

Puedes configurar el tamaño de contexto usando la CLI de Docker Model, que almacena la configuración en los metadatos de Docker:

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

Este comando actualiza la configuración del modelo, pero la implementación tiene limitaciones significativas. La configuración se almacena, pero no siempre se aplica correctamente.

Limitaciones:

  • No funciona cuando usas docker model run directamente, solo a través de curl al punto final de la API
  • No puedes usar docker model run después de configurar - lo ignorará
  • La configuración se ignora cuando usas docker-compose con la imagen docker/model-runner:latest-cuda
  • La configuración puede perderse cuando el modelo se actualiza o se vuelve a extraer

Este método funciona mejor para pruebas con llamadas directas a la API, pero no es adecuado para despliegues de producción usando docker-compose.

Método 2: Empaquetar tu propio modelo

La forma más confiable de establecer un tamaño de contexto personalizado es empaquetar tu propio modelo con el tamaño de contexto deseado usando docker model package. Esto graba el tamaño de contexto en los metadatos del modelo durante el empaquetamiento:

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

Esto crea un nuevo artefacto OCI (similar a una imagen de Docker) con el tamaño de contexto configurado de forma permanente. El modelo empaquetado puede luego ser subido a Docker Hub o cualquier registro compatible con OCI y extraído como cualquier otro modelo de Docker Model Runner.

Sin embargo, este enfoque requiere:

  • Acceso al archivo GGUF original (el formato cuantizado usado por llama.cpp)
  • Reempaquetar cada vez que desees cambiar el tamaño de contexto, lo cual puede ser muy consumidor de tiempo
  • Gestión de tu propio registro de modelos o cuenta de Docker Hub
  • Conocimiento del flujo de trabajo de empaquetamiento de Docker Model Runner

Este método es más adecuado para entornos de producción donde necesitas tamaños de contexto consistentes y reproducibles en todos los despliegues.

Método 3: Docker Compose

Esto está actualmente roto para docker/model-runner:latest-cuda

Pero para tu propia aplicación en la imagen podría funcionar :)

Aunque la sintaxis existe en 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

Esto no funciona - el parámetro context_size es reconocido por docker-compose pero no se aplica. El modelo aún usa 4096 tokens.

Método 4: Variables de entorno (También roto)

Intentando usar la variable de entorno MODEL_CONTEXT:

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

Esto tampoco funciona - la variable de entorno no se respeta al usar docker-compose.

Verificando el tamaño de contexto

Para comprobar qué tamaño de contexto se está usando realmente, examina los registros:

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

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

Verás una salida como:

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

Si ves n_ctx = 4096 a pesar de haber configurado un valor diferente, tu configuración está siendo ignorada.

Probando el tamaño de contexto

Para verificar si tu configuración de tamaño de contexto se está aplicando realmente, necesitas probar con promps que excedan el límite predeterminado de 4096 tokens. Aquí hay un script práctico usando Python para probar si tu configuración de tamaño de contexto está funcionando:

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

# Probar 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

# Verificar uso de tokens
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("✅ El tamaño de contexto es mayor que 4096!")
        else:
            print("⚠️ El tamaño de contexto parece estar limitado a 4096")
PYTHON

Soluciones alternativas

Si necesitas una configuración más flexible del tamaño de contexto, considera estas alternativas:

  • Ollama - Una solución alternativa de alojamiento de LLM que ofrece un mejor control sobre los tamaños de contexto y una configuración más sencilla. Ollama te permite especificar el tamaño de contexto por modelo y no tiene las mismas limitaciones de docker-compose.

  • Comparación entre Docker Model Runner y Ollama - Una comparación detallada de ambas soluciones, incluyendo capacidades de configuración de tamaño de contexto, rendimiento y cuándo elegir cada plataforma.

Recursos relacionados

Docker Model Runner

Docker y infraestructura

Soluciones alternativas de LLM

Documentación oficial

Conclusión

Configurar tamaños de contexto en Docker Model Runner es actualmente problemático al usar docker-compose. Aunque la sintaxis de configuración existe en la especificación de Docker Compose, no se implementa correctamente en la imagen docker/model-runner:latest-cuda, que establece de forma predeterminada un tamaño de contexto de 4096 tokens independientemente de tu configuración.

La solución más confiable es empaquetar tus propios modelos con el tamaño de contexto deseado usando docker model package, aunque esto añade complejidad a tu flujo de trabajo y requiere acceso a los archivos GGUF originales del modelo. Alternativamente, puedes usar docker model configure para el acceso directo a la API, pero esto no funciona con despliegues de docker-compose.

Para la mayoría de los casos de uso, el tamaño de contexto predeterminado de 4096 tokens es suficiente para aplicaciones típicas de inteligencia artificial conversacional. Si necesitas ventanas de contexto más grandes o una configuración más flexible, considera usar Ollama como alternativa, que ofrece un mejor control sobre los tamaños de contexto sin las limitaciones de docker-compose.

Todavía puedes optimizar el uso de VRAM mediante otros medios, como la cuantización del modelo (Q4, Q6, Q8) y la configuración de capas de GPU (MODEL_GPU_LAYERS), que son más efectivas para reducir el consumo de memoria que los ajustes de tamaño de contexto.

Para más detalles sobre la optimización de GPU y la gestión de VRAM, consulta nuestra guía sobre configuración de soporte de GPU NVIDIA.