Qwen3.5-35B-A3B-AWQ-4bit部署避坑：enforce-eager参数误关导致OOM的定位与修复全过程

优质文章学习记录

— 13 min read

Qwen3.5-35B-A3B-AWQ-4bit部署避坑：enforce-eager参数误关导致OOM的定位与修复全过程

1. 引言：一次典型的部署“翻车”现场

上周，我在部署Qwen3.5-35B-A3B-AWQ-4bit这个多模态模型时，遇到了一个让人头疼的问题：服务启动后，只要一上传图片进行推理，GPU内存就会瞬间爆满，然后直接报OOM（Out Of Memory）错误。

这本来不应该发生。Qwen3.5-35B-A3B-AWQ-4bit是一个经过4位量化处理的多模态模型，专门面向视觉理解任务，按理说在双卡24GB的环境下应该能稳定运行。但实际情况是，模型加载正常，Web界面也能打开，可一旦开始推理，内存使用量就像坐火箭一样飙升，几秒钟内就把两张卡的显存全部吃光。

更让人困惑的是，部署脚本和参数配置看起来都没问题。模型是从官方渠道下载的，部署环境也是标准的CUDA环境，为什么会出现这种情况？

经过几个小时的排查，最终发现问题的根源竟然是一个看似不起眼的参数：enforce-eager。这篇文章，我就来完整复盘这次OOM问题的定位和修复过程，希望能帮你避开同样的坑。

2. 问题现象：从正常启动到突然崩溃

2.1 部署环境与配置

先简单介绍一下我的部署环境：

  • 硬件：双卡GPU，每卡24GB显存
  • 模型：Qwen3.5-35B-A3B-AWQ-4bit（4位量化多模态版本）
  • 部署框架：vLLM + compressed-tensors
  • 前端界面：基于Gradio的图文对话页面

部署过程本身很顺利。按照标准的部署流程：

# 启动后端服务 cd /root/workspace 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 
# 启动前端Web服务 cd /root/workspace/web python app.py --port 7860

两个服务都正常启动，日志显示模型加载成功：

INFO 07-15 14:30:22 vllm.engine.llm_engine: Loading model weights... INFO 07-15 14:32:15 vllm.engine.llm_engine: Model loaded in 113.93 seconds INFO 07-15 14:32:15 vllm.engine.llm_engine: KV cache pool created with 4096 blocks

2.2 OOM错误的具体表现

问题出现在第一次实际使用的时候。当我通过Web界面上传一张图片并提问时，后端日志开始出现异常：

ERROR 07-15 14:35:42 vllm.engine.llm_engine: CUDA out of memory. Tried to allocate 18.00 GiB (GPU 0; 23.69 GiB total capacity; 3.45 GiB already allocated; 17.23 GiB free; 3.45 GiB reserved in total by PyTorch)

更详细的内存使用情况显示：

# 使用nvidia-smi监控显存 +-----------------------------------------------------------------------------+ | NVIDIA-SMI 535.104.05 Driver Version: 535.104.05 CUDA Version: 12.2 | |-------------------------------+----------------------+----------------------+ | GPU Name Persistence-M| Bus-Id Disp.A | Volatile Uncorr. ECC | | Fan Temp Perf Pwr:Usage/Cap| Memory-Usage | GPU-Util Compute M. | | | | MIG M. | |===============================+======================+======================| | 0 NVIDIA A100 80GB... On | 00000000:3B:00.0 Off | 0 | | N/A 45C P0 250W / 300W | 23458MiB / 24564MiB | 98% Default | | | | Disabled | +-------------------------------+----------------------+----------------------+ | 1 NVIDIA A100 80GB... On | 00000000:86:00.0 Off | 0 | | N/A 48C P0 255W / 300W | 23467MiB / 24564MiB | 99% Default | | | | Disabled | +-------------------------------+----------------------+----------------------+

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

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

3.1 第一步：检查基础配置

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

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

这些配置看起来都没问题。为了进一步验证，我尝试用更小的输入进行测试：

# 测试最小输入 test_input = { "image": "一张很小的测试图片", "question": "描述这张图片" }

即使输入这么简单，OOM问题依然出现。这说明问题不是由输入大小引起的。

3.2 第二步：分析内存使用模式

接下来，我使用更详细的内存分析工具来观察内存分配模式：

# 使用PyTorch内存分析 import torch torch.cuda.memory_summary(device=0) torch.cuda.memory_summary(device=1)

