Быстрый старт vLLM: высокопроизводительный serving LLM — в 2026 году

vLLM — это высокопроизводительный, энергоэффективный движок вывода и обслуживания для больших языковых моделей (LLM), разработанный лабораторией вычислений Sky Computing Лейденского университета Беркли (UC Berkeley).

Алгоритм PagedAttention в vLLM обрабатывает кэш KV (ключ-значение) подобно страницам виртуальной памяти операционной системы и сочетается с непрерывным батчингом — это комбинация, которая сделала vLLM стандартным движком для продакшен-обслуживания LLM. Чтобы узнать, как vLLM соотносится с Ollama, Docker Model Runner, LocalAI и облачными провайдерами, включая компромиссы между стоимостью и инфраструктурой, ознакомьтесь со статьёй Размещение LLM: локальное, self-hosted и облачная инфраструктура: сравнение.

Это руководство актуально для версии vLLM v0.31.0 (октябрь 2026 г.). Если вы приходите из старых руководств, обратите внимание на два недавних изменения: команда python -m vllm.entrypoints.openai.api_server признана устаревшей (deprecated) и выводит предупреждение — теперь стандартным CLI является vllm serve — а предсобранные колёса (wheels) по умолчанию используют CUDA 12.9, а не 11.8.

Что такое vLLM?

vLLM (virtual LLM) — это open-source библиотека для быстрого вывода и обслуживания LLM, которая быстро стала отраслевым стандартом для продакшен-развёртываний. Выпущенная в 2023 году, она ввела PagedAttention — революционную технику управления памятью, которая значительно повышает эффективность обслуживания.

Ключевые возможности

Высокая пропускная способность: Бенчмарки эпохи запуска vLLM сообщали о 14–24-кратном увеличении пропускной способности по сравнению с HuggingFace Transformers на том же оборудовании, и движок сохранил это лидерство благодаря непрерывному батчингу, оптимизированным ядрам CUDA и алгоритму PagedAttention, который устраняет фрагментацию памяти.

Совместимость с API OpenAI: vLLM включает встроенный API-сервер, полностью совместимый с форматом OpenAI. Это позволяет бесшовно мигрировать с OpenAI на self-hosted инфраструктуру без изменения кода приложения. Просто направьте API-клиент на эндпоинт vLLM, и всё будет работать прозрачно.

Алгоритм PagedAttention: Ядром инноваций в производительности vLLM является PagedAttention, который применяет концепцию пейджинга виртуальной памяти к механизмам внимания. Вместо выделения непрерывных блоков памяти для кэшей KV (что приводит к фрагментации), PagedAttention разделяет память на блоки фиксированного размера, которые могут быть выделены по мере необходимости. Это снижает потери памяти до 4 раз и позволяет использовать гораздо большие размеры батчей.

Непрерывный батчинг (Continuous Batching): В отличие от статического батчинга, когда вы ждете завершения всех последовательностей, vLLM использует непрерывный (скользящий) батчинг. Как только одна последовательность завершается, новая может быть добавлена в батч. Это максимизирует использование GPU и минимизирует задержки для входящих запросов.

Поддержка многоядерного GPU: vLLM поддерживает тензорный параллелизм и конвейерный параллелизм для распределения больших моделей по нескольким GPU. Он может эффективно обслуживать модели, которые не помещаются в память одного GPU, поддерживая конфигурации от 2 до 8+ GPU.

Широкая поддержка моделей: Совместим с популярными архитектурами моделей, включая LLaMA, Mistral, Mixtral, Qwen, Phi, Gemma и многие другие. Поддерживает как instruction-tuned, так и базовые модели из HuggingFace Hub.

Когда использовать vLLM

vLLM демонстрирует лучшие результаты в конкретных сценариях, где его сильные стороны проявляются наиболее полно:

Продакшен API-сервисы: Когда вам нужно обслуживать LLM для многих одновременных пользователей через API, высокая пропускная способность и эффективный батчинг vLLM делают его лучшим выбором. Компании, работающие с чат-ботами, помощниками по коду или сервисами генерации контента, выигрывают от его способности обрабатывать сотни запросов в секунду.

Нагрузки с высокой конкурентностью: Если ваше приложение имеет множество одновременных пользователей, делающих запросы, непрерывный батчинг и PagedAttention в vLLM позволяют обслуживать больше пользователей на том же оборудовании по сравнению с альтернативами.

Оптимизация затрат: Когда стоимость GPU является важным фактором, превосходная пропускная способность vLLM означает, что вы можете обслуживать тот же трафик с меньшим количеством GPU, напрямую снижая инфраструктурные затраты. Четырёхкратная эффективность памяти от PagedAttention также позволяет использовать более мелкие и дешёвые инстансы GPU.

