开源仓库nteract/papermill6,460 Stars

Papermill

让 Jupyter Notebook 变成可用不同参数批量执行的参数化计算单元

适合需要反复跑同一份 notebook 但代入不同参数的数据科学家和研究工程师。把 notebook 中的参数 cell 标记后，用命令行或 Python API 传入新参数值批量执行，输出 notebook 会保留每次运行的元数据和结果。

bo老师判断：推荐

用途和边界相对清楚，可以先从小样本开始。

访问原仓库查看分享卡

...

什么时候用

先判断任务是否合适

同一个数据分析 notebook 需要用不同日期、参数或数据集反复跑
需要把手工交互 notebook 嵌入自动化数据流水线
想查看 notebook 有哪些参数可调而不必打开文件逐行阅读
需要在 notebook 执行过程中实时落盘，防止长时间运行崩溃丢失结果

先准备什么

材料越清楚，结果越有用

•一个带有标记为 parameters 的 cell 的 Jupyter notebook
•Jupyter kernel 运行环境
•参数配置文件或命令行参数值
•输出 notebook 的保存路径
•可选：云存储凭证（S3、Azure、GCS 等）

它会怎样推进

从材料到可以检查的结果

01
标记参数 cell
在 notebook 中添加 parameters 标签，指定默认参数值
02
传入新参数
通过 CLI 或 Python API 将新的参数值注入 notebook 的参数 cell
03
逐 cell 执行
用指定 kernel 按顺序执行每个 cell，执行过程中实时落盘中间结果
04
输出带元数据的 notebook
生成包含运行时间、参数值、执行状态等完整元数据的输出 notebook
05
检查执行结果
查看输出 notebook 中各 cell 的输出和 papermill 运行元数据

第一次这样开始

把仓库地址直接交给 AI

先让 AI 说明环境和风险，再完成最小安装验证。跑通以后，再把自己的真实材料放进去。

第一次直接复制

帮我安装这个库：https://github.com/nteract/papermill
安装前先告诉我需要什么环境，安装后帮我跑通一个最小示例。

结果出来后

先看这些检查点

输出 notebook 的 papermill metadata 中参数值是否与输入一致
是否有 cell 标记为 failed——每个 cell 的 papermill.status 应确认
长时间运行的任务是否因为 autosave 和逐 cell 落盘保留了中间结果
使用云存储路径时输出是否成功写入目标位置

常见误区

这些判断仍由你负责

忘记给 notebook 添加 parameters 标签——没有标记参数 cell 时传入的参数不会被注入
把 papermill 当作替代版本控制的工具——它生成的是带运行结果的 notebook 副本，而不是替代 git 的 notebook 版本管理
在参数 cell 中写复杂逻辑——参数 cell 应该只定义变量，复杂的参数处理逻辑放在后续 cell

技术依据

查看能力拆解、验证范围与来源

能力地图5 项已拆解能力

01
notebook参数化执行
读取一个输入 notebook，应用参数（参数注入），用指定 Jupyter kernel 逐 cell 执行，在执行过程中实时落盘带运行元数据的输出 notebook，并在出错时保留 traceback 和错误标记后抛出结构化异常。这是 papermill 的核心能力，把 notebook 变成可编程、可追踪、可批量运行的计算单元。
02
参数注入与cell标记
把一组外部传入的参数（dict/YAML/base64）注入到一个 Jupyter Notebook 中，覆盖该 notebook 用 parameters cell tag 声明的默认值，生成一个新的带 injected-parameters cell 的 notebook，使其在执行时使用传入值而非默认值。这是 papermill 把手工 notebook 变成可参数化计算单元的核心机制。
03
参数自省
在不执行 notebook 的情况下，静态解析它的 parameters cell，推断出该 notebook 接受哪些参数、每个参数的名称、推断类型、默认值和帮助文本，返回结构化 Parameter 列表。用于 CLI 帮助（--help-notebook）和程序化参数发现，让调用方在执行前知道 notebook 的参数契约。
04
多引擎io读写
让 notebook 的读取和写入能透明地跨本地文件系统、S3、Azure DataLake/Blob、GCS、HTTP/HTTPS、HDFS、Github 和 stdin/stdout，使执行核心不需要关心存储后端差异。通过路径 scheme 前缀路由到对应 handler，并支持第三方包经 entry point 注册新 scheme。

