Deep Learning Paper Replication Skill

读取深度学习论文（PDF 或文本），将论文中的数学描述、网络结构和实现细节转化为可运行、可验证、可维护的 PyTorch 代码与配套文档。

Core Objective

• 先理解论文的核心问题、创新点、数学公式和超参数。

• 再用 Mermaid 可视化关键数据流和张量形状。

• 最后输出工业级 PyTorch 实现，并在需要时生成模块级技术文档。

Workflow

根据用户需求和论文复杂度，选择合适的执行模式：

• 完整模式（默认）：执行全部 4 个 Phase，适用于复杂模型的完整复现。

• 快速模式：用户明确只需要代码时，跳过 Phase 4（文档生成）。

• 代码优先模式：用户已理解论文时，简化 Phase 1 的解构，重点执行 Phase 3。

对于简单模型（如 MLP、单层网络），自动简化：

• Phase 2 的 Mermaid 图使用简化版本。

• Phase 4 的文档结构按需裁剪，不强制生成所有子目录。

Phase 1: 论文审计与架构解构

输出最小但完整的解构结果：

• 论文概述：一句话问题定义 + 2-4 条核心创新。

• 数学原理：核心公式、符号说明、Loss Function 分析。

• 架构细节：层数、头数、维度、卷积参数、dropout、激活函数、归一化方式。

• 实现缺口：把论文未明确说明的实现细节单独标注，不要伪装成论文原文。

推荐输出骨架：

论文概述

问题 (Problem): ...

核心创新 (Contribution):

1. ...
2. ...

数学原理

核心公式

$$ ... $$

Loss Function

$$ ... $$

架构细节

Phase 2: 架构流程可视化

使用 Mermaid 展示论文的数据流，至少覆盖：

• 输入和输出节点。

• Backbone / Encoder / Decoder / Neck / Head / Loss 中的关键路径。

• 关键节点的 Input/Output Tensor Shape，统一使用 [B, C, H, W] 、[B, N, D] 等标准符号。

• 深层网络用模块级粒度，不机械展开所有层。

颜色规范：

• Blue #e1f5fe ：输入/输出节点。

• Orange #fff3e0 ：核心处理模块。

• Green #e8f5e9 ：特征提取或缓存模块。

• Pink #fce4ec ：注意力机制。

• Purple #f3e5f5 ：Loss 或聚合节点。

简单模型可使用简化图；复杂模型优先画模块关系图，再补张量形状变化图。

Phase 3: PyTorch 实现

实现代码时遵循以下要点：

• 继承 torch.nn.Module ，并给核心类加清晰 docstring。

• 严格使用类型提示。

• 在关键运算后显式标注张量形状变化。

• 把复杂子模块拆分为独立 class 或 modules/ 子文件。

• 提供 _init_weights 或等价初始化逻辑，并注明来源。

• 提供 set_seed 或等价可复现性配置。

• 在文件尾部附带最小可运行验证代码：前向传播、shape 检查、参数量检查、梯度流检查。

• 对于论文未说明的超参数，显式标注 Paper did not specify ，同时写明推荐值、参考来源、备选值和潜在影响。

完整编码规范、验证模板和 Paper did not specify 协议见 references/CODING_STANDARD.md 。

Phase 4: 模块文档生成

为每个核心模块生成技术文档，包含：

• 概述：功能、架构位置、输入输出规格。

• 数学原理：公式、符号说明、必要时给推导。

• 数据流图：Mermaid 流程图 + 张量形状变化。

• 实现细节：关键代码、超参数、设计决策。

• 使用示例：调用方式和输入输出示例。

• 注意事项：常见问题、性能考量、与论文差异。

详细文档规范和 Mermaid 模板见 references/DOCUMENTATION_GUIDE.md 。

Tensor Shape Notation Standard

整个复现过程统一使用以下维度符号：

符号 含义

B

Batch size

C

Channels

H , W

Height / Width

T

Time or sequence length

D

Feature dimension

N

Number of elements / tokens

E

Embedding dimension

K

Kernel size

注释格式统一为：

x: [B, C, H, W] <- Input tensor

x: [B, 64, H//2, W//2] <- Conv2d(C, 64, k=3, s=2, p=1)

Output Structure

根据模型复杂度自适应调整输出结构：

简单模型（单文件即可表达，如 MLP、简单 CNN）：

output/ ├── model.py └── README.md

中等模型（需要子模块拆分）：

output/ ├── model.py ├── modules/ └── README.md

复杂模型（完整复现，如 Transformer、检测网络）：

output/ ├── README.md ├── docs/ ├── model.py ├── modules/ ├── config.py └── requirements.txt

如果论文存在训练、推理、配置三条明显边界，可以进一步拆出 train.py 、infer.py 、configs/ ，但仅在复杂度确实需要时这样做。

Reading Strategy

• 先读主论文，再按需读 Appendix 或 Supplementary。

• 先以文字描述、公式和伪代码为准，再用图表做交叉验证。

• 如果官方代码存在，优先用官方代码校正文中歧义，并在注释中说明差异。

• 对于 Supplementary Material / Appendix 的单独文件，优先读取主论文，再补充查找详细超参数、额外消融和完整伪代码；凡来自补充材料的实现细节，标注 Reference: Supplementary Section X 。

更多 PDF 阅读要点和常见陷阱见 references/COMMON_PITFALLS.md 。

Constraints

Tool Stack

• Python 3.10+

• PyTorch 2.0+

• Mermaid

• einops （可选）

• timm （可选）

Language Rules

• 分析与解释使用简体中文。

• 代码注释使用英文。

• 变量命名使用英文并遵循 PEP 8。

Verification Checklist

在结束前确认：

Phase 1

• 核心问题和创新点已明确。

• 关键公式、损失函数和符号说明已提取。

• 超参数配置完整，未指定项已显式标注。

Phase 2

• Mermaid 图覆盖主要组件。

• 关键节点标注了 Tensor Shape。

• 深层网络使用了合适粒度。

Phase 3

• 实现继承 nn.Module 。

• 类型提示完整。

• 关键层后有维度注释。

• 子模块边界清晰。

• 初始化、随机种子和验证代码齐全。

Phase 4（如启用）

• 每个核心模块有对应文档。

• 文档覆盖概述、数学、流程图、实现、示例、注意事项。

• 文档结构与模型复杂度相匹配，不过度生成。

Runtime Validation

• 随机 Tensor 前向传播正常。

• 输出 Shape 与预期一致。

• 参数量与论文或官方实现基本一致（如可比）。

• 梯度流检查通过。

• 已排查关键实现陷阱和框架差异。

References

• references/CODING_STANDARD.md

何时读取：开始写代码前，或需要补全验证模板时。

• references/DOCUMENTATION_GUIDE.md

何时读取：需要生成 docs/ 、模块文档或 Mermaid 模板时。

• references/COMMON_PITFALLS.md

何时读取：读取 PDF、比对论文与代码、处理框架差异、查缺失细节时。