Qwen3.5 多模态模型部署 OOM 排查：enforce-eager 参数配置详解

更详细的内存使用情况显示，两张卡的显存都几乎被占满，明显不正常。一个经过 4 位量化的模型，即使原始参数量很大，也不应该在推理单张图片时占用近 40GB 的显存。

排查过程：一步步缩小问题范围

遇到 OOM 问题，首先怀疑的是基础配置是否正确。我检查了以下几个关键点：

1. 模型文件完整性：确认下载的模型文件完整，没有损坏。
2. tensor-parallel-size：确认设置为 2，与双卡环境匹配。
3. max-model-len：确认设置为 4096，在合理范围内。
4. 量化配置：确认使用的是 AWQ-4bit 量化版本。

这些配置看起来都没问题。为了进一步验证，我尝试用更小的输入进行测试，即使输入非常简单，OOM 问题依然出现。这说明问题不是由输入大小引起的。

接下来，我使用更详细的内存分析工具来观察内存分配模式。分析结果显示，大部分内存是在模型前向传播（forward pass）过程中分配的，而不是在模型加载时。这提示问题可能出在推理计算图（computation graph）的构建上。

这时，我开始怀疑是不是某个启动参数有问题。重新仔细检查启动命令，发现了一个关键遗漏：

# 问题配置（简化版）
python -m vllm.entrypoints.openai.api_server \
  --model Qwen3.5-35B-A3B-AWQ-4bit \
  --tensor-parallel-size 2 \
  --max-model-len 4096 \
  --port 8000 
# 注意：这里缺少了 --enforce-eager 参数！

根据 Qwen 多模态模型的部署文档，这个参数对于 AWQ 量化模型是必需的。

问题根源：enforce-eager 参数的作用与影响

要理解为什么缺少这个参数会导致 OOM，首先需要了解 vLLM 的两种执行模式：

1. Eager 模式（即时执行）：操作立即执行，不构建计算图，内存分配按需进行。调试方便，但可能效率稍低。
2. Graph 模式（计算图模式）：先构建完整的计算图，然后一次性执行，可以优化执行顺序，提高效率。但需要预先分配所有可能用到的内存。

对于 Qwen3.5-35B-A3B-AWQ-4bit 这样的多模态量化模型，问题出在计算图的构建上。AWQ（Activation-aware Weight Quantization）是一种先进的量化技术，但它与传统的计算图优化存在兼容性问题。

具体来说，Graph 模式会尝试为整个计算流程预先分配内存。但对于 AWQ 量化层，内存需求的计算可能不准确，系统会按照未量化的原始模型大小来预留内存，导致实际分配的内存远超过实际需要。

以 Qwen3.5-35B 为例：

• 原始 float16 版本：35B 参数 × 2 字节 ≈ 70GB
• 4bit 量化版本：35B 参数 × 0.5 字节 ≈ 17.5GB

但在 Graph 模式下，系统可能仍按 70GB 来预留内存，这就是即使模型已经量化到 17.5GB，仍然尝试分配 70GB 内存的原因。

解决方案：正确启用 enforce-eager 参数

找到问题根源后，修复就很简单了：在启动命令中明确添加 --enforce-eager 参数。

正确的启动命令应该是：

python -m vllm.entrypoints.openai.api_server \
  --model /root/models/Qwen3.5-35B-A3B-AWQ-4bit \
  --tensor-parallel-size 2 \
  --max-model-len 4096 \
  --enforce-eager \
  # 关键参数！
  --port 8000 \
  --served-model-name qwen-multimodal \
  --trust-remote-code

修改配置后重启服务，再次测试：

1. 服务启动正常：模型加载时间与之前相同。
2. 内存使用正常：启动后显存占用约 18GB（符合 4bit 量化的预期）。
3. 推理测试通过：上传图片并提问，响应正常，显存峰值约 22GB。
4. 长时间运行稳定：连续测试多轮对话，无 OOM 问题。

使用 nvidia-smi 监控修复后的显存使用，可以看到进程显存占用已回归正常水平。

