经验管理：如何让下一次更快

引子

踩完 12 个坑之后，我做了一件比修 bug 更重要的事：写制度。

不是写给老板看的，是写给下一次的自己看的。

为什么需要制度？

单次踩坑不可怕，可怕的是下次换个人（或者自己忘了）继续踩同一批坑。组织的学习成本不应该被反复支付。

从这 12 个问题出发，我设计了四道防线：

L1：执行前强制校验（防止"没想清楚就干"）

□ 环境确定性：用解释器绝对路径，不依赖 conda activate □ 下载最小化：先确认所需文件清单，用 allow_patterns 精确过滤 □ 三要素披露：任何下载命令必须告知文件数 / 总大小 / 预计耗时 □ 依赖完整性：执行前检查 pip list 确认所有依赖已安装 □ API 兼容性：先查 __version__，再选对应的 API 调用方式

示例——执行前校验脚本：

importsubprocessimportsys# 1. 确认解释器路径print(f"Python:{sys.executable}")# 2. 确认关键依赖版本deps={"torch":"2.5.0","diffusers":None,"peft":None}forpkgindeps:try:mod=__import__(pkg)ver=getattr(mod,"__version__","unknown")print(f"{pkg}:{ver}OK")exceptImportError:print(f"{pkg}: MISSING!")

L2：外部资源预检（防止"资源不可达"）

□ 资源是否存在：HuggingFace 仓库是否有效、URL 是否 404 □ 国内是否可达：是否有 ModelScope / 清华源 / 阿里源等国内替代 □ 是否有备用链路：主方案失败后的 Plan B

示例：

importrequestsdefcheck_repo(repo_id):"""检查 HF/ModelScope 仓库是否可访问"""urls=[f"https://huggingface.co/{repo_id}",f"https://modelscope.cn/models/{repo_id}",]forurlinurls:r=requests.head(url,timeout=10)print(f"{url}:{'OK'ifr.okelse'FAILED'}")

L3：执行中状态感知（防止"跑了等于白跑"）

□ 长任务用后台启动 + 日志轮询，不依赖 shell_executor 的同步返回 □ 每步检查实际产物：文件是否真的生成、模型是否真的加载 □ GPU 任务后主动清理 CUDA context，避免残留导致 OOM

importgcimporttorch# GPU 任务完成后清理torch.cuda.empty_cache()gc.collect()print(f"VRAM 剩余:{torch.cuda.memory_reserved()/1e9:.2f}GB")

L4：失败后结构化复盘（防止"踩了白踩"）

五列记录法：

• 全局问题补入通用检查清单
• 专属问题记录到项目文档
• 发现制度缺陷，提修订提案

R1 & R2：最先落地的两条规则

R1 下载三要素：任何下载回复强制附带文件数 / 总大小 / 预计耗时。

R2 大模型下载最小化：

确认加载方式 → 列出所需文件清单 → allow_patterns 过滤 → 禁止全量 snapshot_download

管理办法的由来

这套东西的正式名称叫《项目经验管理办法》，不是凭空想的，是因为 12 个问题里 8 个是全局通用问题——今天做 SD 踩的坑，明天做 LLM 推理、做语音合成、做任何大模型项目，大概率还会踩一遍。

制度的价值不是约束当下，而是让下一次更快。

下一章收个尾，聊聊感想。