# Ml Pitfall Audit

> 新项目/新模型上线前的六问前提审查清单。报告"指标虚高""线下好线上崩""加数据反而 变差""结果不可复现"，或上线/投稿前需健全性检查时调用。六问：训练数据无偏采样吗/ 测试错误率独立采样吗/分布形式假设对吗/集成个体误差独立吗/未标记样本同分布且相似→ 相似吗/完美表现是不是信息泄露。每问配诊断信号+修正方案。不适用于已定位的单一技术 问题、纯工程bug。trigger: data leakage, 数据穿越, assumption check, 线下线上 不一致, offline online gap, too good to be true, sanity check, 审稿被质疑。

- Skill: `fieldlu/ml-pitfall-audit` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add fieldlu/ml-pitfall-audit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/fieldlu/ml-pitfall-audit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: fieldlu (https://skillmd.com/u/fieldlu)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/fieldlu/ml-pitfall-audit

---


# ML 前提审计清单 (Pitfall Audit)

## R — 原文 (Reading)

> "此类方法有一个关键：模型假设必须准确，即假设的生成式模型必须与真实数据分布吻合；
> 否则利用未标记数据反倒会降低泛化性能。遗憾的是，在现实任务中往往很难事先做出准确的
> 模型假设，除非拥有充分可靠的领域知识。"
>
> — 周志华《机器学习》第13章13.2节

> "再缩放的思想虽简单，但实际操作却并不平凡，主要因为'训练集是真实样本总体的无偏采样'
> 这个假设往往并不成立，也就是说，我们未必能有效地基于训练集观测几率来推断出真实几率。"
>
> — 周志华《机器学习》第3章3.6节

---

## I — 方法论骨架 (Interpretation)

机器学习教科书教的是"前提成立时怎么办"；这个 skill 处理的是**前提本身塌了**的情形。书里每个流行技巧背后都藏着一个几乎从不被检查的前提：再缩放假设训练集无偏采样(x18)、交叉验证 t 检验假设错误率独立采样(x11)、极大似然假设分布族正确(x27)、集成指数下降假设误差独立(x32)、半监督假设未标记样本同分布且"相似样本相似输出"(x45)、一切离线评估假设没有信息泄露(x15/x43)。这些前提单独看都是某章的一个脚注，但它们共享同一个结构：**结论的有效范围由一条未被观测的假设决定，且假设失效时的症状恰好长得像"方法不太行"或"运气不错"**——于是被误诊为调参问题或好消息。本 skill 把六个前提聚成一张上线前检查表：每一问都有明确的诊断信号（可观测）、失效后果（可预期）与修正动作（可执行），把"事后翻车归因"前移为"事前三十秒审查"。

---

## A1 — 书中的应用 (Past Application)

### 案例 1: 半监督的反噬警告 (x45, 配 c32)
- **问题**: 西瓜地里只有少量瓜知道好坏（有标记），大量瓜不知道——直接利用未标记瓜一定能提升模型吗？
- **方法论的使用**: 作者先摆出正面机制（聚类假设/流形假设桥接有标记与未标记），随即给出惊悚反转：生成式方法的模型假设不准时，海量未标记数据会把模型拽偏，泛化性能**下降**而非上升；并介绍 S4VM 式最坏情形保护。
- **结论**: 未标记数据不是免费午餐，使用前必须验证桥接假设，并保留纯监督基线对照。
- **结果**: "假设错了会倒扣分"成为全书前提审查主题最强的跨章证据之一。

### 案例 2: 高维小样本下的完美表现 (x15 并入 x43)
- **问题**: p/n=50 的回归任务 R²=0.95、线性 SVM 训练精度 100%——该高兴吗？
- **方法论的使用**: 作者指出高维小样本下普通最小二乘秩亏、闭式解失效，解凭实现细节随机；而"完美线性可分"可能恰是过拟合假象（升维总能分开=记住噪声）。
- **结论**: 训练集满分是红旗不是捷报；动作是加正则、调小 C、交叉验证复核，而非庆祝上线。
- **结果**: 与验证集设计纪律合并，构成第六问"完美表现是不是泄露/过拟合"的诊断原型。

---

## A2 — 触发场景 (Future Trigger) ★

### 用户会在什么情境下需要这个 skill?

1. 离线 AUC 涨了 5 个点、上线后效果持平甚至下跌，找不到原因。
2. 模型表现"好得不真实"（99%+ 准确率、R²=0.95 on p≫n），想确认是不是哪里出了问题。
3. 论文投稿前自查，或审稿人质疑"10 折 CV 的 t 检验 p 值""训练集采样方式"。
4. 加了一大批无标注数据做自训练/伪标签，验证集却掉了两个点。
5. 项目交接 review：接手别人的模型准备上线，需要快速判断评估流程是否可信。

### 语言信号 (用户的话里出现这些就应激活)

- "too good to be true / 好得不像话 / 是不是数据泄露 / data leakage / 数据穿越"
- "offline 好线上差 / 线上线下不一致 / why does it fail in production"
- "帮我检查一下这个实验有没有问题 / sanity check / review 我的 pipeline"
- "加了伪标签反而变差 / semi-supervised hurt performance"
- "审稿人质疑我的显著性检验 / reviewer questioned the t-test"

### 与相邻 skill 的区分（定稿口径）

- 与各专项 skill (`ml-imbalanced-learning`/`ml-dimensionality`/`ml-bayesian-thinking`) 的区别（contrasts-with，"问前提 vs 干活"的分界）：它们各自深挖一个领域的技术执行；本 skill 只负责横切的第一步——判断"你信以为真的数字是否建立在塌掉的前提上"，定位病灶后转介给专项 skill 深修。六问与专项的对应：问 1(x18)→imbalanced、问 3(x27)→bayesian、问 6(x15/x43)→dimensionality。
- 与 `ml-evaluation-design` 的区别: 那是主动的前置设计框架；本 skill 是横向的前提审查清单（含其 x11/x18 两条深坑的跨域延伸）——设计时用尺子，交付前用审计。evaluation-design 完成且模型要交付时，router 会追加本 skill 作收尾闸门。
- 与 `ml-theory-compass` 的区别：理论罗盘回答"理论什么时候能用"的建设性问题；本 skill 回答"实践什么时候会骗你"的防御性问题——一个画地图，一个查塌方。

---

## E — 可执行步骤 (Execution)

当 skill 被激活后, agent 应按以下步骤执行:

1. **采集事实底座**
   - 完成标准: 向用户确认六项事实——(a) 数据来源与采集方式；(b) 训练/验证/测试划分流程；(c) 所用性能度量；(d) 模型族与关键超参数设定；(e) 是否用了未标注数据/集成/概率分布假设；(f) 报告中的"好"具体指什么数字。任一项无法确认则列为待查项。
   - 判停条件: 若用户报告的数字本身来自已知的错误流程（如用训练集评估、测试集参与过调参），无需过六问，直接判定"评估无效"并给出重评方案。

2. **过六问清单（逐问答，不停留在"应该没问题"）**

   **问 1 — 训练数据是无偏采样吗？**(x18)
   - 诊断信号: 数据来自选择性上报/用户主动行为/历史筛选（已报警案件、已审批贷款）。
   - 失效后果: 再缩放/阈值移动方向移错；模型学到上报偏差而非真实规律。
   - 修正: 用领域代价比替代观测几率，或引入随机对照样本重新校准。

   **问 2 — 测试错误率是独立采样吗？**(x11)
   - 诊断信号: 用 k 折 CV 配普通 t 检验比较算法；k 折间训练集高度重叠。
   - 失效后果: 方差被低估、显著性被夸大，"显著提升"实为噪声。
   - 修正: 改 5×2 交叉验证或 McNemar 检验；k 较小时注意 McNemar 倾向"无差别"。

   **问 3 — 分布形式假设对吗？**(x27)
   - 诊断信号: MLE/GMM/生成式方法默认了高斯等分布族但从未画图验证；残差重尾。
   - 失效后果: "假设错了"伪装成"参数没调好"，估计系统性偏向错误方向。
   - 修正: Q-Q 图/拟合优度检验论证分布形式；重尾改厚尾或非参方法。

   **问 4 — 集成个体误差独立吗？**(x32)
   - 诊断信号: 引用"T 个分类器误差指数下降趋零"作理论依据；成员只换了随机种子。
   - 失效后果: 预期收益建立在现实中不成立的前提上，堆数量替代造多样性白费算力。
   - 修正: 测成员分歧度，改从扰动通道制造差异。

   **问 5 — 未标记样本同分布且相似→相似吗？**(x45)
   - 诊断信号: 自训练/伪标签/生成式半监督；类别分布漂移或桥接假设未验证。
   - 失效后果: 未标记数据反噬，泛化性能下降（越训越歪的自我强化）。
   - 修正: 先跑纯监督基线对照；验证聚类/流形假设；考虑 S4VM 式最坏情形保护。

   **问 6 — 完美表现是信息泄露吗？**(x15/x43)
   - 诊断信号: 特征含目标的时间后视信息/全局统计量/ID 类列；p≫n 时训练精度 100%；Stacking 初级预测来自整个训练集。
   - 失效后果: 线下虚高线上崩；高维小样本满分是秩亏+过拟合双重症状。
   - 修正: 特征时间戳审计；out-of-fold 产生次级训练集；高维小样本默认加罚并用 held-out 复核。

   - 完成标准: 六问全部给出 PASS/FAIL/WAIVED 判定及证据行；任何一问 FAIL 即产出对应修正动作。
   - 判停条件: 若问 6 命中"特征含目标的时间后视信息/全局统计量泄露"，立即停止后续各问（结论已反转，其余前提无审计意义），直接转入修复方案。

3. **汇总审计报告**
   - 完成标准: 按"致命(结论反转)/严重(数字虚高)/提示(声明即可)"三级输出发现；FAIL 项转介对应专项 skill 或给出修复优先级排序；全程保留原始证据引用以便复查。

---

## B — 边界 (Boundary) ★

### 不要在以下情况使用此 skill

- 问题已明确定位（如"就是类别不平衡导致 accuracy 虚高"）——直接用专项 skill 修复，审计清单是重复劳动。
- 纯软件工程 bug（内存溢出、特征表 join 错 key）——那是 systematic-debugging 的辖区。
- 用户只是想提升指标而不是怀疑指标——审计是防御性动作，不能当优化手段。

### 作者在书中警告的失败模式

- 六个前提失效本身就是本 skill 的素材库：x18 观测几率≠真实几率、x11 CV-t 检验独立性破坏、x27 MLE 分布猜错、x32 误差独立不成立、x45 半监督反噬、x15+x43 泄露与秩亏满分。
- 元教训：**修复动作也会引入新失败模式**（x17 过采样复制过拟合、x36 Stacking 泄露）——修完第一轮后应复审一轮。

### 作者的盲点 / 时代局限

- 全书 i.i.d. 假设贯穿，对分布漂移/域适应只有只言片语——生产环境最常见的第七种前提失效（训练分布≠未来分布）书中无系统处理，本 skill 使用时应自行补问。
- 工程侧的数据质量管理、特征管道版本化、线上-线下一致性监控不在书内，审计发现泄露后的修复需借助书外工程知识。

### 容易混淆的邻近方法论

- **前提审计 vs 敏感性分析**: 审计问"假设成立吗"(定性判定)，敏感性分析问"假设错一点结论动多少"(定量刻画)——审计先行，敏感分析跟进。
- **审计 vs 单元测试**: 测试验证代码按设计运行；审计验证设计本身的假设是否成立——代码全绿不代表审计通过。

---

## 相关 skills

- depends-on: 无（入口型 skill；router 在"即将上线/结果可疑"信号出现时主动追加它作横向检查）
- contrasts-with: ml-theory-compass（防御面查塌方 vs 建设面画地图）, ml-imbalanced-learning / ml-bayesian-thinking / ml-dimensionality（问前提 vs 干活：问 1/问 3/问 6 的 FAIL 项分别转介）
- composes-with: ml-evaluation-design（其 x11/x18 深坑的前提兜底；交付前收尾闸门）, ml-ensemble-design（问 4"误差独立"的深挖执行版在此）

---

## 审计信息

- **验证通过**: V1 ✓ / V2 ✓ / V3 ✓
- **素材单元**: x18, x11, x27, x32, x45(+c32), x15/x43 / c08(代价不对称作为问 1 的场景延伸)
- **skill_version**: 0.0.1
- **蒸馏时间**: 2026-08-24