企业官网建设流程全解析

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/marimo

本指南聚焦 marimo 响应式笔记本（reactive notebook）中一类高频痛点：单元格包含 API 调用、GPU 训练或大数据处理等昂贵计算时，如何在编辑、启动、交互过程中避免误触发执行。读完本文，你将掌握mo.stop条件中断、运行时配置（禁用自动执行/启动自动运行）、函数封装与del内存回收、mo.cache/mo.persistent_cache两级缓存，以及mo.lazy懒渲染昂贵 UI 的完整方案，并了解每一机制背后的源码级实现原理。

使用mo.stop条件中止单元格执行

marimo 提供了一组工具用于控制单元格何时运行，其中最基本的便是mo.stop。当某个条件成立时，mo.stop会中止当前单元格的执行，防止后续昂贵代码被意外运行：

# 若 condition 为 True，则 mo.stop() 返回后单元格立即停止执行 mo.stop(condition) # 若 condition 为 True，下面这行不会被执行 expensive_function_call()

从源码看，mo.stop的实现非常直接：当predicate为True时抛出一个MarimoStopError（继承自BaseException，与KeyboardInterrupt同级，因此不会被普通的except Exception意外捕获）。该异常一旦未被捕获，会停止当前单元格的执行、把output参数作为该单元格的输出，同时所有原本已调度运行的后代单元格都不会运行，它们的定义也会从程序内存中被移除。这也是它比在单元格里直接return更强大的原因——它能级联阻止整个下游依赖图的执行。

用mo.stop强制用户点击按钮后才运行

mo.stop最经典的实战搭配是mo.ui.run_button()：把昂贵单元格的入口"锁"在按钮之后，只有用户显式点击才会执行：

@app.cell def __(): run_button = mo.ui.run_button() run_button return @app.cell def __(): mo.stop(not run_button.value, mo.md("Click 👆 to run this cell")) mo.md("You clicked the button! 🎉") return

run_button的行为（见 run_button.py）：点击后其value变为True，引用它的单元格自动运行；运行完成后，只要自动执行（autorun）处于开启状态，value会自动复位为False。值得注意的源码细节是，在懒执行（lazy）模式下_on_update_completion不会把值重置为False，因为此时下游单元格尚未读取到更新——这意味着在懒执行笔记本中，按钮语义会有所不同。

run_button还支持丰富的构造参数（见 run_button.py）：

配置 marimo 的单元格执行方式

除逐单元格中断外，marimo 还提供三种运行层面上的配置，适合长期处理昂贵笔记本的场景。完整配置入口见 运行时配置指南。

禁用单元格自动执行（懒执行）

如果你习惯处理非常昂贵的笔记本，可以禁用单元格变更时的自动执行（详见 runtime_configuration.md）：在笔记本设置菜单中把"On cell change"设为"lazy"。此时运行一个单元格后，marimo 不再自动运行其依赖单元格，而是将它们标记为stale（过期）；只有当你手动运行某个单元格，且它有 stale 的祖先时，祖先才会跟着运行以保证输入新鲜。你随时可以通过"运行全部 stale 单元格"按钮或快捷键统一执行。

从配置模型看，这对应 RuntimeConfig 中的on_cell_change键："autorun"时祖先运行后后代自动运行，"lazy"时仅标记 stale。注意：以marimo run分享为应用时，该设置不生效。

禁用启动时自动运行

marimo edit notebook.py在启动时会自动运行整个笔记本，行为上等价于python notebook.py。如果你不希望打开笔记本就触发昂贵计算，可以通过笔记本设置菜单关闭"On startup"自动运行（详见 runtime_configuration.md）。源码中对应auto_instantiate配置项（默认True，见 config.py），且该设置只在编辑模式生效，marimo run分享应用时无效。

禁用单个单元格

当你只想编辑笔记本的某一部分、而不想触发其他昂贵部分执行时，可以直接临时禁用单个单元格：被禁用的单元格及其依赖单元格都会被阻止运行（详见 reactivity.md）。这与前两种全局配置互补，适合精细化控制局部执行流。

管理笔记本内存

无论运行在主机还是 GPU 上，内存管理都是昂贵笔记本的核心问题。marimo 的全局变量默认常驻内核内存，以下是三种行之有效的控制手段。

把中间计算封装进函数

全局变量默认存留在内核内存中，而函数内部定义的中间变量会被自动清理。若X只是临时变量，应当这样做：

def _(): X = torch.randn(1e4, 1e4, device='cuda') Y = f(X) return Y

而不是：

X = torch.randn(1e4, 1e4, device='cuda') Y = f(X) # X 仍然存活在程序内存中！