Развёртывание в Kubernetes: Бессостоятельный дизайн (stateless design) и контейнерная архитектура vLLM делают его идеальным для кластеров Kubernetes. Его стабильная производительность под нагрузкой и простота управления ресурсами хорошо интегрируются с облачными нативными инфраструктурами.

Когда НЕ использовать vLLM: Для локальной разработки, экспериментов или сценариев с одним пользователем инструменты вроде Ollama или llama.cpp обеспечивают лучший пользовательский опыт с более простой настройкой. Сложность vLLM оправдана, когда вам нужны его преимущества в производительности для продакшен-нагрузок.

Как установить vLLM

Предварительные требования

Перед установкой vLLM убедитесь, что ваша система соответствует этим требованиям:

• ОС: Linux с glibc 2.35 или новее (Ubuntu 22.04+, Debian 12+, RHEL 9+)
• GPU: NVIDIA GPU с вычислительной возможностью 7.5 или выше (T4, A10, A100, L4, H100, B200, серии RTX 20/30/40/50). Старые карты поколения 7.0, такие как V100, больше не поддерживаются. GPU AMD поддерживаются через отдельные ROCm колёса — см. ROCm vs Vulkan для локального хостинга LLM на AMD для конкретных образов AMD, флагов устройств и оговорок относительно покрытия ядер.
• CUDA: Стандартные колёса pip скомпилированы против CUDA 12.9; варианты 12.8 и 13.0 публикуются рядом с ними. GPU Blackwell (B200, GB200) требуют CUDA 12.8+. Ваш драйвер NVIDIA должен быть достаточно новым для устанавливаемой версии CUDA.
• Python: 3.10 до 3.13 — рекомендуемая версия 3.12 (колёса ROCm только для 3.12)
• VRAM: Минимум 16 ГБ для моделей 7B, 24 ГБ+ для 13B, 40 ГБ+ для более больших моделей

Установка через pip

Рекомендуемый способ установки — использование uv для создания окружения Python 3.12 и автоматического выбора соответствующего бэкенда PyTorch CUDA (--torch-backend=auto инспектирует установленный драйвер). Чтобы углублённо рассмотреть сам uv, см. uv: Новый менеджер пакетов и проектов Python:

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

# Проверка установки
python -c "import vllm; print(vllm.__version__)"

Обычный pip также работает:

python3 -m venv vllm-env
source vllm-env/bin/activate
pip install vllm

Стандартные колёса скомпилированы против CUDA 12.9. Если вам нужна другая версия CUDA, возьмите соответствующий индекс колёс PyTorch — например, для CUDA 12.8:

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

Старые фиксированные колёса, такие как vllm==0.4.2+cu121, больше не существуют в таком виде. Смешивание vLLM в существующем окружении с другой сборкой PyTorch — частая причина сбоев установки; проект рекомендует создавать новое окружение, а при необходимости настраивать сборку из исходников для кастомных целей CUDA.

Установка с Docker

Docker предоставляет наиболее надёжный метод развёртывания, особенно для продакшена. Фиксируйте образ на версии релиза вместо latest, чтобы обновления были осознанными, и имейте в виду, что существуют варианты образов для CUDA 12.9 (суффикс тега -cu129), AMD ROCm (vllm-openai-rocm), CPU (vllm-openai-cpu) и Intel XPU (vllm-openai-xpu):

# Загрузка официального образа vLLM
docker pull vllm/vllm-openai:v0.31.0

# Запуск vLLM с поддержкой GPU
docker run --gpus all \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    -p 8000:8000 \
    --ipc=host \
    vllm/vllm-openai:v0.31.0 \
    --model Qwen/Qwen3-8B

Флаг --ipc=host важен для конфигураций с несколькими GPU, так как он обеспечивает правильную межпроцессную связь.

Сборка из исходного кода

Для последних функций или кастомных модификаций собирайте из исходного кода:

git clone https://github.com/vllm-project/vllm.git
cd vllm
pip install -e .

Быстрый старт с vLLM

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

Запустите vLLM с моделью, используя командную строку:

# Скачивание и обслуживание модели с OpenAI-совместимым API
vllm serve Qwen/Qwen3-8B \
    --port 8000

vllm serve — это текущий CLI для OpenAI-совместимого сервера. Старый вызов python -m vllm.entrypoints.openai.api_server по-прежнему работает, но выводит предупреждение об устаревании и может быть удалён в будущем релизе, поэтому обновите любые скрипты или манифесты Kubernetes, которые по-прежнему его используют.

vLLM автоматически скачает модель из HuggingFace Hub (если она не кеширована) и запустит сервер. Вы увидите вывод, указывающий на готовность сервера:

INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000

Отправка API-запросов

После запуска сервера вы можете отправлять запросы, используя Python-клиент OpenAI или curl:

Использование curl:

