Почему параметр context_size в docker-compose.yml не работает с образом docker/model-runner?

Изображение docker/model-runner:latest-cuda жестко задает –ctx-size 4096 при вызове llama.cpp, игнорируя параметр context_size в разделе моделей. Это известное ограничение текущей реализации.

Можно ли изменить размер контекста для каждого запроса API?

Нет, размер контекста устанавливается на этапе инициализации модели, а не для каждого запроса. Вы можете контролировать только длину вывода с помощью параметра max_tokens в API-запросах.

Работает ли параметр –context-size в команде docker model configure?

Да, но только при прямом запуске с использованием docker model run. Настройки игнорируются при использовании docker-compose с образом docker/model-runner.

Как можно проверить фактический размер контекста, который используется?

Проверьте логи docker compose с помощью команды docker compose logs 2>&1 | grep -i "n_ctx" , чтобы увидеть фактический размер контекста (n_ctx), который использует llama.cpp.

Как лучше всего использовать пользовательские размеры контекста?

Упакуйте свою модель с помощью docker model package –context-size или используйте docker model configure для прямых команд docker model run. Для docker-compose, возможно, придется подождать будущих обновлений, которые правильно поддерживают context_size.

Почему размер контекста важен для использования видеопамяти?

Более крупные размеры контекста требуют большего объема VRAM. Однако с docker/model-runner размер контекста фиксирован на уровне 4096, поэтому использование VRAM в основном определяется размером модели, уровнем квантования и количеством GPU-слоев (MODEL_GPU_LAYERS).

Руководство по настройке размера контекста Docker Model Runner

Настройка размеров контекста в Docker Model Runner с обходными путями

Содержимое страницы

Настройка размеров контекста в Docker Model Runner сложнее, чем должно быть.

Хотя параметр context_size существует в конфигурации docker-compose, он часто игнорируется образом docker/model-runner:latest-cuda, который жестко задает размер контекста 4096 токенов. Это руководство исследует ограничения и предлагает практические обходные пути.

настройка автомобиля Это изображение было сгенерировано Flux 1 dev.

Понимание проблемы

При использовании Docker Model Runner с docker-compose вы можете настроить размер контекста следующим образом:

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

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

Однако проверка логов показывает фактический используемый размер контекста:

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

Вы увидите вывод, подобный:

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

Образ docker/model-runner:latest-cuda жестко задает --ctx-size 4096 при вызове llama.cpp, полностью игнорируя вашу конфигурацию context_size: 10240.

Почему это происходит

Размер контекста (n_ctx) устанавливается в момент инициализации модели в llama.cpp, движке инференса, который использует Docker Model Runner. Это происходит во время фазы построения контекста модели, до обработки любых API-запросов. Интеграция Docker Model Runner с compose, по-видимому, имеет баг, при котором параметр context_size из раздела models не передается правильно в процесс llama.cpp. Вместо этого он по умолчанию использует 4096 токенов, независимо от вашей конфигурации.

Это ограничение означает, что хотя Docker Compose распознает параметр context_size в вашем YAML-файле, образ docker/model-runner:latest-cuda не учитывает его при построении аргументов командной строки для llama.cpp. Жестко заданный флаг --ctx-size 4096 имеет приоритет над любой указанной вами конфигурацией.

Обходные пути и решения

Что делать? Методы 1-2-3 будут работать, но у них есть ограничения.

Метод 1. временный, будет работать. Метод 2. жестко задан в модели. Метод 3. требует контейнеризации и добавления вашего приложения в состав. Это ближе к производству.

Метод 1: Использование `docker model configure` (Ограниченный)

Вы можете настроить размер контекста с помощью CLI Docker Model, который сохраняет конфигурацию в метаданных модели Docker:

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

Эта команда обновляет конфигурацию модели, но реализация имеет значительные ограничения. Конфигурация сохраняется, но не всегда применяется правильно.

Ограничения:

Это не работает при использовании docker model run напрямую, только через curl к API-эндпоинту
Вы не можете использовать docker model run после настройки - он проигнорирует конфигурацию
Конфигурация игнорируется при использовании docker-compose с образом docker/model-runner:latest-cuda
Конфигурация может быть потеряна при обновлении или повторном получении модели

Этот метод лучше всего подходит для тестирования с прямыми вызовами API, но не подходит для производственных развертываний с использованием docker-compose.

Метод 2: Упаковка собственной модели

Самый надежный способ установить пользовательский размер контекста - упаковать свою модель с нужным размером контекста с помощью docker model package. Это “запекает” размер контекста в метаданные модели на этапе упаковки:

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

Это создает новый OCI-артефакт (похожий на образ Docker) с размером контекста, настроенным навсегда. Упакованная модель затем может быть отправлена в Docker Hub или любой OCI-совместимый реестр и получена как любая другая модель Docker Model Runner.

Однако этот подход требует:

