FastAPI 服务遇到显存不足,一个常见原因是 PyTorch 的 CUDA 缓存不会在请求结束后自动归还。要解决这个问题,可以主动加一个空闲超时清理机制:服务连续空闲超过设定时间后,清理 GPU 缓存或卸载模型。这个方法只针对你能控制的进程,不是所有 OOM 场景都适用。
前置确认:先判断是缓存残留还是模型占用
在加空闲回收前,先运行 nvidia-smi 查看显存占用。找到自己服务的 PID,观察显存变化:如果多次推理后显存持续上涨,大概率是 PyTorch 的空闲缓存块累积;如果显存占用恒定且接近模型体积,问题在模型本身。注意 torch.cuda.empty_cache() 只释放未被引用的缓存,不会把已加载的模型权重从显存里挪走。
在 FastAPI 中加入空闲超时回收
下面是一个可运行的骨架。它用中间件记录最后活跃时间,后台任务按固定周期检查,超过阈值后执行清理。通过环境变量控制是否卸载模型。on_event 在较新版本中可用,生产环境可换为 lifespan 写法。
import asyncio, os, time, torch
from fastapi import FastAPI, Request
app = FastAPI()
IDLE_SECONDS = int(os.getenv("IDLE_GPU_SECONDS", "300"))
CLEANUP_INTERVAL = int(os.getenv("CLEANUP_INTERVAL", "30"))
UNLOAD_ON_IDLE = os.getenv("UNLOAD_ON_IDLE", "0") == "1"
last_active = time.time()
@app.middleware("http")
async def track_activity(request: Request, call_next):
global last_active
last_active = time.time()
return await call_next(request)
def unload_model():
torch.cuda.empty_cache()
# 如果项目里有 global model 引用,需要把 model.cpu() 并置空
async def idle_cleanup():
while True:
await asyncio.sleep(CLEANUP_INTERVAL)
if time.time() - last_active > IDLE_SECONDS:
if UNLOAD_ON_IDLE:
unload_model()
else:
torch.cuda.empty_cache()
@app.on_event("startup")
async def start_cleanup():
asyncio.create_task(idle_cleanup())
这段代码里,IDLE_GPU_SECONDS 是空闲阈值,UNLOAD_ON_IDLE 决定彻底卸载模型还是只清缓存。如果只清缓存,显存碎片会改善,但模型本身占用不会下降。要彻底释放显存,需要在 unload_model() 里把模型权重搬到 CPU 并删除 GPU 上的引用,下次推理前再加载。
参数设置与验证
用环境变量配置空闲时间,例如 IDLE_GPU_SECONDS=180。建议先设成 300 秒,避免误回收。
- 启动服务,发送一次推理请求,记录
nvidia-smi中该 PID 的显存值。 - 等待超过
IDLE_GPU_SECONDS后再nvidia-smi,观察显存是否回落。 - 再次发送请求,确认服务能正常恢复,显存重新上升。
- 如果开了
UNLOAD_ON_IDLE,第一次请求会明显变慢,因为要重新加载模型。
上述验证可以通过脚本或者手动执行。如果显存没有回落,检查是否有其他进程占用,或者代码里还有其他对象持有 CUDA 张量。
失败回退与风险边界
空闲回收不是万能的。它解决的是“显存长时间不归还”的问题,对内存碎片和模型过大导致的 OOM 效果有限。如果回收后服务频繁重新加载模型,推理延迟会大幅增加。建议先只启用 torch.cuda.empty_cache(),观察效果;再考虑彻底卸载模型。回退方案包括:调低并发数、减小 batch size、使用 CUDA_VISIBLE_DEVICES 隔离多进程,或改用 vLLM、Triton 这些自带 GPU 调度机制的推理框架。