Инференс LLM на vLLM

В этом руководстве показано, как на сервере FullGPU запустить инференс LLM (большой языковой модели) с vLLM: создать окружение Python, установить PyTorch и vLLM, запустить OpenAI-совместимый эндпоинт на одном GPU или сразу на восьми, проверить его с помощью curl и оформить как службу systemd. Прежде чем выбирать модель, оцените, сколько памяти ей нужно, с помощью калькулятора видеопамяти (VRAM). В BF16 веса занимают примерно 2 байта на параметр, плюс нужно место под KV-кэш.

Установка PyTorch и vLLM в окружение Python

Создание окружения

uv быстро создаёт окружения и устанавливает пакеты, а ещё умеет скачивать версию Python, которой нет в вашей ОС:

curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env
uv venv ~/venvs/vllm --python 3.12
source ~/venvs/vllm/bin/activate

Если вы предпочитаете стандартные инструменты, выполните sudo apt install -y python3-venv, затем python3 -m venv ~/venvs/vllm и ту же строку с source. Держите vLLM в собственном окружении, отдельно от кода для обучения.

Установка пакетов

uv pip install vllm --torch-backend=auto
python -c "import torch, vllm; print(torch.__version__,
  torch.cuda.is_available(), vllm.__version__)"

Между двумя номерами версий должно стоять True. vLLM фиксирует версию PyTorch, с которой он собран, и сам её устанавливает, а --torch-backend=auto позволяет uv выбрать сборку PyTorch, подходящую для вашего драйвера. Не устанавливайте поверх другую версию PyTorch. Для окружения обучения без vLLM установите только PyTorch тем же способом: uv pip install torch --torch-backend=auto. С обычным pip выполните pip install vllm.

Запуск OpenAI-совместимого сервера

Для первой проверки на одном GPU хорошо подходит модель класса 7B:

vllm serve Qwen/Qwen2.5-7B-Instruct \
  --host 127.0.0.1 --port 8000 \
  --max-model-len 16384 \
  --gpu-memory-utilization 0.90

На 8-GPU-сервере распределите модель покрупнее по всем GPU с помощью тензорного параллелизма:

vllm serve Qwen/Qwen2.5-72B-Instruct \
  --host 127.0.0.1 --port 8000 \
  --tensor-parallel-size 8 \
  --max-model-len 32768

При первом запуске скачиваются веса, и это может занять некоторое время. Сервер готов, когда в логе появится Application startup complete. Веса сохраняются в ~/.cache/huggingface; чтобы хранить их на NVMe-диске для данных, перед запуском выполните export HF_HOME=/data/hf.

Проверка API с помощью curl

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

curl http://127.0.0.1:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "Qwen/Qwen2.5-7B-Instruct",
       "messages": [{"role": "user", "content": "Say hello in five words."}],
       "max_tokens": 32}'

Первый запрос должен вывести модель в списке. Второй возвращает JSON, в котором ответ находится в choices[0].message.content. Подойдёт любой OpenAI-совместимый клиент, если указать в нём базовый URL http://127.0.0.1:8000/v1. Со своего ноутбука обращайтесь к серверу через SSH-туннель: ssh -N -L 8000:127.0.0.1:8000 gpu1.

Токен Hugging Face для моделей с ограниченным доступом

Для некоторых моделей, например семейства Llama от Meta, нужно принять лицензию на Hugging Face. Примите её на странице модели под своим аккаунтом, создайте токен доступа с правом чтения и передайте его vLLM в переменной HF_TOKEN. Если ввести токен по запросу, он не попадёт в историю командной оболочки:

read -rsp 'Hugging Face token: ' HF_TOKEN && export HF_TOKEN
vllm serve meta-llama/Llama-3.1-8B-Instruct \
  --host 127.0.0.1 --port 8000 --max-model-len 16384

Ошибка 401 или 403 при скачивании означает, что токен не задан или неверен либо для этого аккаунта не принята лицензия.

Запуск vLLM как службы systemd

1. Храните настройки и секреты в файле, который может читать только root. Сгенерируйте API-ключ командой openssl rand -hex 32; vLLM читает VLLM_API_KEY так же, как если бы вы передали --api-key.

   sudo mkdir -p /etc/vllm
   sudo tee /etc/vllm/vllm.env >/dev/null <<'EOF'
   HF_HOME=/data/hf
   HF_TOKEN=hf_your_token_here
   VLLM_API_KEY=replace-with-a-long-random-string
   EOF
   sudo chmod 600 /etc/vllm/vllm.env

2. Создайте /etc/systemd/system/vllm.service. В этом примере служба работает от имени root с окружением, созданным выше; для другой учётной записи измените User и пути:

   [Unit]
   Description=vLLM OpenAI-compatible server
   After=network-online.target
   Wants=network-online.target
   
   [Service]
   User=root
   EnvironmentFile=/etc/vllm/vllm.env
   ExecStart=/root/venvs/vllm/bin/vllm serve Qwen/Qwen2.5-7B-Instruct \
     --host 127.0.0.1 --port 8000 --max-model-len 16384
   Restart=on-failure
   RestartSec=10
   
   [Install]
   WantedBy=multi-user.target

3. Запустите службу и следите за логом:

   sudo systemctl daemon-reload
   sudo systemctl enable --now vllm
   sudo journalctl -u vllm -f

   Когда в логе появится Application startup complete, проверки через curl снова заработают, если добавить заголовок -H "Authorization: Bearer YOUR_KEY". Без него вы должны получить 401 Unauthorized. Служба перезапускается после сбоя и стартует при загрузке системы.

Альтернатива: образ vllm/vllm-openai

docker run -d --name vllm --gpus all --ipc=host \
  -p 127.0.0.1:8000:8000 \
  -v /data/hf:/data/hf \
  --env-file /etc/vllm/vllm.env \
  vllm/vllm-openai:latest \
  --model Qwen/Qwen2.5-7B-Instruct --max-model-len 16384

Точка входа (entrypoint) образа — сервер vLLM, поэтому аргументы после имени образа передаются прямо ему. Файл с переменными окружения задаёт HF_HOME=/data/hf — именно поэтому этот путь смонтирован в контейнер. В продакшене фиксируйте тег версии вместо latest. На серверах AMD используйте образ ROCm из руководства по настройке ROCm.

Защита эндпоинта

Для личного использования оставьте vLLM на 127.0.0.1 и подключайтесь через SSH-туннель. Чтобы обслуживать приложения через интернет, поставьте перед ним обратный прокси с TLS, сделайте API-ключ обязательным и открывайте наружу только пути /v1/: ключ защищает маршруты /v1, а другие маршруты, например /metrics, могут оставаться открытыми. Об ufw, портах, опубликованных Docker, и настройке Caddy или nginx рассказывает руководство по файрволу. О подборе оборудования и текущих расходах читайте в статье о самостоятельном развёртывании инференса LLM с vLLM.

Устранение неполадок

• CUDA out of memory при запуске. Уменьшите --max-model-len, распределите модель по большему числу GPU с помощью --tensor-parallel-size или выберите модель поменьше либо квантованную. Проверьте с помощью nvidia-smi, что память GPU не занята другими процессами.
• Число голов внимания не делится на размер тензорного параллелизма. Выберите значение, на которое делится число голов модели, например 4 вместо 8.
• 401 Unauthorized. Нет заголовка Authorization, или ключ не совпадает.