vLLM на Hugging Face Jobs: быстрый сервер за 1 команду

Запуск локальных LLM-серверов часто упирается в сложность настройки окружения, Kubernetes или нехватку VRAM. Hugging Face Jobs решает эту проблему, позволяя развернуть приватный endpoint, совместимый с OpenAI API, одной командой. Это идеальный вариант для тестов, оценки моделей (evals) или пакетной генерации, где не требуется production-устойчивость, но нужна скорость развертывания.

01Быстрый старт: запуск сервера

Для работы требуется установленный huggingface_hub >= 1.20.0 и авторизация через hf auth login. Мы используем официальный образ vllm/vllm-openai, запрашиваем GPU через флаг --flavor и открываем порт 8000 для доступа.

Пример запуска модели Qwen3-4B на GPU NVIDIA A10G (8GB VRAM) с таймаутом 2 часа:

hf jobs run --flavor a10g-large --expose 8000 --timeout 2h \
  vllm/vllm-openai:latest \
  vllm serve Qwen/Qwen3-4B --host 0.0.0.0 --port 8000

После запуска команда выведет ID задачи и URL. Прокси-адрес для запросов будет выглядеть так: https://<job_id>--8000.hf.jobs. Дождитесь сообщения Application startup complete в логах — сервер готов.

02Запросы к API: curl и Python

Сервер полностью совместим с OpenAI API. Все запросы должны содержать ваш HF-токен в заголовке Authorization: Bearer. Это обеспечивает безопасность: endpoint не публичен, доступ есть только у владельца токена.

Проверка здоровья сервера (список моделей):

curl https://<job_id>--8000.hf.jobs/v1/models \
  -H "Authorization: Bearer $(hf auth token)"

Пример запроса на генерацию через curl:

curl https://<job_id>--8000.hf.jobs/v1/chat/completions \
  -H "Authorization: Bearer $(hf auth token)" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "Qwen/Qwen3-4B",
  "messages": [{"role": "user", "content": "Hello!"}],
  "chat_template_kwargs": {"enable_thinking": false}
}'

Для Python-разработчиков используйте клиент OpenAI, указав базовый URL вашего job:

from huggingface_hub import get_token
from openai import OpenAI

client = OpenAI(
    base_url="https://<job_id>--8000.hf.jobs/v1",
    api_key=get_token()
)

resp = client.chat.completions.create(
    model="Qwen/Qwen3-4B",
    messages=[{"role": "user", "content": "Hello!"}],
    extra_body={"chat_template_kwargs": {"enable_thinking": False}}
)
print(resp.choices[0].message.content)

03Масштабирование на большие модели

Для моделей с большим количеством параметров (например, Qwen3.5-122B-A10B) потребуется больше VRAM. Используйте флаги --tensor-parallel-size для распределения модели по нескольким GPU и ограничьте длину контекста, чтобы избежать OOM (Out Of Memory).

Запуск на 2x H200 (141GB VRAM каждый):

hf jobs run --flavor h200x2 --expose 8000 --timeout 2h \
  vllm/vllm-openai:latest \
  vllm serve Qwen/Qwen3.5-122B-A10B \
  --host 0.0.0.0 --port 8000 \
  --tensor-parallel-size 2 \
  --max-model-len 32768 --max-num-seqs 256

04Отладка и UI: SSH и Gradio

Если сервер упал или нужно посмотреть логи GPU, подключитесь к контейнеру через SSH. Для этого добавьте флаг --ssh при запуске и используйте публичный ключ, добавленный в настройки HF.

# Запуск с SSH
hf jobs run --flavor a10g-large --expose 8000 --timeout 2h --ssh \
  vllm/vllm-openai:latest \
  vllm serve Qwen/Qwen3-4B --host 0.0.0.0 --port 8000

# Подключение
hf jobs ssh <job_id>

Для быстрого тестирования можно развернуть веб-интерфейс Gradio локально, подключив его к удаленному job. Это удобно для проверки работы reasoning (мышления) модели:

import gradio as gr
from gradio import ChatMessage
from huggingface_hub import get_token
from openai import OpenAI

client = OpenAI(base_url="https://<job_id>--8000.hf.jobs/v1", api_key=get_token())

def chat(message, history):
    messages = [{"role": m["role"], "content": m["content"]} for m in history if not m.get("metadata")]
    messages.append({"role": "user", "content": message})
    
    thinking, answer = "", ""
    stream = client.chat.completions.create(model="Qwen/Qwen3-4B", messages=messages, stream=True)
    
    for chunk in stream:
        delta = chunk.choices[0].delta
        thinking += delta.model_extra.get("reasoning", "")
        answer += delta.content or ""
        
    out = []
    if thinking.strip():
        out.append(ChatMessage(role="assistant", content=thinking, metadata={"title": "💭 Thinking", "status": "done"}))
    if answer.strip():
        out.append(ChatMessage(role="assistant", content=answer))
    yield out

gr.ChatInterface(chat).launch()

05Использование в агентах (Pi)

Запущенный сервер можно использовать как бэкенд для coding-агентов, например, Pi. Для этого необходимо включить поддержку вызова инструментов (tool calling) при старте vLLM:

hf jobs run --flavor h200x2 --expose 8000 --timeout 2h \
  vllm/vllm-openai:latest \
  vllm serve Qwen/Qwen3.5-122B-A10B \
  --host 0.0.0.0 --port 8000 \
  --tensor-parallel-size 2 \
  --max-model-len 32768 --max-num-seqs 256 \
  --reasoning-parser deepseek_r1 \
  --enable-auto-tool-choice --tool-call-parser hermes

Затем добавьте провайдер в ~/.pi/agent/models.json с вашим job URL и токеном.

06Кому подойдёт / что запустится

• Для тестов и evals: Идеально подходит для быстрой проверки качества моделей без настройки инфраструктуры. Оплата только за время работы.
• Для разработки: Позволяет быстро развернуть совместимый с OpenAI endpoint для интеграции с фреймворками (LangChain, LlamaIndex, Pi).
• Железо:
  • Qwen3-4B: Достаточно A10G (8GB VRAM).
  • Qwen3.5-122B: Требуется H200x2 или H200x8 (высокая VRAM для KV-cache и весов).
• Не для продакшена: Для стабильных production-сервисов лучше использовать Hugging Face Inference Endpoints. Jobs — это инструмент для «сделай и забудь» или временных задач.

Источник: Hugging Face ↗