在 Jupyter 中使用 vLLM 加载大语言模型后，即使删除 llm 对象并调用 torch.cuda.empty_cache()，GPU 显存仍可能被残留进程持续占用，导致后续实例化失败（OOM）。本文提供安全、可靠且可复现的显存清理方案。
在 jupyter 中使用 vllm 加载大语言模型后，即使删除 llm 对象并调用 torch.cuda.empty_cache()，gpu 显存仍可能被残留进程持续占用，导致后续实例化失败（oom）。本文提供安全、可靠且可复现的显存清理方案。
vLLM 在初始化时会启动后台推理引擎（如 AsyncLLMEngine 或独立的 ray/multiprocessing 子进程），这些进程独立于 Python 主线程运行，因此单纯执行 del llm 或 gc.collect() 并不能终止它们——显存将被长期锁定，nvidia-smi 中可见持续占用。
✅ 正确清理步骤如下：
-
显式关闭 vLLM 实例（推荐首选）
若llm对象支持shutdown()方法（vLLM ≥ 0.4.0），应优先调用：llm.shutdown() # 同步关闭推理引擎与所有子进程 del llm torch.cuda.empty_cache()
-
强制终止残留 vLLM 进程（通用兜底方案）
当shutdown()不可用或失效时，需手动清理后台进程。先定位进程：nvidia-smi # 查看哪些 PID 占用 GPU 显存 ps aux | grep -i "vllm\|llm_engine\|ray" # 查找相关进程名
然后精准终止（避免误杀）：
# 推荐：仅杀与当前 notebook 相关的 vLLM 进程（更安全） pkill -f "vllm.entrypoints.api_server" # 若启用了 API server pkill -f "vllm.engine.async_llm_engine" # 或通用方式（谨慎使用） pkill -9 -ef "vllm" # 注意：-9 强制终止，确保无重要任务在运行
-
Jupyter 环境专项建议
- ✅ 每次运行前检查显存：
!nvidia-smi --query-gpu=memory.used,memory.total --format=csv,noheader,nounits - ✅ 避免重复创建
LLM实例；如需多轮测试，复用同一实例并清空请求队列（llm.llm_engine.abort_requests()） - ❌ 不要依赖
%%capture或try/except隐藏错误来“绕过” OOM —— 这只会掩盖进程泄漏问题
- ✅ 每次运行前检查显存：
⚠️ 注意事项：
-
torch.cuda.empty_cache()仅释放缓存（cached memory），不释放已分配（allocated）给 vLLM 引擎的显存； - 使用
bitsandbytes量化时，部分权重可能驻留在 CPU 内存中，但 GPU 引擎仍持有 KV 缓存等核心资源； - 在 Colab / Kaggle 等共享环境中，建议运行完立即重启运行时（Runtime → Restart runtime），确保环境彻底干净。
总结：vLLM 的 GPU 显存释放不是简单的 Python 对象销毁问题，而是进程级资源管理问题。养成“显式 shutdown + 进程核查 + 环境重置”的三步习惯，可稳定规避 OOM，提升开发迭代效率。
