Как подключить свою модель из Hugging Face

    Если среди предустановленных образов нет нужной модели, вы можете загрузить её самостоятельно. Для этого используется базовый образ vLLM — сервер с предустановленными Docker-контейнерами, готовый к работе с любыми совместимыми моделями из Hugging Face.

    Что такое Hugging Face

    Hugging Face — это платформа для сообщества разработчиков в сфере машинного обучения. Она предоставляет централизованный хаб для обмена моделями, датасетами и демонстрационными приложениями. Здесь вы можете найти тысячи предобученных больших языковых моделей (LLM) с открытыми весами — от текстовых генераторов до мультимодальных нейросетей, работающих с изображениями.

    Какие модели можно запускать

    Образ vLLM в Рег.облаке поддерживает более 200 архитектур. Основные категории:

    • текстовые (Decoder-only LLM): Llama, Qwen, Mistral, Gemma;
    • кодовые: DeepSeek Coder, CodeQwen;
    • мультимодальные (текст + изображение): LLaVA, Qwen-VL, Pixtral;
    • эмбеддинги и поисковые: E5-Mistral, GTE, ColBERT;
    • экспертные смеси (MoE): Mixtral, DeepSeek-V3.

    Важно

    Подбирайте GPU-конфигурацию под размер модели. Для 7B-модели рекомендуется не менее 24 ГБ VRAM. Квантизованные версии (AWQ, GPTQ) потребляют меньше памяти.

    Подготовка сервера для инференса

    • 1
      Войдите в панель управления Рег.облака.
    • 2
      Нажмите +Новый ресурс > Cервер.
    • 3
      Выберите образ ИИ-инференса (vLLM).
    • 4
      На вкладке GPU выберите образ ИИ-инференса (vLLM) без модели.
    • 5
      Выберите vGPU-конфигурацию и тип диска. Затем выберите подходящий тариф.
    • 6
      Выберите регион размещения сервера.
    • 7
      Закажите публичный плавающий IP-адрес.
    • 8
      Выберите тариф защиты от DDoS-атак.
    • 9
      Настройте автоматическое резервное копирование.
    • 10
      При необходимости добавьте SSH-ключ и укажите название сервера.
    • 11
      Нажмите кнопку Заказать сервер.

    На электронную почту придут данные для подключения: IP-адрес, логин (root) и пароль. Образ уже содержит всё необходимое для работы: драйверы NVIDIA, CUDA, и Docker-контейнеры vLLM.

    Загрузка и запуск модели

    После создания сервера можно загружать модель и запускать инференс. Доступны 2 способа: простой через docker run и для постоянной работы через docker compose.

    Шаг 1. Подключение к серверу

    Подключитесь по SSH, используя данные из письма:

    ssh root@<IP-адрес>

    При первом входе система предложит сменить пароль. Смените его сразу или используйте SSH-ключ.

    Шаг 2. Загрузка и запуск модели через docker run

    Образ уже содержит Docker-контейнер vLLM.

    • 1

      Запустите инференс:

      docker run -it --rm -d \
  --runtime nvidia \
  --gpus all \
  --name vllm \
  --ipc=host \
  -p 8000:8000 \
  -v /root/.cache/:/root/.cache/ \
  vllm/vllm-openai:gemma4 \
  Qwen/Qwen2.5-7B-Instruct

      Где:

      • --runtime nvidia и --gpus all — подключают GPU к контейнеру;

      • Qwen/Qwen2.5-7B-Instruct — название модели на Hugging Face.

      При первом запуске контейнер автоматически скачает её в директорию /root/.cache/.

    • 2

      Просмотрите журнал работы:

      docker logs -f vllm

    Шаг 3. Загрузка модели без запуска инференса

    Если нужно только скачать модель без запуска сервера — используйте утилиту hf (Hugging Face CLI) из того же контейнера:

    docker run --rm -ti \
  -v /root/.cache/:/root/.cache/ \
  --entrypoint "" \
  vllm/vllm-openai:gemma4 \
  hf download Qwen/Qwen2.5-7B-Instruct

    Где:

    • --entrypoint «» — переопределяет точку входа, чтобы запустить hf вместо vllm serve;

    • hf download — актуальная команда для загрузки моделей (старая huggingface-cli не поддерживается).

    Использование токена Hugging Face

    Передайте переменную окружения с токеном для загрузки моделей из приватных репозиториев или для ускорения скачивания публичных моделей:

    docker run -it --rm -d \
  --runtime nvidia \
  --gpus all \
  --name vllm \
  --ipc=host \
  -p 8000:8000 \
  -v /root/.cache/:/root/.cache/ \
  -e HF_TOKEN=hf_XXXXXX \
  vllm/vllm-openai:gemma4 \
  <название-модели>

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

    Запуск через Docker Compose для постоянной работы

    Для автоматического запуска при старте виртуальной машины используйте Docker Compose.

    • 1

      Создайте конфигурационный файл:

      cat << EOF > /root/compose.yaml
