Флаги vllm serve с разумными стартовыми значениями

vLLM — один из основных движков для раздачи больших языковых моделей, в первую очередь благодаря пропускной способности и тому, как PagedAttention управляет памятью. Обычно им управляют из командной строки: через vllm serve или старую форму python -m vllm.entrypoints.openai.api_server. Ниже одна конкретная команда, а затем обзор флагов, которые вы будете трогать чаще всего, с разумным стартовым значением для каждого.

Стартовая команда

Эта команда раздаёт модель среднего размера на машине с несколькими GPU. Она написана для PowerShell, поэтому переносы строк сделаны обратными апострофами:

vllm serve meta-llama/Llama-3.1-8B-Instruct `
  --host 0.0.0.0 `
  --port 8000 `
  --tensor-parallel-size 2 `
  --gpu-memory-utilization 0.90 `
  --max-model-len 8192 `
  --max-num-seqs 256 `
  --dtype bfloat16 `
  --served-model-name llama3-8b `
  --api-key $env:VLLM_API_KEY

Каждый флаг из неё разобран ниже, плюс несколько дополнительных, о которых стоит знать.

Выбор модели и точности

model — позиционный аргумент: ID модели на Hugging Face или локальный путь к весам. Это единственное, что указать обязательно. У остальных параметров есть значения по умолчанию, но в продакшене они редко подходят.

dtype задаёт числовую точность весов и активаций. Обычные варианты — auto, float16, bfloat16 и float32. На GPU класса Ampere и новее берите bfloat16. Он численно устойчивее, чем float16, практически ничего не стоит по пропускной способности и обходит проблемы с переполнением, на которые некоторые архитектуры натыкаются в float16.

trust-remote-code разрешает vLLM запускать собственный код моделирования из репозитория модели на Hugging Face. Некоторым архитектурам он нужен, чтобы вообще загрузиться. Держите флаг выключенным, если в карточке модели не сказано обратное: включив его, вы исполняете произвольный код из этого репозитория.

quantization выбирает схему сжатия, например awq, gptq или fp8, и уменьшает расход памяти ценой некоторой потери качества. Задавайте его, только если загружаете уже квантизованные веса или памяти GPU иначе не хватает. Если запас есть, лучше bfloat16 или полная точность.

Бюджет памяти GPU и контекста

gpu-memory-utilization — доля памяти GPU, которую vLLM может забрать под веса, активации и KV-кэш. На стабильность и пропускную способность она влияет сильнее почти любой другой настройки. Начните с 0.90. Если поднять намного выше, другие процессы на карте могут вызвать ошибки нехватки памяти. Если опустить ниже, вы теряете место под KV-кэш, а это ограничивает, сколько запросов можно обслуживать одновременно.

max-model-len ограничивает сумму токенов промпта и генерации на один запрос. Потолок — длина контекста, на которой обучали модель, но можно поставить меньше и сэкономить память кэша. Подгоните его под реальные нужды приложения. Если модель поддерживает 128K токенов, а у вас только короткие реплики в чате, резервировать всё это незачем. Меньшее значение освобождает место для большего числа одновременных последовательностей.

max-num-seqs ограничивает, сколько запросов собирается в один батч, то есть управляет параллельностью. Для многих нагрузок подходит 256. Поднимайте, если есть свободная память GPU и плотный трафик, и снижайте, если длинные контексты давят на память.

block-size — число токенов в одном блоке KV-кэша PagedAttention. Блоки побольше означают меньше учёта, но больше потерянного места для коротких последовательностей. Значение по умолчанию 16 подходит для большинства конфигураций, и трогать его придётся редко.

swap-space резервирует оперативную память CPU, в гигабайтах на каждый GPU, куда при нехватке памяти можно выгрузить блоки KV-кэша вместо того, чтобы отклонять запросы. Начните с 4. Если всплески трафика приводят к ошибкам, а не к аккуратной очереди, увеличьте.

Распределение модели по нескольким GPU

tensor-parallel-size — на сколько GPU делится каждый слой. Это решение, когда модель не помещается на одну карту, а заодно способ на машинах с несколькими GPU обменять немного задержки на пропускную способность. Ставьте его равным числу GPU в узле, предпочитая степени двойки (1, 2, 4, 8), потому что число голов внимания обычно на них делится без остатка.

pipeline-parallel-size задаёт число стадий конвейера, обычно в сочетании с тензорным параллелизмом, когда модель приходится растягивать на несколько узлов. Оставьте 1, если только модель не слишком велика для одного тензорного параллелизма внутри одного узла.

Как открыть сервер наружу

host и port определяют, где слушает API-сервер. Используйте 0.0.0.0, если к нему должны обращаться другие машины, или 127.0.0.1 для доступа только локально. Привычный порт — 8000.

served-model-name — имя, которое клиенты указывают в запросах к API, и оно может отличаться от ID на Hugging Face. Это удобно, чтобы дать развёртыванию чистую версионированную метку. Выберите что-то короткое и стабильное, чтобы приложения дальше по цепочке не были привязаны к конкретному пути к весам.

api-key заставляет клиентов отправлять bearer-токен. Без него запросы может слать любой, у кого есть доступ к порту. Задавайте его для всего, что выходит за рамки локальных экспериментов, и читайте из переменной окружения, а не зашивайте в скрипты и не оставляйте в истории shell.

enforce-eager отключает захват CUDA-графов и запускает PyTorch в eager-режиме. Вы жертвуете частью пропускной способности ради более быстрого старта и удобной отладки. В продакшене оставьте флаг выключенным: CUDA-графы обычно дают ощутимое ускорение. Включайте его временно, когда ищете причину падения, потому что в eager-режиме стек-трейсы понятнее.

Как настраивать

Основная работа — баланс трёх величин относительно доступной памяти GPU: длины контекста через max-model-len, параллельности через max-num-seqs и точности через dtype и quantization. Начните осторожно с gpu-memory-utilization, измерьте реальную пропускную способность и задержку под реалистичной нагрузкой и подстраивайте дальше, а не угадывайте цифры заранее.