curl http://localhost:8000/v1/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "Qwen/Qwen3-8B",
        "prompt": "Explain what vLLM is in one sentence:",
        "max_tokens": 100,
        "temperature": 0.7
    }'

Использование Python-клиента OpenAI:

from openai import OpenAI

# Направление на ваш сервер vLLM
client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="not-needed"  # vLLM игнорирует это, если вы не запустите сервер с --api-key
)

response = client.completions.create(
    model="Qwen/Qwen3-8B",
    prompt="Explain what vLLM is in one sentence:",
    max_tokens=100,
    temperature=0.7
)

print(response.choices[0].text)

API чат-комплитов (Chat Completions):

response = client.chat.completions.create(
    model="Qwen/Qwen3-8B",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is PagedAttention?"}
    ],
    max_tokens=200
)

print(response.choices[0].message.content)

Продвинутая конфигурация

vLLM предлагает множество параметров для оптимизации производительности:

vllm serve Qwen/Qwen3-8B \
    --port 8000 \
    --gpu-memory-utilization 0.95 \  # Использовать 95% памяти GPU
    --max-model-len 32k \            # Максимальная длина последовательности (работают и 8192, и 32k)
    --tensor-parallel-size 2 \       # Использовать 2 GPU с тензорным параллелизмом
    --dtype float16 \                # Использовать точность FP16
    --max-num-seqs 256               # Максимальный размер батча

Ключевые параметры:

• --gpu-memory-utilization: Доля памяти GPU для менеджера модели (по умолчанию 0.92). Более высокие значения позволяют использовать более крупные батчи, но оставляют меньше запаса для всплесков памяти.
• --max-model-len: Максимальная длина контекста. Принимает количество токенов или человекочитаемые значения, такие как 32k. Уменьшение этого значения освобождает память для более крупных батчей.
• --tensor-parallel-size: Количество GPU, на которые следует разделить модель.
• --dtype: Тип данных для весов (auto, float16, bfloat16, float32). auto следует типу данных чекпоинта, что обычно является желаемым поведением.
• --max-num-seqs: Максимальное количество последовательностей в батче.
• --max-num-active-seqs: Ограничивает допуск в состояние RUNNING независимо от max_num_seqs (новое в v0.31.0) — полезно для ограничения задержек без сужения окна батча планировщика.

vLLM vs Ollama

vLLM спроектирован для высокопроизводительного, многопользовательского продакшен-обслуживания с непрерывным батчингом, PagedAttention и поддержкой нескольких GPU. Ollama оптимизирован для быстрого локального запуска, удобства для одного пользователя и простого управления моделями.

Для подробного руководства по принятию решений, охватывающего сигналы миграции, этапы планирования, настройку Docker Compose и практический чек-лист, см. Ollama to vLLM: Когда мигрировать ваш локальный LLM-сервер.

vLLM vs Docker Model Runner

Model Runner от Docker — их официальное решение для локального развёртывания ИИ-моделей. Как он сравняется с vLLM?

Философия архитектуры

Docker Model Runner стремится быть «Docker для ИИ» — простым, стандартизированным способом запуска ИИ-моделей локально с той же лёгкостью, что и запуск контейнеров. Он абстрагирует сложность и предоставляет согласованный интерфейс для разных моделей и фреймворков.

vLLM — это специализированный движок вывода, сфокусированный исключительно на обслуживании LLM с максимальной производительностью. Это инструмент нижнего уровня, который вы контейнеризироваете с помощью Docker, а не полноценная платформа.

Настройка и старт

Установка Docker Model Runner проста для пользователей Docker:

docker model pull llama3:8b
docker model run llama3:8b

Это сходство с рабочим процессом Docker с образами делает его мгновенно знакомым разработчикам, уже использующим контейнеры; полный набор команд находится в Шпаргалке по Docker Model Runner.

vLLM требует более сложной начальной настройки (Python, CUDA, зависимости) или использования готовых Docker-образов:

docker pull vllm/vllm-openai:latest
docker run --runtime nvidia --gpus all vllm/vllm-openai:latest --model <model-name>

Характеристики производительности

vLLM обеспечивает превосходную пропускную способность для многопользовательских сценариев благодаря PagedAttention и непрерывному батчингу. Для продакшен API-сервисов, обрабатывающих сотни запросов в секунду, оптимизации vLLM обеспечивают в 2–5 раз лучшую пропускную способность по сравнению с общими подходами к обслуживанию.

Docker Model Runner фокусируется на удобстве использования, а не на максимальной производительности. Он подходит для локальной разработки, тестирования и умеренных нагрузок, но не реализует продвинутые оптимизации, которые делают vLLM выдающимся при масштабировании.

Поддержка моделей

