ml-experiment-standards

ML 实验规范

目的：确保每项 ML 任务（包括快速原型）都可复现、无数据泄漏，且指标选择有依据。这些并非可有可无的润色；通常，任何一项被跳过，最终都会演变成“模型在生产环境中崩溃了”或“结果无法复现”。

1. 先做 EDA

在训练任何模型之前，先生成并展示：分布、缺失率、异常值、目标类别分布、显著相关性。指标和损失函数的选择取决于这些信息；没有 EDA 就推荐模型，无异于猜测。

2. 泄漏审查

每次决定如何划分数据时，都要明确回答（并将答案写成代码注释）：“训练集是否包含任何测试样本的间接信息？”

数据类型	正确的划分方式	原因
独立样本	分层 k 折	保持类别比例
时间序列	TimeSeriesSplit / walk-forward	不能让未来信息泄漏到过去
空间数据	空间分块交叉验证（Spatial block CV）——参见 references/spatial-cv-protocol.md	邻近样本几乎是重复数据
分组数据（患者、地块、场景）	GroupKFold	同一组不能跨越不同数据集划分

• 缩放器／编码器／插补器只能在训练集上拟合；可靠的做法是使用 sklearn.pipeline.Pipeline——交叉验证会因此自动正确拟合。
• 基于目标值生成的特征（目标编码等）必须通过折外方式计算，并展示这一过程。

references/spatial-cv-protocol.md 中的空间协议是本仓库唯一的规范来源——其他技能应链接到这里；不要重复描述。

3. 指标选择——有理有据

切勿默认选择某个指标；请用一句话说明理由：

• 类别不平衡 → F1 / AUC-PR，而非准确率（准确率会奖励对多数类的记忆）。
• 分割 → IoU/Dice（像素准确率会因背景而虚高）。
• 回归 → RMSE（对大误差敏感）、MAE（稳健）或 R²（解释的方差）——应根据使用场景说明选择理由。
• 每个点估计都要附带不确定性：bootstrap CI 或跨 CV 折的均值 ± 标准差。单个数字无法体现差异究竟是信号还是噪声。

4. 可复现性基本框架

每个训练脚本都遵循以下结构（以脚本为先；不依赖 Notebook 魔法）：

"""Experiment: <name>. Goal and success criterion: <one sentence>."""
from dataclasses import dataclass, asdict
import json, random
import numpy as np

@dataclass
class Config:
    seed: int = 42
    lr: float = 1e-3
    batch_size: int = 32
    epochs: int = 100
    patience: int = 10  # early stopping

def set_seed(seed: int) -> None:
    random.seed(seed)
    np.random.seed(seed)
    # if torch: torch.manual_seed(seed); torch.cuda.manual_seed_all(seed)

def main(cfg: Config) -> None:
    set_seed(cfg.seed)
    ...  # data -> split -> pipeline -> train -> evaluate
    with open("runs/run_meta.json", "w", encoding="utf-8") as f:
        json.dump({"config": asdict(cfg), "metrics": metrics}, f, indent=2)

if __name__ == "__main__":
    main(Config())

• 配置存放在 dataclass/YAML 中，绝不硬编码——参数搜索和运行结果比较都依赖它。
• 固定库版本（pip freeze > requirements.txt）。
• 如有条件，使用 MLflow/W&B；上述 JSON 日志是最低要求。

5. 深度学习的额外要求

• 损失函数的理由：类别不平衡的分割任务使用 Dice/Dice+CE；说明原因。只有经过比较后才能使用 Focal——它并非必胜方案。
• 数据增强的理由：说明哪些变换符合问题的物理规律（依赖方向的任务不能使用某些旋转；多光谱任务不能盲目使用颜色抖动）。
• 过拟合控制：使用带耐心值的提前停止，并在报告中附上训练／验证曲线；没有曲线，就不能说“模型效果很好”。
• 模型容量顺序：先从小模型和简单基线开始（逻辑回归、RF）；如果深度模型无法胜过基线，问题出在数据，而不是架构。
• EO 特定的切片／推理细节 → geo-deep-learning。

6. 系统背景（MLOps）

用一段话说明每个模型在整个链路中的位置：数据源 → 清洗 → 特征／版本管理 → 训练 → 评估 → 部署（批处理／实时）→ 监控（数据／模型漂移）。即使是原型，也要说明“这一步在生产环境中会变成什么”。

7. 报告格式

## Experiment: <name>
- Data: n=<>, split: <strategy + rationale>
- Baseline: <model> → <metric ± CI>
- Model: <model> → <metric ± CI>
- Leakage audit: <what was checked>
- Next step: <single recommendation>

报告差异时应遵循统计诚信：如果差距未超过跨折标准差，就说“没有明显差异”——不要 p-hacking，也不要选择性报告。

执行约定

• 工作流： 定义预测目标和决策用途；建立基线；审查数据泄漏；创建空间上有效的划分；以可复现的方式训练；量化不确定性；检查错误和部署适用性。
• 决策规则： 仅将此技能用于预测模型实验；使用空间统计进行推断，使用地统计学估计采样表面，并在无需强行拟合模型时进行描述性分析。
• 验证协议： 在干净环境中复现；跨折或随机种子与基线进行比较；检查空间残差；验证划分独立性；测试最终决策阈值。
• 失效模式： 若存在数据泄漏、划分后预处理、不恰当的指标、测试单元不独立、选择性运行或训练与服务偏差，则相关性能提升声明无效。
• 交付物： 实验配置、划分与随机种子清单、包含不确定性的基线和模型指标、数据泄漏审查、错误分析、制品以及部署注意事项。
• 来源时效性： 使用对版本敏感的划分、指标或可复现性 API 前，请查阅权威来源注册表。