Какие модели поддерживает для запуска VLLM

Перевод на основе страницы документации https://docs.vllm.ai/en/latest/models/supported_models.html#writing-custom-models_1 на 1.09.25.

Страницы документации VLLM могут быть не доступны с Российский IP адресов.

Github проекта VLLM с информацией https://github.com/vllm-project/vllm

Поддерживаемые модели

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

Если модель нативно поддерживается vLLM, её реализация находится в репозитории проекта по пути vllm/model_executor/models

Список моделей на 01.09.25 приведен далее в статье.

vLLM также поддерживает модели, доступные в библиотеке Transformers. Это работает не для всех моделей, но большинство декодерных языковых моделей и распространённые визуально-языковые модели поддерживаются! Визуально-языковые модели на данный момент принимают только изображения в качестве входных данных. Поддержка видео будет добавлена в будущих релизах.

Чтобы проверить, используется ли Transformers в качестве бэкенда, можно сделать следующее:

from vllm import LLM
llm = LLM(model=...)  # Имя или путь к модели
llm.apply_model(lambda model: print(type(model)))

Если тип модели — TransformersForCausalLM или TransformersForMultimodalLM, значит, используется Transformers.

Совет: Можно принудительно использовать TransformersForCausalLM, установив model_impl="transformers" для офлайн-инференса или --model-impl transformers для совместимого с OpenAI сервера.

Примечание: vLLM может не полностью оптимизировать реализацию Transformers, поэтому производительность может быть ниже по сравнению с нативной моделью.

Примечание: Для визуально-языковых моделей, если вы загружаете с dtype="auto", vLLM загружает всю модель с типом данных из конфигурации, если он существует. В отличие от нативного Transformers, который учитывает атрибут dtype каждого бэкенда в модели. Это может вызвать небольшие различия в производительности.

Пользовательские модели

Если модель не поддерживается нативно ни vLLM, ни Transformers, её всё равно можно использовать в vLLM!

Для совместимости с бэкендом Transformers в vLLM модель должна:

• Быть совместимой с Transformers (см. Transformers - Кастомизация моделей):
  • Директория модели должна иметь правильную структуру (например, присутствует config.json).
  • В config.json должен быть указан auto_map.AutoModel.
• Быть совместимой с бэкендом Transformers для vLLM (см. написание пользовательских моделей):
  • Кастомизация должна быть выполнена в базовой модели (например, в MyModel, а не в MyModelForCausalLM).

Если совместимая модель:

• Находится на Hugging Face Model Hub, установите trust_remote_code=True для офлайн-инференса или --trust-remote-code для совместимого с OpenAI сервера.
• Находится в локальной директории, просто передайте путь к директории в model=<MODEL_DIR> для офлайн-инференса или vllm serve <MODEL_DIR> для совместимого с OpenAI сервера.

Это означает, что с бэкендом Transformers для vLLM можно использовать новые модели до их официальной поддержки в Transformers или vLLM!

Написание пользовательских моделей

В этом разделе описаны необходимые изменения для совместимости пользовательской модели с бэкендом Transformers для vLLM. (Предполагается, что пользовательская модель уже совместима с Transformers, см. Transformers - Кастомизация моделей).

Для совместимости модели с бэкендом Transformers необходимо:

• Передавать kwargs через все модули от MyModel до MyAttention.
• MyAttention должен использовать ALL_ATTENTION_FUNCTIONS для вызова механизма внимания.
• MyModel должен содержать _supports_attention_backend = True.

Пример:

# modeling_my_model.py

from transformers import PreTrainedModel
from torch import nn

class MyAttention(nn.Module):

    def forward(self, hidden_states, **kwargs):
        ...
        attention_interface = ALL_ATTENTION_FUNCTIONS[self.config._attn_implementation]
        attn_output, attn_weights = attention_interface(
            self,
            query_states,
            key_states,
            value_states,
            **kwargs,
        )
        ...

class MyModel(PreTrainedModel):
    _supports_attention_backend = True

При загрузке модели происходит следующее:

