vLLM Docker: архитектура, производительность и руководство по облачному развёртыванию

vLLM Docker: архитектура, производительность и руководство по облачному развёртыванию

Docker — самый прямой способ разместить vLLM за OpenAI-совместимым endpoint на GPU, которыми вы управляете. Однако хорошее развёртывание vLLM Docker — это не просто команда docker run: ему необходимы совместимая среда выполнения GPU, ограниченный план памяти и параллелизма, аутентификация на периметре и воспроизводимый способ тестирования производительности до поступления трафика.

В этом руководстве рассматриваются архитектура, безопасное первое развёртывание, параметры, которые действительно меняют ёмкость, и путь от одного GPU до облачного парка GPU.

Используйте vLLM Docker, когда вам нужен контроль над весами модели, местом развёртывания, настройками среды выполнения или постоянной самостоятельно размещённой нагрузкой. Если операционные затраты перевешивают этот контроль, управляемый API модели или унифицированный шлюз часто становятся лучшей границей.

Что даёт vLLM Docker

vLLM публикует официальный Docker-образ vllm/vllm-openai, который запускает OpenAI-совместимый сервер. Благодаря этому vLLM Docker служит полезным мостом между репозиторием модели и приложениями, уже использующими формат клиента OpenAI: список моделей, завершения чата, завершения, эмбеддинги и связанные совместимые endpoint зависят от развёрнутых версии модели и сервера. В документации vLLM по Docker приведены актуальные примеры образов и среды выполнения.

Практический вывод прост: вашему приложению не нужен специализированный клиент модельного сервера только потому, что вы переносите нагрузку на собственный GPU. Тем не менее ему по-прежнему нужны явно заданные имя модели, API-ключ, тайм-аут и поведение повторных попыток, соответствующее вашей целевой доступности.

Как работает архитектура vLLM Docker

На высоком уровне vLLM Docker состоит из пяти слоёв:

1. Ваш клиент отправляет аутентифицированный запрос к OpenAI-совместимому endpoint.
2. API-сервер проверяет и токенизирует запрос, затем передаёт его движку vLLM.
3. Планировщик объединяет совместимую работу в пакеты и направляет её одному или нескольким GPU-воркерам.
4. GPU-воркеры хранят веса модели и кеш «ключ—значение» (KV) во время генерации токенов.
5. Ответ передаётся потоком обратно через API-сервер к клиенту.

Центральная идея производительности — PagedAttention. Вместо резервирования одной большой непрерывной области KV-кеша для максимально возможной длины запроса vLLM управляет состоянием KV блоками. Это упрощает размещение нагрузок переменной длины в доступной памяти и позволяет завершённым запросам освобождать блоки для последующей работы. В исходной статье о PagedAttention описываются планировщик, GPU-воркеры, логические и физические KV-блоки, а также компромисс между использованием кеша и пакетированием.

У этой архитектуры есть важное операционное следствие: VRAM — это не только «размер модели». Она совместно используется весами модели, накладными расходами среды выполнения, активациями и KV-кешем, потребность в котором растёт с длиной контекста и числом одновременных запросов. Рассматривайте контекст, параллелизм и использование памяти как одно решение, а не как три отдельные задачи настройки.

Перед запуском vLLM Docker на облачном GPU

Начните с четырёх проверок:

1. Выберите протестированный тег образа. В production закрепляйте тег релиза vLLM, а не следуйте вслепую за latest. Прежде чем полагаться на флаг или значение по умолчанию, прочитайте документацию, соответствующую этому тегу.
2. Используйте модель, которую вам разрешено скачивать и обслуживать. Некоторые репозитории требуют токен Hugging Face или принятия лицензии модели. После проверки закрепите ревизию модели.
3. Проверьте доступ к GPU вне контейнера модели. Установите драйвер NVIDIA на хосте и NVIDIA Container Toolkit, затем проверьте контейнер с поддержкой GPU с помощью nvidia-smi. В руководстве по установке NVIDIA описаны предварительные требования на стороне хоста и настройка среды выполнения.
4. Сначала держите порт закрытым. Для подтверждения концепции на одном хосте привяжитесь к loopback либо разместите сервис в частной подсети за TLS, аутентификацией и обратным прокси-сервером/балансировщиком нагрузки. Не рассматривайте сервер базовой модели как границу безопасности для доступа из интернета.

Используйте пример команды NVIDIA, прежде чем отлаживать сам vLLM:

docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi

Если эта команда не видит ожидаемый GPU, остановитесь на этом этапе. Лог модельного сервера не исправит отсутствующий драйвер, ненастроенную среду выполнения контейнера или GPU, который так и не был назначен облачной ВМ.

Запуск Docker-сервера vLLM с одним GPU

