Qwen3 显存不足解决 — OOM 报错的五种排查方向

症状

典型报错：

CUDA out of memory. Tried to allocate XX.00 MiB. 
GPU 0 has a total capacity of YY.00 GiB.

或者：

torch.cuda.OutOfMemoryError: CUDA out of memory

解决方案（按优先级排序）

1. 换更小的模型规格

最直接也最有效：

你的显存	推荐模型
≤ 8GB	Qwen3-0.6B / 1.7B / 4B（量化）
16GB	Qwen3-4B / 8B（量化）
24GB	Qwen3-8B / 14B（量化）
48GB	Qwen3-32B / 30B-A3B（量化）

2. 用 4bit / 8bit 量化

把原生 FP16 模型量化：

# AWQ 4bit 加载
from transformers import AutoModelForCausalLM, BitsAndBytesConfig

quant_config = BitsAndBytesConfig(load_in_4bit=True, ...)
model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-8B", quantization_config=quant_config
)

或者直接用 Hugging Face 上已量化的版本（模型名带 -AWQ、-GPTQ）。

3. 降低上下文长度

上下文长度 = KV Cache = 显存。Qwen3-8B 默认支持 128K，但大多数场景用不到。

# Transformers 中限制
model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-8B",
    max_position_embeddings=8192  # 只需要 8K 就设 8K
)

# SGLang / vLLM 启动时
python -m sglang.launch_server \
    --model-path Qwen/Qwen3-8B \
    --context-length 8192

4. 开启思考模式会增加显存

思考模式生成思考链，这些 token 会占用 KV Cache。如果显存紧张：

关闭思考模式（enable_thinking=False）
或限制思考 token 上限

5. 手动管理 GPU 内存

import torch
torch.cuda.empty_cache()  # 清空缓存

# 减少 KV Cache 预留
torch.cuda.set_per_process_memory_fraction(0.8)  # 只用 80% 显存

6. 多卡分摊

如果有多张 GPU，用 device_map="auto" 让模型跨卡加载。

7. 换云端 API（零成本）

如果你的 GPU 实在太小，直接用阿里云百炼。qwen3-flash 的小规模调用几乎免费。

显存估算表（FP16）

规格	模型权重	+ 8K KV Cache	+ 128K KV Cache
0.6B	1.2GB	~2GB	N/A（最大 32K）
4B	8GB	~9GB	N/A（最大 32K）
8B	16GB	~17GB	~24GB
14B	28GB	~29GB	~40GB
32B	64GB	~65GB	~80GB
30B-A3B	60GB	~61GB	~76GB

量化后（4bit）大约 1/4 到 1/3 的体积。