部署视觉模型的教程

1. 环境信息

2. 基础环境安装

2.1 系统依赖

sudoaptupdate&&sudoaptinstall-y\build-essentialgitwgetcurl\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# 确认驱动 ≥ 560nvcc--version# 确认 CUDA 12.6python3-c"import nvidia.cudnn; print(nvidia.cudnn.__version__)"

若未安装或版本不匹配：

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

2.3 Python 虚拟环境

python3-mvenv ~/桌面/ai/.venvsource~/桌面/ai/.venv/bin/activate pipinstall--upgradepip setuptools wheel

2.4 核心依赖版本锁定

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

# PyTorch（必须与 CUDA 12.6 匹配）pipinstalltorch==2.6.0torchvision==0.21.0torchaudio==2.6.0\--index-url https://download.pytorch.org/whl/cu126# Transformers（Qwen2.5-VL 需要 ≥ 4.49）pipinstalltransformers==4.51.3accelerate==1.6.0 qwen-vl-utils==0.0.11# vLLMpipinstallvllm==0.8.5.post1 --no-cache-dir# FlashInfer（可选加速，编译失败可跳过）pipinstallflashinfer-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（国内推荐）

pipinstallmodelscope modelscope download--modelQwen/Qwen2.5-VL-3B-Instruct\--local_dir~/桌面/ai/models/Qwen2.5-VL-3B-Instruct

3.2 HuggingFace（备选）

pipinstallhuggingface_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~/桌面/aisource.venv/bin/activate vllm serve ./models/Qwen2.5-VL-3B-Instruct\--served-model-name Qwen2.5-VL-3B-Instruct\--host0.0.0.0--port8003--dtypebfloat16\--gpu-memory-utilization0.90--max-model-len32768\--max-num-seqs64--enable-prefix-caching\--trust-remote-code --limit-mm-per-prompt'{"image": 10}'\--enforce-eager

关键参数说明

4.2 验证服务就绪

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

# 检查模型列表curlhttp://localhost:8003/v1/models# 纯文本测试curl-m120http://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-m120http://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/usercat>~/.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--userdaemon-reload loginctl enable-linger$USER# 允许未登录时服务持续运行systemctl--userenablevllm-qwen# 设置开机自启systemctl--userstart vllm-qwen# 立即启动

5.3 验证

systemctl--userstatus vllm-qwen journalctl--user-uvllm-qwen-f# 等待 "Uvicorn running" 日志后 Ctrl+C 退出curlhttp://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. 日常运维速查表

8. 性能参考数据

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

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