From 94a6e06d79b3d570998e33989f8362b2daf17a7b Mon Sep 17 00:00:00 2001
From: Zijie Tian <zijietian@mail.xmu.edu.cn>
Date: Tue, 27 Jan 2026 04:36:24 +0800
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20docs:=20add=20GPU=20VRAM=20requi?=
 =?UTF-8?q?rement=20rule=20for=20GPU-only=20mode?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

GPU-only mode requires 40GB+ VRAM. This rule enforces checking GPU
memory before running non-offload tests to prevent OOM errors on
consumer GPUs (3090/4090).

Generated with [Claude Code](https://claude.ai/code)
via [Happy](https://happy.engineering)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>
---
 .claude/rules/gpu-vram-requirement.md | 54 +++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)
 create mode 100644 .claude/rules/gpu-vram-requirement.md

diff --git a/.claude/rules/gpu-vram-requirement.md b/.claude/rules/gpu-vram-requirement.md
new file mode 100644
index 0000000..487af92
--- /dev/null
+++ b/.claude/rules/gpu-vram-requirement.md
@@ -0,0 +1,54 @@
+# GPU VRAM Requirement Rule
+
+## GPU-only 模式显存要求
+
+**强制规则**：执行 GPU-only 代码（不启用 CPU offload）时，**必须**在 40GB 及以上显存的 GPU 上进行测试。
+
+### 检测方法
+
+在运行 GPU-only 测试之前，**必须**先检查 GPU 显存：
+
+```bash
+nvidia-smi --query-gpu=index,name,memory.total --format=csv,noheader
+```
+
+### GPU 分类
+
+| GPU 型号 | 显存 | GPU-only 测试 |
+|----------|------|---------------|
+| A100 40GB | 40GB | ✅ 允许 |
+| A100 80GB | 80GB | ✅ 允许 |
+| H100 80GB | 80GB | ✅ 允许 |
+| A6000 | 48GB | ✅ 允许 |
+| RTX 3090 | 24GB | ❌ **禁止**（仅 offload 模式） |
+| RTX 4090 | 24GB | ❌ **禁止**（仅 offload 模式） |
+
+### 执行流程
+
+1. **检测 GPU 显存**（必须）
+2. **显存 >= 40GB**：继续执行 GPU-only 测试
+3. **显存 < 40GB**：**停止**，提示用户：
+   > "当前 GPU 显存为 XXX GB，不满足 GPU-only 模式的最低 40GB 要求。请使用 `--enable-offload` 参数启用 CPU offload 模式。"
+
+### 代码示例
+
+```python
+# 在运行 GPU-only benchmark 之前
+import subprocess
+result = subprocess.run(
+    ["nvidia-smi", "--query-gpu=memory.total", "--format=csv,noheader,nounits"],
+    capture_output=True, text=True
+)
+vram_mb = int(result.stdout.strip().split('\n')[0])
+if vram_mb < 40000:  # 40GB = 40000MB
+    raise RuntimeError(f"GPU VRAM ({vram_mb}MB) < 40GB. Use --enable-offload for this GPU.")
+```
+
+### 适用范围
+
+| 脚本 | 适用此规则 |
+|------|-----------|
+| `bench.py` | ✅ 必须检查显存 |
+| `bench_offload.py` | ❌ 不适用（始终使用 offload） |
+| `tests/test_*.py --enable-offload` | ❌ 不适用 |
+| `tests/test_*.py` (无 offload) | ✅ 必须检查显存 |