分析结果显示，大部分内存是在模型前向传播（forward pass）过程中分配的，而不是在模型加载时。这提示问题可能出在推理计算图（computation graph）的构建上。

3.3 第三步：对比正常与异常配置

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

# 问题配置（简化版） 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 参数！

等等，我发现了问题！在最初的部署中，我漏掉了--enforce-eager 这个参数。而根据Qwen多模态模型的部署文档，这个参数对于AWQ量化模型是必需的。

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

4.1 什么是enforce-eager模式？

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

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

对于Qwen3.5-35B-A3B-AWQ-4bit这样的多模态量化模型，问题出在计算图的构建上。

4.2 为什么AWQ量化模型需要enforce-eager？

AWQ（Activation-aware Weight Quantization）是一种先进的量化技术，但它与传统的计算图优化存在兼容性问题：

模式对AWQ模型的影响内存使用
Graph模式计算图优化可能错误估计量化层的内存需求严重高估，导致OOM
Eager模式按需执行，准确反映实际内存需求正常，符合预期

具体来说，问题在于：

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

4.3 量化模型的内存特性

为了更直观地理解这个问题，我们来看一下量化模型的内存特点：

# 量化模型 vs 原始模型的内存对比 原始模型内存需求 ≈ 模型参数量 × 精度（如float16=2字节） 量化模型内存需求 ≈ 模型参数量 × 量化精度（如4bit=0.5字节） # 以Qwen3.5-35B为例： 原始float16版本：35B参数 × 2字节 ≈ 70GB 4bit量化版本：35B参数 × 0.5字节 ≈ 17.5GB # 但Graph模式可能仍按70GB来预留内存！

这就是为什么即使模型已经量化到17.5GB，系统仍然尝试分配70GB内存的原因。

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

5.1 修复部署配置

找到问题根源后，修复就很简单了：在启动命令中明确添加 --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

5.2 验证修复效果

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

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

使用nvidia-smi监控修复后的显存使用：

+-----------------------------------------------------------------------------+ | Processes: | | GPU GI CI PID Type Process name GPU Memory | | ID ID Usage | |=============================================================================| | 0 N/A N/A 123456 C+G ...python3.10 18000MiB | | 1 N/A N/A 123456 C+G ...python3.10 18000MiB | +-----------------------------------------------------------------------------+

5.3 完整的部署脚本示例

为了避免再次出现类似问题，我整理了一个完整的部署脚本：

#!/bin/bash # deploy_qwen_multimodal.sh MODEL_PATH="/root/models/Qwen3.5-35B-A3B-AWQ-4bit" LOG_DIR="/root/workspace/logs" PORT=8000 # 创建日志目录 mkdir -p $LOG_DIR # 启动vLLM后端服务 echo "启动vLLM后端服务..." nohup python -m vllm.entrypoints.openai.api_server \ --model $MODEL_PATH \ --tensor-parallel-size 2 \ --max-model-len 4096 \ --enforce-eager \ # 必须包含这个参数！ --port $PORT \ --served-model-name qwen-multimodal \ --trust-remote-code \ > $LOG_DIR/vllm_backend.log 2>&1 & echo "后端服务已启动，日志：$LOG_DIR/vllm_backend.log" # 等待后端服务就绪 sleep 30 # 启动前端Web服务 echo "启动前端Web服务..." cd /root/workspace/web nohup python app.py --port 7860 \ --backend-url "http://localhost:$PORT" \ > $LOG_DIR/web_frontend.log 2>&1 & echo "前端服务已启动，端口：7860" echo "部署完成！"

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

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

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

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

6.2 其他可能影响内存的参数

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

参数作用对AWQ模型的影响建议设置
gpu-memory-utilizationGPU内存利用率影响KV缓存分配0.9（默认）
block-size注意力块大小影响内存碎片16（默认）
swap-spaceCPU交换空间极端情况下的备用4（GiB）
pipeline-parallel-size流水线并行多卡模型切分1（默认）

6.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 
# Python内存检查工具 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()

7. 总结与建议

7.1 关键教训总结

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

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

7.2 给部署者的实用建议

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

部署前检查清单：

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

参数设置黄金法则：

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

故障排查流程：

  1. 查看服务日志，定位错误发生阶段
  2. 监控资源使用，观察异常模式
  3. 简化测试用例，排除输入数据问题
  4. 对比标准配置，检查参数差异
  5. 搜索社区经验，看看是否有已知问题

7.3 Qwen多模态模型部署的最佳实践

