Гайды

vLLM гайд: установка, первый запуск, требования

16 сентября 2026 · 16 минут чтения

Проверка фактов

Юлия Найпак

Методист по автоматизации. Сверяет паспорт инструмента с документацией вендора.

Автор Р

Редакция

Коллектив авторов, редакторов и иллюстраторов статей на сайте блога онлайн-университета «Зерокодер». Пишем…

Черновик готовит редакция с помощью ИИ. За стандарт издания отвечает главный редактор — Валерий Курземнек.

Материал редакции Зерокодера. Пороги сняты с документации vLLM тега v0.29.0, скрипт проверки железа прогнан на машине редакции. Обновлено: сентябрь 2026.

vLLM ставится на Linux командой uv pip install vllm --torch-backend=auto и поднимается командой vllm serve Qwen/Qwen2.5-1.5B-Instruct. Сервер отвечает по протоколу OpenAI на порту 8000. Гайд собран на версии 0.29.0, её релиз опубликован 09.09.2026. Пороги допуска: Linux, Python 3.10 — 3.13, видеокарта с compute capability 7.5 и выше.

Главное:

• Документация vLLM формулирует требования тремя строками: «OS: Linux», «Python: 3.10 — 3.13», «GPU: compute capability 7.5 or higher (e.g., T4, RTX20xx, A100, L4, H100, B200, etc.)».
• Про Windows документация говорит прямо: «vLLM does not support Windows natively». Рабочий путь — WSL с совместимым дистрибутивом Linux.
• Метаданные пакета на PyPI шире документации: Requires-Python указан как «<3.15,>=3.10», классификаторы доходят до Python 3.14.
• Веса моделей в пакет не входят: vllm serve тянет их с Hugging Face при первом старте.
• Самая частая остановка на старте — нехватка памяти под KV-кэш; сама ошибка называет два флага, которыми это чинится.

Что проверить до установки vLLM: три порога

Требования vLLM лежат в двух местах: общие — в разделе Prerequisites страницы Quickstart, требование к видеокарте — на странице установки под GPU, вкладка NVIDIA CUDA. Формулировки дословные:

Порог 7.5 стоит читать как список карт. Проходят T4, RTX 20-й серии и всё, что новее: RTX 30xx, RTX 40xx, A100, L4, H100, B200. Не проходят Tesla V100 с compute capability 7.0 и старые игровые карты вроде GTX 1080 Ti с 6.1 — а именно они попадаются в дешёвых предложениях аренды.

Работает ли vLLM на Windows

Официальная формулировка поддержки Windows записана в документации vLLM так: «vLLM does not support Windows natively. To run vLLM on Windows, you can use the Windows Subsystem for Linux (WSL) with a compatible Linux distribution, or use some community-maintained forks». Документация называет два пути: WSL с совместимым дистрибутивом Linux и форки, которые поддерживает сообщество. Внутри WSL команда python3 -c "import platform; print(platform.system())" печатает Linux — для vLLM это уже поддержанная система. Если модель нужна на ноутбуке под Windows и без консоли, задачу закрывают соседние инструменты — llama.cpp или LM Studio.

Как установить vLLM: uv, pip и машина без видеокарты

Документация рекомендует ставить пакет в свежее окружение: «Therefore, it is recommended to install vLLM with a fresh new environment». Причина там же — «vLLM contains pre-compiled C++ and CUDA (12.9) binaries», и эти бинарники конфликтуют с чужой сборкой PyTorch.

Путь через uv, как он записан в Quickstart:

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

Ключ --torch-backend=auto заставляет uv посмотреть версию установленного драйвера CUDA и выбрать индекс PyTorch. Нужен конкретный бэкенд — вместо auto ставится имя вида cu126 или cu130.

Путь через pip записан в документации с явным индексом:

pip install vllm --extra-index-url https://download.pytorch.org/whl/cu129

Машина без видеокарты тоже обслуживается: у vLLM есть CPU-вариант со своим индексом колёс https://wheels.vllm.ai/nightly/cpu/ и тем же требованием «Python: 3.10 — 3.13». Скорость на процессоре остаётся скоростью процессора, поэтому CPU-сборку разумно держать под проверку кода и тесты; нагрузку выносят на видеокарту.

Где скачать vLLM: PyPI, GitHub, nightly-колёса и образ

Документация vLLM называет четыре точки выдачи, и все четыре ведут в репозиторий vllm-project/vllm:

