vLLM: как запустить сервер локальной модели с API

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

Ниже — первый запуск на Linux с NVIDIA GPU, проверка API и порядок оценки нагрузки. Команды сверены с документацией на 7 ноября 2026 года. Для примера взята небольшая Qwen2.5-1.5B-Instruct. Она помогает проверить соединение и настройки, а рабочую модель выбирают по качеству на своих задачах.

Что проверить на сервере

Для выбранного пути нужны Linux, совместимый NVIDIA GPU, рабочий драйвер, свободное место для весов и Python-окружения. Выполните nvidia-smi и проверьте модель видеокарты, объём памяти и процессы, которые её занимают. На дату проверки документация vLLM указывает для NVIDIA compute capability от 7.5. Для других ускорителей предусмотрены свои инструкции и сборки. Установка vLLM для GPU.

На Windows этот путь выполняют в совместимой среде Linux, например WSL, с настроенным доступом к ускорителю. Для первого серверного запуска проще использовать отдельную Linux-машину. Если арендуете GPU, заранее оцените стоимость простоя, загрузки модели и диска. Оплачиваемое время начнётся раньше, чем первый клиент получит ответ. Как оценить аренду GPU-сервера.

Почему объём весов не равен расходу памяти

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

Для грубой оценки только весов можно умножить число параметров на размер одного значения. Условные 1,5 млрд параметров при двух байтах на значение дают около 3 ГБ без остальных расходов. Это арифметический ориентир, а фактическое размещение зависит от модели, типа данных и движка. Квантизация меняет размер представления и требования к вычислениям. Её поддержку нужно проверять для выбранной модели и оборудования. Как работает квантизация моделей.

Установка в отдельное окружение

Пример ниже рассчитан на оболочку Bash в Linux и уже установленный uv. Создайте отдельный каталог проекта. Рекомендованный в Quickstart вариант с автоматическим выбором PyTorch backend выглядит так:

uv venv --python 3.12 --seed
source .venv/bin/activate
uv pip install vllm --torch-backend=auto
vllm --version

Автоматический выбор backend учитывает установленный драйвер. Если установка завершилась ошибкой, сохраните её полный текст и сверьте версию драйвера с инструкцией проекта. Добавление случайной версии PyTorch поверх существующего окружения усложняет диагностику. Для повторяемого развёртывания сохраните версии зависимостей после успешной проверки. vLLM Quickstart.

Запуск одной модели

Получите случайный ключ, например командой openssl rand -hex 32, и сохраните его в менеджере секретов. Введите это значение в терминале перед запуском сервера. Для службы храните ключ в защищённой конфигурации, доступной процессу.

read -rs -p "API key: " VLLM_API_KEY
export VLLM_API_KEY

vllm serve Qwen/Qwen2.5-1.5B-Instruct \
  --host 127.0.0.1 \
  --port 8000 \
  --served-model-name local-qwen \
  --max-model-len 4096 \
  --gpu-memory-utilization 0.8

Оставьте терминал открытым и дождитесь сообщения о готовности. При первом запуске потребуется загрузка весов. Адрес 127.0.0.1 ограничивает прослушивание локальной машиной. Параметр --served-model-name задаёт имя, которое клиент будет указывать в запросах. В данном примере это local-qwen.

--max-model-len 4096 задаёт ограничение контекста для этого запуска. В него входят входные и выходные токены. --gpu-memory-utilization 0.8 задаёт долю памяти для экземпляра движка. Выбранные значения — исходные настройки для проверки. Их нужно согласовать с оборудованием, моделью и длинами запросов. Параметры vllm serve.

Проверка API

В другом терминале используйте тот же ключ. Можно безопасно ввести его через скрытый ввод read -rs VLLM_API_KEY, затем нажать Enter. Ключ для этой проверки берётся из конфигурации запущенного сервера. Сначала запросите список моделей:

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

Убедитесь, что в ответе присутствует local-qwen. После этого отправьте короткий запрос к чату:

curl http://127.0.0.1:8000/v1/chat/completions \
  -H "Authorization: Bearer $VLLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "local-qwen",
    "messages": [
      {"role": "user", "content": "Объясни HTTP API в двух предложениях."}
    ],
    "max_tokens": 128,
    "temperature": 0
  }'

Проверьте HTTP-статус и содержимое ответа. Для чата нужен подходящий chat template. Он обычно поступает с токенизатором instruct-модели. Если сервер сообщает об отсутствии шаблона, сверьте выбранную модель и настройки в документации. Формат API облегчает подключение клиента, но поддержку конкретного поля или метода нужно проверять отдельно. Онлайн-обслуживание и совместимые API.

Параллельные запросы и измерение задержки

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

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

Если модель не запускается или API отвечает ошибкой

Ошибка загрузки весов требует проверки адреса модели, доступа к репозиторию, сети и свободного диска. При OOM посмотрите, какие процессы занимают GPU, уменьшите длину контекста и нагрузку, затем оцените меньшую модель. Значение доли памяти выбирайте с учётом соседних процессов. Для 401 проверьте ключ клиента и сервера. При ошибке имени модели сравните поле model со списком /v1/models.

Для удалённого приложения настройте контролируемый маршрут к серверу, TLS и ограничения запросов. Учитывайте также тайм-ауты и завершение службы при перезагрузке. Ключ API решает только часть задачи доступа. Размеры запросов, очереди и число клиентов нужно согласовать с ресурсами развёртывания.

Когда выбрать vLLM, а когда Ollama

Если вы хотите быстро установить модель и работать с ней на личной машине, Ollama даёт удобный начальный путь. vLLM стоит оценивать для сервера с несколькими клиентами, настройками памяти и проверяемой нагрузкой. Оба инструмента требуют подходящей модели и оборудования. Выбор по результатам собственного прогона точнее, чем универсальное сравнение скорости. Запуск локальных моделей в Ollama.