vLLM LoRA: как обслуживать адаптеры рядом с базовой моделью

Когда нужен LoRA serving, а не ещё одна базовая модель?

Адаптер LoRA — отдельные параметры дообучения поверх конкретной базовой модели. В PEFT-файле адаптера нет исходных весов базы: чтобы обслуживать его, нужны и база, и совместимая конфигурация/веса адаптера s5. vLLM обслуживает несколько адаптеров для модели с поддержкой SupportsLoRA и позволяет выбрать нужный вариант по полю model каждого запроса s1. Это путь для двух согласованных сценариев на одном сервере, например базового ответа и ответа отраслевого адаптера; из архитектуры нельзя вывести, что дообученный вариант лучше. Качество проверяется на собственных контрольных запросах.

Путь решения: ваша задача → выбранная пара «базовая модель + адаптер» → совместимое железо → vLLM → проверка регистрации обоих идентификаторов → две пары ответов на одном наборе запросов. Для первого запуска без адаптера начните с общего гайда vLLM. Не берите произвольный LoRA-файл от другой архитектуры, даже если имена выглядят похоже.

Как проверить совместимость до запуска?

Сначала уточните версию установленного vLLM: эта инструкция привязана к документации тега v0.30.0, а новые выпуски могут менять параметры и поддерживаемые архитектуры s1s6. GPU-инструкция для этого тега указывает Linux и Python 3.10–3.13 для основного пути установки; Windows нативно не поддерживается, для неё описан WSL. Поддержка GPU зависит от конкретного backend — название CUDA/ROCm/XPU само по себе не доказывает, что ваша модель с данным адаптером загрузится s6.

Укажите конкретную архитектуру базы, а не только маркетинговое семейство: в перечне v0.30.0 для LlamaForCausalLM и Qwen3ForCausalLM отмечена LoRA-поддержка. Это не обещание совместимости каждого репозитория, кванта, целевого слоя или версии адаптера s7. Документация vLLM допускает LoRA только для моделей, реализующих SupportsLoRA s1.

В каталоге адаптера найдите adapter_config.json и adapter_model.safetensors (либо .bin); PEFT описывает именно раздельное хранение конфигурации, адаптерных параметров и исходной базы s5. Проверьте peft_type, r, а при наличии base_model_name_or_path и revision — совпадение с фактически выбранной базой. Поле базы может отсутствовать или иметь null, поэтому одного этого поля недостаточно для доказательства совместимости; происхождение и разрешение на использование файлов выясняйте отдельно s5. Если структура адаптера неизвестна, не подставляйте случайный бинарник и не включайте небезопасную десериализацию лишь ради старта s5.

Минимальная проверка своего локального PEFT-каталога без загрузки модели:

ADAPTER=/srv/models/my-lora
python3 - "$ADAPTER" <<'PY'
import json, pathlib, sys
path = pathlib.Path(sys.argv[1])
cfg = json.loads((path / "adapter_config.json").read_text(encoding="utf-8"))
assert cfg.get("peft_type") == "LORA", "ожидался LoRA-адаптер"
assert isinstance(cfg.get("r"), int) and cfg["r"] > 0, "нужен положительный rank"
assert any((path / name).is_file() for name in ("adapter_model.safetensors", "adapter_model.bin")), "нет файла весов"
print("base:", cfg.get("base_model_name_or_path"), "revision:", cfg.get("revision"), "rank:", cfg["r"])
PY

Этот тест проверяет наличие и декларацию файлов, не архитектурную совместимость, целостность весов, лицензию или успешную генерацию. Не выполняйте чужой код из репозитория, пока не оценили доверенность источника.

Как поднять базу и один адаптер?

Установите vLLM по официальной GPU-инструкции соответствующей версии в отдельном окружении и убедитесь, что базовая модель уже отвечает на локальном API; список поддерживаемых архитектур и пути установки различаются по backend s6s7. Запишите точное имя модели, версии весов и адаптера в журнал собственного испытания. Не превращайте размер файлов весов в «минимум VRAM»: загрузка также зависит от длины контекста, KV-кеша, числа одновременных запросов и конфигурации адаптера.

После предварительной проверки подставьте реальные локальные каталоги (пример ниже намеренно не скачивает модель), а --max-lora-rank установите не ниже ранга вашего адаптера. Документация рекомендует выбирать максимальный rank среди применяемых адаптеров, а не завышать его ради запаса: завышение тратит память и может ухудшить производительность s1. В коде v0.30.0 значения по умолчанию — max_lora_rank=16 и max_loras=1; если у вашего адаптера rank больше, укажите его явно s2.

