Как запустить vLLM локально: установка на Linux, WSL и Docker

vLLM запускает языковую модель на своём компьютере или сервере и даёт приложениям доступ к ней через API. Ниже вы установите его на Ubuntu или Windows через WSL 2, запустите тестовую модель и проверите ответ. Для примеров понадобится совместимая видеокарта NVIDIA.

Что такое vLLM и кому он пригодится

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

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

Для личного чата на компьютере обычно удобнее Ollama или LM Studio: у них проще установка и есть готовый интерфейс. Эти программы тоже запускают локальный API и подходят для прототипа или одного пользователя. vLLM рассчитан на сервер с несколькими одновременными запросами и высокой общей нагрузкой.

Дальше разбираем серверный вариант: приложение отправляет запрос в vLLM, программа передаёт его модели на видеокарте и возвращает ответ.

Что понадобится для запуска

Перед установкой проверьте пять пунктов:

1. Операционная система. vLLM рассчитан на Linux. На Windows потребуется WSL 2 с Ubuntu, поскольку нативная установка в этой системе сейчас не поддерживается.
2. Python. Для установки без Docker нужна версия 3.11–3.14. В примерах ниже используется Python 3.12.
3. Видеокарта. Команды в инструкции рассчитаны на NVIDIA T4, RTX 20-й серии или более новую карту с поддержкой CUDA. Команда nvidia-smi должна видеть GPU.
4. Место на диске и видеопамять. Точный объём зависит от модели. Для первого запуска возьмём Qwen3-0.6B: модель небольшая и подходит для проверки установки.
5. Интернет. Он понадобится для установки пакетов и первой загрузки модели.

Для AMD, Intel и Apple Silicon используются другие варианты установки. Их команды отличаются от примеров ниже, поэтому в этой инструкции разбираем путь с NVIDIA.

Установка через uv и запуск в Docker — два самостоятельных способа. Для первого знакомства выбирайте один из них; ставить оба варианта не требуется.

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

Сначала проверьте доступ к видеокарте. Если вы выбрали установку через uv или pip, заодно проверьте версию Python:

nvidia-smi

python3 --version

Первая команда должна показать видеокарту, версию драйвера и объём занятой памяти. Если терминал пишет, что nvidia-smi не найден, сначала установите или обновите драйвер NVIDIA.

Как подготовить Windows: WSL 2 и Ubuntu

WSL 2 запускает Ubuntu внутри Windows, поэтому команды для Linux можно выполнять без отдельного компьютера. Если у вас уже установлен Ubuntu или другой поддерживаемый Linux, переходите к следующему разделу. В Windows откройте PowerShell от имени администратора и выполните:

wsl --install -d Ubuntu

После установки перезагрузите компьютер. Снова откройте PowerShell и обновите WSL:

wsl --update

Теперь откройте Ubuntu через меню «Пуск». Придумайте имя пользователя и пароль, затем проверьте доступ к видеокарте:

nvidia-smi

Для работы GPU внутри WSL нужен актуальный драйвер NVIDIA для Windows. Отдельный Linux-драйвер NVIDIA в Ubuntu под WSL устанавливать не следует: доступ к видеокарте передаёт Windows-драйвер.

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

Этот раздел нужен для запуска через Python. Если вы выбрали Docker, переходите к разделу «Как запустить vLLM в Docker». Для установки через Python разработчики рекомендуют отдельное окружение и инструмент uv: он хранит библиотеки проекта в отдельной папке и подбирает версию PyTorch, необходимую vLLM для работы с видеокартой.

Установите uv

В Ubuntu или терминале WSL выполните две команды:

curl -LsSf https://astral.sh/uv/install.sh | sh

source "$HOME/.local/bin/env"

Проверьте установку:

uv --version

Создайте окружение и установите vLLM

Создайте папку для теста, активируйте окружение и установите vLLM:

mkdir vllm-test

cd vllm-test

uv venv --python 3.12 --seed

source .venv/bin/activate

uv pip install vllm --torch-backend=auto

vllm download-kernels

Команда vllm download-kernels заранее загружает готовые компоненты для новых видеокарт. Без неё vLLM может скачивать и собирать их при первом запуске, поэтому сервер будет готов не сразу.

Если вы предпочитаете обычный pip, создайте чистое окружение и установите текущую сборку vLLM так:

python3 -m venv .venv

source .venv/bin/activate

python -m pip install --upgrade pip

python -m pip install vllm

vllm download-kernels

Выберите один способ установки — через uv или pip — и выполняйте команды в чистой папке. Отдельное окружение снижает риск конфликтов между версиями CUDA, PyTorch и других библиотек.

Как запустить модель через vLLM

Для проверки используем открытую модель Qwen/Qwen3-0.6B. Она небольшая и подходит для проверки установки. После запуска сервера выбирайте модель по качеству ответов на ваших задачах и доступному объёму видеопамяти.

В том же терминале после команды source .venv/bin/activate выполните:

vllm serve Qwen/Qwen3-0.6B \

  --host 127.0.0.1 \

  --port 8000 \

  --api-key local-test-key \

  --max-model-len 2048

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

Параметр —host 127.0.0.1 оставляет сервер доступным только на этом компьютере. —max-model-len 2048 ограничивает длину контекста и снижает расход видеопамяти во время первого теста. Чтобы остановить сервер, вернитесь в первый терминал и нажмите Ctrl + C.

