部署Qwen2.5-VL-3B-Instruc视觉模型的教程

部署视觉模型的教程

1. 环境信息

项目	详情
主机型号	DPS-Z790-S-DDR4
操作系统	Ubuntu 22.04 LTS (Linux Desktop)
GPU	NVIDIA GeForce RTX 系列 (Z790 平台)
CUDA	12.6
Python	3.10
模型	Qwen2.5-VL-3B-Instruct
推理框架	vLLM 0.8.x
API 端口	8003
部署日期	2026-08-05

---

2. 基础环境安装

2.1 系统依赖

sudo apt update && sudo apt install -y \
    build-essential git wget curl \
    libgl1 libglib2.0-0 ffmpeg \
    python3-pip python3-venv

libgl1 和 libglib2.0-0 是 OpenCV / Pillow 处理图像时的运行时依赖，缺失会导致多模态图片预处理报错。

2.2 CUDA & cuDNN

确认已安装 CUDA 12.6 及对应 cuDNN：

nvidia-smi          # 确认驱动 ≥ 560
nvcc --version      # 确认 CUDA 12.6
python3 -c "import nvidia.cudnn; print(nvidia.cudnn.__version__)"

若未安装或版本不匹配：

pip install nvidia-cuda-runtime-cu12==12.6.* \
            nvidia-cudnn-cu12==9.5.* \
            nvidia-cublas-cu12==12.6.* \
            --no-cache-dir

2.3 Python 虚拟环境

python3 -m venv ~/桌面/ai/.venv
source ~/桌面/ai/.venv/bin/activate
pip install --upgrade pip setuptools wheel

2.4 核心依赖版本锁定

以下版本经实测兼容 Qwen2.5-VL + vLLM，请勿随意升级：

# PyTorch（必须与 CUDA 12.6 匹配）
pip install torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0 \
    --index-url https://download.pytorch.org/whl/cu126

# Transformers（Qwen2.5-VL 需要 ≥ 4.49）
pip install transformers==4.51.3 accelerate==1.6.0 qwen-vl-utils==0.0.11

# vLLM
pip install vllm==0.8.5.post1 --no-cache-dir

# FlashInfer（可选加速，编译失败可跳过）
pip install flashinfer-python==0.2.6 --no-cache-dir

# 验证安装
python3 -c "
import torch, transformers, vllm
print(f'torch:         {torch.__version__}')
print(f'CUDA avail:    {torch.cuda.is_available()}')
print(f'transformers:  {transformers.__version__}')
print(f'vllm:          {vllm.__version__}')
"

预期输出示例：

torch:         2.6.0+cu126
CUDA avail:    True
transformers:  4.51.3
vllm:          0.8.5.post1

---

3. 模型下载

3.1 ModelScope（国内推荐）

pip install modelscope
modelscope download --model Qwen/Qwen2.5-VL-3B-Instruct \
    --local_dir ~/桌面/ai/models/Qwen2.5-VL-3B-Instruct

3.2 HuggingFace（备选）

pip install huggingface_hub
huggingface-cli download Qwen/Qwen2.5-VL-3B-Instruct \
    --local-dir ~/桌面/ai/models/Qwen2.5-VL-3B-Instruct

3.3 校验完整性

ls ~/桌面/ai/models/Qwen2.5-VL-3B-Instruct/
# 应包含: config.json, tokenizer.json, *.safetensors, preprocessor_config.json, chat_template.jinja

---

4. 启动 vLLM 服务

4.1 手动启动（首次调试用）

cd ~/桌面/ai
source .venv/bin/activate

vllm serve ./models/Qwen2.5-VL-3B-Instruct \
  --served-model-name Qwen2.5-VL-3B-Instruct \
  --host 0.0.0.0 --port 8003 --dtype bfloat16 \
  --gpu-memory-utilization 0.90 --max-model-len 32768 \
  --max-num-seqs 64 --enable-prefix-caching \
  --trust-remote-code --limit-mm-per-prompt '{"image": 10}' \
  --enforce-eager

关键参数说明

