Как запустить vLLM в Docker: GPU-сервер и API

vLLM Docker запуск
vLLM Docker запуск инструкция
локальный инференс LLM
Как запустить vLLM в Docker: GPU-сервер и API

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

Инструкцию подготовила AI студия Владимира Ломтева 14 ноября 2026 года для ИТ-команд, разворачивающих первый сервер инференса. Пример рассчитан на Linux и совместимый NVIDIA GPU; он не является инструкцией для любого AMD, Mac или CPU-backend. Команды сверены с официальными источниками, но аппаратный запуск в рамках статьи не выполнялся. Учебная Qwen2.5 1.5B проверяет инфраструктуру и не заявляется лучшей производственной моделью.

Содержание

Что входит в минимальный сервер

vLLM принимает запросы к модели и управляет их исполнением. Docker упаковывает среду, но не заменяет драйвер GPU на хосте. Для NVIDIA нужен механизм передачи ускорителя контейнеру. Наличие видеокарты в спецификации сервера ещё не означает, что приложение внутри образа её увидит.

Схема первого запуска проста: локальный клиент обращается к порту на хосте, Docker перенаправляет соединение в контейнер vLLM, модель загружается из доступного источника или подготовленного каталога. До добавления шлюза доступ ограничивают loopback-интерфейсом.

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

Шаг 1. Проверить хост и совместимость

На целевом хосте выполните:

nvidia-smi
docker version

Первая проверка должна показать доступный NVIDIA GPU и драйвер. Вторая подтверждает работу Docker-клиента и daemon. Если ошибка возникает здесь, не начинайте с изменения параметров модели: проблема находится до vLLM.

Для NVIDIA настройте Container Toolkit по инструкции производителя. Пакеты и команды зависят от дистрибутива и конфигурации Docker, поэтому универсальная установка драйвера одной строкой здесь не приводится.

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

Шаг 2. Закрепить образ и модель

В учебном примере используется опубликованный тег vllm/vllm-openai:v0.32.0. Это закреплённая версия для воспроизводимости примера, а не указание автоматически применять её ко всем проектам. Перед реальным запуском проверьте доступность образа, требования безопасности и поддержку своего оборудования. Выпуски доступны в репозитории vLLM.

Для рабочего выпуска сохраните digest образа и revision модели. Тег и имя репозитория могут оказаться недостаточными для точного восстановления окружения. Если модель требует подтверждения условий доступа, авторизуйтесь разрешённым способом; не встраивайте токены в публикуемые конфигурации и логи.

Учебный артефакт Qwen/Qwen2.5-1.5B-Instruct выбран из-за небольшого размера и существующей карточки модели. Проверка качества бизнес-задачи проводится отдельно после инфраструктурного старта.

Шаг 3. Подготовить ключ и каталог кэша

Следующие команды предназначены для Bash. Они создают каталог кэша и файл окружения со случайным ключом. Ключ не выводится в терминал:

mkdir -p model-cache
umask 077
python3 - <<'PY'
from pathlib import Path
import secrets
path = Path('vllm.env')
if path.exists():
    raise SystemExit('vllm.env уже существует; сохраните текущий ключ')
path.write_text('VLLM_API_KEY=' + secrets.token_urlsafe(32) + '\n')
PY

Файл окружения содержит секрет и не должен попадать в Git, статью, заявку поддержки или общий чат. Docker-администратор на хосте всё равно имеет высокий уровень доступа; переменная окружения не является отдельным защищённым хранилищем секретов.

Каталог кэша нужен, чтобы загрузка файлов не повторялась после каждого пересоздания контейнера. Убедитесь, что на диске достаточно места не только для одного файла весов, но и для полного артефакта, временных данных и будущего обновления.

Шаг 4. Запустить контейнер

Минимальная конфигурация с локальным доступом:

docker run -d \
  --name local-vllm \
  --gpus all \
  --shm-size 2g \
  -p 127.0.0.1:8000:8000 \
  --env-file vllm.env \
  -v "$PWD/model-cache:/root/.cache/huggingface" \
  vllm/vllm-openai:v0.32.0 \
  --model Qwen/Qwen2.5-1.5B-Instruct \
  --served-model-name local-qwen \
  --dtype auto \
  --max-model-len 4096 \
  --gpu-memory-utilization 0.80

Флаг --gpus all предоставляет контейнеру все доступные NVIDIA GPU; в общей среде ограничьте список разрешёнными устройствами. Размер shared memory 2g, контекст 4096 и доля памяти 0,80 — учебные настройки, а не универсальные требования. Они не резервируют безопасную долю для любого соседнего процесса.

Базовый способ запуска официального образа описан в Using Docker vLLM. В рабочей конфигурации параметры нужно сверить с --help именно закреплённого образа. Для первого теста не добавляйте --trust-remote-code без понимания необходимости и происхождения исполняемого кода.

Шаг 5. Прочитать логи и проверить готовность

Проверьте состояние контейнера и последние сообщения:

docker ps -a --filter name=local-vllm
docker logs --tail 120 local-vllm

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

Короткий цикл перезапусков не следует маскировать автоматическим restart-policy. Сначала найдите причину. Для ошибок инициализации используйте официальное руководство vLLM Troubleshooting, сохраняя модель, образ, GPU, драйвер и минимальную конфигурацию.

