先聊一个比较现实的问题很多同学在接触 VLMVision Language Model视觉语言模型时最先感受到的并不是模型效果有多惊艳而是“卡在部署”和“不知道怎么微调”。模型权重下载好了环境却起不来vLLM 装完了显存又不够终于跑通了推理又不知道怎样用业务数据做微调。这一篇我会以 Qwen 系列视觉语言模型的部署与微调为主线完整梳理一条“环境搭建 → 本地部署 → LoRA 微调 → 量化推理 → 应用集成”的闭环流程。本文以 Qwen2.5-VL 的社区实现思路为主要示例相关操作对 Qwen3VL 同样适用只要按实际模型版本调整路径和参数即可。内容会尽量具体到命令、代码和配置而不是只讲概念。文章适合这几类读者刚接触多模态大模型想本地跑通 VLM 的开发者。已经能跑 LLM 推理但还不熟悉视觉模型特殊处理流程的同学。手里有少量业务图片数据想用 LoRA 低成本微调 VLM 的算法工程师。准备在项目里接入“图片问答”“文档分析”等能力但还没定技术方案的人。读完这篇文章你会得到一条完整的操作主线以及一套可以反复参考的排错思路。1. VLM 与 Qwen3VL 基础认知1.1 什么是 VLM它和普通 LLM 有什么区别大语言模型LLM处理的是文本输入是一串 token。VLM 则不同它在文本之外还接收图像、视频等视觉输入。VLM 的常见做法是给模型增加一个“视觉编码器”比如 OpenCLIP 或 SigLIP 这类结构让模型能把图片切块后转换成视觉 token再和文本 token 一起送入语言模型主干进行处理。Qwen 系列的 VLM 模型正是采用了类似的整体架构但在视觉编码器、图像分辨率处理、token 压缩策略上做了大量细节优化。实际使用中VLM 能做的事情通常包括图文理解例如“这张图片里有什么对象”。文档信息抽取例如从截图、PDF 页面中提取关键字段。图表分析例如把折线图、柱状图转化为结构化文字描述。视觉问答基于图片内容回答连续多轮问题。这就是为什么 VLM 的部署和微调会比纯文本大模型更复杂它多了一条图片预处理链路而且图片分辨率、token 长度会直接影响显存占用。1.2 Qwen3VL / Qwen2.5-VL 的定位Qwen2.5-VL 是阿里云 Qwen 团队推出的视觉语言模型系列覆盖 3B、7B、32B 等规格。从 2024 年底发布后它在文档解析、图表理解、视频理解等方面表现比较均衡。Qwen3VL 则是同一体系下的后续演进版本核心思路依然是“视觉编码器 语言模型 投影层”的组合。本文后面的命令和代码主要以 Qwen2.5-VL 系列作为示例。如果你是使用 Qwen3VL只需要把模型名称替换为对应权重路径整体流程保持一致。关于具体的模型卡展示效果和评测数据建议以官方模型仓库公开信息为准不要轻信来源不明的“跑分对比”。1.3 为什么部署 VLM 比部署纯文本模型更麻烦部署 VLM 时往往会遇到下面几个额外问题图片预处理不仅涉及 resize还涉及动态分辨率切分容易和推理框架版本不匹配。视觉 token 数量远高于文本 token长图或多图场景会快速挤占显存。部分推理框架对 VLM 的支持不够稳定需要额外指定视觉相关参数。Qwen 系列模型经常更新旧版本 transformers 可能不兼容最新权重。所以说部署 VLM 不只是“下载一个模型再拉起服务”这么简单环境版本和预处理流程往往才是真正的坑点。2. 环境准备与依赖安装2.1 硬件与操作系统建议微调多模态模型最关键的资源是显存。如果你只是做推理Qwen2.5-VL-3B 在 FP16 精度下大约需要 6GB 到 8GB 显存7B 模型建议至少 12GB 到 16GB32B 模型建议 24GB 以上或者使用量化方案降低占用。如果要做 LoRA 微调显存需求会更紧张3B 模型微调建议 12GB 以上。7B 模型微调建议 24GB 以上。32B 模型微调建议依赖 4bit 量化 LoRA并准备 48GB 以上的共享显存或使用多卡。操作系统方面Linux 和 Windows 都可以但生产环境更推荐 Linux。本文的演示命令基于 Ubuntu 20.04 / 22.04使用 CUDA 11.8 或 12.1 环境。你的机器实际 CUDA 版本不同时需要把对应命令里的版本号替换掉。2.2 Python 环境与 PyTorch 安装先用 conda 创建独立环境避免影响机器上其他项目。conda create -n qwen-vl python3.10 -y conda activate qwen-vl安装 PyTorch 时建议根据你的 CUDA 版本到 PyTorch 官网选择对应命令。这里以 CUDA 12.1 为例pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121安装完成后可以用一段简单代码验证 GPU 是否可用import torch print(torch.__version__) print(torch.cuda.is_available()) print(torch.cuda.get_device_name(0))如果torch.cuda.is_available()返回False说明 PyTorch 与 CUDA 驱动不匹配需要先排查驱动版本而不是继续往下走。2.3 安装 transformers、qwen-vl-utils 等依赖Qwen 系列 VLM 的官方推理代码中通常会用到qwen-vl-utils这个工具库里面封装了图像和视频的预处理逻辑。同时还需要transformers、accelerate等基础库。pip install transformers accelerate qwen-vl-utils安装版本时不要盲目追求最新版因为 transformers 版本过高或过低都可能导致模型权重加载报错。可以先记录一下安装的版本pip show transformers accelerate如果后续出现KeyError: qwen2_vl或者Unsupported model type这类错误优先检查是不是 transformers 版本太旧然后升级到支持 Qwen2.5-VL 架构的版本。2.4 推荐工具LlamaFactory微调部分本文使用 LlamaFactory 作为主要工具。LlamaFactory 是一个开源的大模型微调框架支持多种模型架构、LoRA / QLoRA / 全量微调等训练方式。它的优势在于把训练流程封装得比较完整配置文件写好后一条命令就能启动训练。git clone https://github.com/hiyouga/LLaMA-Factory.git cd LLaMA-Factory pip install -e .LlamaFactory 同时支持文本模型和视觉模型的 LoRA 微调对 Qwen-VL 系列的支持也比较好。如果你想自己写训练脚本也可以参考 LlamaFactory 的源码但不建议新手直接手写 Trainer因为多模态数据的 collator 处理很容易出错。3. Qwen3VL 本地部署实战3.1 模型下载方式模型权重推荐从 Hugging Face 或 ModelScope 下载。国内网络环境下ModelScope 通常更稳定。Hugging Face 下载示例pip install huggingface_hub huggingface-cli download Qwen/Qwen2.5-VL-7B-Instruct --local-dir ./models/Qwen2.5-VL-7B-InstructModelScope 下载示例pip install modelscope modelscope download --model Qwen/Qwen2.5-VL-7B-Instruct --local_dir ./models/Qwen2.5-VL-7B-Instruct如果显存比较紧张可以先拿 3B 模型练手modelscope download --model Qwen/Qwen2.5-VL-3B-Instruct --local_dir ./models/Qwen2.5-VL-3B-Instruct3.2 用 Transformers 实现基础推理模型下载完成后先用 Transformers 写一个最基础的单轮图片问答脚本验证环境是否正常。# 文件路径test_infer.py from transformers import Qwen2_5_VLForConditionalGeneration, AutoProcessor from qwen_vl_utils import process_vision_info import torch model_path ./models/Qwen2.5-VL-7B-Instruct model Qwen2_5_VLForConditionalGeneration.from_pretrained( model_path, torch_dtypetorch.bfloat16, device_mapauto ) processor AutoProcessor.from_pretrained(model_path, min_pixels256 * 28 * 28, max_pixels1280 * 28 * 28) messages [ { role: user, content: [ {type: image, image: ./test.jpg}, {type: text, text: 请描述这张图片里的主要内容。}, ], } ] text processor.apply_chat_template(messages, tokenizeFalse, add_generation_promptTrue) image_inputs, video_inputs process_vision_info(messages) inputs processor( text[text], imagesimage_inputs, videosvideo_inputs, paddingTrue, return_tensorspt, ).to(model.device) with torch.no_grad(): generated_ids model.generate(**inputs, max_new_tokens512) generated_ids_trimmed [ out_ids[len(in_ids):] for in_ids, out_ids in zip(inputs.input_ids, generated_ids) ] output_text processor.batch_decode(generated_ids_trimmed, skip_special_tokensTrue) print(output_text[0])代码说明min_pixels和max_pixels控制图片输入的最小和最大像素数量数值越大图片细节越多但视觉 token 也越多显存占用越高。process_vision_info负责从 messages 中提取图片和视频数据是 Qwen 官方推荐的方式。device_mapauto让模型自动分配 GPU 和 CPU省心但在纯 CPU 环境会很慢。运行python test_infer.py如果输出一段通顺的中文图片描述说明基础部署成功。3.3 用 vLLM 部署 OpenAI 兼容服务本地单脚本推理适合调试但实际项目接入时更推荐用 vLLM 启动一个 OpenAI 兼容的服务。安装 vLLMpip install vllm启动服务vllm serve ./models/Qwen2.5-VL-7B-Instruct \ --served-model-name qwen-vl \ --host 0.0.0.0 \ --port 8000 \ --dtype bfloat16 \ --max-model-len 8192 \ --gpu-memory-utilization 0.9参数含义--served-model-name对外暴露的模型名称调用方用这个名字请求。--max-model-len最大序列长度视觉 token 多时建议调大但也会增加显存。--gpu-memory-utilization允许 vLLM 使用的显存比例可以按机器情况调整。客户端调用示例# 文件路径vllm_client.py from openai import OpenAI client OpenAI(base_urlhttp://localhost:8000/v1, api_keyEMPTY) response client.chat.completions.create( modelqwen-vl, messages[ { role: user, content: [ {type: image_url, image_url: {url: http://localhost:8000/files/test.jpg}}, {type: text, text: 图片里的按钮在什么位置}, ], } ], max_tokens256, ) print(response.choices[0].message.content)需要注意OpenAI 接口通过 image_url 传图片时vLLM 需要能够访问到这个 URL。如果是本地文件需要先下载到客户端通过base64方式传入或者用内网 HTTP 服务托管图片。3.4 Ollama 本地部署的取舍Ollama 提供了非常简单的本地大模型部署方式也有越来越多的人用它跑纯文本模型。但 VLM 模型在 Ollama 中的支持情况不如 vLLM 和 Transformers 完整尤其是 Qwen 系列较新的视觉模型可能无法加载出图能力或需要等待社区适配。如果你的场景只是为了本地试用不要求高并发可以尝试 Ollama如果是项目集成或性能敏感场景优先选择 vLLM 或 Transformers 服务化方案。4. LoRA 微调原理与数据准备4.1 LoRA 到底是什么LoRALow-Rank Adaptation低秩适配是一种参数高效微调方法。它的核心思想是预训练模型在适配新任务时权重更新量往往处于一个低秩空间因此不需要更新全部参数只需要学习两个低秩矩阵的乘积。假设原始权重矩阵是WLoRA 会新增A和B两个小矩阵前向计算时变成y Wx BAx其中B和A的维度远小于W训练时只更新A和B。这样做的好处是训练参数量大幅减少例如 7B 模型可能只需要训练 1% 以下的参数。显存占用显著下降。每个业务场景可以微调出一套轻量 LoRA 权重快速切换。VLM 的 LoRA 微调通常可以选择把 LoRA 加在语言模型部分也可以同时加在视觉编码器部分。对于文档理解类任务视觉编码器上的 LoRA 往往能帮助模型更好地适应特定版式对于纯文本推理能力的调整语言模型部分的 LoRA 更关键。4.2 数据格式选择微调数据质量比数据量更重要。Qwen 系列模型在微调时官方推荐使用 ChatML 格式。下面是一个 VLM 多轮对话的训练样本示例{ messages: [ { role: system, content: [ {type: text, text: 你是一个专业的票据信息抽取助手。} ] }, { role: user, content: [ {type: image, image: train/001.jpg}, {type: text, text: 请提取发票号码、开票日期和价税合计。} ] }, { role: assistant, content: [ {type: text, text: 发票号码12345678开票日期2025年1月1日价税合计人民币1000.00元。} ] } ] }如果使用 LlamaFactory 训练数据文件一般放在data目录下并在dataset_info.json中注册。对于 VLM 数据LlamaFactory 的格式要求比较清晰可以理解成上面这种messages里嵌套content数组的结构。4.3 图片路径处理图片路径建议统一放在同一目录下避免训练时出现FileNotFoundError。目录结构示例data/ images/ 001.jpg 002.jpg ... train_data.json dataset_info.json如果数据量不大比如只有几百张图图片相对路径可以直接写在 JSON 里。LlamaFactory 会根据配置项自动拼接图片路径前缀。4.4 数据规模建议很多人关心“只有几十条数据能不能微调”。如果任务形式比较简单比如固定版式的表格字段抽取几百条高质量数据就能看到明显效果如果是开放式的复杂推理任务数据量需要更大。关键在于样本多样性要足够不要 500 条数据全是同一个版式。答案必须准确错误标注会被模型学习并放大。训练集和验证集要分开避免只看训练 loss 而忽视泛化能力。5. 基于 LlamaFactory 的 LoRA 微调实战5.1 注册数据集修改LLaMA-Factory/data/dataset_info.json新增一个 VLM 数据集的描述。{ qwen_vl_train: { file_name: train_data.json, formatting: sharegpt, columns: { messages: messages, images: images }, tags: { role_tag: role, content_tag: content, user_tag: user, assistant_tag: assistant } } }不同版本的 LlamaFactory 对 dataset_info 的字段定义可能有差异如果启动时报字段解析错误可以查看当前版本自带的dataset_info.json示例来对齐。5.2 准备训练 YAML 配置以 Qwen2.5-VL-3B-Instruct 为例LoRA 微调 YAML 大致如下model_name_or_path: ./models/Qwen2.5-VL-3B-Instruct template: qwen_vl stage: sft finetuning_type: lora lora_rank: 64 lora_alpha: 128 lora_target: all dataset: qwen_vl_train cutoff_len: 4096 learning_rate: 1.0e-4 num_train_epochs: 3 per_device_train_batch_size: 1 gradient_accumulation_steps: 8 lr_scheduler_type: cosine warmup_ratio: 0.05 bf16: true loraplus_lr_ratio: 1.0 logging_steps: 5 save_steps: 200 output_dir: outputs/qwen_vl_lora关键参数解释lora_rank低秩矩阵的秩。数值越大可学习参数量和表达力越强但显存也会增加。lora_alpha缩放系数一般设置为 rank 的 1 到 2 倍例如 rank 为 64alpha 可以设 128。lora_target这里设为all表示在模型包含的线性层上都挂 LoRA。cutoff_len最大序列长度。VLM 的视觉 token 较多建议不要低于 2048。per_device_train_batch_sizeVLM 训练时图片显存占用很大通常从 1 开始。gradient_accumulation_steps通过累积步数模拟更大的 batch size。5.3 执行训练在 LlamaFactory 根目录执行llamafactory-cli train configs/qwen_vl_lora.yaml运行后如果看到类似下面的日志说明训练已进入正轨{loss: 0.82, learning_rate: 0.0001, epoch: 0.1} {loss: 0.46, learning_rate: 0.00008, epoch: 0.5}训练时长取决于 GPU 型号和数据集大小。3B 模型在单张 RTX 4090 上几百条图片数据做几个 epoch通常几十分钟到两三个小时可以完成。5.4 LoRA 权重合并与导出LoRA 训练完成后产物是一个轻量权重目录。如果要独立部署或使用 vLLM 加载需要先合并 LoRA 权重。llamafactory-cli export \ --model_name_or_path ./models/Qwen2.5-VL-3B-Instruct \ --adapter_name_or_path ./outputs/qwen_vl_lora \ --template qwen_vl \ --finetuning_type lora \ --export_dir ./models/Qwen2.5-VL-3B-Instruct-Custom \ --export_size 4合并时建议先确认 adapter 路径下存在adapter_config.json和 adapter 权重文件。合并完成后可以用和基础模型相同的推理脚本加载导出模型。5.5 微调效果验证用微调后的模型重新跑测试图片对比答案是否发生了符合预期的变化。建议准备 5 到 10 张训练时没见过的图片从答案准确率、格式规范性两个维度评估。如果效果不如预期优先检查训练数据是否有标注错误。学习率是否设置过高导致灾难性遗忘。是否过拟合训练集 loss 低但验证集效果差。图片预处理是否与训练时一致。6. 量化推理与部署优化6.1 为什么要量化量化可以降低模型显存占用同时加快推理速度。多模态大模型部署到 8GB、12GB 显存的环境时量化几乎是必经之路。Qwen 系列 VLM 常见的量化方案包括GPTQ对权重进行低比特量化需要离线量化。AWQ按激活值敏感度选择保留通道精度损失通常较小。bitsandbytes方便与 Transformers 结合支持 4bit 加载。6.2 使用 AutoGPTQ 离线量化先安装必要依赖pip install auto-gptq optimum然后执行量化脚本# 文件路径quantize_gptq.py from transformers import AutoModelForCausalLM, AutoTokenizer, GPTQConfig model_id ./models/Qwen2.5-VL-3B-Instruct-Custom quant_path ./models/Qwen2.5-VL-3B-Instruct-GPTQ-Int4 tokenizer AutoTokenizer.from_pretrained(model_id) quantization_config GPTQConfig( bits4, group_size128, desc_actTrue, dataset[请介绍一下你自己。, 什么是多模态模型], ) model AutoModelForCausalLM.from_pretrained( model_id, quantization_configquantization_config, device_mapauto, trust_remote_codeTrue, ) model.save_pretrained(quant_path) tokenizer.save_pretrained(quant_path)量化后加载推理model Qwen2_5_VLForConditionalGeneration.from_pretrained( quant_path, device_mapauto, torch_dtypetorch.float16 )需要注意GPTQ 量化并不是所有模型结构都能完美支持而且 GPU 太老时可能出现算子不兼容。遇到问题时可以改用 AutoAWQ 或 bitsandbytes 方案。6.3 vLLM 推理优化建议如果要在 vLLM 中部署量化模型或合并后的模型建议使用与训练一致的trust_remote_code参数。把--max-model-len控制在 8192 以内避免显存爆破。高并发场景下--gpu-memory-utilization不要设满预留 5% 到 10% 给运行时开销。开启--enable-auto-tool-choice这类功能前先确认模型本身是否支持工具调用。6.4 显存不够时的降级方案当单卡显存不足时可以从几个方向降级换更小参数的模型3B 优先于 7B。降低输入图片的最大像素从1280 * 28 * 28降到1024 * 28 * 28。使用 4bit 量化加载模型。将模型切分到多张卡或在 CPU 与 GPU 间分配部分层。7. 实战应用接入一个图片信息抽取任务7.1 需求描述假设业务场景是从一批商品宣传图中抽取“商品名称”和“促销价格”统一整理成结构化数据。这个任务非常适合 VLM 微调因为图片版式相对固定。抽取字段有限输出格式可以约定。人工标注成本可控。7.2 服务端快速实现启动 vLLM 服务后后端可以写一个简单的 Flask 接口接收图片 base64 或 URL调用 vLLM 生成结构化结果。# 文件路径app.py from flask import Flask, request, jsonify from openai import OpenAI import base64 app Flask(__name__) client OpenAI(base_urlhttp://localhost:8000/v1, api_keyEMPTY) app.route(/extract, methods[POST]) def extract(): data request.get_json() image_base64 data.get(image_base64) image_bytes base64.b64decode(image_base64) image_url data:image/jpeg;base64, image_base64 response client.chat.completions.create( modelqwen-vl, messages[ { role: user, content: [ {type: image_url, image_url: {url: image_url}}, {type: text, text: 请提取商品名称和促销价格并输出 JSON 格式。}, ], } ], max_tokens256, ) content response.choices[0].message.content return jsonify({result: content}) if __name__ __main__: app.run(host0.0.0.0, port9000)生产环境中不要把 base64 字符串塞进日志也不要直接信任模型输出的 JSON最好用json.loads再包一层容错解析。8. 常见问题与排查清单8.1 高频报错对照表问题现象常见原因解决思路KeyError: qwen2_vltransformers 版本过旧不认识模型结构升级 transformers按官方要求对齐版本显存不足 OOM图片最大像素设置过高或并发请求过多降低 max_pixels减小并发数使用量化模型模型输出乱码模板或 chat template 使用错误确保使用processor.apply_chat_template而不是手写 prompt图片加载失败图片路径错误或格式不支持检查路径转成 jpg / png 格式用 PIL 打开验证LoRA 训练后模型效果无变化数据格式错、训练步数太少或 LoRA 没挂到正确层检查 dataset 注册增加训练步数确认 adapter 权重已加载vLLM 启动时报trust_remote_code错误某些模型实现需要动态加载代码启动命令加--trust-remote-code8.2 排查步骤建议遇到问题时按下面顺序排查可以节省很多时间先复现最小案例例如加载模型后输出一句简短文本。检查版本pip list | grep torch、pip list | grep transformers。检查 GPU 状态nvidia-smi看显存和占用率。查看日志中的异常堆栈优先搜索第一处红色报错。用 CPU 模式跑一遍小数据判断是环境问题还是数据问题。到官方 GitHub Issue 或模型仓库讨论区搜索相同报错。8.3 一个典型 OOM 的现场假设你启动 vLLM 后报错CUDA out of memory. Tried to allocate 512.00 MiB排查思路先用nvidia-smi确认是否已有其他进程占满显存。检查 vLLM 的--gpu-memory-utilization如果是 0.95 以上尝试降到 0.85。检查请求中的图片是否过大把max_pixels降低。如果仍然 OOM换 3B 模型或使用 4bit 量化。9. 最佳实践与工程建议9.1 数据管理微调数据本身就是资产。建议把原始图片、标注 JSON、脚本和最终配置文件都纳入版本管理。不要只保存一个“整理好的训练集”因为后续你想调整数据清洗策略时会后悔没有保留中间过程。标注工具方面小规模数据可以用开源标注工具或直接按 JSON 格式手工整理。数据量较大时可以考虑先让模型做一轮预标注再由人工修正能明显提升标注效率。9.2 微调参数与过拟合控制多模态模型参数量大训练数据少时很容易过拟合。一个比较稳妥的策略是先固定好验证集训练过程中持续观察验证集 loss。LoRA rank 从 32 到 64 起步不要一上来就设 128。学习率以 1e-4 为基准根据 loss 波动上下调整。epoch 控制在 2 到 5 之间如果 1 个 epoch 后验证集效果就下降说明数据量不足或模型容量过大。9.3 生产环境部署生产环境部署 VLM 时有几个容易被忽略的细节模型文件比较大建议放在高速磁盘上避免每次启动都重新从网络下载或从慢盘加载。服务启动前先做一次“冒烟测试”用一张固定测试图片验证模型是否正常。监控项不仅包括 CPU、内存、显存还包括请求平均延迟、首 token 延迟和图片预处理耗时。对模型输出要做安全过滤避免生成违反合规的内容。如果业务对响应时间敏感不要走在线实时 LoRA 切换而是提前合并 LoRA 权重并启动独立服务。9.4 安全边界在处理图片内容时要确认你拥有图片的使用和分发权限。涉及用户上传图片时不能直接把图片路径打印到日志也不能把隐私图片用于未经授权的模型训练。应当在数据接入层完成脱敏和合规审批后再进入训练流程。10. 总结与下一步学习方向这篇文章从 VLM 的基础概念开始走完了 Qwen 系列 VLM 的部署、推理、LoRA 微调、量化导出和接口接入全流程。你可以在自己机器上按顺序操作一遍建议先选择 3B 模型跑通全链路再根据业务需要切换到 7B 或更大规模的模型。下一步可以从这几个方向继续深入学习视觉 token 的生成方式和成本控制。尝试在 LlamaFactory 中切换finetuning_type为qwen_vl专用训练策略探索视觉编码器微调的影响。阅读 Qwen 系列官方技术报告理解动态分辨率切分和 token 压缩策略的取舍。在多卡环境下尝试分布式微调提升大批量数据训练效率。研究模型评测方法给微调后的 VLM 建立一套自动化评估集避免每次靠肉眼判断效果。实践是最好的学习方式。建议你准备 100 张左右业务图片整理成标准格式先跑一次微调再对比微调前后的模型输出差异。只有亲手完成一次完整闭环才算真正掌握 VLM 的部署与微调方法。如果这篇文章对你有所帮助可以收藏备用也欢迎留言交流你在本地部署或微调过程中遇到的问题。 Qwen视觉语言模型部署与LoRA微调实战指南
先聊一个比较现实的问题很多同学在接触 VLMVision Language Model视觉语言模型时最先感受到的并不是模型效果有多惊艳而是“卡在部署”和“不知道怎么微调”。模型权重下载好了环境却起不来vLLM 装完了显存又不够终于跑通了推理又不知道怎样用业务数据做微调。这一篇我会以 Qwen 系列视觉语言模型的部署与微调为主线完整梳理一条“环境搭建 → 本地部署 → LoRA 微调 → 量化推理 → 应用集成”的闭环流程。本文以 Qwen2.5-VL 的社区实现思路为主要示例相关操作对 Qwen3VL 同样适用只要按实际模型版本调整路径和参数即可。内容会尽量具体到命令、代码和配置而不是只讲概念。文章适合这几类读者刚接触多模态大模型想本地跑通 VLM 的开发者。已经能跑 LLM 推理但还不熟悉视觉模型特殊处理流程的同学。手里有少量业务图片数据想用 LoRA 低成本微调 VLM 的算法工程师。准备在项目里接入“图片问答”“文档分析”等能力但还没定技术方案的人。读完这篇文章你会得到一条完整的操作主线以及一套可以反复参考的排错思路。1. VLM 与 Qwen3VL 基础认知1.1 什么是 VLM它和普通 LLM 有什么区别大语言模型LLM处理的是文本输入是一串 token。VLM 则不同它在文本之外还接收图像、视频等视觉输入。VLM 的常见做法是给模型增加一个“视觉编码器”比如 OpenCLIP 或 SigLIP 这类结构让模型能把图片切块后转换成视觉 token再和文本 token 一起送入语言模型主干进行处理。Qwen 系列的 VLM 模型正是采用了类似的整体架构但在视觉编码器、图像分辨率处理、token 压缩策略上做了大量细节优化。实际使用中VLM 能做的事情通常包括图文理解例如“这张图片里有什么对象”。文档信息抽取例如从截图、PDF 页面中提取关键字段。图表分析例如把折线图、柱状图转化为结构化文字描述。视觉问答基于图片内容回答连续多轮问题。这就是为什么 VLM 的部署和微调会比纯文本大模型更复杂它多了一条图片预处理链路而且图片分辨率、token 长度会直接影响显存占用。1.2 Qwen3VL / Qwen2.5-VL 的定位Qwen2.5-VL 是阿里云 Qwen 团队推出的视觉语言模型系列覆盖 3B、7B、32B 等规格。从 2024 年底发布后它在文档解析、图表理解、视频理解等方面表现比较均衡。Qwen3VL 则是同一体系下的后续演进版本核心思路依然是“视觉编码器 语言模型 投影层”的组合。本文后面的命令和代码主要以 Qwen2.5-VL 系列作为示例。如果你是使用 Qwen3VL只需要把模型名称替换为对应权重路径整体流程保持一致。关于具体的模型卡展示效果和评测数据建议以官方模型仓库公开信息为准不要轻信来源不明的“跑分对比”。1.3 为什么部署 VLM 比部署纯文本模型更麻烦部署 VLM 时往往会遇到下面几个额外问题图片预处理不仅涉及 resize还涉及动态分辨率切分容易和推理框架版本不匹配。视觉 token 数量远高于文本 token长图或多图场景会快速挤占显存。部分推理框架对 VLM 的支持不够稳定需要额外指定视觉相关参数。Qwen 系列模型经常更新旧版本 transformers 可能不兼容最新权重。所以说部署 VLM 不只是“下载一个模型再拉起服务”这么简单环境版本和预处理流程往往才是真正的坑点。2. 环境准备与依赖安装2.1 硬件与操作系统建议微调多模态模型最关键的资源是显存。如果你只是做推理Qwen2.5-VL-3B 在 FP16 精度下大约需要 6GB 到 8GB 显存7B 模型建议至少 12GB 到 16GB32B 模型建议 24GB 以上或者使用量化方案降低占用。如果要做 LoRA 微调显存需求会更紧张3B 模型微调建议 12GB 以上。7B 模型微调建议 24GB 以上。32B 模型微调建议依赖 4bit 量化 LoRA并准备 48GB 以上的共享显存或使用多卡。操作系统方面Linux 和 Windows 都可以但生产环境更推荐 Linux。本文的演示命令基于 Ubuntu 20.04 / 22.04使用 CUDA 11.8 或 12.1 环境。你的机器实际 CUDA 版本不同时需要把对应命令里的版本号替换掉。2.2 Python 环境与 PyTorch 安装先用 conda 创建独立环境避免影响机器上其他项目。conda create -n qwen-vl python3.10 -y conda activate qwen-vl安装 PyTorch 时建议根据你的 CUDA 版本到 PyTorch 官网选择对应命令。这里以 CUDA 12.1 为例pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121安装完成后可以用一段简单代码验证 GPU 是否可用import torch print(torch.__version__) print(torch.cuda.is_available()) print(torch.cuda.get_device_name(0))如果torch.cuda.is_available()返回False说明 PyTorch 与 CUDA 驱动不匹配需要先排查驱动版本而不是继续往下走。2.3 安装 transformers、qwen-vl-utils 等依赖Qwen 系列 VLM 的官方推理代码中通常会用到qwen-vl-utils这个工具库里面封装了图像和视频的预处理逻辑。同时还需要transformers、accelerate等基础库。pip install transformers accelerate qwen-vl-utils安装版本时不要盲目追求最新版因为 transformers 版本过高或过低都可能导致模型权重加载报错。可以先记录一下安装的版本pip show transformers accelerate如果后续出现KeyError: qwen2_vl或者Unsupported model type这类错误优先检查是不是 transformers 版本太旧然后升级到支持 Qwen2.5-VL 架构的版本。2.4 推荐工具LlamaFactory微调部分本文使用 LlamaFactory 作为主要工具。LlamaFactory 是一个开源的大模型微调框架支持多种模型架构、LoRA / QLoRA / 全量微调等训练方式。它的优势在于把训练流程封装得比较完整配置文件写好后一条命令就能启动训练。git clone https://github.com/hiyouga/LLaMA-Factory.git cd LLaMA-Factory pip install -e .LlamaFactory 同时支持文本模型和视觉模型的 LoRA 微调对 Qwen-VL 系列的支持也比较好。如果你想自己写训练脚本也可以参考 LlamaFactory 的源码但不建议新手直接手写 Trainer因为多模态数据的 collator 处理很容易出错。3. Qwen3VL 本地部署实战3.1 模型下载方式模型权重推荐从 Hugging Face 或 ModelScope 下载。国内网络环境下ModelScope 通常更稳定。Hugging Face 下载示例pip install huggingface_hub huggingface-cli download Qwen/Qwen2.5-VL-7B-Instruct --local-dir ./models/Qwen2.5-VL-7B-InstructModelScope 下载示例pip install modelscope modelscope download --model Qwen/Qwen2.5-VL-7B-Instruct --local_dir ./models/Qwen2.5-VL-7B-Instruct如果显存比较紧张可以先拿 3B 模型练手modelscope download --model Qwen/Qwen2.5-VL-3B-Instruct --local_dir ./models/Qwen2.5-VL-3B-Instruct3.2 用 Transformers 实现基础推理模型下载完成后先用 Transformers 写一个最基础的单轮图片问答脚本验证环境是否正常。# 文件路径test_infer.py from transformers import Qwen2_5_VLForConditionalGeneration, AutoProcessor from qwen_vl_utils import process_vision_info import torch model_path ./models/Qwen2.5-VL-7B-Instruct model Qwen2_5_VLForConditionalGeneration.from_pretrained( model_path, torch_dtypetorch.bfloat16, device_mapauto ) processor AutoProcessor.from_pretrained(model_path, min_pixels256 * 28 * 28, max_pixels1280 * 28 * 28) messages [ { role: user, content: [ {type: image, image: ./test.jpg}, {type: text, text: 请描述这张图片里的主要内容。}, ], } ] text processor.apply_chat_template(messages, tokenizeFalse, add_generation_promptTrue) image_inputs, video_inputs process_vision_info(messages) inputs processor( text[text], imagesimage_inputs, videosvideo_inputs, paddingTrue, return_tensorspt, ).to(model.device) with torch.no_grad(): generated_ids model.generate(**inputs, max_new_tokens512) generated_ids_trimmed [ out_ids[len(in_ids):] for in_ids, out_ids in zip(inputs.input_ids, generated_ids) ] output_text processor.batch_decode(generated_ids_trimmed, skip_special_tokensTrue) print(output_text[0])代码说明min_pixels和max_pixels控制图片输入的最小和最大像素数量数值越大图片细节越多但视觉 token 也越多显存占用越高。process_vision_info负责从 messages 中提取图片和视频数据是 Qwen 官方推荐的方式。device_mapauto让模型自动分配 GPU 和 CPU省心但在纯 CPU 环境会很慢。运行python test_infer.py如果输出一段通顺的中文图片描述说明基础部署成功。3.3 用 vLLM 部署 OpenAI 兼容服务本地单脚本推理适合调试但实际项目接入时更推荐用 vLLM 启动一个 OpenAI 兼容的服务。安装 vLLMpip install vllm启动服务vllm serve ./models/Qwen2.5-VL-7B-Instruct \ --served-model-name qwen-vl \ --host 0.0.0.0 \ --port 8000 \ --dtype bfloat16 \ --max-model-len 8192 \ --gpu-memory-utilization 0.9参数含义--served-model-name对外暴露的模型名称调用方用这个名字请求。--max-model-len最大序列长度视觉 token 多时建议调大但也会增加显存。--gpu-memory-utilization允许 vLLM 使用的显存比例可以按机器情况调整。客户端调用示例# 文件路径vllm_client.py from openai import OpenAI client OpenAI(base_urlhttp://localhost:8000/v1, api_keyEMPTY) response client.chat.completions.create( modelqwen-vl, messages[ { role: user, content: [ {type: image_url, image_url: {url: http://localhost:8000/files/test.jpg}}, {type: text, text: 图片里的按钮在什么位置}, ], } ], max_tokens256, ) print(response.choices[0].message.content)需要注意OpenAI 接口通过 image_url 传图片时vLLM 需要能够访问到这个 URL。如果是本地文件需要先下载到客户端通过base64方式传入或者用内网 HTTP 服务托管图片。3.4 Ollama 本地部署的取舍Ollama 提供了非常简单的本地大模型部署方式也有越来越多的人用它跑纯文本模型。但 VLM 模型在 Ollama 中的支持情况不如 vLLM 和 Transformers 完整尤其是 Qwen 系列较新的视觉模型可能无法加载出图能力或需要等待社区适配。如果你的场景只是为了本地试用不要求高并发可以尝试 Ollama如果是项目集成或性能敏感场景优先选择 vLLM 或 Transformers 服务化方案。4. LoRA 微调原理与数据准备4.1 LoRA 到底是什么LoRALow-Rank Adaptation低秩适配是一种参数高效微调方法。它的核心思想是预训练模型在适配新任务时权重更新量往往处于一个低秩空间因此不需要更新全部参数只需要学习两个低秩矩阵的乘积。假设原始权重矩阵是WLoRA 会新增A和B两个小矩阵前向计算时变成y Wx BAx其中B和A的维度远小于W训练时只更新A和B。这样做的好处是训练参数量大幅减少例如 7B 模型可能只需要训练 1% 以下的参数。显存占用显著下降。每个业务场景可以微调出一套轻量 LoRA 权重快速切换。VLM 的 LoRA 微调通常可以选择把 LoRA 加在语言模型部分也可以同时加在视觉编码器部分。对于文档理解类任务视觉编码器上的 LoRA 往往能帮助模型更好地适应特定版式对于纯文本推理能力的调整语言模型部分的 LoRA 更关键。4.2 数据格式选择微调数据质量比数据量更重要。Qwen 系列模型在微调时官方推荐使用 ChatML 格式。下面是一个 VLM 多轮对话的训练样本示例{ messages: [ { role: system, content: [ {type: text, text: 你是一个专业的票据信息抽取助手。} ] }, { role: user, content: [ {type: image, image: train/001.jpg}, {type: text, text: 请提取发票号码、开票日期和价税合计。} ] }, { role: assistant, content: [ {type: text, text: 发票号码12345678开票日期2025年1月1日价税合计人民币1000.00元。} ] } ] }如果使用 LlamaFactory 训练数据文件一般放在data目录下并在dataset_info.json中注册。对于 VLM 数据LlamaFactory 的格式要求比较清晰可以理解成上面这种messages里嵌套content数组的结构。4.3 图片路径处理图片路径建议统一放在同一目录下避免训练时出现FileNotFoundError。目录结构示例data/ images/ 001.jpg 002.jpg ... train_data.json dataset_info.json如果数据量不大比如只有几百张图图片相对路径可以直接写在 JSON 里。LlamaFactory 会根据配置项自动拼接图片路径前缀。4.4 数据规模建议很多人关心“只有几十条数据能不能微调”。如果任务形式比较简单比如固定版式的表格字段抽取几百条高质量数据就能看到明显效果如果是开放式的复杂推理任务数据量需要更大。关键在于样本多样性要足够不要 500 条数据全是同一个版式。答案必须准确错误标注会被模型学习并放大。训练集和验证集要分开避免只看训练 loss 而忽视泛化能力。5. 基于 LlamaFactory 的 LoRA 微调实战5.1 注册数据集修改LLaMA-Factory/data/dataset_info.json新增一个 VLM 数据集的描述。{ qwen_vl_train: { file_name: train_data.json, formatting: sharegpt, columns: { messages: messages, images: images }, tags: { role_tag: role, content_tag: content, user_tag: user, assistant_tag: assistant } } }不同版本的 LlamaFactory 对 dataset_info 的字段定义可能有差异如果启动时报字段解析错误可以查看当前版本自带的dataset_info.json示例来对齐。5.2 准备训练 YAML 配置以 Qwen2.5-VL-3B-Instruct 为例LoRA 微调 YAML 大致如下model_name_or_path: ./models/Qwen2.5-VL-3B-Instruct template: qwen_vl stage: sft finetuning_type: lora lora_rank: 64 lora_alpha: 128 lora_target: all dataset: qwen_vl_train cutoff_len: 4096 learning_rate: 1.0e-4 num_train_epochs: 3 per_device_train_batch_size: 1 gradient_accumulation_steps: 8 lr_scheduler_type: cosine warmup_ratio: 0.05 bf16: true loraplus_lr_ratio: 1.0 logging_steps: 5 save_steps: 200 output_dir: outputs/qwen_vl_lora关键参数解释lora_rank低秩矩阵的秩。数值越大可学习参数量和表达力越强但显存也会增加。lora_alpha缩放系数一般设置为 rank 的 1 到 2 倍例如 rank 为 64alpha 可以设 128。lora_target这里设为all表示在模型包含的线性层上都挂 LoRA。cutoff_len最大序列长度。VLM 的视觉 token 较多建议不要低于 2048。per_device_train_batch_sizeVLM 训练时图片显存占用很大通常从 1 开始。gradient_accumulation_steps通过累积步数模拟更大的 batch size。5.3 执行训练在 LlamaFactory 根目录执行llamafactory-cli train configs/qwen_vl_lora.yaml运行后如果看到类似下面的日志说明训练已进入正轨{loss: 0.82, learning_rate: 0.0001, epoch: 0.1} {loss: 0.46, learning_rate: 0.00008, epoch: 0.5}训练时长取决于 GPU 型号和数据集大小。3B 模型在单张 RTX 4090 上几百条图片数据做几个 epoch通常几十分钟到两三个小时可以完成。5.4 LoRA 权重合并与导出LoRA 训练完成后产物是一个轻量权重目录。如果要独立部署或使用 vLLM 加载需要先合并 LoRA 权重。llamafactory-cli export \ --model_name_or_path ./models/Qwen2.5-VL-3B-Instruct \ --adapter_name_or_path ./outputs/qwen_vl_lora \ --template qwen_vl \ --finetuning_type lora \ --export_dir ./models/Qwen2.5-VL-3B-Instruct-Custom \ --export_size 4合并时建议先确认 adapter 路径下存在adapter_config.json和 adapter 权重文件。合并完成后可以用和基础模型相同的推理脚本加载导出模型。5.5 微调效果验证用微调后的模型重新跑测试图片对比答案是否发生了符合预期的变化。建议准备 5 到 10 张训练时没见过的图片从答案准确率、格式规范性两个维度评估。如果效果不如预期优先检查训练数据是否有标注错误。学习率是否设置过高导致灾难性遗忘。是否过拟合训练集 loss 低但验证集效果差。图片预处理是否与训练时一致。6. 量化推理与部署优化6.1 为什么要量化量化可以降低模型显存占用同时加快推理速度。多模态大模型部署到 8GB、12GB 显存的环境时量化几乎是必经之路。Qwen 系列 VLM 常见的量化方案包括GPTQ对权重进行低比特量化需要离线量化。AWQ按激活值敏感度选择保留通道精度损失通常较小。bitsandbytes方便与 Transformers 结合支持 4bit 加载。6.2 使用 AutoGPTQ 离线量化先安装必要依赖pip install auto-gptq optimum然后执行量化脚本# 文件路径quantize_gptq.py from transformers import AutoModelForCausalLM, AutoTokenizer, GPTQConfig model_id ./models/Qwen2.5-VL-3B-Instruct-Custom quant_path ./models/Qwen2.5-VL-3B-Instruct-GPTQ-Int4 tokenizer AutoTokenizer.from_pretrained(model_id) quantization_config GPTQConfig( bits4, group_size128, desc_actTrue, dataset[请介绍一下你自己。, 什么是多模态模型], ) model AutoModelForCausalLM.from_pretrained( model_id, quantization_configquantization_config, device_mapauto, trust_remote_codeTrue, ) model.save_pretrained(quant_path) tokenizer.save_pretrained(quant_path)量化后加载推理model Qwen2_5_VLForConditionalGeneration.from_pretrained( quant_path, device_mapauto, torch_dtypetorch.float16 )需要注意GPTQ 量化并不是所有模型结构都能完美支持而且 GPU 太老时可能出现算子不兼容。遇到问题时可以改用 AutoAWQ 或 bitsandbytes 方案。6.3 vLLM 推理优化建议如果要在 vLLM 中部署量化模型或合并后的模型建议使用与训练一致的trust_remote_code参数。把--max-model-len控制在 8192 以内避免显存爆破。高并发场景下--gpu-memory-utilization不要设满预留 5% 到 10% 给运行时开销。开启--enable-auto-tool-choice这类功能前先确认模型本身是否支持工具调用。6.4 显存不够时的降级方案当单卡显存不足时可以从几个方向降级换更小参数的模型3B 优先于 7B。降低输入图片的最大像素从1280 * 28 * 28降到1024 * 28 * 28。使用 4bit 量化加载模型。将模型切分到多张卡或在 CPU 与 GPU 间分配部分层。7. 实战应用接入一个图片信息抽取任务7.1 需求描述假设业务场景是从一批商品宣传图中抽取“商品名称”和“促销价格”统一整理成结构化数据。这个任务非常适合 VLM 微调因为图片版式相对固定。抽取字段有限输出格式可以约定。人工标注成本可控。7.2 服务端快速实现启动 vLLM 服务后后端可以写一个简单的 Flask 接口接收图片 base64 或 URL调用 vLLM 生成结构化结果。# 文件路径app.py from flask import Flask, request, jsonify from openai import OpenAI import base64 app Flask(__name__) client OpenAI(base_urlhttp://localhost:8000/v1, api_keyEMPTY) app.route(/extract, methods[POST]) def extract(): data request.get_json() image_base64 data.get(image_base64) image_bytes base64.b64decode(image_base64) image_url data:image/jpeg;base64, image_base64 response client.chat.completions.create( modelqwen-vl, messages[ { role: user, content: [ {type: image_url, image_url: {url: image_url}}, {type: text, text: 请提取商品名称和促销价格并输出 JSON 格式。}, ], } ], max_tokens256, ) content response.choices[0].message.content return jsonify({result: content}) if __name__ __main__: app.run(host0.0.0.0, port9000)生产环境中不要把 base64 字符串塞进日志也不要直接信任模型输出的 JSON最好用json.loads再包一层容错解析。8. 常见问题与排查清单8.1 高频报错对照表问题现象常见原因解决思路KeyError: qwen2_vltransformers 版本过旧不认识模型结构升级 transformers按官方要求对齐版本显存不足 OOM图片最大像素设置过高或并发请求过多降低 max_pixels减小并发数使用量化模型模型输出乱码模板或 chat template 使用错误确保使用processor.apply_chat_template而不是手写 prompt图片加载失败图片路径错误或格式不支持检查路径转成 jpg / png 格式用 PIL 打开验证LoRA 训练后模型效果无变化数据格式错、训练步数太少或 LoRA 没挂到正确层检查 dataset 注册增加训练步数确认 adapter 权重已加载vLLM 启动时报trust_remote_code错误某些模型实现需要动态加载代码启动命令加--trust-remote-code8.2 排查步骤建议遇到问题时按下面顺序排查可以节省很多时间先复现最小案例例如加载模型后输出一句简短文本。检查版本pip list | grep torch、pip list | grep transformers。检查 GPU 状态nvidia-smi看显存和占用率。查看日志中的异常堆栈优先搜索第一处红色报错。用 CPU 模式跑一遍小数据判断是环境问题还是数据问题。到官方 GitHub Issue 或模型仓库讨论区搜索相同报错。8.3 一个典型 OOM 的现场假设你启动 vLLM 后报错CUDA out of memory. Tried to allocate 512.00 MiB排查思路先用nvidia-smi确认是否已有其他进程占满显存。检查 vLLM 的--gpu-memory-utilization如果是 0.95 以上尝试降到 0.85。检查请求中的图片是否过大把max_pixels降低。如果仍然 OOM换 3B 模型或使用 4bit 量化。9. 最佳实践与工程建议9.1 数据管理微调数据本身就是资产。建议把原始图片、标注 JSON、脚本和最终配置文件都纳入版本管理。不要只保存一个“整理好的训练集”因为后续你想调整数据清洗策略时会后悔没有保留中间过程。标注工具方面小规模数据可以用开源标注工具或直接按 JSON 格式手工整理。数据量较大时可以考虑先让模型做一轮预标注再由人工修正能明显提升标注效率。9.2 微调参数与过拟合控制多模态模型参数量大训练数据少时很容易过拟合。一个比较稳妥的策略是先固定好验证集训练过程中持续观察验证集 loss。LoRA rank 从 32 到 64 起步不要一上来就设 128。学习率以 1e-4 为基准根据 loss 波动上下调整。epoch 控制在 2 到 5 之间如果 1 个 epoch 后验证集效果就下降说明数据量不足或模型容量过大。9.3 生产环境部署生产环境部署 VLM 时有几个容易被忽略的细节模型文件比较大建议放在高速磁盘上避免每次启动都重新从网络下载或从慢盘加载。服务启动前先做一次“冒烟测试”用一张固定测试图片验证模型是否正常。监控项不仅包括 CPU、内存、显存还包括请求平均延迟、首 token 延迟和图片预处理耗时。对模型输出要做安全过滤避免生成违反合规的内容。如果业务对响应时间敏感不要走在线实时 LoRA 切换而是提前合并 LoRA 权重并启动独立服务。9.4 安全边界在处理图片内容时要确认你拥有图片的使用和分发权限。涉及用户上传图片时不能直接把图片路径打印到日志也不能把隐私图片用于未经授权的模型训练。应当在数据接入层完成脱敏和合规审批后再进入训练流程。10. 总结与下一步学习方向这篇文章从 VLM 的基础概念开始走完了 Qwen 系列 VLM 的部署、推理、LoRA 微调、量化导出和接口接入全流程。你可以在自己机器上按顺序操作一遍建议先选择 3B 模型跑通全链路再根据业务需要切换到 7B 或更大规模的模型。下一步可以从这几个方向继续深入学习视觉 token 的生成方式和成本控制。尝试在 LlamaFactory 中切换finetuning_type为qwen_vl专用训练策略探索视觉编码器微调的影响。阅读 Qwen 系列官方技术报告理解动态分辨率切分和 token 压缩策略的取舍。在多卡环境下尝试分布式微调提升大批量数据训练效率。研究模型评测方法给微调后的 VLM 建立一套自动化评估集避免每次靠肉眼判断效果。实践是最好的学习方式。建议你准备 100 张左右业务图片整理成标准格式先跑一次微调再对比微调前后的模型输出差异。只有亲手完成一次完整闭环才算真正掌握 VLM 的部署与微调方法。如果这篇文章对你有所帮助可以收藏备用也欢迎留言交流你在本地部署或微调过程中遇到的问题。