在 marimo 的响应式模型中，单元格中的顶层变量是全局命名空间的一部分（这也是跨单元格响应式引用的基础），因此"用完即弃"的中间值必须通过函数作用域来约束生命周期。相关讨论可进一步参考 reactivity.md 的内存管理小节。

用del从内核内存移除变量

使用 Python 的del操作符可以显式从内核内存中删除变量。

在定义变量的同一单元格内删除。若X只是算出Y后的临时值：

X = torch.randn(1e4, 1e4, device='cuda') Y = f(X) del X

在另一个单元格中删除。有时计算横跨多个单元格，之后才意识到需要释放已分配的内存，此时仍然可以使用del：

data = load_large_dataset()

derived_data = f(data)

del data

这里有一个重要的机制：marimo 会自动插入控制依赖，确保变量在使用前不会被删除。当del删除的是其他单元格定义的变量时，执行del的单元格会成为所有引用该变量的单元格的"子节点"——在上面的例子中，marimo 知道必须先运行第二个单元格（引用了data），再运行第三个单元格（删除data）。但需要注意的是，一旦data被删除，手动重跑第二个单元格会抛出NameError，此时需要重新运行定义单元格，才能让笔记本回到一致状态。

利用局部变量自动回收

以下划线_为前缀的局部（临时）变量（详见 reactivity.md）会在单元格运行结束后自动从内核全局命名空间中移除。如果其他 Python 对象仍持有对它的引用，它将继续留在内存中；否则 Python 的垃圾回收器会自动回收其分配的内存。注意：下划线前缀的导入同样被视为局部变量（如import numpy as _np），而如果导入的符号本身以下划线开头且需要跨单元格使用，应将其别名化为不带下划线的名字（如from ibis import _ as d）。

自动将输出快照为 HTML 或 IPYNB

在编辑笔记本期间，为了让单元格输出留档，可以通过笔记本菜单配置自动保存为 HTML 或 ipynb（这些快照文件与笔记本的.py文件并存，不影响源码存储）。快照会保存到笔记本目录下的__marimo__文件夹中。

这一能力在配置模型中对应 RuntimeConfig 的default_auto_download键：一个可选的导出类型列表，取值包括html、markdown、ipynb，默认值为None（即不自动快照）。更完整的导出方式可参见 导出指南。

缓存昂贵计算

marimo 提供两个装饰器来缓存昂贵函数的返回值（二者既可用作装饰器，也可用作上下文管理器）：

1. 内存缓存mo.cache：把缓存值保存在内存中；
2. 磁盘缓存mo.persistent_cache：把缓存值保存到磁盘。

import marimo as mo @mo.cache def compute_embedding(data: str, embedding_dimension: int, model: str) -> np.ndarray: ...

import marimo as mo @mo.persistent_cache def compute_embedding(data: str, embedding_dimension: int, model: str) -> np.ndarray: ...

大致的语义是：第一次以某组特定参数调用缓存函数时会真正执行并缓存返回值；之后以相同参数调用（缓存命中）时，函数体被跳过，直接返回缓存值。内存缓存更快、不占磁盘，但笔记本重启后丢失；磁盘缓存更慢、占用磁盘，但能跨运行持久化，让你"从上次中断的地方继续"。若需要有界大小的内存缓存，可使用mo.lru_cache（maxsize默认 128，设为-1表示不限制）。三者均完整支持同步与异步函数；对异步函数并发调用同一参数时只会执行一次，其余调用等待该结果。

mo.persistent_cache还支持save_path（保存路径）与method（序列化方式，默认"pickle"）等参数，并可作为上下文管理器：

with mo.persistent_cache("my_cache_name"): X = my_expensive_computation(data, model)

再次运行该代码块时，若检测到缓存命中，整块代码会被跳过，变量直接从缓存加载到内存；上下文管理器的缓存键构造方式与装饰器一致。持久化缓存的默认存放位置是笔记本目录下的__marimo__/cache/，用 git 管理项目时建议把**/__marimo__/cache/加入.gitignore。

缓存键如何构造

mo.cache与mo.persistent_cache使用同一套缓存键机制，差异仅在存储位置。缓存键由函数参数与闭包变量共同决定（详见 缓存指南）：

• 函数参数：基本类型（字符串、字节、数字、None）被哈希；marimo UI 元素按其值哈希；类数组对象（array-like）被内省后对其值哈希；其余对象被 pickle。
• 闭包变量：marimo 首先尝试哈希或 pickle 闭包变量；若无法处理，则回退到定义该变量的源码（连同其祖先单元格的源码）参与缓存键构造，因此即使存在不可哈希、不可 pickle 的参数，闭包方式也能让缓存函数正常工作。

缓存的主要限制

