vLLM部署Qwen2.5时CUDA Out of Memory导致Server崩溃的swap设置

vLLM 在加载或推理 Qwen2.5 这类大模型时报 CUDA Out of Memory，同时服务进程直接退出，首先要分清是显存容量不够，还是显存碎片化或上下文长度把峰值抬高了。swap 对显存本身没有直接帮助，但在进程被系统 OOM killer 杀掉之前，swap 可以提供一段可操作的缓冲时间，不能把 swap 当成显存扩容手段。

swap 只能缓解系统内存压力，绕不过 CUDA 显存上限。部署 Qwen2.5 时若 CUDA OOM 导致 Server 崩溃，优先调整 vLLM 的显存预留、降低并发或改用更小的量化版本；swap 仅在系统内存也吃紧时作为兜底，并且需要把 swap 放在 SSD 或 NVMe 上，避免拖垮整体响应。

先判断是显存不足还是系统内存不足

vLLM 运行时会同时占用显存和系统内存。加载模型权重、KV cache、激活值都在显存里；而 CPU 侧还有框架、调度、tokenizer、临时缓冲区。CUDA OOM 报错通常出现在加载阶段或推理过程中，常见有两种：

模型权重加 KV cache 超过 GPU 总显存，报类似 CUDA out of memory. Tried to allocate ...，此时增加系统 swap 无法解决。
系统内存不足触发进程被杀，日志里可能有 Killed 或退出码 137，这时增加 swap 才能让进程继续跑，但速度会明显变慢。

先运行 nvidia-smi 观察显存占用，同时用 free -h 看系统内存和 swap 使用量。如果看到显存占用接近上限而系统内存还有余量，问题在显存；如果系统内存也耗尽且 swap 为 0，那 swap 可以帮上忙。

swap 能做什么，不能做什么

swap 把不常用的内存页放到磁盘，腾出物理内存给其他进程。对 vLLM 这种需要实时计算的服务，swap 访问速度远低于内存，进程阻塞在磁盘 I/O 时，推理延迟会显著升高，并且可能因为长时间无响应被健康检查判死。

vLLM 自身有许多显存控制参数，优先检查这些：

`--gpu-memory-utilization`：默认 0.9，表示按 GPU 总显存的 90% 预占显存；如果机器上还有别的进程，需要调低到 0.7-0.8。
`--max-model-len`：过大的最大长度会让 KV cache 预留量暴增，把峰值显存拉高。
`--max-num-seqs`：限制同时处理的序列数，能降低峰值显存和内存压力。
量化模型：AWQ、GPTQ 或 FP8 版本能直接减少权重占用的显存，比 swap 更有效。

swap 只有在系统内存不足或显存刚超出几个 MB 时，才可能通过换出其他进程内存来腾出空间，让 vLLM 继续运行。如果显存缺口很大，比如权重加载到一半就 OOM，swap 再大也没有意义。

配置 swap 的具体操作

下面以 Linux 环境为例，创建基于文件的 swap，放在 SSD 或 NVMe 上能减少性能损失。建议先创建 8-16GB 的 swap 文件，并观察效果。

# 创建 8G swap 文件，大小按可用磁盘空间调整
sudo fallocate -l 8G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# 查看 swap 状态
free -h
swapon `--show`

要永久生效，在 /etc/fstab 末尾追加一行：

vLLM部署Qwen2.5时CUDA Out of Memory导致Server崩溃的swap设置

/swapfile none swap sw 0 0

还需要注意 vm.swappiness 参数。默认值通常是 60，代表系统会较积极地把内存页换到 swap。对于 vLLM 服务，可以适当降低，优先使用物理内存，避免 CPU 侧计算被 swap 拖慢：

sudo sysctl vm.swappiness=10
# 永久修改
sudo sh -c 'echo "vm.swappiness=10" > /etc/sysctl.d/99-swap.conf'

创建 swap 后，重新启动 vLLM。如果 CUDA OOM 发生在加载阶段，说明显存本身不够，换更小的模型或量化版本才是正路。如果报错变成 CPU 内存不足导致的进程被杀，那 swap 能让你继续启动服务，但要留意推理速度。

验证 swap 是否真正起了作用

观察 vLLM 进程运行状态：

用 top 或 htop 查看进程的 RES（物理内存）和 VIRT（虚拟内存）占用，如果 RES 接近物理内存上限且 SWAP 列出现数值，说明 swap 正在被使用。
用 dmesg 或 journalctl -k 查看有没有 OOM killer 日志。若不再出现 Out of memory: Killed process，说明 swap 起到了缓冲作用。
输入一段较长的提示词，观察响应时间变化。如果单次请求耗时大幅上涨，说明 swap 换出/换入已经开始影响性能，需要优化显存配置或减少模型规模。

swap 配置本身不改变 CUDA OOM 的根本原因。操作时建议同时调整 `--gpu-memory-utilization` 和 `--max-model-len`，再结合系统日志确认是哪一层内存压力触发的崩溃。

常见问题

swap 设多大合适？

通常建议先设置系统物理内存的 1 倍，或直接给 16GB 作为起点。但 vLLM 更依赖显存，swap 只是为了防进程被杀，设置过大并不会提升 GPU 性能，反而占用磁盘空间。

用了 swap 后 Server 还是崩溃，怎么办？

如果 CUDA OOM 依旧存在，说明显存缺口很大，swap 无法解决。请继续降低 `--gpu-memory-utilization`，缩小 `--max-model-len`，或改用显存占用更小的模型版本。崩溃日志中是否出现 CUDA error 与 Killed 也是区分显存和内存问题的重要依据。