最后，针对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 \ # AWQ模型必需！ --port 8000 \ --trust-remote-code # 4. 验证服务 curl http://localhost:8000/v1/models

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

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

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 ZEEKLOG星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。

Read more

从2025看2026前端发展趋势

从2025看2026前端发展趋势

前言 岁至年关，当我们回望2025年的前端领域，会发现一种矛盾的图景：一面是AI编码工具以惊人的效率生成代码，另一面却是市场对“前端已死”的论调再度泛起。仅管行业数据显示IT岗位需求出现了显著的结构性调整，但一线工程师与架构师却为我们描绘了一幅截然不同的未来，即：前端并非消亡，而是在一场深刻的蜕变中，其内核与边界将被重新定义。 固元 所谓“固元”，是指在技术浪潮冲击下，对前端工程师核心价值的再确认与再坚守。毫无疑问，AI时代软件开发的核心闭环已从“编写”转向“生成-验证”。这意味着，大模型可以负责概率性地创造代码，但无法理解复杂业务场景下的副作用，也无法保障最终用户的体验确定性。那些看似枯燥的传统工程能力——性能优化、稳定性保障、体验一致性维护——恰恰是前端工程师对抗技术熵增、构建职业护城河的根基。因此，“固本培元”，是重拾对体验的极致敏感度，是将人的判断力、产品思维和架构智慧，置于AI生成流程的关键验证节点。 蜕变 所谓“变者化之渐”，在“固元”的同时，前端工程师的能力坐标也必须进行“蜕变”————即：进行系统性升级，
搭建一个基于Django框架的WebApi项目

搭建一个基于Django框架的WebApi项目

让我们一起走向未来 🎓作者简介：全栈领域优质创作者 🌐个人主页：百锦再@新空间代码工作室 📞工作室：新空间代码工作室（提供各种软件服务） 💌个人邮箱：[[email protected]] 📱个人微信：15045666310 🌐网站：https://meihua150.cn/ 💡座右铭：坚持自己的坚持，不要迷失自己！要快乐 目录 * 让我们一起走向未来 * 一、创建Django项目 * 二、安装相关依赖 * 三、配置MySQL数据库 * 四、配置Redis缓存 * 五、配置JWT中间件 * 六、配置Swagger接口文档 * 七、创建示例API * 八、总结 一、创建Django项目 首先，确保你的环境中已安装Django。如果没有，可以通过以下命令安装： pip install django

WebVOWL终极指南：如何用可视化工具轻松理解复杂本体结构

WebVOWL终极指南：如何用可视化工具轻松理解复杂本体结构 【免费下载链接】WebVOWLVisualizing ontologies on the Web 项目地址: https://gitcode.com/gh_mirrors/we/WebVOWL 在语义网和知识图谱领域，本体（Ontology）是描述概念层次和关系的重要工具。然而，面对复杂的RDF和OWL文件，如何直观地理解本体结构成为了许多研究者和开发者的挑战。WebVOWL作为一款专业的Web本体可视化工具，能够将抽象的语义数据转化为易于理解的图形化表示，让复杂的本体关系一目了然。 🎯 为什么你需要WebVOWL本体可视化工具 本体可视化不仅仅是美观的图形展示，更是理解数据关系的有效手段。通过WebVOWL，你可以： * 快速发现模式：在图形界面中立即识别出本体的核心概念和重要关系 * 交互式探索：通过点击、拖拽和缩放操作深入分析特定区域 * 团队协作优化：为技术团队和非技术人员提供统一的可视化交流语言 🚀 三步快速启动WebVOWL可视化环境 环境准备与项目获取 首先确保你的系统已安装Nod

libdatachannel：轻量级C++ WebRTC库完全指南

libdatachannel：轻量级C++ WebRTC库完全指南 【免费下载链接】libdatachannelC/C++ WebRTC network library featuring Data Channels, Media Transport, and WebSockets 项目地址: https://gitcode.com/GitHub_Trending/li/libdatachannel libdatachannel是一个轻量级的C++ WebRTC网络库，提供数据通道、媒体传输和WebSocket功能。这个开源项目让开发者能够在原生应用程序和Web浏览器之间建立直接的实时通信连接，无需依赖谷歌臃肿的参考库。 什么是libdatachannel？ 🤔 libdatachannel是一个独立的WebRTC实现，支持跨平台开发，包括GNU/Linux、Android、FreeBSD、macOS、iOS和Windows。它实现了W3C和IETF标准的WebRTC协议，让设备间能够进行实时点对点数据和媒体交换。 核心功能特性 ✨ WebRTC数据通道 * 基于