1-复现笔记模板

概述与定位

一句话定位: 本模板提供系统性记录论文复现过程的结构化框架，确保实验可复现性和知识积累。

** prerequisites **

机器学习研究基础
Git/GitHub使用经验
实验记录习惯

核心直觉

论文复现是将理论转化为实践的关键步骤，但缺乏系统化记录会导致：（1）相同错误重复出现；（2）超参数选择不可追溯；（3）与他人协作困难。本模板通过结构化记录确保每个复现步骤都有据可查。

为什么需要结构化模板的核心直觉：研究是迭代的，今天记住的实现细节可能在一个月后遗忘。结构化模板确保实验上下文被完整保存，使得重复任何一个历史实验成为可能。

可复现性的核心直觉：可复现不仅是”能跑起来”，而是”能获得论文报告的相近结果”。这需要记录所有影响结果的要素：代码版本、数据版本、超参数、随机种子、硬件环境。

模板结构

1. 论文信息

## 论文信息
- 标题: [论文标题]
- 作者: [作者列表]
- 发表: [会议/期刊, 年份]
- 链接: [论文URL]
- 代码: [代码仓库URL]
- 复现难度: [1-5]

2. 核心贡献总结

## 核心贡献总结
[用2-3句话总结论文的主要贡献和解决的问题]

3. 关键方法

## 关键方法
### 3.1 技术概览
[简要描述方法的核心技术路线]
 
### 3.2 关键公式
[记录关键数学公式及变量定义]
 
### 3.3 与其他工作的区别
[对比related work的核心差异]

4. 代码结构

## 代码结构
project/
├── configs/              # 配置文件
│   ├── default.yaml      # 默认配置
│   └── [experiment].yaml # 实验特定配置
├── src/
│   ├── data/             # 数据处理
│   ├── models/           # 模型定义
│   ├── training/         # 训练逻辑
│   └── utils/            # 工具函数
├── scripts/
│   ├── train.sh          # 训练脚本
│   └── eval.sh          # 评估脚本
├── checkpoints/          # 模型权重
├── logs/                 # 实验日志
└── README.md             # 项目说明

5. 复现步骤

## 复现步骤
 
### 5.1 环境配置
```bash
# 记录安装命令
pip install -r requirements.txt

[记录遇到的问题及解决方案]

5.2 数据准备

数据集来源: [URL/存储位置]
数据版本: [commit hash 或日期]
预处理步骤: [列出预处理命令]

5.3 训练

命令: python train.py --config configs/[config].yaml
关键超参数: [表格记录]
训练时长: [预估/实际]
硬件要求: [GPU/CPU/内存]

5.4 评估

命令: python eval.py --checkpoint checkpoints/[ckpt].pt
评估指标: [列出指标]
预期结果: [论文报告的结果]


### 6. 超参数记录表

| 参数名 | 论文值 | 复现值 | 备注 |
|--------|--------|--------|------|
| learning_rate | 0.001 | 0.001 | - |
| batch_size | 32 | 32 | - |
| hidden_dim | 256 | 256 | - |

### 7. 实验日志

```markdown
## 实验日志

### Exp-001: [实验名称]
- 日期: YYYY-MM-DD
- 目标: [实验目的]
- 配置: [配置文件commit]
- 结果: [数值结果]
- 分析: [结果分析]
- 问题: [遇到的问题]
- 解决: [解决方案]

8. 问题与解决方案

## 问题与解决方案
 
### Q1: [问题描述]
- 原因: [分析原因]
- 解决: [解决方案]
- 参考: [相关资料链接]

复现检查清单

代码层面

代码可以从仓库克隆并运行
所有依赖已记录在 requirements.txt
随机种子已固定（torch.manual_seed, np.random.seed等）
超参数通过配置文件而非硬编码
数据加载使用可复现的方式（固定路径/commit）

实验层面

每个实验有唯一标识符
实验配置已版本化
结果已记录到实验日志
关键指标已保存（JSON/CSV格式）
可视化结果已保存

文档层面

README.md 包含运行说明
代码有必要的注释
关键决策已记录原因
已知问题已记录

复现注意事项

关键文件检查

requirements.txt: 确保所有依赖版本锁定
config/*.yaml: 检查每个超参数是否有注释
seed.py: 确认随机种子设置完整
data_loader.py: 确认数据路径可复现

常见陷阱

随机性未固定: 未设置所有随机种子导致结果不稳定
路径硬编码: 使用绝对路径导致换环境后无法运行
超参数不一致: 微调超参数后未记录导致无法复现
数据版本: 使用不同版本数据导致结果差异

版本控制

# 记录关键版本
git tag exp-001-baseline
git tag exp-002-modified-lr

本章要点总结

结构化模板确保复现步骤完整记录
代码结构标准化便于理解和修改
超参数表格追踪论文值与复现值差异
实验日志记录每次尝试的上下文
问题解决方案库避免重复踩坑
可复现性是科学研究的基础
版本控制保存关键实验状态
代码、配置、数据三位一体记录
定期更新复现笔记形成知识积累
好的记录习惯提升研究效率

关键词

复现笔记模板可复现性研究流程代码结构超参数记录实验日志研究规范最佳实践知识积累科学研究

Huajishe Notes

Explorer