单卡微调 Qwen3-VL 的新版实现

用一张 GPU 微调视觉语言模型，难点往往不在启动训练，而在训练数据、图像处理和推理格式能否对齐。作者把一份围绕 Qwen2-VL-7B 的旧 notebook 改成 Qwen3-VL-8B-Instruct 脚本，给出 DocumentVQA 文档问答的微调流程。

这份教程值得看的，是它把容易失效的接口和数据处理环节单独拎了出来。不过，原文明确报告的验证集中在 processor 路径，没有提供训练效果、显存峰值或完整训练结果。把它当作实验起点比较合适，直接当成单卡落地保证就过头了。

换成 Qwen3-VL，解决的是教程维护问题

作者选择 Qwen3-VL-8B-Instruct，主要依据是模型较新、与原来的 7B 基线处于相近规模，并且 transformers==5.12.1 能处理它的配置、processor 和多模态对话流程。原文还称，Unsloth 已通过 FastVisionModel 支持 Qwen3-VL。

这解释了为什么更新教程，却不能证明它在 DocumentVQA 上优于 Qwen2-VL 或 Qwen2.5-VL。文章没有提供横向评测。对已有稳定流程的团队来说，「更新」可以成为试用理由，迁移仍要看准确率、成本和兼容性。

复现环境要求先安装适配本机 CUDA 或 CPU 的 PyTorch 2.12.x，再安装以下依赖：

pip install "transformers==5.12.1" "datasets>=3.0.0" "trl>=0.19.0" "peft>=0.13.0" "accelerate>=1.0.0" pillow unsloth

要注意这一行只有 Transformers 固定了精确版本，其余部分使用版本下限，pillow 和 unsloth 没有锁版本。它能表达作者预期的环境范围，却不是完整的依赖锁定文件。

训练仍需要容纳 4-bit 权重及训练开销的 CUDA GPU；支持 CPU 的模型加载路径，不等于文章给出了 CPU 微调方案。FlashAttention 2 是可选推理优化，不是示例的运行前提。更关心成本时，作者建议考虑 Qwen/Qwen3-VL-4B-Instruct，但明确把它作为推理侧的较小替代，没有展示对应训练结果。

图像和消息格式，比先调学习率更重要

整个流程可以拆成三步：把文档图片和问题整理成对话，给模型加入 LoRA 适配器，再用视觉数据整理器构建训练批次。

LoRA 可以理解为在基础模型上增加可训练的适配参数。这里通过 FastVisionModel.from_pretrained 加载 unsloth/Qwen3-VL-8B-Instruct，设置 load_in_4bit=True 和 use_gradient_checkpointing="unsloth"，分别控制权重加载方式和训练内存开销。

作者同时打开视觉层、语言层、注意力模块和 MLP 模块的微调，设置 target_modules="all-linear"，并使用 r=16、lora_alpha=16、lora_dropout=0。此外，modules_to_save=["lm_head", "embed_tokens"] 也进入配置。估算资源和保存产物时，应把这些设置一起考虑，不能只看「4-bit + LoRA」几个字。

数据来自 HuggingFaceM4/DocumentVQA。每条记录转换为 messages：用户消息包含图片、任务说明和问题，assistant 消息包含答案。虽然常量叫 SYSTEM_PROMPT，代码实际把它拼进用户文本，没有独立的 system 消息。

图像保持比例缩放，最长边限制为 896，并转成 RGB。这样做是为了约束图像带来的序列成本，但文档小字是否还能看清，需要另外验证。答案则只取 answers[0]，没有答案时使用空字符串；这是一种简化，未处理多参考答案和空标签质量。

训练使用 SFTTrainer，其中 processing_class=processor.tokenizer 负责 tokenizer 接口，UnslothVisionDataCollator(model, processor) 负责视觉批次。几个关键配置是：

• remove_unused_columns=False 保留多模态字段。
• dataset_kwargs={"skip_prepare_dataset": True} 跳过默认数据准备，配合已经构造好的 messages。
• max_length=None 避免按普通文本长度截断时误删图像 token。