Docker Model Runner предоставляет курируемую библиотеку моделей с доступом к популярным моделям одной командой. Он поддерживает несколько фреймворков (не только LLM), включая Stable Diffusion, Whisper и другие ИИ-модели, что делает его более универсальным для различных ИИ-нагрузок.

vLLM специализируется на выводе LLM с глубокой поддержкой трансформерных языковых моделей. Он поддерживает любую LLM, совместимую с HuggingFace, но не распространяется на другие типы ИИ-моделей, такие как генерация изображений или распознавание речи.

Продакшен-развёртывание

vLLM апробирован в продакшене в таких компаниях, как Anthropic, Replicate и многих других, обслуживающих миллиарды токенов ежедневно. Его характеристики производительности и стабильность под высокой нагрузкой делают его фактическим стандартом для продакшен-обслуживания LLM.

Docker Model Runner новее и позиционируется скорее для сценариев разработки и локального тестирования. Хотя он может обслуживать продакшен-трафик, ему не хватает проверенного времени использования и оптимизаций производительности, необходимых для продакшен-развёртываний.

Экосистема интеграций

vLLM интегрируется с инструментами продакшен-инфраструктуры: Kubernetes-операторы, метрики Prometheus, Ray для распределённого обслуживания и расширенная совместимость с API OpenAI для существующих приложений.

Docker Model Runner естественно интегрируется с экосистемой Docker и Docker Desktop. Для команд, уже стандартизированных на Docker, эта интеграция обеспечивает целостный опыт, но с меньшим количеством специализированных функций обслуживания LLM.

Когда использовать каждый

Используйте vLLM для:

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

Используйте Docker Model Runner для:

• Локальной разработки и тестирования
• Запуска различных типов ИИ-моделей (не только LLM)
• Команд, глубоко вовлечённых в экосистему Docker
• Быстрых экспериментов без настройки инфраструктуры
• Обучающих и образовательных целей

Гибридный подход: Многие команды разрабатывают локально с Docker Model Runner для удобства, а затем развёртывают с vLLM в продакшене для производительности. Образы Docker Model Runner также можно использовать для запуска контейнеров vLLM, объединяя оба подхода.

Лучшие практики продакшен-развёртывания

Развёртывание с Docker

Создайте готовый к продакшену конфигурацию Docker Compose:

version: '3.8'

services:
  vllm:
    image: vllm/vllm-openai:latest
    runtime: nvidia
    environment:
      - CUDA_VISIBLE_DEVICES=0,1
    volumes:
      - ~/.cache/huggingface:/root/.cache/huggingface
      - ./logs:/logs
    ports:
      - "8000:8000"
    command: >
      --model Qwen/Qwen3-8B
      --tensor-parallel-size 2
      --gpu-memory-utilization 0.90
      --max-num-seqs 256
      --max-model-len 8192
    restart: unless-stopped
    shm_size: '16gb'
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 2
              capabilities: [gpu]

Развёртывание в Kubernetes

Разверните vLLM в Kubernetes для продакшен-масштаба:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: vllm-server
spec:
  replicas: 2
  selector:
    matchLabels:
      app: vllm
  template:
    metadata:
      labels:
        app: vllm
    spec:
      containers:
      - name: vllm
        image: vllm/vllm-openai:latest
        args:
          - --model
          - Qwen/Qwen3-8B
          - --tensor-parallel-size
          - "2"
          - --gpu-memory-utilization
          - "0.90"
        resources:
          limits:
            nvidia.com/gpu: 2
        ports:
        - containerPort: 8000
        volumeMounts:
        - name: cache
          mountPath: /root/.cache/huggingface
      volumes:
      - name: cache
        hostPath:
          path: /mnt/huggingface-cache
---
apiVersion: v1
kind: Service
metadata:
  name: vllm-service
spec:
  selector:
    app: vllm
  ports:
  - port: 80
    targetPort: 8000
  type: LoadBalancer

Мониторинг и наблюдаемость

OpenAI-совместимый сервер по умолчанию exposes метрики Prometheus на /metrics — дополнительные флаги не нужны:

curl -s http://localhost:8000/metrics | grep '^vllm:'

Ключевые метрики для мониторинга:

• vllm:num_requests_running / vllm:num_requests_waiting / vllm:num_requests_swapped — запросы в состояниях планировщика RUNNING, WAITING и SWAPPED
• vllm:kv_cache_usage_perc — доля используемых блоков кэша KV (0–1)
• vllm:time_to_first_token_seconds — гистограмма TTFT (время до первого токена)
• vllm:time_per_output_token_seconds — скорость генерации на токен
• vllm:num_preemptions_total — накопленные преэмции (preemptions); растущий счётчик означает, что кэш KV переполнен, и запросы пересчитываются

Для дашбордов, примеров PromQL и порогов тревог вокруг обслуживания LLM, см. Мониторинг вывода LLM в продакшене (2026): Prometheus & Grafana для vLLM, TGI, llama.cpp.