参数	值	说明
--dtype	bfloat16	Z790 平台 RTX 卡支持 BF16，比 FP16 数值更稳定
--gpu-memory-utilization	0.90	预留 10% 显存给系统/CUDA context
--max-model-len	32768	Qwen2.5-VL-3B 最大支持 128K，按实际显存调整
--max-num-seqs	64	最大并发请求数，受 KV Cache 总量限制
--enable-prefix-caching	-	相同 system prompt / 图片前缀可复用 KV Cache
--limit-mm-per-prompt	image:10	单条消息最多 10 张图片，防止 OOM
--enforce-eager	-	禁用 CUDA Graph，降低显存占用，适合小显存卡
--served-model-name	短别名	API 调用时使用此名称代替完整路径

4.2 验证服务就绪

等待日志出现 Uvicorn running on http://0.0.0.0:8003 后：

# 检查模型列表
curl http://localhost:8003/v1/models

# 纯文本测试
curl -m 120 http://localhost:8003/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen2.5-VL-3B-Instruct",
    "messages": [{"role":"user","content":"用一句话介绍你自己"}],
    "temperature": 0.7, "max_tokens": 256, "stream": true
  }'

# 图文多模态测试
curl -m 120 http://localhost:8003/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen2.5-VL-3B-Instruct",
    "messages": [{
      "role": "user",
      "content": [
        {"type":"image_url","image_url":{"url":"https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen-VL/assets/demo.jpeg"}},
        {"type":"text","text":"请详细描述这张图片的内容"}
      ]
    }],
    "temperature": 0.7, "max_tokens": 512, "stream": true
  }'

---

5. 配置开机自启动（systemd 用户服务）

5.1 创建服务文件

mkdir -p ~/.config/systemd/user

cat > ~/.config/systemd/user/vllm-qwen.service << 'EOF'
[Unit]
Description=vLLM Server for Qwen2.5-VL-3B-Instruct
After=network-online.target graphical-session.target
Wants=network-online.target

[Service]
Type=simple
WorkingDirectory=%h/桌面/ai
Environment=VIRTUAL_ENV=%h/桌面/ai/.venv
Environment=PATH=%h/桌面/ai/.venv/bin:%h/.local/bin:/usr/local/cuda/bin:/usr/local/bin:/usr/bin:/bin
Environment=LD_LIBRARY_PATH=/usr/local/cuda/lib64:%h/桌面/ai/.venv/lib/python3.10/site-packages/nvidia/cudnn/lib
ExecStart=%h/桌面/ai/.venv/bin/vllm serve ./models/Qwen2.5-VL-3B-Instruct \
    --served-model-name Qwen2.5-VL-3B-Instruct \
    --host 0.0.0.0 --port 8003 --dtype bfloat16 \
    --gpu-memory-utilization 0.90 --max-model-len 32768 \
    --max-num-seqs 64 --enable-prefix-caching \
    --trust-remote-code --limit-mm-per-prompt '{"image": 10}' \
    --enforce-eager
Restart=on-failure
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=default.target
EOF

⚠️ 注意 ：相比之前版本，此处增加了 VIRTUAL_ENV 环境变量并将 ExecStart 指向虚拟环境内的 vllm 二进制，确保 systemd 环境下使用正确的 Python 解释器和依赖。

5.2 启用并启动

systemctl --user daemon-reload
loginctl enable-linger $USER       # 允许未登录时服务持续运行
systemctl --user enable vllm-qwen  # 设置开机自启
systemctl --user start vllm-qwen   # 立即启动

5.3 验证

systemctl --user status vllm-qwen
journalctl --user -u vllm-qwen -f
# 等待 "Uvicorn running" 日志后 Ctrl+C 退出
curl http://localhost:8003/v1/models

---

6. 部署过程中遇到的问题及解决方案

问题 1：PyTorch 与 CUDA 版本不匹配

• 现象 ：torch.cuda.is_available() 返回 False，或 vLLM 启动报 CUDA error: no kernel image is available for execution on the device。
• 原因：通过默认 pip 安装的 PyTorch 链接的是 CUDA 11.8，与本机 CUDA 12.6 不兼容。
• 解决 ：卸载后使用 --index-url https://download.pytorch.org/whl/cu126 重新安装指定 CUDA 版本的 PyTorch。

