Jupyter Notebook科研笔记与可复现研究：从临时草稿到可交付实验记录
凌晨两点，Notebook 不是草稿纸，而是证词
窗外的风把楼道里的声控灯吹得一明一灭，我盯着屏幕上那页 Jupyter Notebook，像盯着一份快要失效的供词。昨天还跑得通的实验，今天换了台机器就开始报错；同样的图，换了个随机种子，曲线像被夜色揉皱了一样。做科研最难的，常常不是“不会写”，而是“隔了一周，连自己都不敢相信自己”。Jupyter Notebook 本该只是记笔记的地方，可真正成熟的用法，是把它变成一份可复现研究的现场记录：你做了什么、为什么这么做、结果如何、下次怎么原样重来。
如果你在搜“Jupyter Notebook科研笔记教程”或者“Jupyter Notebook怎么用来写实验记录”，先别急着追求花哨模板。先把最关键的三件事做对：环境固定、参数留痕、输出可验证。少了这三样，Notebook 只是漂亮的混乱。
先解决最常见的混乱：环境、版本、随机性
我见过太多笔记本，第一格代码是 import pandas as pd，最后一格却没人知道 pandas 版本是多少。要做可复现研究，Notebook 的第一屏就应该写清楚“证件信息”。最实用的做法，是在开头放一个环境块，自动打印 Python、包版本、系统信息，以及随机种子。比如：
import sys, platform, numpy as np, pandas as pd
print(sys.version)
print(platform.platform())
print("numpy", np.__version__)
print("pandas", pd.__version__)
np.random.seed(42)
如果你用 PyTorch、TensorFlow，也要把 GPU、CUDA、cuDNN 版本记进去。我的经验是，只要你的实验会涉及训练或采样，就别省这个步骤。曾经我把一个模型从本机移到服务器，结果仅仅因为 numpy 从 1.23 升到 1.26，某个浮点处理细节就变了，最后表格里的第四位小数全漂了。看起来很小，可论文审稿时，最怕的往往就是“我复现不出来”。
环境管理优先用免费、官方路线：conda env export > environment.yml，或者更轻量的 pip freeze > requirements.txt。如果项目是长期课题，建议每个 Notebook 配一个独立环境，不要把十几个实验塞进同一个全局环境里。你会发现，科研里最奢侈的不是算力，而是秩序。
把笔记写成“可追踪的实验日志”，而不是流水账
真正好用的 Notebook，不是“代码很多”，而是“每一段代码都能回答一个问题”。我通常会把一页笔记拆成四层：研究问题、数据处理、实验参数、结果解释。这样你在两个月后翻回来，能立刻知道那一格 dropna() 为什么存在，那一张图为什么用了对数坐标。
具体写法上，建议你在 Notebook 里固定保留这些信息：数据来源、下载日期、样本量、过滤规则、训练/测试划分方式、随机种子、评价指标。比如做一个文本分类实验，最少要写清楚“原始数据 12,480 条，去掉缺失标题后剩 11,932 条；按 8:2 分层抽样；F1 作为主指标”。如果你在做“学术论文下载Google Scholar开源社区加速”相关的文献计量分析，也要记录检索式、时间范围和去重规则，否则同一个检索今天和下周的结果都可能不同。
为了让笔记真正可回放，我建议你把“会变的东西”单独放到参数单元里，例如：
SEED = 42
TEST_SIZE = 0.2
MAX_LEN = 256
MODEL_NAME = "bert-base-chinese"
然后下面所有实验都引用这些变量。这样你改一次参数，整个 Notebook 都有迹可循。别小看这一步，它能把“试出来的结论”变成“能解释的结论”。
最后一公里：把 Notebook 变成别人也能跑通的证据
很多人以为可复现研究只等于“代码能跑”，其实不够。你还得让别人知道，怎么跑、跑到什么结果算对、哪里算偏差。一个好习惯是，每个 Notebook 结尾都写一个“验证段”。例如：输出关键统计量、保存中间结果、并给出预期范围。对模型实验来说，我常用的验证方式很朴素：固定种子重跑 3 次，观察指标波动是否在 0.3 个百分点以内；对数据分析来说，则检查输出文件的行数、列名和 hash 是否一致。
你可以这样做一个最小闭环：先用 jupyter nbconvert --execute --to notebook your_notebook.ipynb 在干净环境里整本执行；再导出成 HTML 看图表是否完整；最后删除内核缓存后重跑一次。如果两次结果一致，说明你的记录不是“看起来像”，而是真的可复现。若中间出现不一致，优先排查随机种子、文件路径、时间戳字段和隐藏状态单元。尤其是 Notebook 的执行顺序，最容易埋雷：明明上面没报错，下面却用了昨天残留的变量。
我自己的判断标准很简单：当你能把一份 Notebook 发给同组同学，对方在半小时内跑出同样的核心结果，你的科研笔记就及格了。若能进一步做到“换机器、换时间、换人，结果仍然稳定”，那它就不只是笔记，而是研究的一部分。技术总会更迭，工具也会换名，但一份清清楚楚的实验记录，会像深夜电台里那盏不刺眼的灯，安静地照着你回到真相。若你想在现成工具里继续整理、同步和分享这些笔记，最后也可以把 roxi.cc 当作一个可选方案之一，但别忘了，真正决定研究质量的，始终是你写下的每一行证据。
如何确认真的修好了
1）在全新环境中运行 jupyter nbconvert --execute，不报错；2）连续重跑 3 次，关键指标变化在可接受范围内；3）删除内核、重开 Notebook 后，输出仍与上次一致；4）把笔记发给同事或同学，他们不需要口头说明也能复现主要结果。做到这四步，才算真正在 Notebook 里留下了能站得住的研究痕迹。