Настройка производительности

Оптимизация использования памяти GPU: По умолчанию значение 0.92; настраивайте на основе наблюдаемого поведения. Более высокие значения позволяют использовать более крупные батчи, но несут риск ошибок OOM во время всплесков трафика.

Настройка максимальной длины последовательности: Если вашему сценарию не нужен полный контекст, уменьшите --max-model-len. Это освобождает память для более крупных батчей. Например, если вам нужен только контекст 4K, установите --max-model-len 4096, а не используйте максимум модели (часто 8K–32K).

Выбор подходящей квантизации: Для моделей, которые это поддерживают, используйте квантованные версии (8-bit, 4-bit), чтобы снизить потребление памяти и увеличить пропускную способность:

--quantization awq  # Для AWQ квантованных моделей
--quantization gptq # Для GPTQ квантованных моделей

Кэширование префиксов (Prefix Caching): Кэширование префиксов включено по умолчанию в текущем движке, поэтому запросы, разделяющие префикс промпта (фиксированный системный промпт, шаблон контекста RAG), повторно используют его кэш KV без каких-либо флагов. Отключите его с помощью --no-enable-prefix-caching для нагрузок со многими уникальными длинными промптами, где учёт кэша ничего не даёт.

Диагностика типовых проблем

Ошибки нехватки памяти (Out of Memory)

Симптомы: Сервер аварийно завершает работу с ошибками CUDA out of memory.

Решения:

• Уменьшите --gpu-memory-utilization до 0.85 или 0.80
• Уменьшите --max-model-len, если это позволяет ваш сценарий
• Снизьте --max-num-seqs, чтобы уменьшить размер батча
• Используйте квантованную версию модели
• Включите тензорный параллелизм для распределения по большему количеству GPU

Два различных типа OOM требуют разных исправлений. OOM при запуске происходит до любого запроса: vLLM профилирует память и не может выделить даже минимальный кэш KV, поэтому снижение --max-num-seqs не помогает — уменьшите --max-model-len или увеличьте --gpu-memory-utilization, если у вас есть запас. OOM во время работы под нагрузкой может быть вызвано памятью, захваченной CUDA-graph, которая масштабируется с --max-num-seqs, но находится вне учёта кэша KV; запустите один раз с --enforce-eager, чтобы проверить, являются ли CUDA-графы недостающей памятью, и протестируйте точную ту же конфигурацию перед тем, как винить кэш. Если запуски на идентичном оборудовании продолжают успешно завершаться с тем же выделением, передайте значение --kv-cache-memory-bytes, которое vLLM логирует при запуске, чтобы пропустить этап профилирования при последующих запусках.

На одиночной карте 16 ГБ большинство этих ошибок OOM сводятся к бюджету кэша KV, а не только к весам — Кэш KV на GPU с 16 ГБ рассматривает точную формулу, тип данных KV-кэша FP8 и компромиссы кэширования префиксов за --max-model-len и --max-num-seqs до того, как вы перейдёте к более маленькой модели.

Медленный запуск

Симптомы: Серверу требуются минуты от запуска до “Application startup complete”.

Решения:

• Загрузка весов, компиляция и захват CUDA-graph доминируют при запуске — --enforce-eager пропускает обе компиляцию и захват и показывает, сколько времени они занимают, ценой снижения скорости декодирования в стационарном режиме
• Повторно используйте залогированное значение --kv-cache-memory-bytes, чтобы пропустить этапы профилирования памяти и оценки CUDA-graph при повторяющихся запусках
• В v0.30.0+ команда vllm preload запускает постоянный демон кэша весов, который держит квантованные веса в памяти GPU, поэтому перезапуски движка отображают веса через CUDA IPC вместо повторного чтения с диска (--load-format ipc_cache)
• Для чекпоинтов NVFP4, которые получают OOM во время компиляции при запуске, ограничение потоков сборки с помощью MAX_JOBS=4 и NVCC_THREADS=4 — широко используемое исправление — это замедляет JIT-сборку, но останавливает OOM

Низкая пропускная способность

Симптомы: Сервер обрабатывает меньше запросов, чем ожидается.

Решения:

• Увеличьте --max-num-seqs, чтобы позволить более крупные батчи
• Увеличьте --gpu-memory-utilization, если у вас есть запас
• Проверьте, является ли CPU узким местом с помощью htop – рассмотрите более быстрые CPU
• Проверьте использование GPU с помощью nvidia-smi – оно должно быть 95%+
• Включите FP16, если используете FP32: --dtype float16

Медленное время первого токена

Симптомы: Высокая задержка перед началом генерации.

Решения:

