设备环境： NVIDIA GeForce RTX 5090 (32GB / Blackwell 架构)

系统环境： Docker / CUDA 12.8 / PyTorch 2.9.1+cu128

核心目标： 解决显存识别异常，实现 Qwen3 等大模型的高效推理部署。

---

一、 部署核心教程（Standard Procedure）

1. 准备工作

确保宿主机已安装最新的 NVIDIA Driver（推荐 570.x 以上）以支持 RTX 5090。

2. 部署命令模板

推荐使用 vLLM 0.7.0+ 版本，采用 vllm serve 命令启动（该命令已取代旧的 python -m ... 入口）。（注意这里）

Qwen3-14B 启动示例：

vllm serve /path/to/model \
    --served-model-name qwen3-14b \
    --dtype bfloat16 \
    --max-model-len 32768 \
    --gpu-memory-utilization 0.9 \
    --enforce-eager \
    --trust-remote-code

3. Docker Compose 部署建议

对于容器化部署，需注意 shm_size 和 device_ids 的明确指定，避免显存探测冲突。

---

二、 关键问题总结与解决方案（Troubleshooting）

这是本次部署中最具参考价值的部分，记录了显存报错的排查全过程。

问题 1：显存“离奇失踪”报错

现象： nvidia-smi 显示显存全空（32GB），但 vLLM 报错称 Free memory (0.96 GiB) is less than desired...。

定位逻辑：

1. 排除僵尸进程： 通过 nvidia-smi 确认 Processes 为空。

2. 排查硬件状态： 发现 GPU-Util 异常达到 100%，说明 GPU 计算单元被锁定或驱动异常。

3. 底层验证： 使用 python -c 运行 PyTorch 原生命令 torch.cuda.mem_get_info()。

   • 结论： 若 PyTorch 能看到 30GB+，则证明硬件正常，问题出在 vLLM 的显存探测逻辑与新架构/新驱动的不兼容。

问题 2：RTX 5090 新架构兼容性

现象： vLLM 在启动阶段尝试捕获 CUDA Graph 时卡死或报错。

解决方案： * 强制 Eager 模式： 必须添加 --enforce-eager 参数。Blackwell 架构太新，vLLM 的 CUDA Graph 捕获逻辑可能尚未完全稳定，使用 Eager 模式可跳过此步骤直接运行。

• 精度选择： 强烈建议使用 --dtype bfloat16，这是 5090 硬件设计上的“甜点级”精度。

问题 3：Docker 环境下的显存偏移

现象： 容器内程序无法正确获取宿主机显存总量。

解决方案：

• 在 deploy 模块中明确 device_ids: ['0'] 而非仅仅是 count: all。

• 移除环境变量 VLLM_GPU_MEMORY_UTILIZATION，统一使用 command 参数控制，防止双重定义冲突。

---

三、 避坑经验总结（Key Takeaways）

坑点类型	错误表现	核心药方
驱动残留	显存空但利用率 100%	sudo nvidia-smi --gpu-reset -i 0 或重启
架构不识	报错 Free Memory 极小（<1GB）	升级 vLLM 0.7.0+ & 开启 --enforce-eager
版本断层	报错找不到设备/架构	匹配 PyTorch 2.5+ 及 CUDA 12.6+ 环境
模型长度	显存溢出 (OOM)	针对 32G 显存，14B 模型建议 max-model-len 设为 32k