BASE=/srv/models/base
ADAPTER=/srv/models/my-lora
RANK=$(python3 -c 'import json,sys; print(json.load(open(sys.argv[1], encoding="utf-8"))["r"])' "$ADAPTER/adapter_config.json")
# Выполняйте только после проверки совместимости и разрешения на использование обоих наборов весов.
vllm serve "$BASE" --host 127.0.0.1 --port 8000 \
--enable-lora --max-lora-rank "$RANK" \
--lora-modules "trial-lora=$ADAPTER"

Команда запускает сервер в текущем терминале; проверки ниже выполняйте в другом. --lora-modules name=path — документированный статический способ передать адаптер. Именованный адаптер появится в /v1/models наряду с базой; при необходимости в версии v0.30.0 поддерживается JSON-форма с отдельным base_model_name — она обозначает метаданные связи, но сама не исправляет неподходящие веса s1. Адрес 127.0.0.1 ограничивает слушающий HTTP-сервер loopback, но не заменяет анализ сетевой поверхности и изоляцию других процессов на узле s3.

Если нужны несколько адаптеров, vLLM принимает несколько --lora-modules; max_loras ограничивает число одновременно активных адаптеров. Прежде чем повышать его, измерьте память, очередь и задержки именно у своей конфигурации, а не переносите показатели чужого GPU s1s2. Для эксплуатационного контроля пригодятся метрики vLLM.

Как доказать, что ответил нужный маршрут?

Сначала выполните curl -fsS http://127.0.0.1:8000/v1/models: успешный ответ должен перечислить идентификатор базы и trial-lora; если адаптера нет, не трактуйте 200 от базовой модели как доказательство его работы s1. Скопируйте точный id базы из ответа: если в вашей установке он отличается от локального пути, используйте именно возвращённый ID. Completions API документирован для текстовой генерации; Chat Completions дополнительно требует совместимый chat template s4. Для первого контроля используйте один и тот же текстовый prompt в /v1/completions:

curl -fsS http://127.0.0.1:8000/v1/completions \
-H 'Content-Type: application/json' \
-d '{"model":"/srv/models/base","prompt":"Ответь одним словом: тест","max_tokens":32,"temperature":0}'
curl -fsS http://127.0.0.1:8000/v1/completions \
-H 'Content-Type: application/json' \
-d '{"model":"trial-lora","prompt":"Ответь одним словом: тест","max_tokens":32,"temperature":0}'

В первой строке замените /srv/models/base на точный id базы из /v1/models; trial-lora — имя из команды запуска s1. Зафиксируйте HTTP-статус, возвращённое поле model, два ответа и отсутствие ошибок. Наличие разницы в текстах не доказывает улучшения, а одинаковый ответ не доказывает, что адаптер не применился: нужны контрольные входы из задачи, проверка правильности человеком и повторные попытки при зафиксированных настройках. У vLLM могут применяться параметры из generation_config.json репозитория, поэтому не сравнивайте результаты при незаметно разных конфигурациях генерации s4.

Для отдельного performance-теста сначала подтвердите функциональную корректность, потом сравните одинаковые версии модели, длины prompt, число запросов и параметры генерации на одной машине. Методика vLLM bench serve позволяет оформить результаты своего сервера, но в этой статье нет «измеренного ускорения» или обещания снижения VRAM.

Почему не стоит открывать динамическую загрузку?

Кроме стартовой конфигурации vLLM документирует /v1/load_lora_adapter и /v1/unload_lora_adapter, которые требуют VLLM_ALLOW_RUNTIME_LORA_UPDATING=True. Официальное предупреждение: это рискованный режим, его не следует использовать в production вне изолированной полностью доверенной среды s1. В security-документации уточняется, что такие маршруты меняют поведение модели и должны быть доступны лишь доверенным администраторам; даже --api-key не защищает все пути того же HTTP-сервера s3. Для обычного контролируемого пилота оставьте переменную выключенной, закрепите список адаптеров при запуске и ограничьте доступ сетью. Не принимайте путь до адаптера от непроверенного клиента.

Если сервер не стартует, сначала отдельно проверьте базу без --enable-lora, затем структуру адаптера и rank; несовместимую архитектуру или неверную ревизию нельзя лечить увеличением max_loras s1s2s5. Если /v1/models видит оба ID, но приложение всегда отправляет model базы, исправьте маршрутизацию клиента, а не перезаливайте веса s1. Для отката завершите тестовый процесс vLLM и поднимите прежнюю конфигурацию без --lora-modules и --enable-lora; сохраните результат контрольного запроса к базе до и после. Это операционный план, а не выполненный Modelium откат.

Основной следующий шаг: откройте проверенный путь запуска базовой модели в vLLM, запустите её без LoRA и запишите точный model id и исходный ответ. Только после этого включайте совместимый адаптер и сравнивайте пару ответов на своём тестовом наборе.