• Используйте более мелкие модели для приложений, чувствительных к задержкам
• Кэширование префиксов включено по умолчанию — проверьте, что оно активно, вместо повторного добавления флага
• Уменьшите --max-num-seqs, чтобы приоритизировать задержки над пропускной способностью
• Рассмотрите спекулятивное декодирование для поддерживаемых моделей
• Оптимизируйте конфигурацию тензорного параллелизма

Сбои при загрузке модели

Симптомы: Сервер не запускается, не может загрузить модель.

Решения:

• Убедитесь, что название модели точно совпадает с форматом HuggingFace
• Проверьте сетевое соединение с HuggingFace Hub
• Убедитесь в наличии достаточного дискового пространства в ~/.cache/huggingface
• Для закрытых моделей установите переменную окружения HF_TOKEN
• Попробуйте скачать вручную с помощью hf download <model> (или huggingface-cli download <model> в старых установках)

Продвинутые функции

Спекулятивное декодирование

vLLM поддерживает спекулятивное декодирование, где меньшая модель-черновик предлагает токены, которые большая целевая модель проверяет. Это может ускорить генерацию в 1.5–2 раза. Для комплексного руководства по методам спекулятивного декодирования — модель-черновик, EAGLE-3, P-EAGLE и n-gram — см. Спекулятивное декодирование: Более быстрый вывод без потери качества.

vllm serve meta-llama/Llama-3.1-8B-Instruct \
    --speculative-config '{"method": "draft_model", "model": "meta-llama/Llama-3.2-1B-Instruct", "num_speculative_tokens": 4}'

Старые флаги --speculative-model и --num-speculative-tokens исчезли — конфигурация переместилась в единственный аргумент JSON --speculative-config, который также выбирает метод (draft_model, ngram, семейство EAGLE или MTP для моделей с нативными головками предсказания нескольких токенов).

Адаптеры LoRA

Обслуживайте несколько адаптеров LoRA поверх базовой модели, не загружая несколько полных моделей:

vllm serve meta-llama/Llama-3.1-8B-Instruct \
    --enable-lora \
    --lora-modules sql-lora=/path/to/sql-adapter \
                   code-lora=/path/to/code-adapter

Затем укажите, какой адаптер использовать для каждого запроса, поместив его имя в поле model — этот же механизм масштабируется до десятков задач-специфичных адаптеров (специфичных для клиента или доменных вариантов) с только базовой моделью, резидентной в памяти:

response = client.completions.create(
    model="sql-lora",  # Использование SQL-адаптера
    prompt="Convert this to SQL: Show me all users created this month"
)

Кэширование префиксов

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

Оно даёт наибольший эффект для:

• Чат-ботов с фиксированными системными промптами
• Приложений RAG с согласованными шаблонами контекста
• Промптов few-shot обучения, повторяющихся между запросами

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

Примеры интеграции

Интеграция с LangChain

from langchain_community.llms import VLLMOpenAI

llm = VLLMOpenAI(
    openai_api_key="EMPTY",
    openai_api_base="http://localhost:8000/v1",
    model_name="Qwen/Qwen3-8B",
    max_tokens=512,
    temperature=0.7,
)

response = llm("Explain PagedAttention in simple terms")
print(response)

Приложение FastAPI

from fastapi import FastAPI
from openai import AsyncOpenAI

app = FastAPI()
client = AsyncOpenAI(
    base_url="http://localhost:8000/v1",
    api_key="not-needed"
)

@app.post("/generate")
async def generate(prompt: str):
    response = await client.completions.create(
        model="Qwen/Qwen3-8B",
        prompt=prompt,
        max_tokens=200
    )
    return {"result": response.choices[0].text}

Бенчмарки производительности

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

Сравнение пропускной способности (Mistral-7B на GPU A100):

• vLLM: ~3 500 токенов/секунду с 64 одновременными пользователями
• HuggingFace Transformers: ~250 токенов/секунду с той же конкурентностью
• Ollama: ~1 200 токенов/секунду с той же конкурентностью
• Результат: vLLM обеспечивает 14-кратное улучшение по сравнению с базовыми реализациями

Эффективность памяти (LLaMA-2-13B):

• Стандартная реализация: 24 ГБ VRAM, 32 одновременные последовательности
• vLLM с PagedAttention: 24 ГБ VRAM, 128 одновременных последовательностей
• Результат: В 4 раза больше одновременных запросов при той же памяти

Задержки под нагрузкой (Mixtral-8x7B на 2xA100):

• vLLM: P50 задержка 180 мс, P99 задержка 420 мс при 100 req/s
• Стандартное обслуживание: P50 задержка 650 мс, P99 задержка 3 200 мс при 100 req/s
• Результат: vLLM сохраняет стабильные задержки при высокой нагрузке

Анализ затрат

Понимание последствий для затрат при выборе vLLM:

Сценарий: Обслуживание 1 млн запросов/день