services:
  vllm:
    image: vllm/vllm-openai:gemma4
    container_name: vllm
    ipc: host
    ports:
      - 8000:8000
    environment:
      - HF_TOKEN=hf_XXXXXX
    volumes:
      - /opt/vllm/models/:/root/.cache/
    command: Qwen/Qwen2.5-7B-Instruct --api-key your-secure-api-key
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [compute, utility]
EOF

      Где: volumes — директория для хранения моделей (можно изменить на свою);

      После имени модели можно указать любые параметры vLLM, например:

      • --api-key your-secure-api-key — ключ для доступа к API;

      • --max-model-len 4096 — максимальная длина контекста;

      • --served-model-name my-model — имя модели, которое будет отображаться в API.

    • 2

      Запустите сервис:

      docker compose -f /root/compose.yaml up -d

      Контейнер будет автоматически запускаться при перезагрузке сервера.

    • 3

      Проверьте его статус:

      docker compose -f /root/compose.yaml ps

    Подключение к Inference API

    После запуска vLLM сервер принимает запросы по адресу http://:8000.

    Проверить его работу можно через Python-скрипт или любой HTTP-клиент.

    Основные адреса сервисов (эндопоинты), доступные на сервере:

    • /v1/chat/completions — диалоговый API (Chat),

    • /v1/completions — API генерации текста (Completion),

    • /tokenize — подсчет токенов.

    Проверка через Python-клиент

    • 1
      Установите библиотеку OpenAI: 
    pip install openai
    • 2
      Создайте скрипт со следующим содержимым: 
    from openai import OpenAI

client = OpenAI(
    base_url="http://<IP-адрес_сервера>:8000/v1",
    api_key="your-secure-api-key"
)


response = client.chat.completions.create(
    model="/models/Qwen2.5-7B-Instruct",
    messages=[
        {"role": "system", "content": "Ты — полезный ассистент."},
        {"role": "user", "content": "Объясни, что такое p-value"}
    ],
    temperature=0.7,
    max_tokens=512
)


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

    Где:

    • base_url — адрес сервера (endpoint) с префиксом /v1 (API vLLM повторяет структуру OpenAI);

    • api_key — ключ, заданный при запуске vLLM через —api-key;

    • temperature — степень случайности ответа (0 — строго по шаблону, 1 — максимально разнообразно).

    • 3
      Запустите скрипт. Если сервер настроен верно, в консоль выведется ответ модели.

    Передача дополнительных параметров vLLM

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

    Эти параметры передаются в теле запроса через поле extra_body — так они попадают напрямую в vLLM, минуя ограничения OpenAI-спецификации.

    Пример передачи дополнительных параметров:

    response = client.chat.completions.create(
    model="Qwen/Qwen2.5-7B-Instruct",
    messages=[{"role": "user", "content": "Напиши три синонима к слову 'хороший'"}],
    extra_body={
        "top_k": 50,
        "repetition_penalty": 1.1
    }
)

    Где:

    • top_k — ограничивает выборку на каждом шаге генерации K наиболее вероятными токенами (снижает случайность);

    • repetition_penalty — штрафует модель за повторение уже использованных слов (значение > 1.0 уменьшает повторы).

    Этот механизм полезен, когда стандартных параметров (temperature, top_p) недостаточно для получения нужного стиля или качества ответа.

    Была ли статья полезна?

    Спасибо за оценку. Рады помочь 😊

     👍
    Специальные предложения