Доступа к исходному файлу модели в формате GGUF (квантованный формат, используемый llama.cpp)
Переупаковки каждый раз, когда вы хотите изменить размер контекста, что может быть долгим процессом
Управления своим собственным реестром моделей или аккаунтом Docker Hub
Понимания процесса упаковки Docker Model Runner

Этот метод лучше всего подходит для производственных сред, где требуется согласованный, воспроизводимый размер контекста при развертывании.

Метод 3: Docker Compose

Это сейчас не работает для docker/model-runner:latest-cuda

Но для вашего приложения в образе может сработать :)

Хотя синтаксис существует в 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

Это не работает - параметр context_size распознается docker-compose, но не применяется. Модель все еще использует 4096 токенов.

Метод 4: Переменные окружения (Также не работает)

Попытка использования переменной окружения MODEL_CONTEXT:

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

Это тоже не работает - переменная окружения не учитывается при использовании docker-compose.

Проверка размера контекста

Чтобы проверить, какой размер контекста действительно используется, просмотрите логи:

# Проверка аргументов llama.cpp
docker compose logs 2>&1 | grep "llamaCppArgs"

# Проверка фактического размера контекста
docker compose logs 2>&1 | grep -i "n_ctx" | tail -10

Вы увидите вывод, подобный:

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

Если вы видите n_ctx = 4096 несмотря на настройку другого значения, ваша конфигурация игнорируется.

Тестирование размера контекста

Чтобы проверить, действительно ли ваша конфигурация размера контекста применяется, вам нужно протестировать ее с подсказками, превышающими лимит в 4096 токенов по умолчанию. Вот практический скрипт на Python, чтобы проверить, работает ли ваша конфигурация размера контекста:

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

# Тест с большой подсказкой
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

# Проверка использования токенов
python3 << 'PYTHON'
import json
with open('response.json') as f:
    r = json.load(f)
    if 'usage' in r:
        print(f"Токены подсказки: {r['usage']['prompt_tokens']}")
        if r['usage']['prompt_tokens'] > 4096:
            print("✅ Окно контекста больше 4096!")
        else:
            print("⚠️ Окно контекста, похоже, ограничено 4096")
PYTHON

Альтернативные решения

Если вам нужна более гибкая настройка размера контекста, рассмотрите эти альтернативы:

Ollama - Альтернативное решение для хостинга LLM, предоставляющее лучший контроль над размерами контекста и более простую конфигурацию. Ollama позволяет указывать размер контекста для каждой модели и не имеет таких ограничений docker-compose.
Сравнение Docker Model Runner и Ollama - Подробное сравнение обоих решений, включая возможности настройки размера контекста, производительность и когда выбирать каждую платформу.

Связанные ресурсы

Docker Model Runner

Шпаргалка Docker Model Runner - Полное руководство по командам с примерами для всех операций Docker Model Runner
Добавление поддержки GPU NVIDIA в Docker Model Runner - Пошаговое руководство по включению ускорения GPU
Docker Model Runner vs Ollama: что выбрать?

Docker и инфраструктура

Шпаргалка Docker - Основные команды Docker для управления контейнерами
Шпаргалка Docker Compose - Полное руководство по конфигурации и командам Docker Compose

Альтернативные решения LLM

Шпаргалка Ollama - Альтернативное решение для хостинга LLM с встроенной поддержкой GPU и более простой настройкой размера контекста
Интеграция Ollama с Python

Официальная документация

Документация Docker Model Runner - Официальная документация Docker для Model Runner
Конфигурация контекста llama.cpp - Документация движка инференса

Заключение

Настройка размеров контекста в Docker Model Runner в настоящее время вызывает проблемы при использовании docker-compose. Хотя синтаксис конфигурации присутствует в спецификации Docker Compose, он не реализован должным образом в образе docker/model-runner:latest-cuda, который жестко задает размер контекста 4096 токенов, независимо от вашей конфигурации.

Наиболее надежный обходной путь — упаковывать свои собственные модели с нужным размером контекста с помощью docker model package, хотя это добавляет сложности в ваш рабочий процесс и требует доступа к исходным файлам модели GGUF. Альтернативно, вы можете использовать docker model configure для прямого доступа к API, но это не работает с развертываниями docker-compose.

Для большинства случаев использования размер контекста 4096 токенов по умолчанию достаточен для типичных приложений конверсионного ИИ. Если вам нужны более крупные окна контекста или более гибкая настройка, рассмотрите использование Ollama в качестве альтернативы, которая предоставляет лучший контроль над размерами контекста без ограничений docker-compose.

Вы все еще можете оптимизировать использование VRAM другими способами, такими как квантование моделей (Q4, Q6, Q8) и настройка конфигурации GPU (MODEL_GPU_LAYERS), которые более эффективны для снижения потребления памяти, чем настройки размера контекста.

Для получения более подробной информации об оптимизации GPU и управлении VRAM см. наше руководство по настройке поддержки NVIDIA GPU.