Finetune-Qwen2.5-VL

想象一下：你训练好了一个视觉语言模型，想让它专门看懂自己业务场景的发票、表格或说明书，却发现原生模型总是'答非所问'。市面上的通用微调工具要么上手门槛极高（需要写一堆分布式训练代码），要么对多模态支持残缺（只能调语言部分，视觉编码器被'冻结'）。

Finetune-Qwen2.5-VL 正是为解决这一痛点而生。它是一套围绕 Qwen2.5-VL（通义千问2.5视觉语言大模型）打造的微调工具包，核心亮点是支持 LoRA + PEFT 全参数微调——既能优化语言理解能力，也能同步微调视觉编码器，让模型真正'看懂'你的专属场景。

项目由独立开发者 sandy1990418 于 2025 年 2 月创建，基于 LLaMA-Factory 框架设计，GitHub 已积累 166 颗星、23 个 Fork，Topics 涵盖 AI、LLM、LoRA、PEFT、VLM 等，是目前针对 Qwen2.5-VL 微调较为活跃的开源工具之一。

什么是 Qwen2.5-VL？

Qwen2.5-VL 是阿里巴巴通义团队开源的新一代视觉语言大模型，支持 3B / 7B / 72B 三种规格。相比前代，2.5 版本在视觉理解、指令遵循和视频理解上有显著提升，并原生支持 agent 能力。模型可处理图像、视频，并能在 20K 上下文窗口内完成多轮多图对话。然而，通用预训练模型在垂直场景（如中文票据识别、医疗报告理解、工业图纸解析）上往往表现不够精准，需要进行领域适配。

核心功能：从训练到推理的全链路支持

Finetune-Qwen2.5-VL 提供了完整的视觉语言模型微调工作流，主要分为四个阶段：

1. 监督微调（SFT）—— 单卡与多卡

这是项目的核心功能。通过 src/train.py 调用统一的 run_exp() 入口，底层封装了 LLaMA-Factory 的训练引擎。配置文件中可指定 LoRA 目标模块（默认 lora_target: all，即同时微调 Qwen2.5-VL 的视觉编码器、MLP 和语言解码器），LoRA rank 默认为 8。训练支持单 GPU（use_accelerate: false）和分布式多卡（use_accelerate: true + accelerate.yaml）两种模式。示例配置使用 Qwen2.5-VL-3B-Instruct，batch_size=1（per device），gradient_accumulation=8，bf16 混合精度，学习率 1e-4，余弦退火调度，3 个 epoch 完整微调。值得注意的是，项目还预留了 Ray 多卡训练接口（虽然在 README 中标注为'待解决'）。

2. LoRA 权重合并

微调完成后，通过 src/merge_model.py 将 LoRA adapter 与基座模型合并，输出可直接用于推理的完整模型文件。这解决了 LoRA 增量权重无法独立部署的问题。合并后模型体积与基座相同，兼容性良好。

3. 推理（Inference）

推理模块 src/inference.py 是项目中工程化程度最高的组件。它封装了 VLMInference 类，支持从 URL 或本地路径加载图片，内置 ImageLoader 和 MessageBuilder 工具类，预设了 OCR 任务的消息模板。推理流程遵循标准 VLM 范式：chat template -> vision info 处理 -> processor 编码 -> model.generate -> decode。此外，项目依赖中包含了 Gradio（4.38-5.12），意味着很可能也支持 Web UI 交互式推理界面。

4. 评估（Evaluation）

evaluation/evaluation.py 提供了评估流水线，支持中文 OCR 评测（依赖 jiwer、rouge-chinese 等指标），但 README 中标注评估管道为 TODO 状态，尚未完全成熟。

技术架构：LLaMA-Factory 血统的模块化设计

代码结构清晰，分为六大模块：

值得关注的是 model_utils/ 目录，包含了 RoPE 优化、梯度检查点、视觉注意力 patch 等底层优化手段，以及 Unsloth 集成（unsloth.py）——Unsloth 是一个能实现 2-5x 训练加速和 50% 显存节省的 LoRA 训练库，这意味着项目预留了高效微调的加速路径。量化方面，支持 4-bit QLoRA（quantization_bit: 4），通过 bitsandbytes 实现，大幅降低显存门槛。

部署体验：有 Docker 但不够'一键'

项目提供了官方 Dockerfile，基于 NVIDIA CUDA 12.0 镜像，安装了完整的 Python 3.10 + PyTorch + Transformers 生态。构建镜像后运行容器，挂载本地数据目录即可开始训练。但没有 docker-compose.yml，也没有 K8s manifest，意味着生产级部署需要自己编写编排脚本。推理侧虽然导入了 Gradio，但 README 中未说明如何启动 Web UI，略显遗憾。

硬件需求方面，Qwen2.5-VL-3B 推理约需 6-8GB VRAM，微调（即使 LoRA）显存需求也会显著增加，建议 16GB+ VRAM 的 NVIDIA GPU（如 3090/4090/A10G）。CPU 训练虽然技术上可行，但效率极低。

局限与待改进

1. 多卡分布式训练不稳定：README 明确提到 Ray 多卡训练存在问题，这在大模型微调中是关键功能缺失。
2. 评估管道不完整：evaluation.py 存在但被标记为 TODO，缺少自动化评测报告。
3. 文档不够详细：README 仅约 3000 字，对数据集格式、训练监控、常见报错缺少说明。
4. 缺乏生产级部署方案：无 docker-compose，无 Helm chart，不支持 API 服务化部署。

总结

Finetune-Qwen2.5-VL 是一个专注于 Qwen2.5-VL 视觉语言模型微调的工具包，提供了从 SFT -> 合并 -> 推理 -> 评估的完整链路。它不是'玩具级'脚本，而是基于 LLaMA-Factory 工业级训练框架构建的实用工具。适合有 LoRA 微调基础、了解 VLM 基本原理的开发者使用。主要局限在于多卡分布式训练和评估管道的完善度。如果你的场景是单卡微调中文视觉任务（如票据 OCR、表格理解），它是一个值得一试的方案。

图1：项目作者 GitHub 头像