这个系列写到现在已经聊过张量并行、投机采样、前缀缓存这些基础玩法了。今天这篇是我自己在实际部署时积累出的一个组合场景在一个 vLLM 服务里同时跑多模态模型和 LoRA 推理。说白了就是两个方向叠加——一个是让模型能“看图说话”另一个是把微调出来的低秩适配器挂到服务上动态切换。这两个功能单独拎出来文档里都有但一旦放在同一个项目里做很多细节就只能靠翻源码和踩坑来补。这篇文章我就把踩过的坑、验证过的命令、参数怎么配、显存怎么算一次性说清楚。先声明一个容易混淆的点这里说的 LoRA 是 Low-Rank Adaptation大模型参数高效微调里那个 LoRA不是物联网无线通信里那个长距离 LoRa 模块。这两个名字只差一个字母但完全是两码事。搞 STM32、ESP32 做环境监测的同学看到这篇文章别走错门我们聊的是模型权重适配器。这篇文章适合谁看已经跑通过 vLLM 基础部署想给服务加多模态能力或者手里有一批微调好的 LoRA 适配器想统一管理的人。如果你只是刚装好 vLLM 想跑个 demo建议先把基础那几篇过一遍再来。1. 多模态与LoRA在vLLM里的基本盘1.1 多模态模型在vLLM中的架构适配vLLM 最早只支持纯文本 LLM后来多模态模型火起来了官方才逐步把视觉语言模型的推理链路加进去。但 vLLM 不是简单地把模型权重塞进 Transformer 就完事它需要处理视觉塔、投影层和 LLM 主干三者之间的数据流。以 Qwen2-VL 这类视觉语言模型为例结构上分三块视觉编码器负责把图片转成视觉特征投影层把视觉特征映射到文本 embedding 空间LLM 主干最后统一处理。vLLM 内部用了一个叫 MultiModalRegistry 的注册机制每个支持的多模态模型都会注册自己的图像预处理逻辑和 token 拼接方式。所以你在启动服务的时候vLLM 需要识别模型的 model_type去调用对应的多模态处理器。这意味着一个很实际的问题不是所有多模态模型在 vLLM 里都能开箱即用。版本滞后的时候新发布的模型在旧版 vLLM 里会直接报 model class not found。我自己遇到过几次解决方式基本就是升级 vLLM 版本或者等官方合入新模型的支持。1.2 多模态推理与LoRA推理的关系这两个功能在 vLLM 里不是互斥的它们可以同时启用。但要注意多模态模型的 LoRA 支持在 vLLM 里是逐步开放的。早期版本只能做纯文本模型的 LoRA 推理Qwen2-VL 这类模型的 LoRA 是后面版本才合入的。如果你要同时用最好确认一下 vLLM 版本对目标模型 LoRA 的支持状态。从工程角度讲同时开启多模态和 LoRA 后服务端要做的事变多了图像要预处理成视觉 token文本要走 tokenizerLoRA 适配器要注入到对应层的权重计算里最后还要把这些拼在一起做自回归生成。链路变长出问题的概率也变大。所以在实操里我一直建议一个原则先把纯多模态跑通再挂 LoRA。两个功能拆开验证都没问题组合起来才容易排查到底是哪一环出的错。2. 多模态推理的完整链路详解2.1 图像输入从哪来到哪去多模态推理和纯文本推理最大的区别就是输入不再是“一句话”而是“一张图加一句话”。以 OpenAI 兼容接口为例请求里 content 字段变成一个数组里面既有 text 类型也有 image_url 类型。from openai import OpenAI client OpenAI(base_urlhttp://localhost:8000/v1, api_keyEMPTY) # 本地图片转 base64 import base64 with open(demo.png, rb) as f: b64_image base64.b64encode(f.read()).decode(utf-8) response client.chat.completions.create( modelqwen2-vl, messages[{ role: user, content: [ {type: text, text: 描述一下这张图片里的主要内容}, {type: image_url, image_url: {url: fdata:image/png;base64,{b64_image}}} ] }], max_tokens512 ) print(response.choices[0].message.content)服务端收到请求后vLLM 的多模态处理器会把 base64 图片解码、缩放到模型配置指定的分辨率、切成 patch再通过视觉编码器得到视觉 token。这些视觉 token 会跟文本 token 拼接在一起作为 LLM 主干的输入。2.2 动态分辨率对显存和性能的影响这里有个多模态推理特有的问题图像经过处理后产生的 token 数量不是固定的。不同尺寸的图片切出来的 patch 数量不一样导致一个请求占用的显存也差异很大。像 Qwen2-VL 这类模型内部有动态分辨率机制输入图像会根据模型配置被缩放到不同的尺寸组合视觉 token 数量从几百到几千都有可能。你按 512x512 预估的显存来一张 2000x1500 的大图直接多出几倍的视觉 token显存占用瞬间飙升。所以我建议在服务端做一层限制用 vLLM 提供的--limit-mm-per-prompt参数控制每张图片能产生的最大视觉 token 数或图片数量--limit-mm-per-prompt image5这个参数的意义在于约束输入规模。如果业务场景里用户可能上传超大尺寸图片建议在应用层先做压缩把最长边限制到 1568 像素以内既能保住识别精度又能避免显存峰值过大。2.3 多模态的统一接口设计从用户视角看vLLM 把多模态的复杂性全部收敛到了 OpenAI 兼容接口里。你不需要单独调一个“图像识别 API”只要在 chat 消息里带上 image_url 就能实现视觉理解。这个设计对 AI Agent 场景特别友好。Agent 在处理任务时经常需要同时读取网页截图、分析本地图片、提取文字信息。统一接口意味着 Agent 的调用逻辑不用区分“这是视觉任务还是文本任务”模型能处理什么输入Agent 就发什么输入。多模态词元化协议这个词听起来玄乎实际上就是上面讲的这个机制图像被转成视觉 token文本被转成文本 token两种 token 在同一套词表空间里拼接模型统一处理。对齐这两类 token 的语义空间正是多模态大模型最重要的训练目标之一。3. LoRA推理机制与参数规划3.1 LoRA适配器在推理时是怎么工作的先简单回顾一下 LoRA 的原理。全量微调会更新整个模型的权重矩阵 W而 LoRA 假设权重更新量 ΔW 是低秩的可以拆成两个小矩阵的乘积ΔW B × A。训练时只更新 A 和 B推理时把这两个低秩矩阵合并回原权重W W (α / r) × B × A。所以在 vLLM 里挂 LoRA本质上是把额外的低秩分支叠加到基础模型的某些层上。vLLM 内部不是直接改权重文件而是在运行时把 LoRA 权重加载进来在 attention 层计算时动态加上低秩分支的结果。这里有一个关键点LoRA 适配器必须和基础模型匹配。你在 Qwen2-VL-7B 上微调出来的 LoRA不能挂到 Qwen2-7B 上也不能挂到 Qwen2-VL-72B 上。因为 LoRA 只记录权重增量而增量是对应层的维度相关的模型架构和层数不一致矩阵乘都做不了。3.2 vLLM挂载LoRA的三种姿势方式一启动时静态挂载。用--lora-modules参数指定 LoRA 名称和路径--enable-lora \ --lora-modules my-lora/data/lora/qwen2vl-style-lora \这样服务启动后这个 LoRA 就常驻在显存里请求时通过lora_name字段选择是否启用。方式二运行时动态加载。新版本 vLLM 支持通过 API 动态添加 LoRA 适配器不用重启服务。这个功能对多租户场景特别有用你可以在一个基础模型上挂多个 LoRA每个租户用各自的适配器互不干扰。方式三请求级切换。这也是我认为最优雅的用法。同一个模型名 qwen2-vl请求 A 用 LoRA请求 B 不用 LoRA完全由请求里的参数决定response client.chat.completions.create( modelqwen2-vl, messages[...], extra_body{lora_name: my-lora} )不传lora_name走基础模型原生推理传了就走对应 LoRA 适配器。这样一套服务可以同时服务多个业务线每个业务线用不同风格或能力的适配器运维上非常省心。3.3 LoRA显存开销怎么算很多人问挂一个 LoRA 到底多占多少显存。我给个经验公式LoRA 权重本身的显存很小一个 rank32、7B 模型上的 LoRAFP16 精度大约只有几十 MB。但 vLLM 为了加速 LoRA 推理会缓存 LoRA 相关的中间结果这部分开销不能忽视。vLLM 里有几个关键参数--max-lora-rank限制 LoRA 的最大 rank 值。默认值在不同版本有差异建议显式指定至少大于等于你训练时的 rank。--max-loras-per-gpu每张 GPU 上最多同时缓存几个 LoRA。默认 1。--max-cpu-lorasCPU 上缓存多少个 LoRA用来在 GPU 显存不够时做换入换出。我常用的配置是这样--enable-lora \ --max-lora-rank 64 \ --max-loras-per-gpu 4 \ --max-cpu-loras 8 \这个配置的含义是GPU 上同时缓存 4 个 LoRACPU 里再备 8 个请求指定了不在 GPU 上的 LoRA 时vLLM 会自动从 CPU 加载到 GPU。换入换出有性能损耗但比重启服务强太多。下面这个表是实测下来的显存估算以 Qwen2-VL-7B-Instruct 为基准FP16 精度gpu-memory-utilization 设为 0.9场景模型权重显存视觉 token 缓存KV CacheLoRA 缓存24G 卡跑不跑得动纯文本推理~16 GB0动态0可以单图多模态~16 GB1~2 GB动态0可以注意大图多模态 2 个 LoRA~16 GB1~2 GB动态0.5~1 GB紧张建议量化多模态 4 个 LoRA~16 GB1~2 GB动态1~2 GB不行会 OOM这里有个非常重要的经验多模态模型的权重显存就比纯文本模型大一截因为多了视觉编码器。在这个基础上再挂多个 LoRA24GB 的 3090/4090 很容易吃紧。我实际部署时经常把gpu-memory-utilization调到 0.95同时限制单请求最大视觉 token 数才能在 24G 卡上跑得舒服。4. 实操案例Qwen2-VL带自有LoRA跑起来4.1 环境准备与依赖版本先说我验证过的版本组合Ubuntu 22.04 / WSL2、Python 3.10、CUDA 12.1、vLLM 0.10.x 及以上、transformers 4.46 以上。安装命令pip install vllm注意vLLM 从 0.8.x 开始自带 flash-attn 相关依赖不需要手动编译 flash-attn。如果你装完发现缺什么算子优先检查是不是 vLLM 版本和 CUDA 版本不匹配。Windows 原生环境我实测过多模态和 LoRA 的支持不太完整建议用 WSL2 或者 Docker。vLLM 官方镜像直接拉下来用也行docker pull vllm/vllm-openai:latest4.2 启动多模态与LoRA服务完整启动命令如下vllm serve Qwen/Qwen2-VL-7B-Instruct \ --served-model-name qwen2-vl \ --enable-lora \ --lora-modules style-lora/data/lora/style-lora \ --max-lora-rank 64 \ --max-loras-per-gpu 2 \ --max-cpu-loras 4 \ --gpu-memory-utilization 0.92 \ --limit-mm-per-prompt image5 \ --max-model-len 32768逐参数解释一下--served-model-name对外暴露的模型名客户端调用时用这个名字。--enable-lora开启 LoRA 功能不加这个参数--lora-modules会被忽略。--lora-modules style-lora/data/lora/style-lora静态挂载一个 LoRA。--limit-mm-per-prompt image5限制单个请求最多 5 张图片。--max-model-len 32768模型最大上下文长度包括文本 token 和视觉 token。启动日志里看到类似Starting vLLM server和Uvicorn running on http://0.0.0.0:8000就说明服务起来了。4.3 同时验证视觉理解和LoRA切换先用不带 LoRA 的请求测视觉理解from openai import OpenAI client OpenAI(base_urlhttp://localhost:8000/v1, api_keyEMPTY) resp client.chat.completions.create( modelqwen2-vl, messages[{ role: user, content: [ {type: text, text: 这张图里有几个物体分别是什么}, {type: image_url, image_url: {url: https://example.com/test.jpg}} ] }], max_tokens256 ) print(resp.choices[0].message.content)再测带 LoRA 的请求注意 extra_body 里加了 lora_nameresp client.chat.completions.create( modelqwen2-vl, messages[{ role: user, content: [ {type: text, text: 用你自己的风格描述这张图}, {type: image_url, image_url: {url: https://example.com/test.jpg}} ] }], max_tokens256, extra_body{lora_name: style-lora} ) print(resp.choices[0].message.content)两个请求的差异只在lora_name这个字段。测试时注意观察响应时延和显存变化LoRA 生效时如果首次使用该适配器会有一次显存加载的延迟后续请求就稳定了。LoRA 目录结构一般长这样你可以自己核对一下/data/lora/style-lora/ ├── adapter_config.json ├── adapter_model.safetensors └── README.mdadapter_config.json 里最关键的两个字段是base_model_name_or_path和rrank 值。如果base_model_name_or_path和你启动时用的模型不一致vLLM 可能会拒绝加载这个 LoRA所以训练完 LoRA 记得检查一下这个字段。4.4 工具链对比vLLM vs sglang写到这里顺便提一嘴 sglang。作为 vLLM 的主要竞品sglang 也支持多模态和 LoRA 推理启动命令长这样python -m sglang.launch_server \ --model-path Qwen/Qwen2-VL-7B-Instruct \ --lora-paths style-lora/data/lora/style-lora我的使用感受是sglang 在部分模型上的吞吐量有优势但在 LoRA 动态切换、多模态模型覆盖度、OpenAI 接口兼容性上vLLM 目前还是更成熟。如果你只是做内部验证两个都能选如果要上生产尤其是有多租户动态 LoRA 需求的我建议优先 vLLM。5. 避坑手册与性能调优建议5.1 多模态常见报错与处理第一个典型报错是显存超限日志里出现CUDA out of memory。这个在多模态场景太常见了原因是单张图产生的视觉 token 太多导致 KV Cache 瞬间暴涨。处理方法降低--limit-mm-per-prompt里的图片数量限制。在应用层压缩图片限制最长边。把--gpu-memory-utilization调低一点给显存留出余量。第二个典型问题是图片 token 数超过上下文长度报token limit exceeded或context_length_exceeded。这是因为视觉 token 和文本 token 加起来超过了--max-model-len。解决方案是增大 max-model-len或者限制图片分辨率。第三个是模型版本不匹配。比如日志里出现ValueError: Model class Qwen2VLForConditionalGeneration not found这种一般是 transformers 或 vLLM 版本太旧不支持目标模型架构。优先升级 vLLM 和 transformers。有时候模型文件里 config.json 的 model_type 写得不标准也会触发这种报错可以用 transformers 直接加载一下模型配置确认 model_type 是否被 vLLM 支持。5.2 LoRA加载与切换的坑LoRA 最常见的坑是 target_modules 不匹配。你在训练时用 peft 配置的 target_modules 是 q_proj、v_proj加载时 vLLM 按照它自己支持的模块列表去匹配如果训练时设置了奇怪的模块名加载会失败。解决办法很简单训练时不要改 target_modules 的默认值保持 q_proj、v_proj、k_proj、o_proj、gate_proj、up_proj、down_proj 这些常见命名。第二个坑是 rank 超过--max-lora-rank。训练时 r64启动服务时 max-lora-rank 写的 32vLLM 会直接拒绝加载。日志里会有明确的 rank mismatch 提示。所以启动参数最好和训练参数对齐。第三个坑是多个 LoRA 切换时的显存峰值。动态切换 LoRA 时vLLM 需要把新 LoRA 加载到显存旧 LoRA 可能还在缓存里瞬时显存占用会上升。如果你在切换时遇到偶发 OOM可以把--max-loras-per-gpu调大一点让常用 LoRA 常驻显存减少换入换出的频次。5.3 组合场景的性能调优心得多模态和 LoRA 组合使用性能调优要分两头看。图像预处理这块我建议在客户端做尺寸归一化不要把原图直接传上去。实测下来一张 1568px 的图和一张 4096px 的图在视觉 token 数量上能差出 3 到 4 倍推理时延差别明显。做业务的话给用户上传的图片做压缩既能省显存又能降延迟。LoRA 这块如果你的服务里只有一个 LoRA建议直接静态挂载省去动态加载的开销。如果 LoRA 很多但每次只有少数几个活跃用--max-cpu-loras把不常用的缓存在 CPU 内存里比全部塞 GPU 更合理。CPU 与 GPU 的换入换出虽然有时延但总比重启服务强。另外如果你计划让量化模型AWQ、GPTQ和 LoRA 一起用提前做好心理准备量化基座 LoRA 的组合支持度在各版本中有波动实测 AWQ 量化模型挂 LoRA 的兼容性不如 GPTQ但胜在显存占用低。建议先拿一个适配器跑通全链路再决定要不要上量化。5.4 上线前的检查清单说几个我每次都会过一遍的检查项基础模型是否支持目标 LoRA 的base_model_name_or_path。LoRA 的 rank 是否小于等于服务的--max-lora-rank。图片输入是否有尺寸和数量限制防止恶意大图打满显存。请求接龙里的 lora_name 是否和服务端注册的名字完全一致大小写都不能错。多模态请求的超时时间是否给够首 token 时延会比纯文本长不少尤其是大图场景。这些问题踩过一次就有教训了。我之前有一次生产事故就是客户端传了一张 4K 屏的截图没压缩直接把 24G 显存打爆服务 OOM 重启。后来加了图片尺寸限制和单请求图片数量限制就再没出过类似问题。写在最后的操作体会如果你现在正准备把多模态和 LoRA 一起上我的建议是别急着一口气配完所有功能。先单独跑通多模态推理确认图片输入、视觉 token、上下文长度都没问题再单独挂一个 LoRA确认能加载能切换最后再把两个功能合在一起测。分步推进虽然多花半小时但排查问题的成本能省下一整天。这个小技巧很实用vLLM 服务启动后可以用nvidia-smi看显存曲线来判断 LoRA 是否真的加载到了显存。正常情况启动时显存占用是一次性涨上去的如果你看到显存在请求过程中突然又涨了一大截说明那个时刻 LoRA 在做换入或首次加载。抓住这个规律很多显存问题不用看日志就能定位到原因。多模态和 LoRA 的组合场景后续大概率是 AI Agent 落地的标配。一套服务既要能看图又要能针对不同用户切换微调风格vLLM 这条技术路线现在是市面上最接近生产可用的。把这套东西吃透后面接什么场景都不慌。