深入理解：多模态量化模型的部署要点

1. 为什么选择 vLLM + compressed-tensors 方案？

在排查过程中，我也了解了为什么这个部署方案被推荐。主要有以下几个原因：

• 量化权重完整支持：compressed-tensors 专门处理打包的量化权重，能正确加载 AWQ、GPTQ 等量化格式，避免 HF Transformers 原生加载时可能出现的问题。
• 内存管理优化：vLLM 的 PagedAttention 技术，更高效的内存复用，适合长上下文多模态任务。
• 推理性能平衡：在 Eager 模式下仍能保持不错的推理速度，避免 Graph 模式的内存预估问题，实际测试中 QPS（每秒查询数）仍可接受。

2. 其他可能影响内存的参数

除了 enforce-eager，还有一些其他参数也需要注意：

3. 监控与调试技巧

部署完成后，建议建立监控机制：

#!/bin/bash
# monitor_gpu.sh
while true; do
  clear
  echo "=== GPU 监控 $(date) ==="
  nvidia-smi --query-gpu=memory.used,memory.total,utilization.gpu \
    --format=csv,noheader,nounits
  echo ""
  echo "=== 进程监控 ==="
  ps aux | grep vllm | grep -v grep
  sleep 5
done

import torch
import gc

def check_memory_usage():
    """检查 GPU 内存使用情况"""
    for i in range(torch.cuda.device_count()):
        allocated = torch.cuda.memory_allocated(i) / 1024**3
        reserved = torch.cuda.memory_reserved(i) / 1024**3
        print(f"GPU {i}: 已分配 {allocated:.2f}GB, 已保留 {reserved:.2f}GB")
    # 强制垃圾回收
    gc.collect()
    torch.cuda.empty_cache()

总结与建议

回顾这次 OOM 问题的排查和修复过程，有几个关键教训值得分享：

1. 参数重要性不只看表面：--enforce-eager 看起来只是一个执行模式开关，但对于特定类型的模型（如 AWQ 量化模型），它是稳定运行的关键。不要因为参数"看起来不重要"就忽略它。
2. 量化模型有特殊要求：量化技术能大幅减少磁盘存储和内存占用，但部署时需要框架的专门支持。不同量化格式（AWQ、GPTQ、GGUF）可能有不同的部署要求。
3. 内存问题要系统排查：从配置检查开始，使用工具分析内存分配模式，对比正常和异常情况，查阅官方文档和社区经验。

基于这次经验，总结了以下几点建议：

部署前检查清单：

• 确认模型量化格式（AWQ/GPTQ/GGUF 等）
• 查阅该模型和量化格式的官方部署指南
• 检查所有必需参数是否都已设置
• 准备监控工具，实时观察资源使用

参数设置黄金法则：

1. AWQ 量化模型：必须使用 --enforce-eager
2. 多卡部署：正确设置 --tensor-parallel-size
3. 长上下文：根据需求调整 --max-model-len
4. 内存限制：如有需要，设置 --gpu-memory-utilization

最后，针对 Qwen3.5-35B-A3B-AWQ-4bit 这个特定模型，建议的完整部署流程是：

# 1. 环境准备
pip install vllm compressed-tensors

# 2. 模型下载（确保是 AWQ-4bit 版本）
# 从官方渠道下载模型到指定目录

# 3. 启动服务（关键参数不能少）
python -m vllm.entrypoints.openai.api_server \
  --model /path/to/Qwen3.5-35B-A3B-AWQ-4bit \
  --tensor-parallel-size 2 \
  --max-model-len 4096 \
  --enforce-eager \
  --port 8000 \
  --trust-remote-code

# 4. 验证服务
curl http://localhost:8000/v1/models

记住，对于量化模型，特别是使用较新量化技术（如 AWQ）的模型，一定要仔细阅读部署要求。一个看似微小的参数差异，可能就是稳定运行和频繁 OOM 的区别。

希望我的这次踩坑经历能帮你顺利部署 Qwen 多模态模型。如果你在部署过程中遇到其他问题，欢迎交流讨论！