vllm-playground + Gemma4 模型部署问题排查与解决报告

排查时间：2026 年 4 月 19 日 — 4 月 20 日
部署环境：大脑服务器（192.168.51.70），NVIDIA RTX 4090 48GB
涉及组件：vllm-playground、vLLM (Docker)、google/gemma-4-E2B-it、ModelScope

一、问题概述

在 vllm-playground 上部署 Google Gemma4（google/gemma-4-E2B-it）模型，目标是：

• 通过 ModelScope（魔塔）下载模型（网络原因无法访问 HuggingFace）
• 充分利用 48GB GPU 显存，支持长上下文（max_model_len）和长输出（max_tokens）
• 通过 vllm-playground Web UI 进行交互

共发现并修复了 6 个关键问题，涉及镜像版本、OOM、输出截断等多个层面。

二、问题列表与解决方案

问题 1：vLLM Docker 镜像版本过旧

现象：vllm-playground 默认使用 vllm/vllm-openai:v0.12.0，内置 transformers 4.57.3，不支持 Gemma4 新架构。

原因：Gemma4 的架构支持（sliding window attention + 新 tokenizer）是在 2026 年 4 月中旬才合并进 transformers 主干的，v0.12.0 的依赖约束 transformers<5 导致无法升级。

解决：

# 找到并替换 vllm-playground 中的默认镜像配置
# 文件 1: container_manager.py
sed 's|vllm/vllm-openai:v0.12.0|docker.io/vllm/vllm-openai:latest|g'

# 文件 2: cli.py
sed 's|vllm/vllm-openai:v0.12.0|docker.io/vllm/vllm-openai:latest|g'

之后重启 vllm-playground 服务。

问题 2：GPU 显存分配过高导致 OOM

现象：vLLM 容器启动后，在 warmup 阶段（CUDA graph 编译）抛出 torch.OutOfMemoryError。

原因：gpu_memory_utilization=0.98（98%）几乎用满 47.37 GiB 全部显存。vLLM 在 warmup 时会用最大序列长度（max_model_len）跑一次前向传播来捕获 CUDA graph，此时激活值的显存峰值会短暂超过可用显存。

Gemma4 内存占用分解：

问题不在于 KV cache，而在于 warmup 激活峰值：CUDA graph 编译时需要保存完整前向传播的中间激活，32K 序列长度约需 6 GiB。98% 分配已无余量。

解决：将 gpu_memory_utilization 从 0.98 降至 0.85，保留 ~7 GiB 缓冲：

import json
f = '/home/brain/.vllm-playground/instances.json'
data = json.load(open(f))
for inst in data.get('instances', []):
    inst['gpu_memory_utilization'] = 0.85
json.dump(data, open(f, 'w'), indent=2)

问题 3：ModelScope 配置未传递到容器

现象：选择了 ModelScope 作为模型源，但容器内环境变量 VLLM_USE_MODELSCOPE 未设置，vLLM 仍然尝试连接 HuggingFace。

原因：vllm-playground 的 container_manager.py 中 build_container_config() 方法缺少 ModelScope 相关的环境变量传递逻辑，且 volumes 变量在使用时尚未定义。

解决：修改 container_manager.py，在 build_container_config() 中添加 ModelScope 配置块：

# 设置环境变量
config['environment']['VLLM_USE_MODELSCOPE'] = 'true'
# 如果提供了 token
if modelscope_token:
    config['environment']['MODELSCOPE_SDK_TOKEN'] = modelscope_token
# 挂载宿主机模型缓存目录
config['volumes']['/root/.cache/modelscope'] = {
    'bind': '/root/.cache/modelscope',
    'mode': 'ro'
}

同时修复 volumes 变量引用错误（需在使用前声明 volumes = []）。

问题 4：ModelScope 模型路径错误

现象：ModelScope API 调用返回 404。

原因：误以为路径是 modelscope://google/gemma-4-E2B 或其他变体，实际正确的路径是：

google/gemma-4-E2B-it   # 指令微调版本
google/gemma-4-E2B       # 基座模型

验证方法：

from modelscope import snapshot_download
snapshot_download('google/gemma-4-E2B-it', cache_dir='/tmp/ms_test')
# 成功下载 8 个文件，共 9.54 GB

问题 5：输出内容被截断

现象：模型输出到一半（约 2000 字 / 4096 tokens）就停止，看起来像被截了一半。

原因：前端 max_tokens 限制有两处硬编码：

1. HTML slider 元素：max="4096"
2. JS 事件处理：Math.min(4096, val) —— 无论用户拖到多少，都被 clamp 回 4096

vLLM API 本身没有任何截断限制（max_model_len=32768，可输出任意多），问题纯粹出在 UI 前端。

解决：

# index.html
- <input type="range" max="4096" value="256" ...>
+ <input type="range" max="16384" value="4096" ...>

# app.js
- Math.min(4096, val)
+ Math.min(16384, val)
- maxTokens: 256
+ maxTokens: 4096

修改后 UI 上限从 4096 提升到 16384，默认值从 256 提升到 4096。API 测试证明 8192 tokens 输出完全正常。

问题 6：vllm-playground UI 实例创建页面点击无响应

现象：在 Instances 配置页面填写完信息后点击"Create"或"Save"，页面不做任何反应，反复尝试均无效。

原因：UI 内部 React 状态管理问题，点击某些元素（如 radio button）会触发状态更新导致表单重新渲染，输入值丢失。

解决：绕过 UI，直接通过 API 创建实例：

# 创建实例
curl -X POST http://localhost:7860/api/start \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemma-4-E2B-it",
    "model_source": "ModelScope",
    "gpu_memory_utilization": 0.85,
    "max_model_len": 32768,
    "enforce_eager": false,
    "port": 8000
  }'

三、最终配置

Gemma4 架构补充信息

• 注意力机制：GQA（Grouped Query Attention），仅 1 个 KV head
• Sliding Window：35 层中 28 层使用 sliding window（512 tokens），仅 7 层全注意力
• KV cache 占用：极小，每 token 仅 0.034 MiB
• 原生上下文：max_position_embeddings=131072（131K tokens），但受 GPU 显存限制

显存估算（gpu_memory_utilization=0.85 时）

四、访问地址

五、后续建议

1. 长输出验证：在 Chat Settings 中将 Max Tokens 设为 8192 或 16384，测试长篇小说、代码等场景
2. 增大上下文：如需更大 context（>32K），将 enforce_eager 设为 true 以禁用 CUDA graph，可节省 ~0.63 GiB，但吞吐量降低 20-30%
3. 监控：KV Cache 和 Throughput 监控面板在 vllm-playground UI 的 vLLM Server 页面
4. 模型量化：如需进一步节省显存，Qwen3.5-27B 已支持 FP8 量化，可用于对比测试