Со стандартным обслуживанием:

• Необходимо: 8x A100 GPU (80 ГБ)
• Стоимость AWS: ~$32/час × 24 × 30 = $23 040/месяц
• Стоимость за 1 млн токенов: ~$0.75

С vLLM:

• Необходимо: 2x A100 GPU (80 ГБ)
• Стоимость AWS: ~$8/час × 24 × 30 = $5 760/месяц
• Стоимость за 1 млн токенов: ~$0.19
• Экономия: $17 280/месяц (снижение на 75%)

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

Соображения по безопасности

Аутентификация

vLLM поставляется со встроенным флагом --api-key, но, согласно официальной документации, он аутентифицирует только эндпоинты под префиксами путей /v1, /v2 и /inference — другие эндпоинты на том же сервере остаются неаутентифицированными. Рассматривайте его как один слой, а не как полный ответ; для полного покрытия реализуйте аутентификацию на уровне обратного прокси:

# Конфигурация Nginx
location /v1/ {
    auth_request /auth;
    proxy_pass http://vllm-backend:8000;
}

location /auth {
    proxy_pass http://auth-service:8080/verify;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
    proxy_set_header X-Original-URI $request_uri;
}

Используйте API-шлюзы, такие как Kong, Traefik или AWS API Gateway, для корпоративной аутентификации и ограничения частоты запросов.

Сетевая изоляция

Запускайте vLLM в частных сетях, а не прямо экспонируйте в интернет:

# Пример NetworkPolicy Kubernetes
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: vllm-access
spec:
  podSelector:
    matchLabels:
      app: vllm
  policyTypes:
  - Ingress
  ingress:
  - from:
    - podSelector:
        matchLabels:
          role: api-gateway
    ports:
    - protocol: TCP
      port: 8000

Ограничение частоты запросов

Реализуйте ограничение частоты запросов для предотвращения злоупотреблений:

# Пример использования Redis для ограничения частоты
from fastapi import FastAPI, HTTPException
from fastapi.middleware.cors import CORSMiddleware
import redis
from datetime import datetime, timedelta

app = FastAPI()
redis_client = redis.Redis(host='localhost', port=6379)

@app.middleware("http")
async def rate_limit_middleware(request, call_next):
    client_ip = request.client.host
    key = f"rate_limit:{client_ip}"
    
    requests = redis_client.incr(key)
    if requests == 1:
        redis_client.expire(key, 60)  # 60-секундное окно
    
    if requests > 60:  # 60 запросов в минуту
        raise HTTPException(status_code=429, detail="Rate limit exceeded")
    
    return await call_next(request)

Контроль доступа к моделям

Для мульти-тенантовых развёртываний контролируйте, какие пользователи имеют доступ к каким моделям:

ALLOWED_MODELS = {
    "user_tier_1": ["Qwen/Qwen3-8B"],
    "user_tier_2": ["Qwen/Qwen3-8B", "meta-llama/Llama-2-13b-chat-hf"],
    "admin": ["*"]  # Все модели
}

def verify_model_access(user_tier: str, model: str) -> bool:
    allowed = ALLOWED_MODELS.get(user_tier, [])
    return "*" in allowed or model in allowed

Руководство по миграции

С OpenAI на vLLM

Миграция с OpenAI на self-hosted vLLM проста благодаря совместимости API:

До (OpenAI):

from openai import OpenAI

client = OpenAI(api_key="sk-...")
response = client.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[{"role": "user", "content": "Hello"}]
)

После (vLLM):

from openai import OpenAI

client = OpenAI(
    base_url="https://your-vllm-server.com/v1",
    api_key="your-internal-key"  # Если вы добавили аутентификацию
)
response = client.chat.completions.create(
    model="Qwen/Qwen3-8B",
    messages=[{"role": "user", "content": "Hello"}]
)

Необходимо всего два изменения: обновить base_url и название model. Весь остальной код остаётся идентичным.

С Ollama на vLLM

Ollama использует другой формат API. Базовое изменение на стороне клиента — переключение с REST-эндпоинта Ollama на OpenAI-совместимый API vLLM:

API Ollama:

import requests

response = requests.post('http://localhost:11434/api/generate',
    json={'model': 'llama2', 'prompt': 'Why is the sky blue?'})

Эквивалент в vLLM:

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="not-needed")
response = client.completions.create(
    model="meta-llama/Llama-2-7b-chat-hf",
    prompt="Why is the sky blue?"
)

API Ollama — это простой REST с собственной формой запроса, тогда как vLLM говорит на протоколе OpenAI — это различие в формате API является основным изменением на стороне клиента, и поэтапный подход (запуск обоих серверов, сдвиг трафика эндпоинт за эндпоинтом) описан в руководстве по миграции, на которое дана ссылка ранее в этой статье.