多模态训练能否成立，先取决于模型收到的图片和对话是否正确。

max_length=None 也没有消除显存限制。作者用限制图像分辨率来控制另一端的成本，两者应一起理解。

示例只取 train[:1000]，训练 200 步，单设备批大小为 1，梯度累积 8 次。学习率为 2e-4，预热 5 步，优化器用 adamw_8bit，权重衰减为 0.01，学习率线性调度，随机种子为 3407。每 10 步记录日志，每 100 步保存，最多保留 2 个 checkpoint；训练精度依据 is_bf16_supported() 在 BF16 与 FP16 间选择。

这些是可执行的起始参数，不是作者验证过的最优组合。原文也明确说，1000 条数据用于调试和快速迭代，不能代表完整训练策略。

推理接口变简洁了，训练假设仍要逐项对齐

训练后，脚本保存适配器和 processor。推理则加载基础模型 Qwen/Qwen3-VL-8B-Instruct，通过 PeftModel.from_pretrained 挂载 qwen3-vl-documentvqa-lora/checkpoint-200。

最值得保留的是下面这段：它把对话模板和真实图片转换成模型输入，省去单图推理中的额外拼装逻辑。

    chat_text = processor.apply_chat_template(
        messages,
        tokenize=False,
        add_generation_prompt=True,
    )

    inputs = processor(
        text=[chat_text],
        images=[image],
        padding=True,
        return_tensors="pt",
    )
    inputs = move_to_model_device(inputs, model)

重点是 images=[image]：模板里的图片位置与这里传入的图片需要对应。随后调用 model.generate，设置 max_new_tokens=64、do_sample=False，并在解码前裁掉输入部分的 token，得到新增回答。

作者明确说，AutoProcessor.from_pretrained、processor.apply_chat_template(...) 和带图片的 processor 调用，在 transformers==5.12.1 下做过冒烟测试，也就是验证基本路径可运行。原文没有给出完整训练日志或微调前后的准确率。

读代码还能看到几处需要补齐的对齐问题。训练把长边缩到 896，推理只转 RGB，没有复用缩放函数；训练保存了 processor，推理却从基础模型加载 processor。两种写法未必立即出错，但都应检查是否符合训练时的假设。

另外，训练用了 4-bit 加载，推理代码并没有指定 4-bit，而是在 CUDA 下使用 BF16、CPU 下使用 FP32。因此，不能拿训练侧的量化配置直接推断推理显存需求。

我的判断

我赞成这篇文章把注意力放在数据构造、processor 和适配器回载上。对于文档问答，图片没传对、消息模板错位，即使 loss 在下降，也不能证明模型学到了预期能力。先验证一个完整批次，再扩大训练规模，是有用的工程顺序。

但标题中的「一张 GPU」缺少硬件型号、显存峰值、耗时和吞吐量支撑；「现代基线更合适」也缺少模型对照。这些部分属于配置建议和经验判断，不能替它背书。

相比直接用基础模型推理，这篇教程多提供了一条任务适配路径，却没有证明微调收益。相比直接上全量训练，它的小样本方案适合排查流程。是否继续投入，应补上微调前后的 exact-match 或 ANLS 风格评估，并检查标签噪声。单看 validation[:1] 的打印结果，只够确认链路，无法判断效果。

能拿来做什么

• 如果你在做内部文档问答，先按文中的 messages 结构整理少量图片、问题和答案，检查空答案、多参考答案及缩放后的小字，再启动短训练。
• 把 processor 单独做成可验证步骤，确认输出同时包含 input_ids 和 pixel_values，一个 PIL 图片批次能够进入模型，保存的适配器也能重新挂载。
• 将模型、processor、提示词和图片缩放策略一起记录，并固定依赖版本，避免训练脚本能跑、推理脚本却沿用另一套输入规则。
• 在扩大 train[:1000] 之前，用同一验证集比较基础模型与适配模型；若主要限制是成本，再测试 4B 推理方案，用实测结果决定后续投入。