能力	主要输入	主要输出	人工检查
notebook参数化执行源码已核对	inputpath：notebook 路径（本地/云/URL/NotebookNode/- stdin）。支持路径参数化（{param} 插值）。 outputpath：输出路径（None 则不落盘；- 则写 stdout）。 parameters（dict，可选）：传入参数，交由 papermill-能力-参数注入与cell标记注入。	执行后 notebook（含 cell outputs、executioncount、papermill 运行元数据）。 stdout/stderr 文件（若指定）。错误标记 cell（失败时）。	autosave 指数退避的真实触发条件需运行验证（长 cell + 慢盘）。 cell 失败后 break 的行为意味着后续 cell 不执行，需人工确认部分结果是否可信。 DeadKernel 退出码 138 的下游处理（调度系统）需人工确认。
参数注入与cell标记源码已核对	notebook（NotebookNode）：必须先用 nbformat 读取并 upgrade 到 v4，cell 需有 tags 属性。期望含一个 tag 为 parameters 的 code cell，声明默认参数（如 alpha = 0.6 学习率）。 parameters（dict 或 str）：调用方传入的参数字典。若为 str，视为 YAML 文件路径（readyamlfile）。 reportmode（bool）：注入 cell 是否标记 sourcehidden。	injected-parameters cell：含目标语言参数赋值代码的 code cell（产物）。修改后的 NotebookNode（cells 插入/替换、metadata.papermill.parameters 写入）。后续交由 papermill-能力-notebook参数化执行执行。	非 Python 语言的 translator 输出正确性需人工或测试复核（本轮只静态阅读）。无 parameters cell 时注入到顶部可能改变 notebook 语义（变量定义顺序），需人工确认。 pm 内置参数注入路径后，跨时区机器的 datetime 可能不一致，需人工确认时间口径。
参数自省源码已核对	notebookpath：notebook 路径（支持路径参数化，可传 parameters 解析路径占位符）。 parameters（可选，仅用于路径插值）：opennotebook 调 addbuiltinparameters + parameterizepath 解析路径。 notebook 内的 parameters cell 源码（需有 tag parameters）。	inspectnotebook 返回 {name: {name, inferredtypename, default, help}}。 CLI 打印格式化帮助。	PythonTranslator.inspect 对复杂类型注解（list[int]、dict[str, float]）的解析正确性需测试复核。多行 dict/list 定义的 flatten 行为（中间行注释丢弃）需人工确认是否符合预期。非 Python notebook 的自省完全不可用（返回空），调用方需人工确认是否接受。
多引擎io读写源码已核对	path：notebook 路径字符串，scheme 前缀决定 handler。 buf（写时）：notebook 序列化后的字符串（nbformat.writes）。 extensions（可选）：read/write 时检查文件扩展名（默认 ['.ipynb','.json']），不匹配警告。	notebook 文件内容（读时，str/bytes→decode）。落盘的 notebook（写时，到各后端）。 listdir 返回的路径列表（listnotebookfiles 过滤 .ipynb）。	各云 handler 的真实读写行为需凭证环境验证（本轮未配置）。 GCS 重试的实际触发条件（429/None code）需运行确认。 Github handler 的 path 解析（splits[3]/[4]/[6]）对非常规 URL 的鲁棒性需人工复核。
引擎与io扩展注册源码已核对	第三方包的 entry point 声明：在 pyproject.toml 的 [project.entry-points."papermill.engine"]、[project.entry-points."papermill.io"] 声明 name→class 映射。编程式 register 调用：直接调 papermillengines.register(name, EngineClass)、papermillio.register(scheme, HandlerClass)、papermilltranslators.register(language, TranslatorClass)。 engine 需继承 papermill.engines.Engine 并实现 executemanagednotebook。	注册到单例的新 engine/handler/translator，可被 --engine/路径前缀/kernel 名调用。扩展后的可用执行后端/存储后端/语言集合。	entry point 加载失败（目标包损坏）时 papermill 是否整体崩溃，需运行确认。多个第三方包注册同名 engine/scheme 时的冲突解决（I/O 是 LIFO 后注册优先，engine 是 dict 覆盖），需人工确认。 translator 不支持 entry point 是设计缺口还是有意，需结合 changelog 复核。