• PyPI — pypi.org/project/vllm. Здесь лежит релизный пакет, на 16.09.2026 это 0.29.0, загруженный 09.09.2026. Лицензия — Apache-2.0.
• Релизы GitHub — github.com/vllm-project/vllm/releases: архивы и колёса под конкретные версии CUDA.
• Nightly-индекс — wheels.vllm.ai/nightly, сборки на каждый коммит, начиная с v0.5.3. Документация предупреждает: «Using pip to install from nightly indices is not supported», то есть отсюда ставят через uv.
• Docker Hub — образ vllm/vllm-openai.

Весов моделей ни в одной из этих точек нет. Документация говорит об этом прямо: «By default, vLLM downloads models from Hugging Face». Значит, диск под кеш Hugging Face закладывается отдельно от самого пакета, а для закрытых репозиториев моделей в окружение прокидывается HF_TOKEN. Альтернативный источник весов включается переменной VLLM_USE_MODELSCOPE.

Документация vLLM и репозиторий на GitHub

Документация vLLM живёт на docs.vllm.ai, и у адреса две ветки. На страницах с /en/latest/ висит баннер: «You are viewing the latest developer preview docs. Click here to view docs for the latest stable release». То есть latest показывает состояние ветки main, где описаны разделы, которых в установленном пакете может ещё не быть; адрес с /en/stable/ показывает последний релиз, и для гайда, который повторяют на 0.29.0, нужен он.

Исходники документации лежат в том же репозитории в папке docs, поэтому формулировку можно открыть привязанной к тегу: адрес вида raw.githubusercontent.com/vllm-project/vllm/v0.29.0/docs/getting_started/quickstart.md отдаёт текст той версии, на которой вы работаете. В репозитории github.com/vllm-project/vllm рядом с кодом движка лежат папка docs, папка examples со скриптами офлайн-инференса и вкладка Releases с колёсами под версии CUDA.

Как запустить vLLM в Docker

Официальный образ называется vllm/vllm-openai и запускается так, как показано в документации:

docker run --runtime nvidia --gpus all \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    --env "HF_TOKEN=$HF_TOKEN" \
    -p 8000:8000 \
    --ipc=host \
    vllm/vllm-openai:latest \
    --model Qwen/Qwen3-0.6B

Три детали этой команды и решают, поедет ли контейнер. Монтирование ~/.cache/huggingface сохраняет скачанные веса между перезапусками, иначе каждый старт качает модель заново. Флаг --ipc=host документация объясняет через разделяемую память: «vLLM uses PyTorch, which uses shared memory to share data between processes under the hood, particularly for tensor parallel inference»; вместо него подойдёт --shm-size. Аргументы после имени образа — обычные engine-args, те же, что у vllm serve.

Второй кеш живёт отдельно, и про него забывают: «each new container still starts with an empty VLLM_CACHE_ROOT (default ~/.cache/vllm) and recompiles the model’s torch.compile artifacts». Пока на этот путь не смонтирован именованный том, каждый новый контейнер заново компилирует модель под torch.compile. Для продакшена образ готов работать от встроенного пользователя: «It is also prepared to run as the built-in vllm user (UID 2000, GID 0)».

Первый запуск vLLM и проверка, что сервер живой

Сервер поднимается командой из Quickstart:

vllm serve Qwen/Qwen2.5-1.5B-Instruct

Сервер по умолчанию слушает http://localhost:8000, адрес меняется ключами --host и --port, и в один момент времени он обслуживает одну модель. Проверка живости — запрос списка моделей:

curl http://localhost:8000/v1/models

Закрыть сервер ключом можно через --api-key или переменную VLLM_API_KEY; ключей разрешено передать несколько, чтобы менять их без остановки сервиса. Офлайн-режим HTTP не поднимает и работает классом LLM: llm = LLM(model="facebook/opt-125m"), дальше llm.generate(prompts, sampling_params). Для инструкт-моделей документация предупреждает, что llm.generate чат-шаблон сам не применяет, и предлагает метод llm.chat.

Какие модели поддерживает vLLM

Список поддержанных архитектур vLLM ведёт файлом supported_models.md. Редакция посчитала в файле тега v0.29.0 строки таблиц, чья первая ячейка — имя архитектуры в обратных кавычках:

Если архитектуры в списках нет, остаётся Transformers-бэкенд: «vLLM also supports model implementations that are available in Transformers. We call this feature the «Transformers modeling backend»». Он включается ключом --model-impl transformers, а для моделей с собственным кодом на Hugging Face — флагом --trust-remote-code. Что такое сама модель и чем архитектура отличается от весов, разобрано в статье что такое LLM.

Почему vLLM падает на старте: KV-кэш и два флага

Самая частая остановка при первом запуске выглядит как ошибка про KV-кэш. В исходниках 0.29.0 её текст лежит шаблоном в файле vllm/v1/core/kv_cache_utils.py, строки 880-888, подстановки стоят в фигурных скобках:

