vllm-lora

vLLM 多 LoRA 服务：一个基座模型动态挂载多个适配器，按请求路由

补充说明

vLLM 支持在同一个基座模型上加载多个 LoRA 适配器，按请求里的 model 字段路由到不同适配器。它解决“多个微调版本共用一个基座、又不想每个版本单独起一个完整模型”的问题，适合多租户、A/B 测试和按客户定制。LoRA 只训练低秩适配器，不改变基座权重；推理时适配器权重会额外占用显存。

vLLM 的 LoRA 支持有上限：--max-loras 控制同时加载的适配器数量，--max-lora-rank 控制最大秩。vLLM 0.12 起已移除 LoRA 额外词表支持（原 --lora-extra-vocab-size）。适配器需要是 PEFT 格式，并与基座模型架构、隐藏维度匹配。

常用示例

# 启动基座模型，加载两个 LoRA 适配器
vllm serve Qwen/Qwen2.5-7B-Instruct \
  --enable-lora \
  --max-loras 4 --max-lora-rank 64 \
  --lora-modules customer-a=/models/lora/customer-a \
                   customer-b=/models/lora/customer-b \
  --host 0.0.0.0 --port 8000

# 请求时用 model 字段选择适配器
curl http://localhost:8000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"customer-a","messages":[{"role":"user","content":"你好"}]}'

# 不指定适配器时使用基座模型
curl http://localhost:8000/v1/models

运行时动态加载/卸载（需要开启对应开关，按 vLLM 版本确认）：

VLLM_ALLOW_RUNTIME_LORA_UPDATING=1 vllm serve Qwen/Qwen2.5-7B-Instruct \
  --enable-lora --max-loras 8 --max-lora-rank 64

curl -X POST http://localhost:8000/v1/load_lora_adapter \
  -H 'Content-Type: application/json' \
  -d '{"lora_name":"customer-c","lora_path":"/models/lora/customer-c"}'

易错点与排错

• 适配器与基座不匹配：LoRA 的隐藏维度、层数、target modules 必须与基座一致；换基座后要重新训练或转换适配器。
• 只调大 --max-loras 不看显存：每个适配器都占显存，长上下文和高并发会放大占用；先压测再定上限。
• model 字段写基座名：请求会走基座而不是适配器；用 /v1/models 确认暴露的名称，名称要和 --lora-modules 一致。
• 适配器格式不是 PEFT：直接拿训练框架的 checkpoint 目录可能缺少 adapter_config.json；按 vLLM 文档转换。
• 新增词表：vLLM 0.12 起已移除 LoRA 额外词表支持，扩展 tokenizer 的适配器无法再通过 --lora-extra-vocab-size 加载；应改用不扩展词表的适配器。
• 动态加载没有鉴权：开放 /v1/load_lora_adapter 等于允许加载任意路径；生产环境要限制来源、路径和调用方权限。
• 多适配器并发下的公平性：某个适配器请求过多会挤占基座资源；用配额、限流或独立部署隔离重负载租户。
• 版本差异：LoRA 相关参数和动态加载接口随 vLLM 版本变化；升级前看 release notes，并回归路由和显存。

相关命令

• vllm — vLLM 基础部署与 OpenAI 兼容服务。
• vllm-tuning — 吞吐、延迟与显存参数调优。
• peft — LoRA/QLoRA 等参数高效微调。
• llama-factory — 微调并导出适配器。
• quantization — 基座模型的量化部署。

参考链接

• vLLM LoRA 文档
• vLLM 官方文档
• PEFT 文档

读完自测

合上页面，先回答，再展开对照。

1. vLLM 多 LoRA 服务如何把请求路由到不同适配器？
2. --max-loras 和 --max-lora-rank 分别限制什么？为什么不能只调大？
3. 生产环境开放动态加载 LoRA 有什么风险？