处理机制

01
核心处理链
让 Jupyter Notebook 变成可用不同参数批量执行的参数化计算单元

已核对范围

只读上游快照本地只读快照，commit e4e4ddd362037309c53ab5230541759707779687
papermill/execute.py（executenotebook、preparenotebookmetadata、removeerrormarkers、raiseforexecutionerrors）
papermill/engines.py（Engine、NBClientEngine、NotebookExecutionManager、PapermillEngines）
papermill/clientwrap.py（PapermillNotebookClient、papermillexecutecells）
papermill/cli.py（CLI 参数与退出码）
papermill/iorw.py（loadnotebooknode、writeipynb）
README.md、docs/usage-execute.rst
README.md（Parameterizing a Notebook 段）

仍待核对

未运行真实 notebook 执行
未验证逐 cell 落盘（requestsaveoncellexecute）的实际写入时机
未验证 autosave 指数退避的实际触发
未验证 starttimeout/executiontimeout 的超时行为
未验证 DeadKernel 退出码 138 的实际触发
未运行真实 notebook 验证注入 cell 的实际位置与覆盖行为
未验证非 Python 语言（R/Scala/Julia/Matlab/C/F/Powershell/Bash）translator 的 codify 输出正确性
未验证 Black 格式化（PythonTranslator.codify 的 black 调用）在无 black 时的降级

原仓库

nteract/papermill

读取版本

e4e4ddd362037309c53ab5230541759707779687

许可

BSD-3-Clause

AI 可以参与科研的哪些环节？一张 11 环节工作流全景图

从选题、文献、理论、数据到投稿，逐环节判断 AI 可以主导、需要人工校验和必须由研究者把关的工作。

查看内容

科研之我见

AI 科研从哪里开始？先跑通一个完整闭环

科研 AI 新手先选择一个输入、输出和检查点都清楚的小任务，通过真实结果建立流程感、判断感和边界感。

查看内容

文献 · 验证

paper-qa

从本地论文和文档中检索证据并生成带精确引用的科研答案

查看内容

文献 · 分析 · 写作

grobid

把学术论文PDF解析成结构化TEI XML，提取元数据、全文结构和参考文献

查看内容

设计 · 分析 · 验证

CausalPy

用贝叶斯方法做准实验因果推断，含10+方法和稳健性诊断套件

查看内容