• 副作用不会被缓存：缓存命中时，打印、文件 I/O、网络请求等副作用不会发生；
• 计算缓存键时不使用导入模块的源码；设置pin_modules=True可让缓存随模块版本变化（如模块__version__改变）而失效；
• 持久化缓存的返回值必须可被 pickle 序列化；
• 装饰器若来自其他模块且未使用functools.wraps，会导致缓存键冲突（详见 caching.md 示例）；
• 跨单元格尽量不要修改变量，因为缓存键不一定能感知到突变；
• 建议把缓存函数隔离到独立单元格，避免同单元格中依赖代码的变化连带使缓存失效；并尽量闭包体积小的变量（如先算出length再用），减少缓存键序列化开销。

与functools.cache的取舍

marimo 缓存与标准库functools.cache的差异（详见 caching.md 对比表）：marimo 缓存支持磁盘持久化、在单元格重跑后保留、跟踪闭包变量、允许不可哈希与类数组参数、支持异步函数；而functools.cache仅缓存内存、无法感知单元格重跑，但其开销更小，适合微秒级轻量函数（如用记忆化算斐波那契），marimo 缓存则适合耗时数毫秒以上的昂贵计算。

笔记本级自动缓存（cache_cells）

除了逐函数/逐代码块手动装饰，marimo 还支持对每个被执行单元格自动尝试缓存的笔记本级机制。在pyproject.toml中开启：

[tool.marimo.runtime] cache_cells = true

也可以直接写入笔记本的 PEP 723 元数据。开启后，marimo 会在笔记本重启时尝试保存并恢复每个单元格的状态：命中缓存时跳过重跑、直接从存储的 stub 恢复变量；若 stub 无法恢复（如值不可哈希或不可序列化），marimo 会使该单元格及其产生祖先的缓存失效并现场重跑，无需手动清理。注意该功能仍处于实验阶段：缓存单元格定义的 UI 元素在命中时不会被恢复，会强制该单元格真实重跑。该机制同时支撑了"缓存执行"的 WASM 导出能力。详见 缓存指南。

懒加载昂贵的 UI

mo.lazy（实现见 lazy.py）可以把计算昂贵的 UI 元素延迟到用户真正能看到它时再渲染。

懒渲染：数据先算，渲染后置

import marimo as mo data = db.query("SELECT * FROM data") mo.lazy(mo.ui.table(data))

在这个例子中，mo.ui.table(data)在进入视口之前不会被前端渲染——例如元素因滚动在视口之外、位于未选中的 tab 中、或位于未展开的 accordion 中时。但注意：这里data仍是急切计算的，只是表格的渲染被延迟了。

懒计算：连数据也延迟获取

如果数据本身也昂贵，可以给mo.lazy传一个函数，而不是一个组件：

import marimo as mo def expensive_component(): import time time.sleep(1) data = db.query("SELECT * FROM data") return mo.ui.table(data) accordion = mo.accordion({ "Charts": mo.lazy(expensive_component) })

只有当用户展开 accordion 时，expensive_component才会被调用，此时才真正查询数据库。从 lazy.py 的_load实现可以看到：mo.lazy暴露了一个load前端函数，元素首次可见时前端触发该函数；若传入的是可调用对象则调用它获取内容，并支持同步与异步函数（返回协程时会await）。构造参数show_loading_indicator可控制加载过程中是否显示加载指示器。

一个值得注意的源码细节（lazy.py）：在非交互式上下文（如 ipynb、PDF 导出）中，mo.lazy会急切解析并直接返回渲染好的 HTML，因为此时没有内核可以执行懒加载；异步元素无法在同步构造中解析，会回退为懒加载组件；HTML 导出则保留懒加载组件本身。

小结：昂贵笔记本的四层防护

综合以上机制，处理昂贵笔记本时可以按"防误触 → 控运行 → 省内存 → 提速度"四层组织防护策略：

1. 防误触：用mo.stop+mo.ui.run_button()为昂贵单元格加"确认闸门"；
2. 控运行：通过笔记本设置（on_cell_change懒执行、关闭启动自动运行、禁用单个单元格）控制执行时机；
3. 省内存：函数封装中间变量、del显式释放、下划线局部变量自动回收；
4. 提速度：mo.cache/mo.persistent_cache/cache_cells缓存重复计算，mo.lazy延迟昂贵 UI 的渲染与计算，并配合default_auto_download自动快照输出留档。

这些能力全部可在当前仓库源码中进一步追踪：执行中断逻辑在 control_flow.py，缓存实现位于 save.py，懒加载位于 lazy.py，运行时配置模型见 config.py。完整的运行时配置说明见 运行时配置指南，缓存细节见 缓存指南，响应式与内存相关概念见 reactivity.md。

【免费下载链接】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