部署视觉模型的教程1. 环境信息项目详情主机型号DPS-Z790-S-DDR4操作系统Ubuntu 22.04 LTS (Linux Desktop)GPUNVIDIA GeForce RTX 系列 (Z790 平台)CUDA12.6Python3.10模型Qwen2.5-VL-3B-Instruct推理框架vLLM 0.8.xAPI 端口8003部署日期2026-08-052. 基础环境安装2.1 系统依赖sudoaptupdatesudoaptinstall-y\build-essentialgitwgetcurl\libgl1 libglib2.0-0 ffmpeg\python3-pip python3-venvlibgl1和libglib2.0-0是 OpenCV / Pillow 处理图像时的运行时依赖缺失会导致多模态图片预处理报错。2.2 CUDA cuDNN确认已安装 CUDA 12.6 及对应 cuDNNnvidia-smi# 确认驱动 ≥ 560nvcc--version# 确认 CUDA 12.6python3-cimport nvidia.cudnn; print(nvidia.cudnn.__version__)若未安装或版本不匹配pipinstallnvidia-cuda-runtime-cu1212.6.*\nvidia-cudnn-cu129.5.*\nvidia-cublas-cu1212.6.*\--no-cache-dir2.3 Python 虚拟环境python3-mvenv ~/桌面/ai/.venvsource~/桌面/ai/.venv/bin/activate pipinstall--upgradepip setuptools wheel2.4 核心依赖版本锁定以下版本经实测兼容 Qwen2.5-VL vLLM请勿随意升级# PyTorch必须与 CUDA 12.6 匹配pipinstalltorch2.6.0torchvision0.21.0torchaudio2.6.0\--index-url https://download.pytorch.org/whl/cu126# TransformersQwen2.5-VL 需要 ≥ 4.49pipinstalltransformers4.51.3accelerate1.6.0 qwen-vl-utils0.0.11# vLLMpipinstallvllm0.8.5.post1 --no-cache-dir# FlashInfer可选加速编译失败可跳过pipinstallflashinfer-python0.2.6 --no-cache-dir# 验证安装python3-c import torch, transformers, vllm print(ftorch: {torch.__version__}) print(fCUDA avail: {torch.cuda.is_available()}) print(ftransformers: {transformers.__version__}) print(fvllm: {vllm.__version__}) 预期输出示例torch: 2.6.0cu126 CUDA avail: True transformers: 4.51.3 vllm: 0.8.5.post13. 模型下载3.1 ModelScope国内推荐pipinstallmodelscope modelscope download--modelQwen/Qwen2.5-VL-3B-Instruct\--local_dir~/桌面/ai/models/Qwen2.5-VL-3B-Instruct3.2 HuggingFace备选pipinstallhuggingface_hub huggingface-cli download Qwen/Qwen2.5-VL-3B-Instruct\--local-dir ~/桌面/ai/models/Qwen2.5-VL-3B-Instruct3.3 校验完整性ls~/桌面/ai/models/Qwen2.5-VL-3B-Instruct/# 应包含: config.json, tokenizer.json, *.safetensors, preprocessor_config.json, chat_template.jinja4. 启动 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关键参数说明参数值说明--dtypebfloat16Z790 平台 RTX 卡支持 BF16比 FP16 数值更稳定--gpu-memory-utilization0.90预留 10% 显存给系统/CUDA context--max-model-len32768Qwen2.5-VL-3B 最大支持 128K按实际显存调整--max-num-seqs64最大并发请求数受 KV Cache 总量限制--enable-prefix-caching-相同 system prompt / 图片前缀可复用 KV Cache--limit-mm-per-promptimage:10单条消息最多 10 张图片防止 OOM--enforce-eager-禁用 CUDA Graph降低显存占用适合小显存卡--served-model-name短别名API 调用时使用此名称代替完整路径4.2 验证服务就绪等待日志出现Uvicorn running on http://0.0.0.0:8003后# 检查模型列表curlhttp://localhost:8003/v1/models# 纯文本测试curl-m120http://localhost:8003/v1/chat/completions\-HContent-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\-HContent-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.serviceEOF [Unit] DescriptionvLLM Server for Qwen2.5-VL-3B-Instruct Afternetwork-online.target graphical-session.target Wantsnetwork-online.target [Service] Typesimple WorkingDirectory%h/桌面/ai EnvironmentVIRTUAL_ENV%h/桌面/ai/.venv EnvironmentPATH%h/桌面/ai/.venv/bin:%h/.local/bin:/usr/local/cuda/bin:/usr/local/bin:/usr/bin:/bin EnvironmentLD_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 Restarton-failure RestartSec10 StandardOutputjournal StandardErrorjournal [Install] WantedBydefault.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 日志后 CtrlC 退出curlhttp://localhost:8003/v1/models6. 部署过程中遇到的问题及解决方案问题 1PyTorch 与 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。问题 2Transformers 版本过低导致模型加载失败现象KeyError: qwen2_vl或AttributeError: Qwen2VLForConditionalGeneration has no attribute ...。原因Qwen2.5-VL 架构在 transformers ≥ 4.49 才引入旧版无法识别模型类型。解决pip install transformers4.51.3同时安装qwen-vl-utils提供图像处理工具函数。问题 3FlashInfer 编译失败现象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超时保护。问题 6systemd 环境中 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/activate8. 性能参考数据基于本次部署实测Qwen2.5-VL-3B-Instruct, Z790 平台指标数值模型权重占用~7.16 GiBKV Cache 分配~9.80 GiB (285K tokens)最大上下文长度32,768 tokens纯文本 prompt tokens23图文 prompt tokens3,604 (含图像编码)理论并发数 (32K ctx)~8.7x9. 完整依赖版本清单供复现环境时对照torch2.6.0cu126 torchvision0.21.0cu126 torchaudio2.6.0cu126 transformers4.51.3 accelerate1.6.0 qwen-vl-utils0.0.11 vllm0.8.5.post1 flashinfer-python0.2.6 # 可选 nvidia-cuda-runtime-cu1212.6.* nvidia-cudnn-cu129.5.* nvidia-cublas-cu1212.6.* modelscope1.24.0 # 或 huggingface_hub0.30.2文档版本v2.0 |最后更新2026-08-05 |作者DP
部署视觉模型的教程1. 环境信息项目详情主机型号DPS-Z790-S-DDR4操作系统Ubuntu 22.04 LTS (Linux Desktop)GPUNVIDIA GeForce RTX 系列 (Z790 平台)CUDA12.6Python3.10模型Qwen2.5-VL-3B-Instruct推理框架vLLM 0.8.xAPI 端口8003部署日期2026-08-052. 基础环境安装2.1 系统依赖sudoaptupdatesudoaptinstall-y\build-essentialgitwgetcurl\libgl1 libglib2.0-0 ffmpeg\python3-pip python3-venvlibgl1和libglib2.0-0是 OpenCV / Pillow 处理图像时的运行时依赖缺失会导致多模态图片预处理报错。2.2 CUDA cuDNN确认已安装 CUDA 12.6 及对应 cuDNNnvidia-smi# 确认驱动 ≥ 560nvcc--version# 确认 CUDA 12.6python3-cimport nvidia.cudnn; print(nvidia.cudnn.__version__)若未安装或版本不匹配pipinstallnvidia-cuda-runtime-cu1212.6.*\nvidia-cudnn-cu129.5.*\nvidia-cublas-cu1212.6.*\--no-cache-dir2.3 Python 虚拟环境python3-mvenv ~/桌面/ai/.venvsource~/桌面/ai/.venv/bin/activate pipinstall--upgradepip setuptools wheel2.4 核心依赖版本锁定以下版本经实测兼容 Qwen2.5-VL vLLM请勿随意升级# PyTorch必须与 CUDA 12.6 匹配pipinstalltorch2.6.0torchvision0.21.0torchaudio2.6.0\--index-url https://download.pytorch.org/whl/cu126# TransformersQwen2.5-VL 需要 ≥ 4.49pipinstalltransformers4.51.3accelerate1.6.0 qwen-vl-utils0.0.11# vLLMpipinstallvllm0.8.5.post1 --no-cache-dir# FlashInfer可选加速编译失败可跳过pipinstallflashinfer-python0.2.6 --no-cache-dir# 验证安装python3-c import torch, transformers, vllm print(ftorch: {torch.__version__}) print(fCUDA avail: {torch.cuda.is_available()}) print(ftransformers: {transformers.__version__}) print(fvllm: {vllm.__version__}) 预期输出示例torch: 2.6.0cu126 CUDA avail: True transformers: 4.51.3 vllm: 0.8.5.post13. 模型下载3.1 ModelScope国内推荐pipinstallmodelscope modelscope download--modelQwen/Qwen2.5-VL-3B-Instruct\--local_dir~/桌面/ai/models/Qwen2.5-VL-3B-Instruct3.2 HuggingFace备选pipinstallhuggingface_hub huggingface-cli download Qwen/Qwen2.5-VL-3B-Instruct\--local-dir ~/桌面/ai/models/Qwen2.5-VL-3B-Instruct3.3 校验完整性ls~/桌面/ai/models/Qwen2.5-VL-3B-Instruct/# 应包含: config.json, tokenizer.json, *.safetensors, preprocessor_config.json, chat_template.jinja4. 启动 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关键参数说明参数值说明--dtypebfloat16Z790 平台 RTX 卡支持 BF16比 FP16 数值更稳定--gpu-memory-utilization0.90预留 10% 显存给系统/CUDA context--max-model-len32768Qwen2.5-VL-3B 最大支持 128K按实际显存调整--max-num-seqs64最大并发请求数受 KV Cache 总量限制--enable-prefix-caching-相同 system prompt / 图片前缀可复用 KV Cache--limit-mm-per-promptimage:10单条消息最多 10 张图片防止 OOM--enforce-eager-禁用 CUDA Graph降低显存占用适合小显存卡--served-model-name短别名API 调用时使用此名称代替完整路径4.2 验证服务就绪等待日志出现Uvicorn running on http://0.0.0.0:8003后# 检查模型列表curlhttp://localhost:8003/v1/models# 纯文本测试curl-m120http://localhost:8003/v1/chat/completions\-HContent-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\-HContent-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.serviceEOF [Unit] DescriptionvLLM Server for Qwen2.5-VL-3B-Instruct Afternetwork-online.target graphical-session.target Wantsnetwork-online.target [Service] Typesimple WorkingDirectory%h/桌面/ai EnvironmentVIRTUAL_ENV%h/桌面/ai/.venv EnvironmentPATH%h/桌面/ai/.venv/bin:%h/.local/bin:/usr/local/cuda/bin:/usr/local/bin:/usr/bin:/bin EnvironmentLD_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 Restarton-failure RestartSec10 StandardOutputjournal StandardErrorjournal [Install] WantedBydefault.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 日志后 CtrlC 退出curlhttp://localhost:8003/v1/models6. 部署过程中遇到的问题及解决方案问题 1PyTorch 与 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。问题 2Transformers 版本过低导致模型加载失败现象KeyError: qwen2_vl或AttributeError: Qwen2VLForConditionalGeneration has no attribute ...。原因Qwen2.5-VL 架构在 transformers ≥ 4.49 才引入旧版无法识别模型类型。解决pip install transformers4.51.3同时安装qwen-vl-utils提供图像处理工具函数。问题 3FlashInfer 编译失败现象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超时保护。问题 6systemd 环境中 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/activate8. 性能参考数据基于本次部署实测Qwen2.5-VL-3B-Instruct, Z790 平台指标数值模型权重占用~7.16 GiBKV Cache 分配~9.80 GiB (285K tokens)最大上下文长度32,768 tokens纯文本 prompt tokens23图文 prompt tokens3,604 (含图像编码)理论并发数 (32K ctx)~8.7x9. 完整依赖版本清单供复现环境时对照torch2.6.0cu126 torchvision0.21.0cu126 torchaudio2.6.0cu126 transformers4.51.3 accelerate1.6.0 qwen-vl-utils0.0.11 vllm0.8.5.post1 flashinfer-python0.2.6 # 可选 nvidia-cuda-runtime-cu1212.6.* nvidia-cudnn-cu129.5.* nvidia-cublas-cu1212.6.* modelscope1.24.0 # 或 huggingface_hub0.30.2文档版本v2.0 |最后更新2026-08-05 |作者DP
