paper-to-code

从论文到代码

将一篇没有发布代码的论文转化为最精简的实现，只回答一个问题：该方法是否如论文所述有效？

输出的是结论，而不是代码库。本技能中的一切都服务于快速证伪：如果方法无效，你希望在一个下午内以玩具规模发现这一点，而不是花一周时间围绕一个有问题的机制搭建基础设施。

何时不使用

• 论文有官方代码 → 改为阅读／审查官方代码（如果要确认已发布的产物能否复现结果，请使用 reproducibility-audit）。
• 用户想将论文中的组件改编到自己的代码库，或设计完整的训练方案 → 使用 pytorch-training-recipe。
• 用户想理解方法，而不是运行方法 → 使用 professor-mentor-technical-teaching 或 flow-deep-understanding。

流程

1. 将论文归纳为一项可测试的主张

在写任何内容之前，先确定复现要测试的单一机制。论文往往包含许多内容（新组件 + 调优后的基线 + 数据技巧）；全部复现成本高昂，而且对于健全性检查来说没有必要。

用一句可证伪的话陈述主张，例如：“将 softmax 注意力替换为机制 X，能在降低内存占用的同时保持准确率”，而不是 “复现表 2”。如果论文提出了多个主张，请先与用户确认这一设定。

然后选择能验证该机制的最小设置：玩具数据集（合成数据、MNIST 规模，或论文数据集的一小部分）、包含该组件的最小模型、较短的训练过程。默认情况下，论文的全规模数值不在范围内。

2. 提取方法

依据论文中的算法框、公式和正文说明。在编写代码之前，先生成两项产物：

符号 → 张量表。 对核心公式中的每个符号，记录名称、形状、数据类型／取值范围，以及它的来源。大多数复现错误都源于此处（批次轴还是特征轴、归一化前还是归一化后、求和还是取平均）。代码中的变量名应与论文符号一致（如 alpha、z_t、H），这样就能逐行对照论文阅读代码。

假设记录表。 论文总会省略细节：初始化方案、归一化顺序、dropout 的位置、学习率预热、损失项是取平均还是求和、“标准数据增强”的具体形式。对于每个未充分说明的细节，都记录：缺失之处、所选假设、选择理由（常见默认做法、引用的先前工作、消融实验暗示），以及结果可能对此有多敏感。阅读 references/underspecified-defaults.md，了解常见缺失项、合理默认做法和敏感度评级目录——复现失败时，高敏感度条目是首先要排查的对象。假设记录表应随结论一同提供：记录完整假设的失败复现是有关论文的证据；没有记录的失败复现只能说明你的猜测有误。

如果某个细节既是关键因素，又无法推断（缺少它就无法实现该机制），请停下来告知用户，不要默默自行编造。

3. 尽量精简地实现

使用直接、易读的单文件 PyTorch。之所以制定这些风格规则，是因为代码唯一的任务就是让人能够对照论文进行检查：

• 一个文件（reproduce_<method>.py），除非确实无法放下：依次包含模型、数据、训练循环和评估。不要使用配置系统、命令行框架，也不要为假想的复用场景增加抽象。超参数以普通字典或常量的形式放在顶部，并注明来源（论文 §4.1、假设 #3 等）。
• 纯 PyTorch，不使用 Lightning／框架封装——每一行都应对应论文中的内容或有据可查的假设。
• 核心机制单独设为一个类或函数，并在注释中标出论文中的公式编号，以便各关卡单独测试它。
• 朴素基线是实现的一部分，而不是事后补充：同一脚本必须能通过一个标志运行消融版／标准版（例如用常规注意力替代机制 X），因为第 5 步的结论需要比较。
• 固定随机种子；在开销较低时确保确定性；打印／记录各关卡所需的少量数值——不需要实验跟踪框架。

4. 分阶段验证关卡

按顺序运行各关卡；任何一关未通过，都不要继续。每一关都用于在不同类型的故障伪装成“该方法不起作用”之前，将其定位出来。

关卡 1 — 机制正确性。 单独对核心组件进行单元级检查：测试几种输入形状下的输出形状；确认梯度能传到所有参数（执行一次反向传播后，.grad 不为 None，且并非全为零）；检查论文声明的任何不变量（行和为 1、输出是有效概率、等变性、X 守恒）。用于发现实现错误。

关卡 2 — 拟合能力。 对一个小批次（8–32 个样本）进行过拟合：损失必须接近 0／准确率达到 100%。如果模型无法记住 16 个样本，说明损失函数有误、计算图已断开，或数据有问题——而不是方法表现不佳。用于发现连接错误。

关卡 3 — 机制效果。 真正的测试：在玩具规模下比较方法与朴素基线，使用相同预算和相同的随机种子策略（如果效果较小，至少使用 3 个随机种子）。通过标准是方向性的：论文所声称的效果是否出现（方法优于基线／内存占用更低／收敛更快）？玩具规模下的效果大小不会与论文相符，这很正常。

关卡 4 — 锚点（可选）。 如果论文报告了容易实现的数值（例如消融表中的小配置结果），尝试将结果控制在其合理范围内。这能提高结论的可信度，但不是健全性检查的必要条件。

5. 结论

最后给出明确结论，三选一：

• **在玩具规模下符合预期：**观察到了方向性效果；说明观察到的效果，以及该效果依赖哪些假设。
• **未能复现：**关卡 1–2 已通过，但效果未出现或方向相反；列出最可能需要负责的假设账本条目；如果有任何条目可以低成本调整，请在最终定论前测试调整后的结果。
• **无法确定：**有一项关键细节无法推断，或玩具规模无法验证该主张（例如该机制只有在长上下文／大宽度下才起作用）。说明需要哪些条件才能作出判断。

输出格式

按以下顺序提交：

1. 待验证的主张（一句话）以及所选的玩具设置。
2. 假设账本（表格：差异／假设／依据／敏感度）。
3. 实现（单文件，可通过 python reproduce_<method>.py 运行）。
4. 各关卡结果（逐关注明通过／未通过及数值）。
5. 结论，并给出上述要求的推理过程。

如果用户只想先看计划（暂不需要代码），则在第 1–2 项之后停止，并先征求确认，再进行实现。