• Загружается конфигурация.
• Загружается класс MyModel из auto_map в конфигурации, и проверяется, что модель совместима с бэкендом (is_backend_compatible()).
• MyModel загружается в TransformersForCausalLM или TransformersForMultimodalLM (см. vllm/model_executor/models/transformers.py), где устанавливается self.config._attn_implementation = "vllm", чтобы использовался слой внимания vLLM.

Для совместимости модели с функциями тензорного и/или конвейерного параллелизма vLLM необходимо добавить base_model_tp_plan и/или base_model_pp_plan в класс конфигурации модели:

Пример:

# configuration_my_model.py

from transformers import PretrainedConfig

class MyConfig(PretrainedConfig):
    base_model_tp_plan = {
        "layers.*.self_attn.k_proj": "colwise",
        "layers.*.self_attn.v_proj": "colwise",
        "layers.*.self_attn.o_proj": "rowwise",
        "layers.*.mlp.gate_proj": "colwise",
        "layers.*.mlp.up_proj": "colwise",
        "layers.*.mlp.down_proj": "rowwise",
    }
    base_model_pp_plan = {
        "embed_tokens": (["input_ids"], ["inputs_embeds"]),
        "layers": (["hidden_states", "attention_mask"], ["hidden_states"]),
        "norm": (["hidden_states"], ["hidden_states"]),
    }

• base_model_tp_plan — словарь, сопоставляющий полностью квалифицированные имена слоёв с тензорными стилями параллелизма (в настоящее время поддерживаются только "colwise" и "rowwise").
• base_model_pp_plan — словарь, сопоставляющий имена дочерних слоёв с кортежами списков строк:
  • Это нужно только для слоёв, которые не присутствуют на всех этапах конвейера.
  • vLLM предполагает, что будет только один nn.ModuleList, распределённый по этапам конвейера.
  • Список в первом элементе кортежа содержит имена аргументов ввода.
  • Список во втором элементе кортежа содержит имена переменных, которые слой выводит в вашем коде моделирования.

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

Hugging Face Hub

По умолчанию vLLM загружает модели с Hugging Face Hub. Чтобы изменить путь для загрузки моделей, можно установить переменную окружения HF_HOME; подробнее см. в официальной документации.

Чтобы определить, поддерживается ли модель нативно, можно проверить файл config.json внутри репозитория Hugging Face. Если поле "architectures" содержит архитектуру модели из списка ниже, то она должна поддерживаться нативно.

Модели не обязательно должны поддерживаться нативно, чтобы использоваться в vLLM. Бэкенд Transformers позволяет запускать модели напрямую с использованием их реализации в Transformers (или даже удалённого кода на Hugging Face Model Hub!).

Совет: Самый простой способ проверить, действительно ли модель поддерживается во время выполнения, — запустить следующую программу:

from vllm import LLM

# Только для генеративных моделей (runner=generate)
llm = LLM(model=..., runner="generate")  # Имя или путь к модели
output = llm.generate("Hello, my name is")
print(output)

# Только для пулинговых моделей (runner=pooling)
llm = LLM(model=..., runner="pooling")  # Имя или путь к модели
output = llm.encode("Hello, my name is")
print(output)

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

В противном случае см. Добавление новой модели для инструкций по реализации модели в vLLM. Или можно создать issue на GitHub, чтобы запросить поддержку vLLM.

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

Если вы предпочитаете, можно использовать Hugging Face CLI для загрузки модели или конкретных файлов из репозитория модели:

# Загрузить модель
huggingface-cli download HuggingFaceH4/zephyr-7b-beta
# Указать пользовательскую директорию кэша
huggingface-cli download HuggingFaceH4/zephyr-7b-beta --cache-dir ./path/to/cache
# Загрузить конкретный файл из репозитория модели
huggingface-cli download HuggingFaceH4/zephyr-7b-beta eval_results.json

Список загруженных моделей

Используйте Hugging Face CLI для управления моделями, хранящимися в локальном кэше:

# Список кэшированных моделей
huggingface-cli scan-cache
# Показать подробный (verbose) вывод
huggingface-cli scan-cache -v
# Указать пользовательскую директорию кэша
huggingface-cli scan-cache --dir ~/.cache/huggingface/hub

