Запуск vLLM сервера на Hugging Face Jobs одной командой | AiManual
AiManual Logo Ai / Manual.
25 Июн 2026 Гайд

Как запустить vLLM сервер на Hugging Face Jobs одной командой: пошаговое руководство

Полный гайд по быстрому развертыванию vLLM на Hugging Face Jobs через `hf jobs run`. Запускаем Qwen3-4B на a10g-large, тонкая настройка, подводные камни.

Реклама
partv2

Сценарий: вам нужно протестировать свежую модель, а GPU-сервер местный уже разобрали коллеги. Или хочется быстрого прототипа, без геморроя с Docker, Terraform и просьбами к админам. Hugging Face Jobs (не путать с Inference Endpoints — там копеечка капает постоянно) позволяет арендовать железо на минуты и выполнить свою задачу одной командой. А vLLM — самый популярный движок для инференса LLM на своих GPU, с поддержкой PagedAttention, continuous batching и гостевым API, совместимым с OpenAI. Соединяем — получаем магию.

💡
Почему это выстрелило? Раньше, чтобы попробовать LLM не на своей видеокарте, нужно было идти в Lambda Labs, Vast.ai, PaperSpace — везде свои конфиги, авторизация, и прощай время. Hugging Face Jobs берет твой entrypoint.sh, выделяет инстанс и возвращает тебе URL. Чистый DevOps-кайф.

Откуда взялась эта возможность и почему это не панацея

Hugging Face Jobs — это, по сути, serverless GPU-аренда с прерыванием (аналог Spot/Preemptible). Ты запускаешь джобу, она живет максимум несколько часов (если не указать --timeout), и платишь за секунды использования. Идеально для экспериментов, CI/CD, дообучения (в связке с Unsloth, о чем я писал в отдельном гайде), а теперь и для живого инференса.

Только не ждите, что vLLM с a10g-large (24GB VRAM) будет крутить Qwen3-4B с тысячным контекстом и сотнями запросов в секунду. Это песочница для тестов. Для продакшена — используйте Inference Endpoints или поднимайте свой кластер (я рассказывал про мульти-нод на примере Kimi K2).

Одна команда, чтобы править всеми

Самое красивое в Hugging Face Jobs — это команда hf jobs run. Она принимает образ Docker (или базовый образ HF), твой startup-скрипт и флаги железа. Вот как выглядит запуск vLLM сервера для Qwen3-4B:

hf jobs run \
  --machine a10g-large \
  --name vllm-qwen3-4b \
  --image ghcr.io/huggingface/text-generation-inference:latest \
  --command """
pip install vllm==0.8.0
vllm serve Qwen/Qwen3-4B \
  --host 0.0.0.0 \
  --port 8080 \
  --max-model-len 4096 \
  --gpu-memory-utilization 0.9
"""

⚠️ На 25 июня 2026 года vLLM 0.8.0 — последний стабильный релиз. Он уже включает поддержкой архитектуры Qwen3 (на базе LLaMA), так что дополнительные пайплайны ставить не нужно. Если у вас модель из приватного репозитория — не забудьте передать HUGGING_FACE_HUB_TOKEN через --env.

1 Что происходит под капотом?

Флаг --machine a10g-large запускает одну NVIDIA A10G с 24GB VRAM. --image — это базовый образ от Hugging Face с предустановленным CUDA, PyTorch и Python. --command — твой payload: ставим свежий vLLM (он качается за пару секунд, так как образ уже содержит драйвера) и запускаем сервер в фоне. Честно, я предпочитаю выносить команду запуска в отдельный entrypoint.sh, чтобы не вышло каши в консоли, но в одну строку это выглядит эффектно.

2 А где взять URL сервера?

После запуска джоба получает публичный эндпоинт вида https://youraccount-jobs.hf.space. Но только если ты настроил редирект портов. Hugging Face Jobs автоматически пробрасывает порт 8080 (если указать --port 8080:8080). Иначе сервер будет торчать наружу на случайном порту, что ломает совместимость с OpenAI-клиентами. Вот так делать не надо:

# Как НЕ надо - порт не задан, будет сюрприз
hf jobs run --machine a10g-large --name broken-server --command "vllm serve Qwen/Qwen3-4B"

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

hf jobs run \
  --machine a10g-large \
  --name vllm-qwen3-4b \
  --port 8080:8080 \
  --image ghcr.io/huggingface/text-generation-inference:latest \
  --command """
pip install vllm==0.8.0 && \
vllm serve Qwen/Qwen3-4B \
  --host 0.0.0.0 \
  --port 8080 \
  --max-model-len 4096 \
  --gpu-memory-utilization 0.9
"""

Тонкая настройка: не дай памяти утечь

Главная боль любого vLLM под капотом — фрагментация кучи glibc. Я уже писал про это. Когда модель грузится, vLLM резервирует почти всю VRAM под KV-cache. Если не выставить --gpu-memory-utilization 0.9, он может схватить оставшиеся 10% запасом под swap, и тогда OOM-killer убьет сервер.