能力	主要输入	主要输出	人工检查
notebook参数化执行源码已核对	inputpath：notebook 路径（本地/云/URL/NotebookNode/- stdin）。支持路径参数化（{param} 插值）。 outputpath：输出路径（None 则不落盘；- 则写 stdout）。 parameters（dict，可选）：传入参数，交由 papermill-能力-参数注入与cell标记注入。	执行后 notebook（含 cell outputs、executioncount、papermill 运行元数据）。 stdout/stderr 文件（若指定）。错误标记 cell（失败时）。	autosave 指数退避的真实触发条件需运行验证（长 cell + 慢盘）。 cell 失败后 break 的行为意味着后续 cell 不执行，需人工确认部分结果是否可信。 DeadKernel 退出码 138 的下游处理（调度系统）需人工确认。
参数注入与cell标记源码已核对	notebook（NotebookNode）：必须先用 nbformat 读取并 upgrade 到 v4，cell 需有 tags 属性。期望含一个 tag 为 parameters 的 code cell，声明默认参数（如 alpha = 0.6 学习率）。 parameters（dict 或 str）：调用方传入的参数字典。若为 str，视为 YAML 文件路径（readyamlfile）。 reportmode（bool）：注入 cell 是否标记 sourcehidden。	injected-parameters cell：含目标语言参数赋值代码的 code cell（产物）。修改后的 NotebookNode（cells 插入/替换、metadata.papermill.parameters 写入）。后续交由 papermill-能力-notebook参数化执行执行。	非 Python 语言的 translator 输出正确性需人工或测试复核（本轮只静态阅读）。无 parameters cell 时注入到顶部可能改变 notebook 语义（变量定义顺序），需人工确认。 pm 内置参数注入路径后，跨时区机器的 datetime 可能不一致，需人工确认时间口径。
参数自省源码已核对	notebookpath：notebook 路径（支持路径参数化，可传 parameters 解析路径占位符）。 parameters（可选，仅用于路径插值）：opennotebook 调 addbuiltinparameters + parameterizepath 解析路径。 notebook 内的 parameters cell 源码（需有 tag parameters）。	inspectnotebook 返回 {name: {name, inferredtypename, default, help}}。 CLI 打印格式化帮助。	PythonTranslator.inspect 对复杂类型注解（list[int]、dict[str, float]）的解析正确性需测试复核。多行 dict/list 定义的 flatten 行为（中间行注释丢弃）需人工确认是否符合预期。非 Python notebook 的自省完全不可用（返回空），调用方需人工确认是否接受。
多引擎io读写源码已核对	path：notebook 路径字符串，scheme 前缀决定 handler。 buf（写时）：notebook 序列化后的字符串（nbformat.writes）。 extensions（可选）：read/write 时检查文件扩展名（默认 ['.ipynb','.json']），不匹配警告。	notebook 文件内容（读时，str/bytes→decode）。落盘的 notebook（写时，到各后端）。 listdir 返回的路径列表（listnotebookfiles 过滤 .ipynb）。	各云 handler 的真实读写行为需凭证环境验证（本轮未配置）。 GCS 重试的实际触发条件（429/None code）需运行确认。 Github handler 的 path 解析（splits[3]/[4]/[6]）对非常规 URL 的鲁棒性需人工复核。
引擎与io扩展注册源码已核对	第三方包的 entry point 声明：在 pyproject.toml 的 [project.entry-points."papermill.engine"]、[project.entry-points."papermill.io"] 声明 name→class 映射。编程式 register 调用：直接调 papermillengines.register(name, EngineClass)、papermillio.register(scheme, HandlerClass)、papermilltranslators.register(language, TranslatorClass)。 engine 需继承 papermill.engines.Engine 并实现 executemanagednotebook。	注册到单例的新 engine/handler/translator，可被 --engine/路径前缀/kernel 名调用。扩展后的可用执行后端/存储后端/语言集合。	entry point 加载失败（目标包损坏）时 papermill 是否整体崩溃，需运行确认。多个第三方包注册同名 engine/scheme 时的冲突解决（I/O 是 LIFO 后注册优先，engine 是 dict 覆盖），需人工确认。 translator 不支持 entry point 是设计缺口还是有意，需结合 changelog 复核。

先判断任务是否合适

材料越清楚，结果越有用

从材料到可以检查的结果

标记参数 cell

传入新参数

逐 cell 执行

输出带元数据的 notebook

检查执行结果

把仓库地址直接交给 AI

先看这些检查点

这些判断仍由你负责

查看能力拆解、验证范围与来源

notebook参数化执行

参数注入与cell标记

参数自省

多引擎io读写

notebook参数化执行

参数注入与cell标记

参数自省

多引擎io读写

引擎与io扩展注册

处理机制

核心处理链

已核对范围

仍待核对

相关文章

AI 可以参与科研的哪些环节？一张 11 环节工作流全景图

AI 科研从哪里开始？先跑通一个完整闭环

具备相关能力的其他库

paper-qa

grobid

CausalPy