Удаление кэшированной модели

Используйте Hugging Face CLI для интерактивного удаления загруженной модели из кэша:

huggingface-cli delete-cache

Использование прокси

Несколько советов по загрузке/скачиванию моделей с Hugging Face через прокси:

• Установите прокси глобально для сессии (или в файле профиля):

  export http_proxy=http://your.proxy.server:port
  export https_proxy=http://your.proxy.server:port

• Установите прокси только для текущей команды:

  https_proxy=http://your.proxy.server:port huggingface-cli download <model_name>
  # или используйте команду vllm напрямую
  https_proxy=http://your.proxy.server:port vllm serve <model_name>

• Установите прокси в интерпретаторе Python:

  import os
  os.environ['http_proxy'] = 'http://your.proxy.server:port'
  os.environ['https_proxy'] = 'http://your.proxy.server:port'

ModelScope

Чтобы использовать модели из ModelScope вместо Hugging Face Hub, установите переменную окружения:

export VLLM_USE_MODELSCOPE=True

И используйте с trust_remote_code=True:

from vllm import LLM
llm = LLM(model=..., revision=..., runner=..., trust_remote_code=True)

# Только для генеративных моделей (runner=generate)
output = llm.generate("Hello, my name is")
print(output)

# Только для пулинговых моделей (runner=pooling)
output = llm.encode("Hello, my name is")
print(output)

Легенда статуса функций

• ✅ — функция поддерживается для модели.
• 🚧 — функция запланирована, но ещё не поддерживается.
• ⚠️ — функция доступна, но может иметь известные проблемы или ограничения.

Список текстовых языковых моделей

Генеративные модели

См. эту страницу для получения дополнительной информации о том, как использовать генеративные модели.

Генерация текста Эти модели в основном поддерживают API LLM.generate. Модели чата/инструкций дополнительно поддерживают API LLM.chat.

Пулинговые модели

См. эту страницу для получения дополнительной информации о том, как использовать пулинговые модели.

Важно: Поскольку некоторые архитектуры моделей поддерживают как генеративные, так и пулинговые задачи, необходимо явно указать --runner pooling, чтобы модель использовалась в режиме пулинга, а не генерации.

Встраивание Эти модели в основном поддерживают API LLM.embed.

Классификация

Эти модели в основном поддерживают API LLM.classify.

Кросс-энкодеры / Реранкеры

Кросс-энкодеры и реранкеры — это подмножество классификационных моделей, которые принимают два промпта в качестве входных данных. Эти модели в основном поддерживают API LLM.score.

Модели вознаграждения

Эти модели в основном поддерживают API LLM.reward.

Список мультимодальных языковых моделей

Следующие модальности поддерживаются в зависимости от модели:

• Текст
• Изображение
• Видео
• Аудио

Любая комбинация модальностей, соединённых знаком +, поддерживается. Например: T + I означает, что модель поддерживает текст, изображение и текст с изображением.

С другой стороны, модальности, разделённые /, являются взаимоисключающими. Например: T / I означает, что модель поддерживает только текст или только изображение, но не текст с изображением.

Важно: Чтобы включить несколько мультимодальных элементов на текстовый промпт в vLLM V0, необходимо установить limit_mm_per_prompt (для офлайн-инференса) или --limit-mm-per-prompt (для онлайн-сервиса). Например, чтобы передать до 4 изображений на текстовый промпт:

# Офлайн-инференс:
from vllm import LLM
llm = LLM(
    model="Qwen/Qwen2-VL-7B-Instruct",
    limit_mm_per_prompt={"image": 4},
)

# Онлайн-сервис:
vllm serve Qwen/Qwen2-VL-7B-Instruct --limit-mm-per-prompt '{"image":4}'

Это не требуется, если вы используете vLLM V1.

Совет: Для гибридных моделей, таких как Llama-4, Step3 и Mistral-3, можно включить режим "только текст", установив все поддерживаемые мультимодальные модальности в 0 (например, --limit-mm-per-prompt '{"image":0}'), чтобы их мультимодальные модули не загружались и освободилось больше памяти GPU для кэша KV.

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

