vLLM в Docker: первый проверяемый запуск на NVIDIA GPU

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

Проверьте ускоритель до загрузки модели

Сначала убедитесь, что nvidia-smi видит карту на хосте. Затем проверьте доступ GPU внутри контейнерной среды по инструкции NVIDIA Container Toolkit. Если карта доступна только снаружи, скачивание больших весов пока не поможет. Сохраните версию драйвера и идентификатор устройства, чтобы потом сопоставить их с журналом движка.

Различайте CUDA, указанную драйвером, и библиотеки внутри образа: это разные элементы совместимости. Для основного маршрута установки используйте официальную документацию vLLM. Подготовка самой машины разобрана в чек-листе сервера.

Запустите минимальный локальный пример

Следующая команда — учебный пример для совместимой NVIDIA-среды, а не универсальная конфигурация любого сервера:

docker run --rm --gpus all \
  -p 127.0.0.1:8000:8000 \
  -v vllm-hf-cache:/root/.cache/huggingface \
  --ipc=host \
  vllm/vllm-openai:latest \
  --model Qwen/Qwen3-0.6B --max-model-len 4096

Синтаксис образа и передачу аргументов описывает инструкция Docker. Для повторяемого пилота после проверки замените плавающий тег конкретной проверенной версией или digest. Доступ к общему IPC в примере также следует согласовать с правилами своей машины.

Дождитесь именно готовности движка

Первый запуск может скачивать веса, компилировать компоненты и прогревать вычисления. Следите за журналом: отсутствие ответа в первые секунды не обязательно означает сбой. Ошибки доступа к репозиторию, нехватка диска и CUDA OOM относятся к разным этапам и требуют разных исправлений.

После сообщения о готовности выполните curl http://127.0.0.1:8000/v1/models. Полученный идентификатор модели используйте в следующем тестовом запросе. Если список доступен, но генерация не работает, сохраните ответ API и последние строки журнала, вместо повторного удаления всего кеша.

Разделите постоянные данные и контейнер

Именованный том в примере сохраняет скачанные файлы между контейнерами. Он не гарантирует сохранение всех компиляционных артефактов: для них может понадобиться отдельный путь. Это влияет на время повторного старта и объём диска, поэтому холодный и тёплый запуск измеряют отдельно.

Проверьте свободное место перед скачиванием второй версии модели. Не удаляйте общий кеш без согласования с другими процессами. Для модели с ограниченным доступом понадобятся разрешения репозитория; токен не следует помещать в опубликованный пример, скриншот или заявку на оборудование.

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

Зафиксируйте базовый результат для пилота

Сохраните точный образ, модель, команду, время до готовности и один успешный ответ. Затем переходите к нагрузке, описанной в руководстве bench serve. Первый запуск подтверждает совместимость цепочки, а рабочая ёмкость определяется отдельным экспериментом с контекстом и параллельностью.

Для владельца оборудования это минимальное доказательство пригодности машины к дальнейшей проверке. Для партнёра по финансированию — понятное основание оценить оставшиеся работы.