这次咱们聊点实在的。做LLM应用落地的人最近应该都明显感觉到一个趋势光会部署一个“能聊天的模型”已经不够用了。业务侧要么想让模型“看得懂图”要么想用少量数据“调教”出一个有专属风格的模型或者两个需求同时出现。于是vLLM里两个经常被一起提起的功能——多模态推理和LoRA推理就成了绕不开的实战主题。我自己是从单卡部署纯文本模型起步的后来被业务逼着去搞图文理解又被逼着把微调好的LoRA权重挂到生产服务上整个过程踩了不少坑。这篇教程就基于我实际跑通的经验把多模态推理和LoRA推理这两块在vLLM里的落地方式完完整整拆一遍包括环境怎么搭、脚本怎么写、参数怎么调、遇到问题怎么查。不搞花架子全是能直接抄作业的东西。1. 整体设计思路为什么要把多模态和LoRA放在一起聊1.1 多模态推理解决的不只是“看图说话”先对齐一个概念。vLLM里说的多模态推理核心是让文本生成模型接受图像还有音频、视频但目前落地最广的是图像作为输入在生成回复时参考这些非文本信息。实现逻辑并不神秘图像先经过一个视觉编码器转成特征向量再经过投影层映射到和文本embedding同一个空间然后和文本token的embedding拼在一起一起送进大模型的Transformer主干做attention计算。这个架构带来的直接好处是部署端不用关心视觉模型和语言模型之间复杂的交互细节vLLM已经把中间过程包好了。你只需要准备一个支持多模态的模型权重然后按它的接口格式组织输入即可。对工程同学来说这意味着不需要自己写图像特征提取、拼接、缓存那些代码能把精力集中在业务逻辑上。但这同时也带来一个隐含问题多模态模型对输入格式的约束比纯文本严格得多。图像要怎么传、Prompt怎么写、图像token占多少长度、max_model_len要设多大每一项都有讲究。稍不注意推理出来的内容就不是乱答就是直接OOM。1.2 LoRA推理为什么是微调推理的最佳搭档LoRALow-Rank Adaptation微调这几年火本质上是因为它在“省钱”和“有效”之间找到了一个平衡点。它的原理简单说是这样的大模型的全量参数W很大我们不去改动它而是给它加一个低秩的增量ΔW。这个增量被拆成两个小矩阵A和B训练时只更新这两个小矩阵最后生效的权重就是 W BA。打个比方全量微调相当于把整个房子重新装修一遍LoRA微调则像是往卧室里添一件定制家具——工程量小得多但对房间功能的改变可能非常精准。在推理侧LoRA的价值就体现在两个地方。第一同一个base模型可以挂多个不同的LoRA按业务需要动态切换不需要每个微调版本都单独部署一个完整模型服务。第二LoRA权重的体积远小于全量模型通常是几十到几百MB加载和切换的成本都低很多。vLLM对这类场景支持得比较成熟既能单独推理某个LoRA也能在离线批量场景里同时跑多个LoRA。1.3 这套组合拳最适合什么业务场景把多模态和LoRA结合起来实际能覆盖的场景比想象中多不少。比如电商场景图像是商品主图LoRA微调的是某一类商品的文案风格模型。用户上传商品图模型看图写营销文但风格符合店铺调性。再比如内容审核辅助用LoRA把通用模型微调成垂类审核模型输入是截图或海报模型输出是否存在违规元素。还有知识库问答的升级版文档里有大量配图图文一起作为上下文让模型作答LoRA则负责让模型回答问题的“口吻”更像客服专员而非通用助手。在这些场景里多模态负责“看得见”图像信息LoRA负责“说话像谁”两者各管一段又天然能叠在同一套服务里。这也是我为什么建议做推理部署的同学把这两个功能放在同一个进阶教程里学习的原因它们不是孤立的功能点而是一个完整的“图文输入—领域定制—文本输出”链路。2. 动手前的三板斧环境、模型和LoRA权重准备2.1 版本和硬件先把基础设施对齐每次写教程我都想强调版本问题。vLLM的迭代速度很快不同版本的接口和模型支持列表差异很大。我这边稳定跑多模态和LoRA的版本组合是这样的你们可以参考但一定要以你装的版本为准组件我用的版本说明CUDA Toolkit12.1兼顾主流模型编译需求和PyTorch稳定性PyTorch2.1.xvLLM官方对2.1系列的兼容性较好vLLM0.5.x或更新版0.5起多和LoRA支持大幅完善GPU单卡24GB如RTX 3090/4090或A107B-8B级别多模态模型LoRA推理够用提示如果显卡显存只有16GB跑8B级别的多模态模型会比较吃力。建议优先考虑6B-7B模型或者用4bit量化版权重vLLM对AWQ、GPTQ这些量化格式都支持得不错。安装方面很多人喜欢直接用pip install vllm但如果你要用到比较新的模型架构我更推荐从源码安装指定分支或者用官方发布的Docker镜像打底。尤其是多模态模型经常刚出没多久vLLM就加入支持了等PyPI发布对应轮子可能会晚几周。当然对大多数人来说装稳定版就足够了遇到模型不支持时先看文档再决定要不要换分支。2.2 多模态模型怎么选直接看支持列表vLLM对多模态模型的支持是按架构走的不是所有HuggingFace上号称多模态的模型都能直接跑。目前社区里验证得比较多、资料也好找的几类包括Qwen2-VL系列7B、72B都有图文理解能力在同体量里属于第一梯队vLLM支持很积极。LLaVA系列生态成熟基座变体多学术资料丰富适合做对比实验。InternVL系列国内团队出品图文理解细节做得好vLLM支持情况要查对应版本。我的建议是第一跑通流程不要太追求极致效果。选社区最热、vLLM验证最充分的模型比如Qwen2-VL-7B-Instruct。等整个推理链路通了再换更垂直的模型不迟。2.3 LoRA权重长什么样怎么准备LoRA推理有一个前提你已经通过训练拿到了LoRA权重文件。如果你熟悉HuggingFace生态的微调流程比如用peft库那最终产物通常是一个目录里面包含两个关键文件adapter_config.json记录LoRA的超参数比如r秩、lora_alpha、目标模块target_modules、是否用了量化的base model等。adapter_model.safetensorsLoRA增量权重的实际参数。有这两个文件vLLM就能直接加载。但你需要注意vLLM对LoRA的兼容性是有边界的不是任何模型都能挂任何LoRA。它要求LoRA的目标模块和base模型的结构匹配且必须是在vLLM支持的模型架构上调出来的。所以你在训练LoRA时如果用peft库设置target_modules时最好不要选太冷门的模块组合。最常见的做法是只对q_proj、k_proj、v_proj、o_proj这些attention层的投影矩阵做低秩适应这也是兼容性最好的配置。3. 多模态推理实操让模型真正“看见”图像3.1 模型加载比纯文本多了一个trust_remote_code问题多模态模型的加载和纯文本模型有两个明显差异。第一部分模型的代码没有完全合入Transformers主库加载时要开启trust_remote_codeTruevLLM才能在初始化时动态执行模型目录里的代码。第二需要确认vLLM对这个模型的支持方式是“原生内置”还是“remote code模式”。如果是后者加载配置和依赖要更小心。我建议最简单的加载方式还是用CLI命令先验证一次。注意我这里是举例Qwen2-VL比较特殊它早期版本需要remote code后续版本逐步原生支持了。大家以官方文档为准。命令长这样vllm serve Qwen/Qwen2-VL-7B-Instruct \ --trust-remote-code \ --max-model-len 8192 \ --gpu-memory-utilization 0.9这条命令里两个参数值得关注。--max-model-len决定了输入文本图像占用的token总和上限多模态场景里图像是按token算的所以不能像纯文本那样按对话长度估。--gpu-memory-utilization决定KV cache能占用多少显存设得太高容易OOM设得太低吞吐上不去。我一般先设0.9观察OOM再降。3.2 图像输入vLLM的接口到底长什么样在离线批量推理场景中这也是最常被问到的场景直接用LLM类和MultiModalData类。好多人在这一步卡住就是对MultiModalData怎么用不熟悉。这个类本质上是多模态输入的容器目前支持MultiModalDataImage、MultiModalDataAudio、MultiModalDataVideo这些子类图像类用法如下from PIL import Image from vllm import LLM, SamplingParams from vllm.multimodal import MultiModalData, MultiModalDataImage # 1. 加载模型 llm LLM( modelQwen/Qwen2-VL-7B-Instruct, trust_remote_codeTrue, max_model_len8192, gpu_memory_utilization0.9, ) # 2. 读取图片 image Image.open(test.jpg).convert(RGB) # 3. 组织多模态输入 multi_modal_data MultiModalData({ MultiModalDataImage.placeholder: [image] }) # 4. 用huggingface的chat template把对话消息转成指令 from transformers import AutoTokenizer tokenizer AutoTokenizer.from_pretrained(Qwen/Qwen2-VL-7B-Instruct) messages [ { role: user, content: [ {type: image}, {type: text, text: 请描述这张图片里的主要内容。}, ], }, ] prompt tokenizer.apply_chat_template( messages, tokenizeFalse, add_generation_promptTrue, ) # 5. 发起推理 outputs llm.generate( { prompt: prompt, multi_modal_data: multi_modal_data, }, sampling_paramsSamplingParams(temperature0.2, max_tokens256), ) print(outputs[0].outputs[0].text)这段代码里有个关键点MultiModalDataImage.placeholder这个键实际上是一个占位字符串用于生成时定位图像特征插入的位置。不同模型对占位符的要求不一样比如有的模型用image有的用|vision_start||image_pad||vision_end|之类更复杂的形式。所以我的建议是先看这个模型在HuggingFace上的chat template是怎么组织图像占位符的确保和vLLM里的prompt完全匹配否则模型不会知道图像特征该插在哪。3.3 图像token数量最容易忽略的显存杀手多模态推理和纯文本推理在显存计算上有个本质差别图像不是“一张图”它被视觉编码器切成了很多个patch每个patch映射成一个token参与后续计算。Qwen2-VL这类模型还会对图像做动态分辨率切分图像越大token越多。我实测过一个1024x1024左右的图片在Qwen2-VL-7B上大概会占用几百到上千个token。这也意味着如果你的max_model_len设成2048一张大图加一段长Prompt就挤占了大量token空间留给生成回复的位置可能只有几百个token稍长的回答就会被截断。所以实操建议是图像输入前自己先做一次预处理。能压缩到不影响理解的尺寸就压缩既能降低token占用又能提升推理速度。另外max_model_len不要设8000就以为万事大吉你要把这个值理解为“图像token 系统Prompt 历史对话 回复token”的总和超过就会报错。4. LoRA推理实操把微调产物挂上去4.1 接一个LoRA只需要一个参数vLLM对LoRA推理的支持从CLI命令到Python API都做了封装。如果你只挂一个固定的LoRA最简单的方式是在命令行里加上--enable-lora然后通过--lora-modules参数把LoRA名字和路径绑在一起vllm serve Qwen/Qwen2-VL-7B-Instruct \ --trust-remote-code \ --enable-lora \ --lora-modules my-lora/path/to/lora-weights \ --max-model-len 8192启动后服务就会以base模型为底携带my-lora这个LoRA。请求时如果指定使用该LoRA模型输出就会带有微调后的风格不指定时则退回base模型行为。如果你的场景是离线批量推理Python API的写法也很直观from vllm import LLM, SamplingParams from vllm.lora.request import LoRARequest llm LLM( modelQwen/Qwen2-VL-7B-Instruct, enable_loraTrue, max_model_len8192, ) outputs llm.generate( [介绍一下这款产品的特点], sampling_paramsSamplingParams(temperature0.3, max_tokens128), lora_requestLoRARequest(my-lora, 1, /path/to/lora-weights), )这里LoRARequest的三个参数分别是显示名称、唯一ID、权重路径。在离线批量场景里如果你同时处理多个不同LoRA的任务要保证lora_request的ID和名称各自唯一否则可能出现串权重的问题。4.2 动态切换多LoRA服务端怎么做缓存vLLM的多LoRA机制和很多人想的不一样它不是把每个LoRA都加载到显存里占一份完整显存而是采用了一种动态加载/卸载的方式。也就是说多个LoRA的权重按需加载到GPU内存用完后可以被替换或释放但这中间有一个缓存机制。这带来的实际影响是切换LoRA不是零成本的。第一次使用某个LoRA时要从磁盘加载到显存会有一次明显的延迟如果没有命中缓存还需要重新加载。所以在生产环境里需要合理设置--max-loras和--max-lora-memory这两个参数。--max-loras控制最多同时驻留几个LoRA--max-lora-memory控制LoRA权重最大占用多少显存。它们的设置直接影响到并发请求处理时的切换频率。如果这两个参数设得太小频繁切换就会降低吞吐。我对一般业务场景的建议是先用默认值跑一版压测观察日志中LoRA切换时长和GPU显存占用曲线。若切换太频繁调高--max-loras若显存余量不足调低--max-lora-memory。这个没有绝对标准得按你的实际并发模型来调。4.3 推理时LoRA参数和base模型的关系很多人在推理阶段会纠结一个问题要不要把LoRA合并进base模型权重再部署如果业务上只有一个LoRA且长期不变合并不是不行。把LoRA权重合并回base模型后模型文件变得更完整部署也更简单不需要额外的LoRA加载逻辑。但这么做有个代价模型文件体积变大了尽管LoRA本身不大合并后base模型整体存储和分发成本会上涨而且失去了动态切换能力。如果业务上比较灵活比如同一个base模型要服务多个团队各团队有自己的LoRA那强烈建议不要合并直接用vLLM的动态LoRA功能。这样才能做到一套服务多套专属风格。还有一个容易踩的坑base模型和LoRA之间不能有色差。意思是如果LoRA是在某个微调过的base权重上训练的推理时也建议用同一个base权重文件不要换用别的副本。比如有人在HuggingFace上不小心下了原始版而不是某个衍生版挂上LoRA后效果暴跌查了半天才发现是base权重对不上。这一点务必记牢。5. 常见问题与排查实录这些坑我帮你踩过了5.1 模型加载报错ModelClassNotFound和trust_remote_code不少同学在加载多模态模型时会遇到类似“ValueError: Model class XXXXPipeline not found”的报错。这个问题的原因通常是vLLM内置模型注册表里没有收录这个模型类需要靠trust_remote_codeTrue来动态加载模型定义但你启动时没有开启这个开关。排查顺序很明确先确认模型是否在vLLM官方支持的模型列表里。如果支持检查你用的vLLM版本是否太老升级到支持该模型的版本。如果模型需要remote code确保加载时传了trust_remote_codeTrue。看看模型目录下的config.json里面auto_map字段是否定义了AutoModelForCausalLM等类的映射如果没有remote code支持光靠trust_remote_codeTrue也救不回来。提示生产环境用remote code时一定注意供应链风险。模型权重里的自定义Python代码是会被执行的必须确认代码来源可信后再允许加载不要随便跑陌生人发布的模型。5.2 显存OOM尤其是Unsloth训练完LoRA后评估卡死热词里有不少人问“unsloth训练LoRA时进行评估总是占满显存导致速度很慢怎么办”这个问题其实分两段看。Unsloth这个库本身在训练阶段做了很多显存优化但评估阶段如果用Transformers的evaluate流程会在GPU上重新跑一遍完整前向推理此时所有训练优化都不再生效显存占用自然猛涨。解决办法是在评估时大幅减小per_device_eval_batch_size比如训练batch是4评估batch设为1让显存占用降下来。另外评估时还可以临时关闭梯度计算用torch.no_grad()包住推理逻辑并禁用compute_metrics里不必要的中间变量缓存。训练完成之后如果切到vLLM推理又OOM那就是另一类问题。你需要检查vLLM启动参数里的--gpu-memory-utilization是否设得太高同时确认--max-model-len是否预留了足够空间。多模态场景下图像token不可控尤其要留出余量。我一般建议图像场景下gpu-memory-utilization设为0.85左右比纯文本场景略低一些。5.3 推理效果不对优先查Prompt和LoRA触发词排查推理问题大多数人第一反应是模型不行但我排查过很多案例最后发现都是Prompt组织不合理或者LoRA的使用方式不对。以LoRA为例很多人训练LoRA时习惯设一些“触发词”。比如你想训练一个客服风格LoRA训练数据里每条都以“你是客服”开头。这种情况下推理时的Prompt也要带上这些触发词LoRA的效果才能真正显现。如果你推理时用的是普通PromptLoRA对输出的影响可能微弱到几乎不可感知。触发词还有个冷知识中英文触发词不能混用。训练时用的是中文“你是客服”推理时换成“You are a customer service agent”是没用的LoRA学到的分布非常依赖训练时的输入模式这种跨语言的替换大概率失效。再比如多模态场景Prompt的描述质量直接决定输出质量。同样是看图回答写“这是什么”和写“请从颜色、材质、功能、适用场景四个维度描述这张图中的物品”效果完全不在一个层面。多模态模型对指令的具体化程度非常敏感这是实测过很多次的结论。5.4 LoRA推理时显存开销怎么估算很多人在训练LoRA之前就想知道LoRA一个9B模型需要多少显存。这个问题既要看训练也要看推理。训练阶段LoRA的显存开销主要来自三部分base模型权重即便冻结也要占显存、可训练的LoRA参数及对应优化器状态、中间激活值。9B模型做LoRA训练通常需要24GB以上显存才比较从容。如果只有16GB需要配合梯度检查点gradient checkpointing和small batch size有时还要用“4bit量化加载base模型 LoRA”的QLoRA方案才能压进显存。推理阶段就轻松得多。vLLM推理时base模型权重占大头LoRA权重本身很小。比如9B模型的KV cache和激活值是主要开销一个64GB显存等级的GPU部署9B base模型带一两个LoRA是够用的。我实测经验是LoRA推理的总显存占用基本等同于“base模型推理 LoRA权重 少量缓存余量”不用为LoRA本身额外预留过多空间。最后的实操心得写到这里多模态推理和LoRA推理在vLLM里的落地路径基本就走完一遍了。我个人的体会是这两个功能单独一个都不算特别难真正难的地方在于它们组合起来时变量变多了输入格式要对、token预算要算、LoRA触发词要一致、显存分配要留余量。任何一个环节没对齐效果和性能都会打折扣。所以如果你正在搭建类似的能力我的建议是先不要试图一步到位。第一轮单独跑通多模态推理熟悉图像输入和token预算的关系。第二轮单独跑通LoRA推理体验一下挂载和切换的流程。第三轮再做组合这时候你已经清楚每个报错大概出在哪一层排查起来心里有数。说到底vLLM是一个工程工具不是玄学。它的每个参数、每个接口都是可以被验证和理解的。希望这篇教程能让你少走几个弯路也希望你把这套链路跑起来之后能多去探索更多有意思的业务场景。