多模态大模型这两年从论文里的概念快速落到了工程实践中但真正动手跑通一个视觉语言模型VLM的推理和微调中间踩的坑远比想象中多。Yi-VL 系列开源之后我第一时间在自己的环境里把它从权重加载、图片推理一路跑到 LoRA 微调整个过程里有些环节文档写得比较简略有些则是版本兼容的暗坑。这篇就把我实际跑下来的完整链路整理出来包括环境怎么配、推理脚本怎么写、微调数据怎么组织、显存怎么省以及几个我调了很久才定位到的问题。不管你是刚接触多模态、想先跑个 Demo 看看效果还是已经准备拿自己的业务数据做微调下面这些内容应该都能直接拿去用。Yi-VL 是零一万物开源的视觉语言模型系列包含 6B 和 34B 两个规格架构上是视觉编码器加投影层再对接语言模型主干的经典三段式结构。它能做的事很直接给一张图加一段文字提问模型输出对图片的理解、描述、推理结果。适合的人群其实挺广——做文档理解、图表问答、商品图描述、工业质检辅助判断这类场景的开发者都可以拿它当基座来试。我下面讲的所有操作都是基于常见工程实践补全的细节原始资料里没写透的地方我会明确说明这是我的经验补充。1. 先把运行环境和权重加载这件事理清楚很多人卡在第一步不是因为不会写代码而是环境装完发现模型加载报错或者显存直接爆掉。这一节把环境准备和权重加载的完整逻辑拆开讲包括为什么这么选版本、显存大概要多少、加载时有哪些容易忽略的参数。1.1 依赖版本的选择逻辑与常见冲突Yi-VL 的推理依赖主要围绕 transformers、torch、accelerate 和 Pillow 这几个包。我这里给一套实测能跑通的组合但更重要的是理解为什么版本要对齐。pip install torch2.1.0 torchvision0.16.0 --index-url https://download.pytorch.org/whl/cu118 pip install transformers4.35.0 accelerate0.24.1 pip install Pillow10.1.0 sentencepiece0.1.99为什么锁 transformers 的版本因为 Yi-VL 的模型代码里用到了LlavaForConditionalGeneration类似的视觉语言模型接口约定不同版本的 transformers 对多模态 processor 的字段命名和返回结构有过调整。版本太新processor 返回的pixel_values维度顺序可能和模型预期不一致表现为推理结果全是乱码或者直接 shape mismatch版本太旧又可能不认识模型 config 里的某些字段。4.35 这个区间是我试下来比较稳的。torch 和 CUDA 的对应关系也要注意。cu118 对应的是 CUDA 11.8 驱动环境如果你机器上是 CUDA 12.x 的驱动向下兼容一般没问题但反过来不行。装之前先nvidia-smi看一眼驱动支持的 CUDA 版本别盲目装。提示不要在一个已经装了其他大模型依赖的全局环境里直接叠装版本冲突排查起来非常痛苦。用 conda 或 venv 建独立环境这是省时间而不是浪费时间。1.2 权重下载与目录结构权重从模型托管平台拉下来之后目录结构要保持原样不要自己重命名文件。典型的结构是这样Yi-VL-6B/ ├── config.json ├── generation_config.json ├── tokenizer.model ├── tokenizer_config.json ├── preprocessor_config.json ├── model-00001-of-00002.safetensors ├── model-00002-of-00002.safetensors └── model.safetensors.index.jsonpreprocessor_config.json这个文件很关键里面定义了图像预处理的分辨率、归一化均值方差等参数。有些人为了省事只拷了权重和 config结果图片进去之后模型输出完全不对就是因为预处理参数丢了。加载时直接用目录路径from transformers import AutoModelForCausalLM, AutoTokenizer from PIL import Image import torch model_path ./Yi-VL-6B tokenizer AutoTokenizer.from_pretrained(model_path, trust_remote_codeTrue) model AutoModelForCausalLM.from_pretrained( model_path, torch_dtypetorch.float16, device_mapauto, trust_remote_codeTrue )trust_remote_codeTrue这个参数不能省Yi-VL 的模型定义里有自定义的前向逻辑不加会直接报找不到模型类。device_mapauto让 accelerate 自动分配显存单卡够用就全放一张卡多卡会自动切分。1.3 显存占用的估算方法6B 模型用 fp16 加载光权重就大约 12GB加上推理时的 KV cache 和图像编码的中间激活单张图推理峰值大概在 16GB 到 18GB 之间。所以 24GB 显存的卡跑 6B 推理是比较舒服的16GB 的卡会紧张需要控制输入图片分辨率和生成长度。34B 版本 fp16 权重约 68GB单卡基本放不下要么用多卡 device_map 切分要么上量化。我实测 34B 用 4bit 量化后大约 20GB 出头能跑起来但量化会带来一定的输出质量损失尤其是细粒度文字识别类任务损失比较明显。如果你的任务对精度要求高优先考虑多卡 fp16 而不是单卡量化。估算显存的粗略公式可以记一下权重显存 ≈ 参数量 × 精度字节数fp16 是 2 字节4bit 是 0.5 字节再额外留 20% 到 30% 给激活和 cache。这个公式不精确但足够你做容量规划。2. 图片推理的完整调用链路与参数调优环境通了之后下一步是把推理跑对。这一节讲清楚从图片输入到文本输出的每一步在做什么以及生成参数怎么调才能既快又准。2.1 从图片到模型输入的预处理细节模型不是直接吃原始图片的中间要经过 resize、归一化、切 patch 这一套。Yi-VL 的图像编码器对输入分辨率有固定要求预处理时会先把图片调整到指定尺寸。这里有个实操要点图片的宽高比如果和模型预期差异太大resize 会造成形变影响识别效果。我的处理习惯是先做一次等比缩放加 padding而不是直接硬 resize。比如目标分辨率是 448×448我会把原图按长边缩到 448短边不足的部分用背景色填充这样内容不变形。对于文档类图片这个细节对文字识别准确率影响很大。from PIL import Image def smart_resize(image, target448): w, h image.size scale target / max(w, h) new_w, new_h int(w * scale), int(h * scale) resized image.resize((new_w, new_h), Image.LANCZOS) canvas Image.new(RGB, (target, target), (255, 255, 255)) canvas.paste(resized, ((target - new_w) // 2, (target - new_h) // 2)) return canvas用 LANCZOS 重采样而不是默认的最近邻是因为它在缩小图片时保留的细节更多对文字和细线条更友好。这个函数不是模型强制的是我自己加的预处理层你可以按任务需要决定要不要用。2.2 对话模板与 prompt 组织方式Yi-VL 走的是对话式接口图片通过特殊的占位符嵌入到对话里。调用时一般是这样组织query 请描述这张图片里的主要内容如果有文字请一并识别出来。 image smart_resize(Image.open(test.jpg).convert(RGB)) response, history model.chat( tokenizertokenizer, queryquery, imageimage, historyNone, max_new_tokens512, temperature0.3 ) print(response)model.chat是模型自定义的方法内部会把图片编码成视觉 token 拼接到文本 token 序列前面。history传 None 表示单轮对话如果要连续追问同一张图把上一轮的 history 传回去即可但注意每轮都会重新编码图片多轮场景下开销会累积。prompt 的写法直接影响输出质量。我总结的经验是任务描述要具体输出格式要约束。比如你要做结构化抽取与其说分析这张图不如说提取图中表格的所有行每行输出为 JSON字段为名称和数值。模型对明确格式指令的遵循度明显更高。2.3 生成参数的取舍temperature、top_p 与 max_new_tokens这几个参数不是随便填的每个都对应不同的行为倾向。参数作用我的常用取值说明temperature控制随机性0.1~0.3描述、抽取类任务要低创意类可到 0.7top_p核采样阈值0.9配合 temperature 用一般不动max_new_tokens最大生成长度256~1024按任务输出长度估设太大浪费显存和时间repetition_penalty抑制重复1.05~1.1长输出时防止车轱辘话temperature 设 0 理论上最确定但部分实现里 0 会触发除零或退化成贪心我一般设 0.1 而不是 0。max_new_tokens 设太大不只是慢的问题KV cache 会随长度线性增长长输出场景下显存峰值可能比你预期高不少。做批量推理时尤其要卡住这个值。2.4 批量推理的显存与吞吐平衡单张推理跑通之后很多人想直接上 batch。这里要泼个冷水多模态模型的 batch 推理不像纯文本那么线性因为每张图的视觉 token 数量固定但文本长度不一padding 会浪费算力。我的做法是把长度相近的请求分到一组减少 padding 比例。另外视觉编码器那部分计算是每张图独立的batch 化收益有限真正能并行的是语言模型解码阶段。所以如果你的场景是大量图片各问一个问题提升吞吐更有效的办法是多进程各占一张卡而不是单卡大 batch。这个结论是我对比过两种方案之后得出的单卡 batch4 和四卡各 batch1 的总吞吐接近但后者显存更从容。3. LoRA 微调数据组织、训练配置与显存优化推理跑顺了接下来就是拿自己的数据做微调。全参数微调 6B 模型对大多数团队来说成本偏高LoRA 是更现实的选择。这一节讲数据怎么准备、LoRA 挂在哪、训练参数怎么定。3.1 微调数据的格式设计与质量把控多模态微调数据本质上是图片路径 对话的配对。我用的格式是 JSON Lines每行一条样本{image: images/0001.jpg, conversations: [{from: user, value: 这张图里的设备指示灯是什么颜色}, {from: assistant, value: 指示灯为绿色。}]}几个数据质量上的经验点都是踩过坑总结的图片路径要能稳定解析训练脚本里做一次存在性校验缺图样本直接跳过并记录不要让训练中途崩。回答要短而准多模态微调最容易犯的错是答案写得太长太发散模型学到的是一堆废话。目标任务的答案控制在 1 到 3 句格式统一。负样本和边界样本要覆盖比如图片里没有用户问的物体时答案应该是图中未发现该物体而不是硬编一个。这类样本不加模型上线后会疯狂幻觉。数据量上LoRA 微调一般几百到几千条就能看到明显效果但前提是分布要对齐你的目标场景。我试过用 500 条高质量垂类数据效果比 5000 条泛泛的通用数据好得多。3.2 LoRA 目标模块的选择LoRA 的核心是在注意力层的线性变换上挂低秩矩阵。对 Yi-VL 这类模型通常挂在语言模型主干的 q_proj、k_proj、v_proj、o_proj 上视觉编码器一般冻结不动。from peft import LoraConfig, get_peft_model lora_config LoraConfig( r8, lora_alpha16, target_modules[q_proj, k_proj, v_proj, o_proj], lora_dropout0.05, biasnone, task_typeCAUSAL_LM ) model get_peft_model(model, lora_config) model.print_trainable_parameters()为什么视觉编码器不挂 LoRA因为视觉编码器参数量相对小且预训练的视觉表征已经比较通用微调它容易过拟合且收益不明显。真正需要适配业务的是如何根据视觉特征组织语言回答这部分在语言主干里。r8 是个保守起点任务复杂可以加到 16 或 32但 r 越大显存和过拟合风险越高。lora_alpha一般设成 r 的两倍这是社区里比较通行的经验比例控制的是 LoRA 更新量相对于原权重的缩放。3.3 训练超参与显存优化组合拳训练配置上我常用的一套起点是这样的training_args TrainingArguments( output_dir./yi-vl-lora, per_device_train_batch_size1, gradient_accumulation_steps8, learning_rate2e-4, num_train_epochs3, logging_steps10, save_strategyepoch, fp16True, gradient_checkpointingTrue, optimadamw_torch, report_tonone )显存不够时的优化顺序我按效果排序先开gradient_checkpointing用时间换显存能省 30% 到 40%再降 batch 到 1 配合梯度累积然后考虑 8bit 优化器最后才是量化基座。gradient_accumulation_steps8配合 batch1等效 batch 是 8对小数据集够用。学习率 2e-4 是 LoRA 的常见量级比全参数微调高一个数量级因为 LoRA 只更新少量参数。epoch 数不要贪多多模态任务 3 到 5 轮就够再多容易把模型带偏表现为通用能力下降、回答变得模板化。注意训练时把验证集留出来每个 epoch 存一次 checkpoint最后按验证集表现选模型而不是用最后一个 epoch。我吃过这个亏最后一轮过拟合验证指标反而掉了。4. 那些文档里没写、我实际踩到的坑这一节是整篇里最私货的部分都是我在真实环境里撞出来的问题排查过程也一并写出来方便你对照复现。4.1 图片通道数导致的诡异报错有一次推理脚本在部分图片上稳定报错错误信息指向张量维度不匹配但换一张图就正常。排查了半天发现是 PNG 图片带了 alpha 通道RGBA 四通道而模型预处理预期三通道 RGB。修复很简单加载时统一convert(RGB)image Image.open(path).convert(RGB)这个坑的隐蔽性在于大部分 JPG 是三通道所以不报错只有部分 PNG 或截图类图片会触发。养成加载即转 RGB 的习惯能省掉这类随机性故障。4.2 多轮对话里图片被重复编码的性能问题前面提过多轮对话每轮都会重新编码图片。我一开始没在意直到做一个连续追问的 Demo 时发现响应越来越慢。原因是每轮 chat 调用都把图片重新过了一遍视觉编码器而视觉编码的计算量不小。解决办法有两个方向一是把图片编码结果缓存下来后续轮次复用视觉特征二是如果业务允许把多轮问题合并成一轮提问。前者需要改模型调用逻辑后者更简单。我最终选了合并提问因为我的场景里追问之间没有强依赖合并后一次输出反而更连贯。4.3 微调后通用能力下降的定位过程第一次 LoRA 微调完垂类任务准确率上去了但拿通用图片测试时发现模型描述能力明显变差回答变得生硬。排查思路是这样的先确认不是推理参数问题——用相同 temperature 对比微调前后排除采样差异。检查训练数据分布——发现我的数据里 90% 是短答案模型被带成了惜字如金的风格。混入一定比例的通用描述数据做回放比例大概 1:4通用:垂类再训一轮。调整后垂类指标基本没掉通用能力恢复了大半。这个经验说明LoRA 微调不是只喂目标任务数据就完事适当混入通用数据做正则是保住基座能力的关键。这个比例没有标准答案得按你的数据量和任务偏离程度试。4.4 生成结果截断与 EOS 处理有段时间发现模型输出经常在句子中间断掉。查下来是 max_new_tokens 设得太小输出被硬截断。但把值调大之后又出现另一个问题部分样本生成停不下来一直输出到上限。根因是模型没有正常输出结束符。处理办法是在生成后做一次后处理按句号或换行截断同时训练数据里确保每条回答都以正常结束符结尾。另外检查 tokenizer 的 eos_token 配置是否和模型一致这个不一致会导致模型不知道该在哪停。我在一次换用不同来源的 tokenizer 文件后就遇到过这个问题换回权重目录自带的 tokenizer 就好了。5. 从 Demo 到可用部署侧的几个务实建议跑通推理和微调只是第一步真要上线还得考虑服务化和稳定性。这一节聊几个部署层面的实际问题。5.1 推理服务的并发与超时设计多模态推理单次耗时通常在几百毫秒到几秒之间取决于图片大小和输出长度。做服务时请求队列要有上限超时时间要按 P99 耗时来设而不是平均值。我见过按平均耗时设超时导致高峰期大量请求被误杀的情况。并发数不要按 GPU 显存除以单请求显存来算因为峰值是波动的。保守做法是先压测出单卡稳定并发数再留 30% 余量。图片预处理解码、resize其实也吃 CPU高并发下 CPU 可能先成为瓶颈这点容易被忽略。5.2 模型版本与配置的固化上线前把模型权重、tokenizer、preprocessor 配置、推理代码版本全部固化下来打成一个不可变镜像或版本化目录。多模态模型对预处理参数敏感任何一处配置漂移都可能导致线上输出和测试环境不一致。我习惯在服务启动时打印一份配置摘要到日志出问题时第一时间能对照。5.3 效果监控的落地方式线上没法像离线那样人工看每条输出我的做法是抽样加规则双管按比例抽样人工复核同时对输出做规则检查比如空输出率、超长输出率、特定关键词命中率。这些指标异常往往先于用户投诉暴露问题。另外把输入图片的尺寸分布也监控起来突然出现大量超大图可能是上游传参出了问题会拖垮推理耗时。这套东西搭起来不复杂但能让你在模型看起来正常的时候提前发现退化。多模态模型的效果退化往往很隐蔽不像纯文本那样容易从字面看出来所以监控要更主动一些。最后分享一个我自己的使用习惯每次换模型版本或改训练数据都固定用同一批回归测试图跑一遍人工扫一眼输出。这批图覆盖文档、图表、自然场景、带文字截图几类数量不用多二三十张就够。它能帮你快速判断这次改动是变好还是变坏比看一堆指标数字直观得多。