问题 2：Transformers 版本过低导致模型加载失败

• 现象 ：KeyError: 'qwen2_vl' 或 AttributeError: 'Qwen2VLForConditionalGeneration' has no attribute ...。
• 原因：Qwen2.5-VL 架构在 transformers ≥ 4.49 才引入，旧版无法识别模型类型。
• 解决 ：pip install transformers>=4.51.3，同时安装 qwen-vl-utils 提供图像处理工具函数。

问题 3：FlashInfer 编译失败

• 现象 ：pip install flashinfer-python 报 C++ 编译错误或找不到 nvcc。
• 原因：FlashInfer 需要本地 CUDA toolkit 头文件和匹配的 GCC 版本。
• 解决 ：确认 nvcc --version 可用且 GCC ≤ 12；若仍失败可跳过安装，vLLM 自动回退到 PyTorch 原生采样，功能不受影响。

问题 4：模型名称过长导致调用不便

• 现象 ：默认模型 ID 为完整路径 ./models/Qwen2.5-VL-3B-Instruct，对接 SDK 时易出错。
• 解决 ：启动时添加 --served-model-name Qwen2.5-VL-3B-Instruct。

问题 5：非流式响应长回复超时

• 现象：图文理解任务 prompt_tokens 高达 3604，非流式模式下 curl 长时间无响应。
• 解决 ：所有请求添加 "stream": true 和 -m 120 超时保护。

问题 6：systemd 环境中 GPU / CUDA 不可见

• 现象 ：手动终端启动正常，systemd 拉起后报 CUDA not found。
• 原因 ：systemd 用户会话不继承 .bashrc 中的环境变量。
• 解决 ：在服务文件中显式声明 PATH、LD_LIBRARY_PATH、VIRTUAL_ENV，并将 ExecStart 指向虚拟环境内的绝对路径。

问题 7：开机自启未生效

• 现象 ：enable 成功但重启后服务未拉起。
• 原因：未开启 linger，用户服务仅在登录会话存活时运行。
• 解决 ：loginctl enable-linger $USER，验证 loginctl show-user $USER | grep Linger 输出 yes。

问题 8：中文路径兼容性隐患

• 现象 ：工作目录 ~/桌面/ai 含中文，当前组合可正常运行，但部分旧版工具链可能异常。
• 建议 ：长期生产使用建议迁移至纯英文路径如 ~/projects/ai。

---

7. 日常运维速查表

操作	命令
查看实时日志	journalctl --user -u vllm-qwen -f
查看服务状态	systemctl --user status vllm-qwen
重启服务	systemctl --user restart vllm-qwen
停止服务	systemctl --user stop vllm-qwen
禁用自启	systemctl --user disable vllm-qwen
重新启用自启	systemctl --user enable vllm-qwen
编辑服务配置	nano ~/.config/systemd/user/vllm-qwen.service && systemctl --user daemon-reload
验证 API 可用	curl http://localhost:8003/v1/models
进入虚拟环境	source ~/桌面/ai/.venv/bin/activate

---

8. 性能参考数据

基于本次部署实测（Qwen2.5-VL-3B-Instruct, Z790 平台）：

指标	数值
模型权重占用	~7.16 GiB
KV Cache 分配	~9.80 GiB (285K tokens)
最大上下文长度	32,768 tokens
纯文本 prompt tokens	23
图文 prompt tokens	3,604 (含图像编码)
理论并发数 (32K ctx)	~8.7x

---

9. 完整依赖版本清单

供复现环境时对照：

torch==2.6.0+cu126
torchvision==0.21.0+cu126
torchaudio==2.6.0+cu126
transformers==4.51.3
accelerate==1.6.0
qwen-vl-utils==0.0.11
vllm==0.8.5.post1
flashinfer-python==0.2.6          # 可选
nvidia-cuda-runtime-cu12==12.6.*
nvidia-cudnn-cu12==9.5.*
nvidia-cublas-cu12==12.6.*
modelscope==1.24.0                # 或 huggingface_hub==0.30.2

📝 文档版本 ：v2.0 | 最后更新 ：2026-08-05 | 作者：DP