Ниже приведён намеренно небольшой стартовый пример. Он повторяет шаблон официального образа, но добавляет API-ключ и привязывает опубликованный порт к loopback-интерфейсу. Замените заполнители на модель и тег образа, которые вы протестировали.

export HF_TOKEN="your_hugging_face_token"
export VLLM_API_KEY="replace-with-a-long-random-secret"
export VLLM_IMAGE="vllm/vllm-openai:<tested-version>"
export MODEL="Qwen/Qwen3-0.6B"

docker run -d \
  --name vllm-api \
  --restart unless-stopped \
  --runtime=nvidia \
  --gpus all \
  --ipc=host \
  -p 127.0.0.1:8000:8000 \
  -v "$HOME/.cache/huggingface:/root/.cache/huggingface" \
  -e HF_TOKEN \
  -e VLLM_API_KEY \
  "$VLLM_IMAGE" \
  --model "$MODEL" \
  --dtype auto \
  --api-key "$VLLM_API_KEY"

Настройка общей памяти и монтирование кэша Hugging Face соответствуют официальному примеру vLLM Docker. Монтирование кэша позволяет не загружать повторно те же веса модели при пересоздании контейнера. API-ключ является средством контроля на уровне приложения, а не заменой сетевой изоляции, TLS, ограничений скорости или менеджера секретов.

Прежде чем подключать приложение, убедитесь, что сервер обслуживает ожидаемую модель:

curl --fail --silent --show-error \
  http://127.0.0.1:8000/v1/models \
  -H "Authorization: Bearer $VLLM_API_KEY"

Затем отправьте небольшой запрос с тем же идентификатором модели, который возвращает /v1/models:

curl --fail --silent --show-error \
  http://127.0.0.1:8000/v1/chat/completions \
  -H "Authorization: Bearer $VLLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen3-0.6B",
    "messages": [{"role": "user", "content": "Reply with the word ready."}],
    "max_tokens": 16
  }'

Если ваша модель не содержит пригодного шаблона чата, запросы chat-completion могут завершаться ошибкой, даже если контейнер запустился. vLLM документирует, как указать --chat-template для моделей, в конфигурации токенизатора которых он отсутствует; протестируйте это до развёртывания приложения. См. рекомендации по шаблонам чата.

Определите границы производительности перед изменением флагов

Универсально правильной команды vLLM Docker не существует. Подходящая конфигурация зависит от архитектуры модели, типа и объёма памяти GPU, распределения длины ввода/вывода, параллелизма и целевых показателей задержки. Создайте базовый уровень на репрезентативной нагрузке, затем меняйте по одной переменной за раз.

Зафиксируйте как минимум следующие метрики:

• Долю успешных запросов и ошибок, а также события перезапуска/OOM.
• Время до первого токена (TTFT) и время на выходной токен (TPOT) с сегментацией по длине промпта.
• Сквозную задержку на p50 и p95/p99 при ожидаемом параллелизме.
• Входные токены, выходные токены, время в очереди, активные запросы и использование памяти GPU.
• Пропускную способность — только вместе с целевыми показателями задержки и качества, которым она соответствовала.

Флаги vLLM Docker, существенно влияющие на ёмкость

Точные значения по умолчанию и поведение опций зависят от версии. В актуальном справочнике аргументов движка vLLM определены элементы управления планировщиком, кэшем, параллелизмом и очередью; в его справочнике конфигурации кэша объясняются настройки использования памяти и кэша префиксов.

Практический порядок настройки

1. Задайте реалистичное значение --max-model-len с учётом ограничений приложения.
2. Начните с консервативного уровня использования памяти, оставив запас для накладных расходов драйвера и среды выполнения.
3. Проведите нагрузочное тестирование --max-num-seqs и --max-num-batched-tokens с реальными длинами промптов и генерируемых ответов.
4. Добавляйте тензорный параллелизм только тогда, когда модель не помещается на одном GPU или один GPU не позволяет достичь целевых показателей её работы.
5. Добавляйте реплики за балансировщиком нагрузки, когда требования к доступности или совокупному трафику предполагают наличие независимых зон отказа.

Такая последовательность помогает избежать распространённой ошибки: добавления GPU или повышения уровня параллелизма до того, как выяснено, чем именно ограничена рабочая нагрузка — контекстом, очередью, памятью или вычислительными ресурсами.

Масштабирование vLLM Docker на несколько GPU

Для одной модели, которой требуется несколько GPU, vLLM поддерживает обслуживание с тензорным и конвейерным параллелизмом. На одном хосте предоставьте контейнеру доступ к GPU и установите размер тензорного параллелизма равным количеству GPU, которые вы выделили этому серверу модели:

docker run -d \
  --name vllm-tp \
  --restart unless-stopped \
  --runtime=nvidia \
  --gpus all \
  --ipc=host \
  -p 127.0.0.1:8000:8000 \
  -v "$HOME/.cache/huggingface:/root/.cache/huggingface" \
  -e HF_TOKEN \
  -e VLLM_API_KEY \
  "$VLLM_IMAGE" \
  --model "$MODEL" \
  --tensor-parallel-size 4 \
  --api-key "$VLLM_API_KEY"

