可复现性

可复现的五要素：固定的代码版本、数据版本与预处理、环境（依赖锁定/容器）、随机种子、完整配置。本章给出可复现研究项目的目录结构、实验记录规范，以及 ML 中"设了种子仍不可复现"的原因（非确定性算子）。

五要素

可复现的结果应能追溯到五个要素：

1. 代码版本：固定的 commit（见研究代码的组织）；
2. 数据版本与预处理：数据从哪来、哪个版本、预处理脚本与顺序；
3. 环境：依赖锁定（conda/uv lockfile）或容器（Docker），关键库（框架、CUDA、驱动）的版本；
4. 随机种子：初始化、数据顺序、采样等所有随机源；
5. 完整配置：训练与评测的全部超参，代码之外的任何开关都要在配置里。

每个结果都应能追溯到 commit + 配置 + 数据版本。反过来说：任何一个结果，如果三者拼不齐，它就不可复现——将来写论文、做 rebuttal、发 artifact 时都会缺证据。

项目结构与记录

一个可复现研究项目的最小结构：

project/
  configs/          # 每个实验一个配置文件，命名含日期与目的
  src/              # 代码
  scripts/          # 运行入口：python run.py --config configs/xxx.yaml
  results/          # 自动生成：指标、日志、检查点，按实验 ID 归档
  data/             # 数据（版本固定，预处理脚本单独存）
  README.md         # 复现步骤：环境 → 数据 → 命令 → 预期结果

记录规范：每个实验有唯一 ID；结果目录由代码自动创建并写配置快照；表格中的每个数字都能用 ID 找回原始日志。工具组合见实验管理与代码工具。

ML 的特殊情况：设了种子仍不可复现

GPU 上的某些算子默认非确定性：浮点并行归约的顺序不定、原子操作、框架的非确定性 kernel。即使固定种子，跨 run/跨硬件仍可能有微小差异，长训练中会被放大。对策：

• 框架层的确定性开关（如 PyTorch 的 deterministic 模式）能换来逐位可复现，但常牺牲速度——用于关键对比；
• 更务实的标准是统计可复现：多种子均值与方差可复现（见统计显著性与效应量），而非逐位一致；
• 报告硬件与库版本，让读者能判断非确定性的范围。

提交时的复现清单

顶会多有复现清单（如 NeurIPS Paper Checklist）。投稿前的自查：代码与依赖能否让陌生人跑起来？数据能否获得或重建？每个表能否追溯到配置？变体与种子是否记录完整？对外发布的版本要过一遍 artifact 标准（见开源、复现包与 Artifact 评估）。

本章要点

• 每个结果都应能追溯到 commit + 配置 + 数据版本
• GPU 上的某些算子默认非确定性
• 论文提交时的复现清单（NeurIPS checklist）