Как проверить, что сервер отвечает

Откройте второй терминал. Сначала запросите состояние сервера:

curl http://127.0.0.1:8000/health

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

curl http://127.0.0.1:8000/v1/models \

  -H "Authorization: Bearer local-test-key"

Теперь отправьте сообщение модели:

curl http://127.0.0.1:8000/v1/chat/completions \

  -H "Content-Type: application/json" \

  -H "Authorization: Bearer local-test-key" \

  -d '{

    "model": "Qwen/Qwen3-0.6B",

    "messages": [

      {

        "role": "user",

        "content": "Ответь одним предложением: что такое vLLM?"

      }

    ],

    "max_tokens": 80

  }'

В ответ придёт JSON. Текст модели находится в поле choices[0].message.content. Если вы его получили, установка закончена и локальный API готов принимать запросы.

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

Docker запускает vLLM и его библиотеки внутри отдельного контейнера, поэтому они не смешиваются с пакетами в основной системе. В Linux понадобятся Docker Engine, драйвер NVIDIA и NVIDIA Container Toolkit. В Windows используйте Docker Desktop с включённым движком WSL 2, обновлённым WSL и актуальным драйвером NVIDIA.

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

docker run --rm --gpus all \

  -p 127.0.0.1:8000:8000 \

  --ipc=host \

  -v "$HOME/.cache/huggingface:/root/.cache/huggingface" \

  vllm/vllm-openai:v0.33.0 \

  --model Qwen/Qwen3-0.6B \

  --api-key local-test-key \

  --max-model-len 2048

Папка с моделями подключена как том, поэтому Docker не будет скачивать одни и те же файлы при каждом запуске. Порт опубликован только на 127.0.0.1, и к нему нельзя обратиться с другого устройства в сети.

Для модели с ограниченным доступом сначала получите токен Hugging Face. В команде docker run добавьте строку —env HF_TOKEN=»$HF_TOKEN» перед названием образа vllm/vllm-openai:v0.33.0. У Qwen3-0.6B открытый доступ, поэтому в этом примере токен не нужен.

Запуск через Docker Compose

Docker Compose сохраняет все параметры запуска в одном файле. Для первого теста этот подраздел можно пропустить; если сервер требуется запускать регулярно, создайте файл compose.yaml:

services:

  vllm:

    image: vllm/vllm-openai:v0.33.0

    ports:

      - "127.0.0.1:8000:8000"

    ipc: host

    volumes:

      - ${HOME}/.cache/huggingface:/root/.cache/huggingface

    deploy:

      resources:

        reservations:

          devices:

            - driver: nvidia

              count: all

              capabilities: [gpu]

    command:

      - --model

      - Qwen/Qwen3-0.6B

      - --api-key

      - local-test-key

      - --max-model-len

      - "2048"

Запустите контейнер:

docker compose up

Для остановки нажмите Ctrl + C, затем выполните docker compose down.

Как подключить vLLM к Python-приложению

Благодаря совместимости с OpenAI API для vLLM подходит официальный Python-клиент OpenAI. Установите библиотеку в окружение своего приложения:

pip install openai

Создайте файл app.py:

from openai import OpenAIclient = OpenAI(    base_url="http://127.0.0.1:8000/v1",    api_key="local-test-key",)response = client.chat.completions.create(    model="Qwen/Qwen3-0.6B",    messages=[        {            "role": "user",            "content": "Предложи три темы для статьи о работе с нейросетями",        }    ],    max_tokens=150,)print(response.choices[0].message.content)

Запустите скрипт командой python app.py. По такому принципу к vLLM подключают чат-ботов, внутренние инструменты, обработчики документов и сервисы для работы с контентом. Команде в digital-маркетинге локальный API может пригодиться для классификации текстов, подготовки черновиков и поиска по собственной базе знаний.

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

Частые ошибки при запуске vLLM

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

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

Как открыть доступ к серверу безопасно

В примерах сервер принимает запросы только на 127.0.0.1, и это подходящий вариант для знакомства с vLLM. Для доступа из локальной сети или интернета запросы лучше пропускать через отдельный веб-сервер-посредник, например Nginx, и настроить HTTPS, фильтрацию адресов и авторизацию.

Параметр —api-key проверяет ключ для адресов /v1, /v2 и /inference, но часть адресов сервера остаётся без такой проверки. Например, это относится к /invocations. Поэтому открывать порт 8000 в интернет, полагаясь только на этот ключ, небезопасно; логи и история запросов тоже требуют защиты, особенно при работе с клиентскими или внутренними данными.

Когда лучше выбрать другой способ запуска модели

vLLM рассчитан на серверный сценарий и видеокарту. Для эксперимента на обычном ноутбуке проще начать с Ollama или LM Studio. Если своего GPU нет, можно арендовать сервер с видеокартой или использовать облачный API.

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

Что делать после первого запуска

После первого ответа отправьте модели несколько задач из своей работы: классификацию текстов, извлечение фактов или подготовку черновика. Сравните качество ответа, скорость и расход видеопамяти. Если сервер нужен регулярно, сохраните параметры в Docker Compose и настройте доступ через веб-сервер-посредник. Более крупную модель имеет смысл проверять, когда текущей не хватает качества, а на видеокарте остаётся свободная память.

FAQ