В руководстве vLLM по параллелизму и масштабированию описаны тензорный и конвейерный параллелизм, а также варианты выполнения на одном и нескольких узлах. Не копируйте значение 4 из примера на узел с двумя GPU: укажите в параметре количество GPU, выделенных этому серверу, и проверьте топологию межсоединений, баланс памяти и поведение при сбоях.

Подробнее о реализации, проверке топологии и выборе между тензорным и конвейерным параллелизмом см. в руководстве Flatkey по инференсу vLLM на нескольких GPU. Если вы выбираете среду выполнения для обслуживания моделей, а не способ развёртывания Docker, см. vLLM vs. SGLang.

Архитектура облачного развёртывания для production

При развёртывании vLLM Docker в production общедоступный пограничный уровень обычно отделяют от уровня выполнения на GPU:

Разместите кэш Hugging Face в постоянном или предварительно прогретом хранилище, чтобы обычный перезапуск не привёл к неожиданной загрузке модели. Зафиксируйте лицензию модели и правила управления доступом в документации по развёртыванию. Одной фиксации тега образа недостаточно, если репозиторий модели указывает на изменяемую ветку.

Для получения дополнительной информации о выборе GPU, планировании памяти с учётом длины контекста и случаях, когда облачная инфраструктура подходит лучше всего, добавьте в этот регламент ссылки на руководство Flatkey по требованиям LLM к памяти GPU, руководство по GPU cloud и материал для выбора между GPU cloud и API моделей.

Диагностика неполадок vLLM Docker без догадок

Если сервер запускается, но поведение приложения всё ещё отличается от размещённого API, явно проверьте совместимость конечных точек и параметров. В руководстве Flatkey по серверу инференса, совместимому с OpenAI рассматриваются миграция на стороне клиента и область тестирования совместимости.

Когда не стоит самостоятельно эксплуатировать vLLM Docker

Самостоятельный хостинг — это обязательства по инфраструктуре. Вы отвечаете за обновления образов, происхождение моделей, ёмкость GPU, сбои узлов, контроль доступа, проверку задержек и порядок действий дежурной команды. Это может быть правильным компромиссом, когда требуется контроль над средой выполнения.

Для рабочих нагрузок, где выбор модели, доступность провайдера или простота эксплуатации важнее прямого контроля GPU, сохраните в архитектуре путь через управляемый API. Flatkey разработан для дополняющего сценария: единая интеграция, совместимая с OpenAI, для доступа к моделям у разных провайдеров с централизованным биллингом, при этом самостоятельно размещённая конечная точка vLLM остаётся вариантом для рабочих нагрузок, которым она действительно необходима.

Следующий правильный шаг — не максимизировать отдельный бенчмарк. Прежде чем направлять производственный трафик на vLLM Docker, зафиксируйте версии образа и модели, подтвердите работу среды выполнения GPU, задайте явную политику контекста и очереди, протестируйте запросами, соответствующими продакшену, и задокументируйте сценарий сбоя.

Часто задаваемые вопросы

Является ли vLLM Docker тем же, что и управляемый LLM API?

Нет. vLLM Docker предоставляет среду обслуживания моделей на GPU, которыми вы управляете. Управляемый API абстрагирует хостинг моделей и эксплуатацию GPU. Оба варианта могут предоставлять клиентский интерфейс, совместимый с OpenAI, но операционная ответственность различается.

Нужен ли vLLM Docker NVIDIA Container Toolkit?

Для контейнеров с NVIDIA GPU на хосте требуются совместимый драйвер NVIDIA и настроенная среда выполнения GPU-контейнеров. NVIDIA Container Toolkit — стандартный путь, документированный NVIDIA, для предоставления GPU контейнерам Docker.

Какой флаг vLLM Docker следует настраивать первым?

Сначала задайте реалистичную максимальную длину контекста, затем протестируйте использование памяти, конкурентность и ограничения на количество токенов в батче с репрезентативным набором запросов. Изменение флагов без базового профиля рабочей нагрузки в основном даёт неповторяемые результаты.

Может ли vLLM Docker запускать модель на нескольких GPU?

Да. vLLM поддерживает обслуживание с тензорным и конвейерным параллелизмом. Начните с одного хоста и проверьте точное количество GPU, топологию и поведение обмена данными, прежде чем расширять архитектуру.

Источники и дополнительные материалы

• vLLM: использование Docker
• vLLM: параллелизм и масштабирование
• vLLM: аргументы движка
• Руководство по установке NVIDIA Container Toolkit
• Эффективное управление памятью для обслуживания больших языковых моделей с помощью PagedAttention