Qwen-VL · 阿里通义千问多模态视觉语言模型 · 本地部署与使用全指南

项目仓库： https://github.com/QwenLM/Qwen-VL

开源协议：见仓库 LICENSE · 类型：视觉语言模型（VLM） · 运行时：Python 3.8+ / PyTorch 1.12+（推荐 2.0+） · 推理库：Hugging Face Transformers / ModelScope · 仓库分支：master

1 项目简介

Qwen-VL 是阿里巴巴通义千问（Qwen）团队开源的多模态视觉语言模型，支持输入图像与文本进行对话、图像描述、视觉问答、文档理解与指代理解等任务。升级版本 Qwen-VL-Plus 与 Qwen-VL-Max 已在 DocVQA 等评测中取得领先，可通过 Hugging Face Spaces、ModelScope、DashScope API 免费体验。

本文聚焦开源 Qwen-VL / Qwen-VL-Chat 模型在本地的部署与推理。

1.1 核心信息一览

1.2 适用场景

• 想在本地用 Transformers 跑一个图文多模态对话模型。
• 需要做图像描述、视觉问答、文档/图表理解等任务。
• 希望在 CPU / GPU 之间灵活切换（bf16 / fp16 / cpu）。

1.3 能力边界（官方口径）

• 官方提供 Transformers 与 ModelScope 两种推理路径。
• 量化推理需 torch 2.0+ 与 transformers 4.32.0+，并安装 AutoGPTQ。
• 更强大的 Qwen-VL-Plus/Max 走 DashScope API，不直接在本仓库权重中。

2 功能特性

• 图文对话：输入图像 + 文本，输出文本回答。
• 多种精度：bf16 / fp16 / CPU 加载，device_map 灵活分配。
• 双推理后端：Hugging Face Transformers 与 ModelScope。
• 量化支持：基于 AutoGPTQ 的量化推理。
• 视觉编码器：更多用法见仓库 TUTORIAL.md。

3 官方界面预览

本仓库 README 以代码与评测表为主，实际对话界面以自行运行的推理脚本为准；在线体验见 Hugging Face Spaces / ModelScope。

4 官方跳转链接汇总

5 前置要求与服务器配置

5.1 软件前提

• Python 3.8+。
• PyTorch 1.12+（推荐 2.0+）。
• CUDA 11.4+（GPU 用户）。
• Transformers 4.32.0+（生成配置可省略手写）。

5.2 硬件建议

6 方式一：Transformers 推理（推荐）

git clone https://github.com/QwenLM/Qwen-VL.git
cd Qwen-VL
pip install -r requirements.txt

from transformers import AutoModelForCausalLM, AutoTokenizer
from transformers.generation import GenerationConfig
import torch
torch.manual_seed(1234)

tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen-VL-Chat", trust_remote_code=True)

# 可选精度：bf16 / fp16 / cpu / cuda
model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen-VL-Chat", device_map="cuda", trust_remote_code=True
).eval()

7 方式二：ModelScope 推理

官方同时提供 ModelScope 路径（modelscope 库加载 Qwen/Qwen-VL-Chat），用法与 Transformers 类似，详见 README 中 ModelScope 小节。

8 量化推理

# 需 torch 2.0+、transformers 4.32.0+
pip install optimum
git clone https://github.com/JustinLin610/AutoGPTQ.git
cd AutoGPTQ
pip install -v .

安装 auto-gptq 遇问题时，建议按官方 AutoGPTQ 仓库寻找对应 wheel。

9 配置项说明

10 常见故障排查

• transformers 版本过低：升级到 4.32.0+，避免手写生成配置。
• 显存不足：改用 fp16 或量化模型，或 device_map="cpu"。
• auto-gptq 安装失败：按官方仓库找对应 Python/torch 版本的 wheel。
• 模型下载慢：用 ModelScope 镜像或本地缓存权重。

11 风险与合规说明

• 许可证：以仓库 LICENSE 为准，商用前核对。
• API 与开源区分：Qwen-VL-Plus/Max 走 DashScope API，本地权重为开源 Qwen-VL。
• 内容合规：图像与生成内容需自行负责。
• 非官方声明：本文基于官方仓库 README 整理，参数以 master 分支最新为准。