Генеративные модели

См. эту страницу для получения дополнительной информации о том, как использовать генеративные модели.

Генерация текста Эти модели в основном поддерживают API LLM.generate. Модели чата/инструкций дополнительно поддерживают API LLM.chat.

Транскрипция - Модели Speech2Text, обученные специально для автоматического распознавания речи.

Пулинговые модели

См. эту страницу для получения дополнительной информации о том, как использовать пулинговые модели.

Встраивание для Vision-Language

Эти модели в основном поддерживают API LLM.embed.

Кросс-энкодеры / Реранкеры

Кросс-энкодеры и реранкеры — это подмножество классификационных моделей, которые принимают два промпта в качестве входных данных. Эти модели в основном поддерживают API LLM.score.

Политика поддержки моделей

В vLLM стремятся облегчить интеграцию и поддержку сторонних моделей в своей экосистеме. Подход направлен на баланс между необходимостью в надёжности и практическими ограничениями поддержки широкого спектра моделей.

Принципы политики от VLLM:

• Поддержка сообществом: Мы приветствуем вклад сообщества в добавление новых моделей. Когда пользователь запрашивает поддержку новой модели, мы приветствуем pull request (PR) от сообщества. Эти вкладки оцениваются в первую очередь на основе разумности генерируемого вывода, а не на строгом соответствии с существующими реализациями, такими как в Transformers. Призыв к участию: PR, поступающие напрямую от вендоров моделей, особенно приветствуются!

• Максимальное соответствие: Хотя мы стремимся поддерживать определённый уровень соответствия между моделями, реализованными в vLLM, и другими фреймворками, такими как Transformers, полное совпадение не всегда возможно. Факторы, такие как методы ускорения и использование вычислений с низкой точностью, могут вносить расхождения. Наша цель — обеспечить, чтобы реализованные модели были функциональными и давали разумные результаты.

• Совет: При сравнении вывода model.generate из Hugging Face Transformers с выводом llm.generate из vLLM учтите, что первый считывает файл конфигурации генерации модели (т.е. generation_config.json) и применяет параметры по умолчанию для генерации, тогда как второй использует только параметры, переданные в функцию. Убедитесь, что все параметры выборки идентичны при сравнении выводов.

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

• Мониторинг и обновления: Пользователям, заинтересованным в конкретных моделях, рекомендуется отслеживать историю коммитов для этих моделей (например, отслеживая изменения в директории main/vllm/model_executor/models). Этот проактивный подход помогает пользователям быть в курсе обновлений и изменений, которые могут повлиять на используемые ими модели.

• Выборочное внимание: Наши ресурсы в первую очередь направлены на модели с высоким интересом и влиянием пользователей. Модели, которые используются реже, могут получать меньше внимания, и мы полагаемся на сообщество, чтобы оно играло более активную роль в их поддержке и улучшении.

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

Обратите внимание, что vLLM как движок инференса не вводит новые модели. Следовательно, все модели, поддерживаемые vLLM, являются сторонними моделями в этом отношении.

У нас есть следующие уровни тестирования моделей:

• Строгое соответствие: Мы сравниваем вывод модели с выводом модели в библиотеке HuggingFace Transformers при жадном декодировании. Это самый строгий тест. См. тесты моделей для моделей, прошедших этот тест.

• Разумность вывода: Мы проверяем, является ли вывод модели разумным и связным, измеряя перплексию вывода и проверяя наличие очевидных ошибок. Это менее строгий тест.

• Функциональность во время выполнения: Мы проверяем, может ли модель быть загружена и запущена без ошибок. Это наименее строгий тест. См. функциональные тесты и примеры для моделей, прошедших этот тест.

• Обратная связь от сообщества: Мы полагаемся на сообщество в предоставлении обратной связи по моделям. Если модель сломана или работает не так, как ожидалось, мы призываем пользователей создавать issue для её исправления или открывать pull request. Остальные модели попадают в эту категорию.