【手把手从零实现】Qwen2.5-VL：环境配置/功能实验（图片识别理解、目标检测、文字OCR、文档解析、视频理解）/模型微调(MS-Swift 和 LLaMA-Factory)
目录
1 先看结论
2 环境准备与安装
2.1 基础环境与依赖
2.2 Transformers 开发版安装
2.3 模型权重下载（HF / ModelScope）
3 快速推理上手
3.1 显存占用测试
3.2 单图问答 Demo
4 功能实验全记录
4.1 多图联合理解
4.2 输出目标检测框（bbox）
4.3 OCR（含繁体/手写/票据）
4.4 文档结构化解析（HTML / Markdown）
4.5 视频理解（关键帧/字幕/动作概括）
5 批量推理脚本与常见报错定位
6 训练与微调实践
6.1 选择 MS-Swift 还是 LLaMA-Factory？
6.2 数据格式准备（图文对话、多模态指令）
6.3 MS-Swift 微调流程示例
6.4 LLaMA-Factory 微调流程示例
6.5 低成本方案：QLoRA / Freeze-Vision-Encoder
6.6 评测与导出部署
7 资源整理 & 参考命令速查
8 常见问题 FAQ
1. 先看结论
- Qwen2.5-VL（阿里通义千问最新视觉语言家族）在 图像理解、检测框、OCR、表格解析、视频理解 等方面给出“开箱即用”的接口，3B 模型就很能打。
- 实测显存需求见下表。
| 模型 | FP16 纯推理显存（之前） | INT8 权重量化后 | 备注 |
|---|---|---|---|
| Qwen2.5‑VL‑3B | ~8 GB | ≈4–5 GB | 再低可用 4-bit 约 2.5–3 GB |
| Qwen2.5‑VL‑7B | ~20 GB | ≈10–12 GB | KV Cache 仍是 FP16/FP32，序列越长越涨 |
| Qwen2.5‑VL‑72B | ~150 GB | ≈75–90 GB（多卡/CPU Offload） | 实操基本要分布式 + offload |
- HuggingFace
transformers正式版暂时跟不上最新接口，需要从源码装 新的transformers，博主直接使用的4.51.3。也可以使用其他版本，>=4.49.0应该都能满足。 - MS-Swift（ModelScope 原生工具链）与 LLaMA-Factory（社区爆款微调框架）均已支持多模态微调，可选自己熟悉的生态；本篇给出两套命令行 & 配置模板。
- 训练数据核心是 图像/视频路径 + Prompt/Answer 的多模态对话格式，注意对齐字段、max_pixels、抽帧策略等。
- 推理环节推荐自己包一层脚本，解决路径、批处理、可视化等重复工作。
- 建议：英文 prompt + 中文输出要求，往往效果更稳定。
2. 环境准备与安装
2.1 基础环境与依赖
建议环境（亲测稳定）：
- OS：Ubuntu 20.04/22.04（Win 也能跑，但 CUDA/路径权限坑多）
- Python：3.10（官方示例多数基于 3.10）
- CUDA：12.4（本人使用的此版本，也可以使用11.8之类的）
- PyTorch：2.6.0（和 CUDA 对应，好装好用）
# 1) 新建虚拟环境 conda create -n qwen25-vl python=3.10 -y conda activate qwen25-vl # 2) 安装 PyTorch（任选一个 CUDA 版本） # or CUDA 12.4 pip insta