To serve at least one request with the model's max seq len ({max_model_len}),
({format_gib(needed_memory)} GiB KV cache is needed, which is larger than the
available KV cache memory ({format_gib(available_memory)} GiB). {estimated_msg}
Try increasing `gpu_memory_utilization` (which also controls CPU memory on the
CPU backend) or decreasing `max_model_len` when initializing the engine.

Ошибка сама называет оба рычага. Первый — gpu_memory_utilization, доля видеопамяти, которую движок забирает под себя. В версии 0.29.0 её значение по умолчанию равно 0.92 и задано строкой gpu_memory_utilization: float = Field(default=0.92, gt=0, le=1) в файле vllm/config/cache.py. В командах из выдачи это значение обычно выставляют руками — 0.90, 0.95, 0.97, — а дефолт не называют, хотя именно от него считается бюджет. Второй рычаг — max_model_len, длина контекста: модель с окном на 128 тысяч токенов требует кэша на все 128 тысяч, даже если запросы короткие. Документация добавляет ещё два способа: tensor_parallel_size разносит модель по нескольким картам, max_num_seqs режет размер батча.

Арифметика бюджета простая: видеопамять карты умножается на gpu_memory_utilization, из результата вычитается вес модели, остаток уходит под KV-кэш. Для карты на 16376 MiB при дефолте 0.92 движку достаётся 15065 MiB на веса и кэш вместе.

Preflight-скрипт Зерокодера для vLLM

Три порога из первого раздела проверяются машиной до установки пакета и до скачивания весов. Редакция Зерокодера написала для этого скрипт проверки машины на стандартной библиотеке — 62 строки без зависимостей. Без аргументов он читает свою машину, с ключами --os, --python и --gpu проверяет чужую конфигурацию: ту, что предлагает хостер, до оплаты.

#!/usr/bin/env python3
# vllm_preflight.py - preflight-скрипт Зерокодера для vLLM.
# Пороги взяты дословно из документации тега v0.29.0.
# Код возврата: 0 - все три требования выполнены, 1 - хотя бы одно нарушено.
import argparse, platform, subprocess, sys

REQ = {
    "os":     "OS: Linux",
    "python": "Python: 3.10 -- 3.13",
    "gpu":    "GPU: compute capability 7.5 or higher",
}
GMU = 0.92   # gpu_memory_utilization по умолчанию, vllm/config/cache.py:111 (v0.29.0)
NVSMI = ["nvidia-smi", "--query-gpu=name,compute_cap,memory.total",
         "--format=csv,noheader,nounits"]


def read_gpus():
    try:
        r = subprocess.run(NVSMI, capture_output=True, text=True, timeout=20)
        return [ln for ln in r.stdout.strip().splitlines() if ln.strip()]
    except Exception:
        return []


def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("--os")
    ap.add_argument("--python")
    ap.add_argument("--gpu", action="append", metavar="NAME,CC,MIB")
    a = ap.parse_args()

    os_name = a.os or platform.system()
    py = a.python or "%d.%d.%d" % sys.version_info[:3]
    gpus = a.gpu if a.gpu else read_gpus()
    bad = []

    ok = os_name.strip().lower() == "linux"
    print(f"[{'OK  ' if ok else 'FAIL'}] ОС {os_name} | требование: {REQ['os']}")
    bad += [] if ok else ["os"]

    major, minor = (int(x) for x in py.split(".")[:2])
    ok = (3, 10) <= (major, minor) <= (3, 13)
    print(f"[{'OK  ' if ok else 'FAIL'}] Python {py} | требование: {REQ['python']}")
    bad += [] if ok else ["python"]

    if not gpus:
        print(f"[FAIL] GPU не опрошен: nvidia-smi молчит | требование: {REQ['gpu']}")
        bad += ["gpu"]
    for line in gpus:
        name, cc, mib = (p.strip() for p in line.split(",")[:3])
        ok = float(cc) >= 7.5
        print(f"[{'OK  ' if ok else 'FAIL'}] {name}: compute capability {cc} | требование: {REQ['gpu']}")
        print(f"       под веса и KV-кэш: {mib} MiB * {GMU} = {int(float(mib) * GMU)} MiB")
        bad += [] if ok else ["gpu"]

    print("ИТОГ: " + ("требования выполнены" if not bad
                      else "нарушено - " + ", ".join(sorted(set(bad)))))
    return 1 if bad else 0


if __name__ == "__main__":
    sys.exit(main())

Прогон 16.09.2026 на машине редакции — WSL2 с ядром Linux 6.6.114.1, интерпретатор из дистрибутива, видеокарта NVIDIA GeForce RTX 4080 SUPER:

[OK  ] ОС Linux | требование: OS: Linux
[FAIL] Python 3.14.4 | требование: Python: 3.10 -- 3.13
[OK  ] NVIDIA GeForce RTX 4080 SUPER: compute capability 8.9 | требование: GPU: compute capability 7.5 or higher
       под веса и KV-кэш: 16376 MiB * 0.92 = 15065 MiB
ИТОГ: нарушено - python
код возврата: 1

Красная строка здесь содержательная. Интерпретатор дистрибутива — 3.14.4, а документация называет поддержанным диапазон 3.10 — 3.13. При этом метаданные пакета на PyPI объявляют Requires-Python как «<3.15,>=3.10» и держат классификатор «Programming Language :: Python :: 3.14». По метаданным pip такой интерпретатор по версии Python не отклонит, хотя документация его поддержанным не называет. Лечится это строчкой uv venv --python 3.12 --seed из той же документации.

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

Эталон даёт ноль, четыре мутации дают единицу, и в каждом случае в строке ИТОГ названо нарушенное требование.

Чего не пишут в топе выдачи: замер десяти страниц

Пороги выглядят общеизвестными, пока их не поискать в выдаче. Редакция сняла топ-10 Яндекса по запросу «vllm гайд» через Search API, регион 225 (16.09.2026), скачала все десять страниц и поискала в видимом тексте каждой три вещи: порог compute capability числом, диапазон версий Python и версию vLLM, на которой сделан материал, — в том числе в тегах Docker-образов.

Порог видеокарты числом не назван ни на одной из десяти страниц. Диапазон Python назван на двух страницах, и одна из двух — сама официальная документация, которая в этой выдаче стоит шестой. Версия vLLM названа на четырёх страницах — 0.6.0, 0.6.1, 0.17.0 и 0.17.1, последняя тегом Docker-образа, — против актуальной 0.29.0.

Две строки таблицы стоит читать с оговоркой, и она видна по колонке символов: страница YouTube отдала 293 символа служебного текста, а адрес glukhov.org из выдачи отдал нашей машине страницу 404 на 2424 символа навигации. Замер говорит про текст, который эти десять адресов отдали нам 16.09.2026, и ни про что больше: внешний адрес машины шведский, на браузер пользователя из России результат не переносится.

Чек-лист перед установкой vLLM

1. Сверить машину с тремя порогами: Linux, Python 3.10 — 3.13, compute capability 7.5 и выше.
2. На Windows — поднять WSL с дистрибутивом Linux.
3. Создать свежее окружение: uv venv --python 3.12 --seed.
4. Поставить пакет: uv pip install vllm --torch-backend=auto.
5. Освободить диск под кеш Hugging Face и положить в окружение HF_TOKEN, если модель закрытая.
6. Поднять сервер: vllm serve <модель>, проверить curl http://localhost:8000/v1/models.
7. При ошибке про KV-кэш — уменьшить max_model_len либо поднять gpu_memory_utilization от дефолта 0.92.
8. Записать версию vLLM, на которой конфигурация сошлась: между релизами дефолты меняются.

FAQ

Какие требования у vLLM к железу?
Документация тега v0.29.0 называет три: «OS: Linux», «Python: 3.10 — 3.13», «GPU: compute capability 7.5 or higher». Порог 7.5 отсекает Tesla V100 (7.0) и GTX 1080 Ti (6.1). В разделе требований объём видеопамяти числом не задан: он зависит от модели, длины контекста и квантизации.

Как установить vLLM на Ubuntu?
Создать свежее окружение и поставить пакет: uv venv --python 3.12 --seed, затем uv pip install vllm --torch-backend=auto. Вариант через pip — pip install vllm --extra-index-url https://download.pytorch.org/whl/cu129. Свежее окружение документация рекомендует потому, что пакет несёт скомпилированные бинарники CUDA 12.9.

Работает ли vLLM на Windows?
Официально нет: «vLLM does not support Windows natively». Документация предлагает WSL с совместимым дистрибутивом Linux либо форки сообщества.

Где скачать vLLM?
Пакет — на pypi.org/project/vllm, исходники и релизные колёса — на github.com/vllm-project/vllm, сборки на каждый коммит — на wheels.vllm.ai/nightly, Docker-образ — vllm/vllm-openai.

Сколько моделей поддерживает vLLM?
В файле supported_models.md тега v0.29.0 234 строки с именем архитектуры: 118 текстовых генеративных, 114 мультимодальных, 2 в плагинах. Архитектуру вне списков поднимают Transformers-бэкендом: --model-impl transformers.