И еще один грабель — количество одновременно висящих соединений. vLLM по умолчанию использует uvloop, но на сервер будет долбиться много клиентов. Посмотрите на LazyGate — механизм динамической лени, который снижает TTFT при пиковых нагрузках. В джобах это не так критично, но если ставите для демо — клиенты скажут спасибо.

3 Отладка: джоба упала, и что?

Скорее всего, команда не запускается в фоне, а умрет вместе с SSH-сессией. Hugging Face Jobs выполняет --command как bash-скрипт. Если vLLM запущен напрямую, после выхода из скрипта джоба считается завершенной. Решение: используй nohup или запускай через & с ожиданием. Или самый надежный вариант:

# entrypoint.sh
#!/bin/bash
set -e
pip install vllm==0.8.0
vllm serve Qwen/Qwen3-4B --host 0.0.0.0 --port 8080 --max-model-len 4096 --gpu-memory-utilization 0.9 &
sleep infinity

И затем:

hf jobs run --machine a10g-large --name vllm-qwen3 --port 8080:8080 --entrypoint ./entrypoint.sh

sleep infinity держит контейнер живым, пока не истечет таймаут или ты сам не удалишь джобу. Только не забудь, что плата капает за все время жизни.

Где еще может пригодиться такой сервер в джобах

Помимо чистого тестирования, один из сценариев — это бэкенд для мульти-агентных систем. Например, ты хочешь запустить 3 AI-агента с разными LLM на одном старом GPU (я детально разбирал кейс с GTX 1080 8GB). С vLLM на HF Jobs можно арендовать A10G, развернуть там единый эндпоинт и скидывать туда запросы от локального кода. Это гибридная архитектура: приватные данные остаются локально, а тяжелый инференс уходит в облако. Подробнее про такой подход — в статье про гибридную архитектуру.

Ну и классика — обкатка модели перед выкаткой на Inference Endpoints. Если Qwen3-4B не взлетит (вдруг у нее гигантский vocab, не влазит в память), ты потратишь копейки вместо десятков долларов на полноценном эндпоинте.

Типичные ошибки и как их не повторить

  • Забыли указать --port — порт не проброшен, сервер не отвечает. Всегда указывай --port 8080:8080.
  • Слишком большой --max-model-len — vLLM попытается зарезервировать KV-cache под указанную длину. Для Qwen3-4B на A10G реальный максимум — 8192 (с gpu-memory-utilization 0.95). 16384 уже вызовет OOM.
  • Не поставили sleep infinity — джоба завершится сразу после старта vLLM (который уйдет в фон). Либо используй foreground, либо явный wait.
  • Попытка запустить модель с huggingface.co по HTTP — vLLM скачивает веса в память. Если твоя модель приватная, ставь --env HUGGING_FACE_HUB_TOKEN=.... Лучше создать Access Token с read-правами и хранить в секретах GitHub/GitLab.
  • Забыли учесть фрагментацию glibc — на долгих сессиях vLLM может начать кушать CPU на перераспределение памяти. Добавьте в entrypoint export MALLOC_MMAP_THRESHOLD_=131072 — это снижает rate фрагментации.
📦
Pro tip: Используйте образ ghcr.io/huggingface/text-generation-inference:latest. Он тяжелее (около 10GB), но внутри уже есть CUDA, PyTorch, трансформеры и экономная вам секунда на установку. Для vLLM нужен Python 3.11+ — этот образ как раз подходит.

Сколько это стоит и стоит ли игра свеч?

GPU Цена за час (25.06.2026) Подходит для
a10g-large (1x A10G 24GB) $1.08 Qwen3-4B, Llama-3.1-8B (4-bit), Mistral-7B
a100-large (1x A100 80GB) $4.32 Codestral-22B, Llama-3.3-70B (4-bit)
h100-large (1x H100 80GB) $8.64 Llama-4-400B (4-bit), DeepSeek-V3

Цены актуальны на сегодня, но могут скакнуть. Сравните с Inference Endpoints: там тот же a10g-large стоит ~$0.85/час, но идет всегда включенным (даже когда не используется — платите 50% за простой). Jobs — чистые Spot-цены: работа закончилась — платить перестали. Для прототипов это святая экономия.

Резюме: когда использовать, а когда бежать

Лично я за последнюю неделю запускал так три разных vLLM-сервера: тестировал GLM-4.7 (кстати, она может имитировать Claude API), проверял совместимость с разными клиентами. Джобы позволили не завязываться на постоянный GPU-сервер и быстро убивать неработающие конфиги.

Но если вам нужно стабильно крутить эндпоинт 24/7 — лучше взять Inference Endpoints (там SLA) или поднять свой инстанс на обычном облаке с высокой надёжностью. Hugging Face Jobs — про гибкость и скорость. Одна команда, и сервер твой.

А если захотите собрать мульти-нод кластер для инференса — смотрите на Kimi K2 и распределенный запуск. Там уже не обойтись одной командой, но для реального продакшна это must read.

Подписаться на канал