Шаг 6. Проверить API из Python

Следующий клиент читает ключ из созданного файла и обращается к локальному endpoint. Сохраните его как check_vllm.py:

import json
from pathlib import Path
from urllib.request import Request, ProxyHandler, build_opener

values = {}
for line in Path('vllm.env').read_text().splitlines():
    if '=' in line and not line.startswith('#'):
        key, value = line.split('=', 1)
        values[key] = value
payload = {
    'model': 'local-qwen',
    'messages': [{'role': 'user', 'content': 'Назови столицу Франции.'}],
    'max_tokens': 40,
    'temperature': 0,
    'stream': False,
}
request = Request(
    'http://127.0.0.1:8000/v1/chat/completions',
    data=json.dumps(payload, ensure_ascii=False).encode(),
    headers={
        'Content-Type': 'application/json',
        'Authorization': 'Bearer ' + values['VLLM_API_KEY'],
    },
)
with build_opener(ProxyHandler({})).open(request, timeout=120) as response:
    result = json.load(response)
print(result['choices'][0]['message']['content'])
print('Завершение:', result['choices'][0].get('finish_reason'))

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

Как читать основные параметры

Параметр Назначение Ошибка интерпретации
--model Источник артефакта модели Путать с публичным именем в запросе
--served-model-name Имя модели для клиента Считать его гарантией неизменных весов
--max-model-len Предел длины последовательности Учитывать только пользовательское сообщение
--gpu-memory-utilization Доля памяти для планирования экземпляра Считать универсальной защитой других процессов
--dtype Выбор вычислительного представления в поддерживаемом пути Путать с произвольной конвертацией в любой формат

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

Что делать с частыми ошибками

Если GPU не виден внутри контейнера, проверьте передачу устройства и toolkit. Если веса не скачиваются, проверьте источник, доступ и свободный диск. Если модель не поддерживается, нужна совместимая версия runtime или другой артефакт; дополнительная память это не исправит.

При OOM определите момент отказа: загрузка, подготовка runtime или обработка запроса. Сначала попробуйте меньший учебный артефакт и короткую последовательность. Уменьшение нагрузки помогает локализовать причину, но не заменяет расчёт рабочей мощности.

Если API отвечает, а приложение ошибается, проверьте имя модели, формат сообщений и адрес соединения. Внутри другого контейнера 127.0.0.1 относится к его собственной сети. Не исправляйте это публикацией порта во весь интернет.

Что добавить перед эксплуатацией

Локальный bind защищает только сетевой маршрут данного примера. Для сотрудников или клиентов организуйте разрешённый шлюз, аутентификацию, лимиты и правила журналирования. Проверьте, что технические endpoints не раскрывают лишние данные.

Назначьте владельца обновления и сохраните предыдущий артефакт. Перезапуск сервера, смена образа и замена модели должны проходить по описанной процедуре. Полезно отделить проверку процесса от проверки качества: успешный HTTP-ответ ещё не означает применимый результат.

Включите наблюдаемость до роста нагрузки. Документация Production Metrics vLLM описывает серверные показатели, а материал о корпоративном доступе к ИИ помогает определить роль шлюза и интерфейса.

Чек-лист первого выпуска

  • GPU доступен на хосте и внутри предназначенной среды.
  • Образ, модель и конфигурация закреплены и записаны.
  • Кэш весов сохраняется независимо от контейнера.
  • Ключ не попадает в репозиторий и логи приложения.
  • Порт доступен только разрешённому маршруту.
  • Проверены правильный и ошибочный API-запросы.
  • Пройден контрольный набор бизнес-задачи.
  • Измерены задержка, память и ошибки под нагрузкой.
  • Сохранены процедура перезапуска и условия отката.

Это шаблон приёмки: рядом с каждым пунктом запишите результат и ссылку на фактический лог. Соблюдение списка не заменяет требования вашей организации к защищённому контуру.

Механизмы, которые стоят за настройками сервера, разобраны в гиде по движкам и ускорению инференса. До выбора оборудования полезно пройти сравнение собственного инференса и API.

Частые вопросы

Можно ли использовать latest?

Для одноразового исследования это возможно, но рабочий выпуск лучше фиксировать по версии и digest. Иначе повторный запуск может получить другой состав среды.

Нужен ли Hugging Face token?

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

Почему Docker не решает все проблемы CUDA?

Контейнер содержит пользовательскую среду, но работает через драйвер и оборудование хоста. Совместимость проверяют на обоих уровнях.

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

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

Как AI студия Владимира Ломтева помогает развернуть сервер

AI студия Владимира Ломтева может связать развёртывание LLM с подготовкой данных, интеграцией API и проверкой результата перед запуском. Для команды это означает выбрать рабочий процесс, согласовать критерии и проверить подходящую конфигурацию в рамках допустимого размещения.

Первый шаг — описать процесс, разрешённые данные и требуемое время ответа. Обсудить задачу.

Как завершить первый запуск

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

Оставить заявку

Заполните форму и мы свяжемся с вами

← Все статьи

Комментарии (0)

Пока нет комментариев. Будьте первым!

Оставить комментарий
Регистрация не требуется