# vLLM в Docker: запуск модели на NVIDIA GPU и проверка локального API

Источник: https://modelium.tech/zhurnal/vllm-v-docker/

Официальный образ `vllm/vllm-openai` позволяет поднять OpenAI-совместимый сервер в Docker на поддерживаемом NVIDIA GPU. Зафиксируйте образ и ревизию модели, публикуйте порт только на localhost и отдельно проверьте список моделей и ответ Chat API. Контейнер не отменяет требований к драйверу, памяти и контролю сетевого доступа; пример ниже составлен по документации, а не запущен Modelium.

На 5 октября 2026 года документация vLLM показывает официальный образ `vllm/vllm-openai` для CUDA и OpenAI-совместимого HTTP-сервера. Docker упрощает упаковку окружения, но не обеспечивает совместимый GPU, драйвер или память автоматически. В этом руководстве — **один** пример на NVIDIA GPU; инструкции для AMD, Intel и WSL отличаются. [s1](#src-s1)

## Что подготовить до запуска контейнера

Нужны Linux-хост с поддерживаемым NVIDIA GPU, работающий Docker с доступом к GPU и свободный порт 8000. Убедитесь, что GPU доступен на хосте и Docker действительно передаёт его в контейнер; если этого нет, сначала разберите установку драйвера и GPU-контейнерного runtime. На Windows сам vLLM нативно не поддерживается: для отдельного сценария используется Linux в WSL. Требуемую память определяют конкретные веса, настройки и нагрузка, а не только размер файла модели; Modelium не проверял ваш GPU. [s1](#src-s1)

Контрольная модель — `Qwen/Qwen3-0.6B`, именно она приведена в примере официальной установки Docker. Её карточка на ревизии `c1899de289a04d12100db370d81485cdf75e47ca` указывает `license: apache-2.0` и показывает chat template; это **метка репозитория**, а не юридическое заключение о вашем применении. Компактный контрольный пример не доказывает, что модель подходит для русского документооборота или корпоративной нагрузки. [s1](#src-s1) [s5](#src-s5)

## Как поднять vLLM в Docker без публичного порта

Сначала проверьте тег и digest образа на Docker Hub. На дату проверки тег `v0.31.0` имеет digest `sha256:c1c9f6fd5c109ba7f0546a59f5b2f15fb87f64c77782e90a27b648b42a8e67c3`; фиксация digest удерживает конкретный образ вместо меняющегося `latest`. Проверьте также платформу и совместимость образа с драйвером вашего хоста; успешная загрузка контейнера не равна успешной загрузке модели. [s8](#src-s8) [s1](#src-s1)

Для Linux shell приведён **не запущенный Modelium пример**, собранный из официальных параметров: `docker run --rm --gpus all --ipc=host -p 127.0.0.1:8000:8000 -v "$HOME/.cache/huggingface:/root/.cache/huggingface" vllm/vllm-openai@sha256:c1c9f6fd5c109ba7f0546a59f5b2f15fb87f64c77782e90a27b648b42a8e67c3 --model Qwen/Qwen3-0.6B --revision c1899de289a04d12100db370d81485cdf75e47ca`. Официальный образ документирует `--gpus all`, общий кеш HF, порт 8000 и `--ipc=host`; аргумент `--revision` подтверждён кодом CLI. Тома и режим IPC дают контейнеру дополнительные права на ресурсы хоста: применяйте их только на доверенном тестовом хосте, не монтируйте секреты или чужие документы. Для развёртывания с иной моделью сверяйте её формат, лицензию и требуемые ресурсы отдельно. [s1](#src-s1) [s7](#src-s7) [s5](#src-s5) [s8](#src-s8)

Обратите внимание на `-p 127.0.0.1:8000:8000`: обычное `-p 8000:8000` публикует порт на внешних интерфейсах. Docker предупреждает, что в выпусках **до 28.0.0** другие хосты одного L2-сегмента могли достигать даже порта, опубликованного на localhost. Для значимых данных проверьте актуальную версию Docker и сетевые правила, а не полагайтесь только на синтаксис `-p`. [s6](#src-s6)

## Как проверить модель и реальный ответ API

Дождитесь сообщения сервера о готовности. С хоста запросите `curl -sS http://127.0.0.1:8000/v1/models`: ответ должен быть JSON со списком `data`, где есть ожидаемая идентификация загруженной модели. Это проверка *объявленной* модели, но ещё не генерации. Если контейнер завершается, изучите `docker logs` у запущенного контейнера и ошибки загрузки модели/GPU; флаг `--rm` удаляет остановившийся контейнер, поэтому для диагностики временно снимите его и задайте явное имя. [s2](#src-s2) [s3](#src-s3) [s1](#src-s1)

Затем отправьте POST на `http://127.0.0.1:8000/v1/chat/completions` с `Content-Type: application/json` и объектом `{"model":"Qwen/Qwen3-0.6B","messages":[{"role":"user","content":"Напиши одно короткое слово"}],"max_tokens":128}`. Параметр `model` должен совпадать с доступным ID в `/v1/models`. Проверьте, что HTTP успешен, тело содержит `choices[0].message` и непустой ответ либо диагностируемую причину обрыва; ручная смысловая сверка обязательна для вашей задачи. Для Chat API требуется подходящий chat template; Qwen3 имеет режим рассуждений, поэтому один короткий ответ не доказывает качество работы или отсутствие thinking-токенов. Это протокол проверки по документации, а **не** полученный Modelium результат. [s2](#src-s2) [s3](#src-s3) [s5](#src-s5)

Если `/v1/models` доступен, но Chat API отвечает ошибкой, сверяйте ID, chat template и логи, не объявляя сервер работоспособным по одному HTTP 200. При ошибках CUDA проверьте видимость GPU внутри контейнера и совместимость хостового драйвера с образом; при нехватке памяти выбирайте другую модель/настройку по фактическим логам, не выводя минимальную VRAM из размера весов. Сравнение времени ответа выполняйте лишь после функционального теста на одинаковых входных данных. [s1](#src-s1) [s2](#src-s2) [s3](#src-s3)

## Где Docker не решает проблему безопасности

Порт localhost предназначен для работы на одном хосте. Не выставляйте этот пример в корпоративную или публичную сеть без отдельного сетевого периметра, авторизации и политики доступа. Даже `--api-key` в vLLM покрывает не все маршруты: официальный раздел безопасности называет `/invocations` среди незащищённых точек вывода. По этой причине API-ключ не заменяет изоляцию сервера; монтирование кеша и общий IPC тоже требуют оценки доверия к контейнеру и данным хоста. [s4](#src-s4) [s6](#src-s6) [s1](#src-s1)

Чтобы остановить интерактивный запуск, завершите `docker run` через Ctrl+C; с `--rm` контейнер удаляется, но локальный кеш Hugging Face на хосте остаётся, поскольку это смонтированный каталог. Для следующего шага откройте [основное руководство vLLM](/zhurnal/vllm/) и проверьте требования конкретной модели/устройства перед реальной нагрузкой. Если нужна производительность под вашим профилем, после корректного API-ответа переходите к [воспроизводимому тесту](/zhurnal/vllm-bench-serve/). Скорость и потребление памяти Modelium не измерял. [s1](#src-s1) [s2](#src-s2)

## Источники

1. [vLLM: установка NVIDIA CUDA, официальный Docker-образ](https://github.com/vllm-project/vllm/blob/138810056093301f4881050fcf2b1786939da387/docs/getting_started/installation/gpu.cuda.inc.md) — получено 2026-10-05
2. [vLLM: Quickstart, online serving и тест /v1/models](https://github.com/vllm-project/vllm/blob/138810056093301f4881050fcf2b1786939da387/docs/getting_started/quickstart.md) — получено 2026-10-05
3. [vLLM: OpenAI Compatible Server, Chat Completions](https://github.com/vllm-project/vllm/blob/138810056093301f4881050fcf2b1786939da387/docs/serving/online_serving/openai_compatible_server.md) — получено 2026-10-05
4. [vLLM: Security, ограничения аутентификации API](https://github.com/vllm-project/vllm/blob/138810056093301f4881050fcf2b1786939da387/docs/usage/security.md) — получено 2026-10-05
5. [Qwen/Qwen3-0.6B: закреплённая карточка модели](https://huggingface.co/Qwen/Qwen3-0.6B/blob/c1899de289a04d12100db370d81485cdf75e47ca/README.md) — получено 2026-10-05
6. [Docker: Publishing and exposing ports](https://docs.docker.com/engine/network/port-publishing/) — получено 2026-10-05
7. [vLLM: аргументы модели --revision в CLI](https://github.com/vllm-project/vllm/blob/138810056093301f4881050fcf2b1786939da387/vllm/engine/arg_utils.py) — получено 2026-10-05
8. [Docker Hub: vllm/vllm-openai v0.31.0, digest](https://hub.docker.com/v2/repositories/vllm/vllm-openai/tags/v0.31.0) — получено 2026-10-05