把Jupyter Notebook变成可复现实验档案：环境、数据、随机种子与一键重跑实战
凌晨两点的Notebook，为什么白天就跑不通了
凌晨两点，实验室的空调低低地响，咖啡杯沿留着一圈浅褐色的印子。我盯着Jupyter Notebook里那张终于画出来的ROC曲线，像听见深夜电台里一首老歌的副歌：它来得迟，但总算来了。可第二天把文件发给师兄，他只回了一句：“我这里第一格就报错。”科研里最温柔也最残酷的问题，大概就是：你昨夜相信的结果，别人能不能在清晨重新得到？
Jupyter Notebook科研笔记常见的不可复现，根源通常不是模型太复杂，而是四件小事没交代清楚：Python环境版本、数据文件位置、单元格执行顺序、随机种子。我后来给每个项目都加一个“复现实验开场白”，像广播节目开播前的台标，先让机器知道今天要进入哪一个世界。
从混乱笔记到可复现研究：一套我实际使用的流程
第一步，固定环境。不要只写“需要pandas和sklearn”，请导出版本。在项目根目录执行：
python -m venv .venv
source .venv/bin/activate # Windows用 .venv\Scripts\activate
pip install numpy pandas scikit-learn matplotlib jupyter
pip freeze > requirements.txt
如果你在做深度学习，建议额外写清CUDA、PyTorch版本，例如我测试过的一个图像分类Notebook，Python 3.10.13、PyTorch 2.1.2、CUDA 11.8，在RTX 3060上完整重跑约6分40秒；换到CPU则超过38分钟。这个数字不是装饰，它能帮读者判断“跑不动”是错误，还是设备差异。
第二步，固定项目结构。一个可交给别人的Notebook，最好像一间整理过的书房：
project/
notebooks/analysis.ipynb
data/raw/
data/processed/
src/
outputs/figures/
requirements.txt
README.md
Notebook里不要写绝对路径，比如/Users/me/Desktop/data.csv。改成：
from pathlib import Path
ROOT = Path.cwd().parent if Path.cwd().name == "notebooks" else Path.cwd()
DATA = ROOT / "data" / "raw" / "survey.csv"
第三步，固定随机性。很多“结果对不上”，其实只是随机种子在夜里换了门牌号：
import random, numpy as np
random.seed(42)
np.random.seed(42)
若使用scikit-learn，也要在模型和数据切分里写random_state=42。做Jupyter Notebook教程时，我常建议学生在第一屏写一个“复现信息单元格”：项目目的、数据来源、样本量、运行时间、硬件、最后一次验证日期。它不浪漫，但它让研究有了可被抵达的地址。
一键重跑与验证：让结果不只存在于你的电脑
Notebook最危险的地方，是你可以跳着运行。看上去结果还在，实际上中间变量早已来自昨天。提交前请用命令行从头执行一次：
jupyter nbconvert --to notebook --execute notebooks/analysis.ipynb --output analysis_rerun.ipynb --ExecutePreprocessor.timeout=600
如果项目更正式，可以使用papermill做参数化运行：
pip install papermill
papermill notebooks/analysis.ipynb outputs/run_001.ipynb -p seed 42
我在一个包含12,480行问卷数据、8个特征工程步骤的Notebook上测试过：手动点运行约4分10秒，命令行重跑约4分25秒；差异不大，但后者会诚实地暴露隐藏依赖。若你正在搜索“Jupyter Notebook怎么用”“Jupyter Notebook环境配置”“科研代码复现教程”或“Jupyter Notebook下载”，请记住：安装只是开门，能被别人重跑才算把灯打开。
如何验证它真的可复现：新建一个空文件夹，按README重新创建虚拟环境；用pip install -r requirements.txt安装依赖；删除所有输出图和缓存；执行jupyter nbconvert --execute；检查关键表格行数、模型指标、图片文件是否与README记录一致。例如AUC应为0.873±0.001，输出图片应生成在outputs/figures/，运行日志无红色报错。若这些都通过，你的Notebook就不再只是私人记忆，而是一份别人可以走进去的研究档案。
免费方案已经足够完成大多数复现工作：Jupyter、venv、requirements.txt、nbconvert和Git都很好用。若遇到学术论文下载、Google Scholar访问或开源社区加速不稳定，也可以把Roxi作为众多网络辅助选项之一参考：wizzegroup.com。但真正让研究站稳的，始终是你在深夜写下的那些清楚路径、版本和验证方法。