经验管理：如何让下一次更快
经验管理：如何让下一次更快
引子
踩完 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，避免残留导致 OOMimportgcimporttorch# GPU 任务完成后清理torch.cuda.empty_cache()gc.collect()print(f"VRAM 剩余:{torch.cuda.memory_reserved()/1e9:.2f}GB")L4：失败后结构化复盘（防止"踩了白踩"）
五列记录法：
| 问题 | 原因 | 分类 | 解决方案 | 制度修订 |
|---|---|---|---|---|
| conda 静默失效 | Windows shell 兼容性 | 环境 | 改用绝对路径 | 补入 L1 |
| CPU 版 PyTorch | -i 覆盖索引 | 包管理 | –extra-index-url | 补入 L2 |
| 底模 404 | 仓库下架 | 外部资源 | ModelScope 替代 | 补入 L2 |
- 全局问题补入通用检查清单
- 专属问题记录到项目文档
- 发现制度缺陷，提修订提案
R1 & R2：最先落地的两条规则
R1 下载三要素：任何下载回复强制附带文件数 / 总大小 / 预计耗时。
R2 大模型下载最小化：
确认加载方式 → 列出所需文件清单 → allow_patterns 过滤 → 禁止全量 snapshot_download管理办法的由来
这套东西的正式名称叫《项目经验管理办法》，不是凭空想的，是因为 12 个问题里 8 个是全局通用问题——今天做 SD 踩的坑，明天做 LLM 推理、做语音合成、做任何大模型项目，大概率还会踩一遍。
制度的价值不是约束当下，而是让下一次更快。
下一章收个尾，聊聊感想。