С HuggingFace Transformers на vLLM

Миграция прямого использования Python:

HuggingFace:

from transformers import AutoModelForCausalLM, AutoTokenizer

model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen3-8B")
tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen3-8B")

inputs = tokenizer("Hello", return_tensors="pt")
outputs = model.generate(**inputs, max_new_tokens=100)
result = tokenizer.decode(outputs[0])

vLLM:

from vllm import LLM, SamplingParams

llm = LLM(model="Qwen/Qwen3-8B")
sampling_params = SamplingParams(max_tokens=100)

outputs = llm.generate("Hello", sampling_params)
result = outputs[0].outputs[0].text

Python API vLLM проще и намного быстрее для пакетного вывода.

Недавние релизы: Что изменилось в 2026 году

Три релиза в сентябре–октябре 2026 (v0.29.0, v0.30.0, v0.31.0) показывают, куда направлено развитие:

Быстрые перезапуски: vllm preload запускает постоянный демон кэша весов на каждый GPU, который держит квантованные, разделённые по TP веса резидентными в памяти GPU, поэтому перезапущенные движки отображают их через CUDA IPC (--load-format ipc_cache) вместо повторного чтения с диска. Экспериментальная vllm snapshot create/restore снимает снапшот полностью инициализированного движка с CRIU.

Спекулятивное декодирование в Model Runner V2: спекулятивное декодирование с моделью-черновиком, кастомные обработчики логитов и адаптивная проверка перемещены на новый модельный раннер, с добавлением драфта LiLiCorr и асинхронного планирования для драфта DFlash.

Обслуживание MoE в больших масштабах: новые сбалансированные бэкенды all2all с экспертным параллелизмом (--all2all-backend moonep), DeepEPv2 с последовательным параллелизмом, EPLB с перекрытием общего эксперта и параллелизм префилл-контекста, комбинированный с параллелизмом данных.

Контроль планирования: --max-num-active-seqs ограничивает допуск в состояние RUNNING независимо от max_num_seqs, и очередь ожидания теперь планирует запросы, которые уже удерживают блоки KV, в первую очередь.

Пункты дорожной карты из старых руководств по vLLM давно вышли — поддержка GGUF, мультимодальное обслуживание, дизагрегированный префилл/декод и многосерверный вывод являются частью текущих релизов, поэтому относитесь к любому руководству, которое перечисляет их как «скоро», к устаревшим. Заметки о релизах для каждой версии находятся на странице релизов vLLM.

Полезные ссылки

Связанные статьи на этом сайте

• Шпаргалка по Ollama - Полное справочное руководство по командам Ollama и шпаргалка, охватывающая установку, управление моделями, использование API и лучшие практики для локального развёртывания LLM. Необходимо для разработчиков, использующих Ollama вместе с vLLM или вместо него.

• Docker Model Runner vs Ollama: Что выбрать? - Глубокое сравнение Model Runner от Docker и Ollama для локального развёртывания LLM, анализ производительности, поддержки GPU, совместимости API и случаев использования. Помогает понять конкурентную среду, в которой работает vLLM.

Внешние ресурсы и документация

• Репозиторий vLLM на GitHub - Официальный репозиторий vLLM с исходным кодом, исчерпывающей документацией, руководствами по установке и активными обсуждениями сообщества. Необходимый ресурс для отслеживания последних функций и решения проблем.

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

• Статья о PagedAttention - Академическая статья, представляющая алгоритм PagedAttention, обеспечивающий эффективность vLLM. Обязательное чтение для понимания технических инноваций, стоящих за преимуществами производительности vLLM.

• Блог vLLM - Официальный блог vLLM с анонсами релизов, бенчмарками производительности, техническими глубинными разборами и примерами из продакшен-развёртываний сообщества.

• Хаб моделей HuggingFace - Комплексный репозиторий open-source LLM, которые работают с vLLM. Ищите модели по размеру, задаче, лицензии и характеристикам производительности, чтобы найти подходящую модель для вашего сценария.

• Документация Ray Serve - Документация фреймворка Ray Serve для построения масштабируемых, распределённых развёртываний vLLM. Ray предоставляет продвинутые функции, такие как автоскейлинг, обслуживание нескольких моделей и управление ресурсами для продакшен-систем.

• NVIDIA TensorRT-LLM - TensorRT-LLM от NVIDIA для высокооптимизированного вывода на GPU NVIDIA. Альтернатива vLLM с другими стратегиями оптимизации, полезная для сравнения и понимания ландшафта оптимизации вывода.

• Справка по API OpenAI - Официальная документация API OpenAI, с которой совместим API vLLM. Ссылайтесь на неё при создании приложений, которые должны работать как с OpenAI, так и с self-hosted эндпоинтами vLLM взаимозаменяемо.