从 Papermill 迁移到 marimo：参数化、程序化执行与产物分发的完整指南-北京尧图网络

从 Papermill 迁移到 marimo参数化、程序化执行与产物分发的完整指南【免费下载链接】marimoA reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.项目地址: https://gitcode.com/GitHub_Trending/ma/marimoPapermill 是 Jupyter 生态中常用的笔记本参数化与批处理执行工具而 marimo 作为纯 Python 存储的响应式笔记本内置了 CLI 参数、URL 查询参数、命名单元格执行与App.run()定义覆盖等机制可以覆盖 Papermill 的典型使用场景。本文以 docs/guides/coming_from/papermill.md 为主线结合仓库源码与测试系统讲解如何用 marimo 实现笔记本参数化、程序化执行、产物存储以及工作流集成帮助从 Papermill 迁移过来的读者快速上手。Papermill 与 marimo 的能力对照Papermill 的核心工作流是在 Jupyter 笔记本中标记一个 parameters 单元格运行时注入参数值并整体执行最后把带输出的.ipynb文件存盘常用于数据管道与批处理任务。marimo 的实现路径完全不同但目标一致参数化通过mo.cli_args()读取命令行参数通过mo.query_params()读写 URL 查询参数执行marimo 笔记本本质是纯 Python 文件可被import、被subprocess调用也可通过Cell.run()与App.run(defs...)在代码中精确控制执行产物分发支持导出 HTML、以 Web App 运行、编辑期自动导出 HTML 快照。下文按这四个维度逐一展开。参数化笔记本两种注入方式Papermill 在运行前把参数注入 parameters 单元格marimo 则提供两种参数入口分别面向脚本/服务端与面向用户交互的场景。方式一命令行参数mo.cli_args()mo.cli_args()返回一个只读字典对象键是命令行参数名值会被自动解析为基本类型import marimo as mo # Access CLI args args mo.cli_args() param1 args.get(param1, default_value)以脚本方式运行注意--分隔符其后的内容才作为笔记本参数python notebook.py -- --param1 value1以 App 方式运行marimo run notebook.py -- --param1 value1参数解析规则参见 marimo/_runtime/runtime.py 与 marimo/_runtime/params.pypython notebook.py -- --arg1 value1 --arg2 value2 # mo.cli_args() {arg1: value1, arg2: value2} python notebook.py -- --arg110 --arg2true --arg3 # mo.cli_args() {arg1: 10, arg2: True, arg3: } python notebook.py -- --arg1 10.5 --arg2 hello --arg2 world # mo.cli_args() {arg1: 10.5, arg2: [hello, world]}可见 marimo 会尝试把字符串解析为int、float、bool解析失败的保持str同一个参数重复出现时聚合为列表。CLIArgs还提供get_all(key)强制以列表形式取值、key in args判断存在性、len(args)统计数量等接口且该对象是只读的不能在单元格中修改。关键区别marimo 官方推荐在复杂场景下直接使用argparse或simple-parsing而非mo.cli_args()。mo.cli_args()不会声明参数、不生成帮助文本而argparse等工具可以。无论哪种方式在marimo edit、marimo run、marimo export及python notebook.py四种运行形态下--之后的参数都会进入sys.argv脚本形式下sys.argv与普通 Python 程序一致。参见 docs/api/cli_args.md 与 docs/guides/scripts.md。方式二URL 查询参数mo.query_params()对于以 Web App 形式运行marimo run的场景查询参数是天然的用户输入通道import marimo as mo # Access query params params mo.query_params() param1 params.get(param1, default_value)访问方式marimo run notebook.py然后浏览器访问http://your-app-url/?param1value1与 CLI 参数的本质差异mo.query_params()返回的QueryParams对象实现见 marimo/_runtime/params.py既可以读也可以写。它继承自 marimo 的State任何修改params[key] value、params.set(...)、params.append(...)、params.remove(...)、params.clear()都会同步到前端 URL并触发依赖它的单元格自动重跑——这让URL 即状态成为可能例如query_params mo.query_params() # 把 UI 输入与 URL 保持同步 search mo.ui.text( valuequery_params[search] or , on_changelambda value: query_params.set(search, value), )示例见 marimo/_runtime/runtime.py 的 docstring。QueryParams.to_dict()可一次性导出为普通字典方便进一步处理。进阶用法配合 Pydantic 做参数校验与 UI 初始化来自 docs/api/query_params.md。查询参数常被用来设定 UI 组件的初始状态用 Pydantic 模型承载参数既能文档化又能校验范围import marimo as mo from pydantic import BaseModel, Field class MyModel(BaseModel): r: int Field(28, ge0, le255, descriptionRed Channel) g: int Field(115, ge0, le255, descriptionGreen Channel) b: int Field(97, ge0, le255, descriptionBlue Channel) message: str Field(br, descriptionSome text) model MyModel(**mo.query_params().to_dict()) # UI with initial state from query params r_slider mo.ui.slider(start0, stop255, step1, labelR, valuemodel.r) g_slider mo.ui.slider(start0, stop255, step1, labelG, valuemodel.g) b_slider mo.ui.slider(start0, stop255, step1, labelB, valuemodel.b)访问http://your-app-url/?g255即可让绿色滑块的初始值变为 255实现可分享、可收藏的 App 状态。若把 marimo App 挂载到 FastAPI参见 docs/guides/deploying/programmatically.md该 Pydantic 模型还可直接接入主应用的 API 文档。两者如何取舍CLI 参数面向不可由终端用户控制的注入批量跑批、定时任务查询参数面向可由用户控制的注入Web 交互、分享链接。这与 Papermill 的参数单元格相比边界更清晰服务端批量注入走 CLI用户侧交互注入走 URL。程序化执行笔记本三种手段Papermill 通过nbconvert/papermill.execute_notebook编程式执行.ipynb。marimo 笔记本是纯 Python 文件因此执行方式更多样、也更容易嵌入现有 Python 生态。手段一运行命名单元格Cell.run()在编辑器中或直接修改单元格函数名给单元格命名后可以像调用函数一样在别的笔记本或脚本中运行它API 定义见 marimo/_ast/cell.pyfrom my_notebook import my_cell # last_expression is the visual output of the cell # definitions is a dictionary of the variables defined by the cell last_expression, definitions my_cell.run()run()返回二元组last_expression是该单元格的最后一个表达式即可视化输出definitions是该单元格定义变量的名字到值的映射。不传参数时marimo 会自动计算该单元格依赖的所有引用也可以传入任意子集的引用覆盖例如from notebook import add # add 单元格定义 z x y output, defs add.run(x2, y2) # defs[z] 4需要留意两个细节异步单元格如果单元格是async协程函数或其任一祖先单元格是协程run()返回的是可等待对象必须awaitoutput, defs await cell.run()。可以用isinstance(ret, Awaitable)做兼容判断UI 元素联动如果单元格的 output 中包含定义在defs里的 UI 元素如滑块前端交互会触发引用这些定义的单元格响应式执行。此外Cell对象本身可直接调用__call__实现于 marimo/_ast/cell.py 起能被pytest等测试框架收集名字以test_开头即可这让为笔记本单元格写单元测试成为 Papermill 生态难以直接获得的附加价值。手段二App.run()定义覆盖App.run()可运行整个 marimo App并允许用defs参数整体替换某些单元格产生的定义实现见 marimo/_ast/app.pyimport marimo from my_notebook import app # Run the app with overridden definitions outputs, defs app.run(defs{batch_size: 64, learning_rate: 0.001, model_type: transformer})重要限制务必理解否则极易踩坑完全覆盖语义传入defs后定义这些变量的单元格整体不再执行其逻辑必须提供完整定义集需要给出某个单元格正常情况下产生的全部定义而不只是个别参数否则下游单元格会因变量缺失而报错与 CLI 参数的本质区别CLI 参数是在单元格执行过程中由mo.cli_args()解析读取的单元格逻辑照常运行而defs是跳过整个定义单元格不能覆盖 setup 单元格with app.setup:块中定义的变量不可通过defs覆盖否则抛出TypeError见 marimo/_ast/app.py。官方 docstring 中的示例marimo/_ast/app.pyapp.cell def config(): batch_size 32 learning_rate 0.01 return batch_size, learning_rate要覆盖该单元格必须同时提供两个变量# Correct: Override the entire cells definitions outputs, defs app.run(defs{batch_size: 64, learning_rate: 0.001}) # Incorrect: This would leave learning_rate undefined # outputs, defs app.run(defs{batch_size: 64})仓库测试 tests/_ast/test_app.py 中app.run(defs...)的用例如app.run(defs{x: 100, y: 200})验证了覆盖后下游单元格使用新值、以及试图覆盖 setup 定义会报错的行为。app.run()返回的outputs是各单元格可视化输出的序列defs是全部顶层定义的名字到值的映射可用于后续断言或传递。手段三subprocess 调用既然笔记本就是 Python 脚本最朴素的管道集成方式就是子进程调用与调用任何脚本无异import subprocess subprocess.run([python, notebook.py, --, --param1, value1])该方法天然适配 crontab、CI、Airflow BashOperator 等以进程为单位的工作流系统。存储或分享产物Papermill 以带输出的 .ipynb 文件作为产物载体marimo 提供三种产物策略可覆盖从审计快照到线上服务的不同需求。策略一导出静态 HTMLmarimo export html notebook.py -o notebook.html -- -arg1 foo --arg2 bar导出时同样支持--传参便于为不同参数组合生成不同版本的 HTML 快照。HTML 产物自包含、无需 Python 环境即可浏览适合作为审计记录或只读分享。更完整的导出能力PDF、Markdown、IPYNB、脚本等参见 docs/guides/exporting。策略二部署为 Web Appmarimo run notebook.py这是把笔记本变成可交互 Web 应用的方式配合mo.query_params()提供用户可控参数配合mo.ui组件提供交互输入非常适合把批量实验脚本升级为团队自助查询工具。也可以选择挂载到 FastAPI 等框架中与其他服务整合docs/guides/deploying/programmatically.md。策略三编辑期自动导出 HTML在 marimo 编辑器的应用设置中开启自动导出Auto-export后每次对笔记本的修改都会触发一次 HTML 快照生成产物存放在与笔记本同级的.marimo/目录下。这相当于 Papermill 的每次执行后存盘习惯的编辑期版本适合需要持续留存每次改动快照的审计场景。工作流集成从批处理脚本到多笔记本管道Papermill 通常嵌入数据管道如 Airflow、Prefect、Kubeflow。marimo 笔记本因其纯 Python 属性可以更低成本地融入既有工作流作为 Python 脚本直接执行python notebook.py -- --param1 value1任何能运行 Python 的工作流系统都可以直接调度仓库的 examples 目录提供了与 FastAPI、Flask、Modal、GCP 等框架/平台集成的可运行示例可作为模板参考程序化串联多本笔记用import方式导入笔记本模块并调用Cell.run()/App.run(defs...)或用subprocess逐个执行都能把多个笔记本串成管道——前者共享同一进程内的对象引用适合数据量大的场景后者进程隔离、天然可重试适合容错要求高的批处理可测试性收益命名单元格配合pytest可编写针对单元格的单元测试App.run()的defs机制则可在测试中注入桩数据或边界参数参见 tests/_ast/test_app.py 的既有用例这是 Papermill 工作流中较难实现的工程质量保障。迁移路线建议从 Papermill 迁到 marimo 可以按以下顺序渐进先把参数单元格改写为mo.cli_args()读取保持python notebook.py -- ...的调度方式不变实现最小改动迁移涉及 Web 交互的参数改用mo.query_params()并考虑用 Pydantic 模型做校验需要程序化控制的场景测试、多笔记本管道引入Cell.run()与App.run(defs...)注意遵守完整定义集覆盖约束产物侧按需选择marimo export html、marimo run或编辑期自动导出。核心参考资料参数 API 详见 docs/api/cli_args.md 与 docs/api/query_params.md执行语义的源码依据在 marimo/_ast/app.py 与 marimo/_ast/cell.py参数解析与类型转换逻辑在 marimo/_runtime/params.py 与 marimo/_runtime/runtime.py行为验证用例可查阅 tests/_ast/test_app.py。【免费下载链接】marimoA reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.项目地址: https://gitcode.com/GitHub_Trending/ma/marimo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

从 Papermill 迁移到 marimo：参数化、程序化执行与产物分发的完整指南

相关推荐

Valkey 如何用 FAILOVER 命令完成一次手动的主从切换？

PythonRobotics 如何用 C-GMRES 求解非线性模型预测控制做路径跟踪

RomM 自托管 ROM 管理器：免费索引 CHD 压缩光盘镜像，覆盖 400+ 平台

更多资讯

Spring OrderUtils 源码解析：从注解缓存到排序优先级提取的完整机制

Coze Studio 前端上传体系解析：`@coze-arch/uploader-interface` 类型契约包的设计与实战

Kohya_SS 实操指南：从十几张照片到训练出你的第一个 LoRA 模型

VoiceStudio 仓库架构全解：从根目录布局到测试体系的结构化导航

Excel曲线回归实战指南：零代码完成统计建模

从复位向量到main：单片机启动流程全拆解

今日更新

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？