Mercury：Notebook 发布全攻略

为什么需要 Mercury：Notebook 交付的断点

传统做数据交付的链路是断裂的：业务同事收到 .ipynb 文件后，需要自行安装 Python 和依赖，逐个单元格运行才能看到结果；一旦想换一组参数，就必须理解代码并手动修改，门槛极高。要绕过这个门槛，团队往往得调度前后端资源，为同一个分析重新开发一个 Web 界面，耗时远超分析本身。Notebook 里沉淀的分析逻辑，就此停留在“能看不能用”的状态。

Mercury 的解法是把“数据代码”和“交互界面”直接绑定在 Notebook 上。你在 Notebook 最前面加一段 YAML 元数据，声明标题、描述、需要暴露的参数以及参数类型（文本框、滑块、下拉选项、文件上传等），其余代码保持原样。运行 mercury run 启动服务后，浏览器中访问该地址即可看到自动生成的表单；每提交一组参数，Mercury 会在服务端重新执行整个 notebook，并展示最新的图表、表格和文字结果。整个过程无需掌握 HTML/CSS/JS，也不需要迁移代码。

与同类工具相比，Mercury 的气质差异明显：Streamlit 要求以脚本为中心重写逻辑，Voilà 更偏静态展示，而 Mercury 尊重已有的 Notebook 资产，适合“从研究到交互演示”的跳跃，尤其适合已经用 Notebook 完成建模、只差一个发布出口的 AI 团队。

安装与环境配置：3 步就绪

第一步，安装 PyPI 包。Mercury 依赖较少，pip 会自动处理 Jupyter 生态相关依赖，不需要单独安装 JupyterLab 扩展。

第二步，准备一个存放 notebook 的目录。实际生产中建议一个应用一个目录，便于后续用 Docker 打包。

第三步，启动服务并验证。mercury run 默认监听 8000 端口，启动后终端会显示访问地址，用浏览器或 curl 确认返回 200 即安装成功。

注意事项：如果你之前装过早期版本，升级后用 pip show mercury 查看版本号，避免继续使用旧命令入口。

# 安装 Mercurypip install mercury # 创建并进入应用目录mkdir -p notebooks && cd notebooks # 启动服务（默认端口 8000）mercury run --port 8000 # 验证服务已启动curl -I http://127.0.0.1:8000

快速上手：15 分钟跑通第一个示例

思路很直接：新建一个 notebook，在顶部加一个 Raw 单元格写 YAML 参数定义，在代码单元格中直接使用参数对应的变量名，保存后启动服务即可。最小可用流程不涉及任何前端代码。

1. 在 Jupyter 中新建 notebook，插入一个空白单元格。

2. 通过菜单 Cell → Cell Type → Raw NBConvert 将该单元格改为 Raw。

3. 在 Raw 单元格中粘贴 YAML 配置（见下方代码块），定义应用标题、是否显示代码和两个参数控件。

4. 新建一个代码单元格，写入使用 name 和 clicks 变量的 Python 逻辑。

5. 保存 notebook，在终端运行 mercury run --port 8000。

6. 浏览器打开 http://127.0.0.1:8000，左侧列表中选择刚保存的 notebook，页面上会出现文本框、滑块和 Run 按钮。

7. 把滑块值从 20 改为 50，点击 Run，直方图会按新参数重新计算并刷新。

结果是一个可交互的直方图应用：修改滑块、点击 Run，图表立刻更新。进阶技巧：把 show-code 改为 true 可以让访问者看到代码；把 text 控件换成 select 或 file，即可扩展成“选择分组”或“上传 CSV 后分析”的真实业务场景。

---title: 我的第一个 Mercury 应用description: 数据科学团队内部演示show-code: falseparams:    name:        input: text        label: 你的名字        value: 数据科学家    clicks:        input: slider        label: 模拟次数        min: 1        max: 100        value: 20---

import numpy as npfrom matplotlib import pyplot as plt # 这里的 name、clicks 由 Mercury 在运行时注入# value 字段的值就是 notebook 离线运行的默认值print(f"你好，{name}！下面是用 {clicks} 次模拟生成的直方图：")plt.hist(np.random.randn(clicks), bins=10)plt.show()

核心能力详解：参数化、执行引擎与发布能力

参数化控件自动生成。 Mercury 的参数定义放在 notebook 顶部 Raw 单元格的 YAML 块中，格式以 --- 包裹。params 下的键名必须与 notebook 代码中出现的变量名一致；value 字段不仅是控件默认值，也是 notebook 脱离 Mercury 独立运行时的回退值。框架按 input 字段映射控件类型：text 映射文本框，numeric 映射数字输入，slider 映射滑杆，select 和 multiselect 映射单选/多选下拉，date 映射日期选择器，file 映射文件上传。min、max、step 等键控制数值约束。这意味着给 Notebook 增加交互能力不需要新框架，只需要一段声明式 YAML。

服务端执行引擎与多用户状态。 当用户在网页上提交参数，Mercury 不会改动你的 notebook 源文件：它创建一个独立执行实例，把表单值替换为同名变量，执行全部单元格，再把图表、print 输出、DataFrame 渲染回页面。多个用户同时操作同一个应用时，各自的任务独立排队，互不干扰。执行过程中的 stdout 和 stderr 会显示在页面上，方便使用者判断任务是否成功。需要留意的是，每次执行都是一次完整重跑，应用的响应时间约等于 notebook 从上到下跑完一遍的时间。

发布与保护能力。 show-code 字段控制代码在浏览器端的可见性，设为 false 时源码不会发送到浏览器，只传输执行结果。服务端支持用户名/密码的 Basic Auth，以及 GitHub、Google 的 OAuth 登录，适合挂在公司内网给非技术同事使用。官方提供 Docker 镜像 mljar/mercury，可以一键把多个 notebook 打包成独立服务，嵌入现有基础设施。对 AI 团队而言，从 notebook 到可交付应用的路径被压缩到“写 YAML + 跑服务”两步。

生产部署与监控：从上线到运维

单机部署。 生产环境最直接的方案是把 mercury run --port 8000 交给 systemd 或 supervisor 常驻运行，前面架一层 Nginx 做域名和 TLS 终结，反代到 8000 端口。内部工具场景下这个架构足够稳定；如果涉及文件上传，需要同步调整 Nginx 的请求体大小限制和超时配置。

Docker 化部署。 官方镜像 mljar/mercury 自带运行环境。写一个极简 Dockerfile：FROM mljar/mercury，把 notebooks 目录 COPY 进镜像，WORKDIR 指向该目录，EXPOSE 8000，最后用 CMD ["mercury", "run", "--port", "8000"] 启动。用 docker-compose 统一管理资源限制、重启策略和日志卷，交付给运维团队时比裸机方案更可复现。流量增长后可以加多副本，前面用负载均衡分发。

可观测性。 Mercury 把应用内日志输出到控制台，建议统一收集 stdout/stderr 到 Loki 或 ELK。监控重点有三个：应用响应延迟（从反向代理侧统计）、执行失败率（检查终端日志中的 traceback）、内存与 CPU 占用（频繁整本重跑大型 notebook 会显著拉高资源）。页面上的执行状态本身就是一种粗粒度监控——用户在页面看到进度和报错信息，能第一时间反馈给负责人。

<p class="para-label">避坑清单：</p>

<ul class="dash-list"><li>旧 Python 环境直接安装失败：建议在 Python 3.9+ 的干净虚拟环境中安装，避免和 Conda 基础环境冲突，安装后用 pip show mercury 验证。</li><li>YAML 变量名与代码不一致：params 的键必须与 notebook 代码中的变量名严格对应，否则用户修改控件后，执行结果不会变化。</li><li>依赖未固化导致运行报错：notebook 中 import 了 pandas、scikit-learn，但部署镜像没装，一执行就 ModuleNotFoundError；务必用 requirements.txt 随镜像一起构建。</li><li>把重型训练直接放进交互应用：每次提交参数都会整本重跑，训练类任务会拖垮单机；交互应用只放推理和分析，训练放到异步批处理。</li><li>低估敏感代码的暴露风险：未设置 show-code 时代码默认可见，涉及密钥或机密逻辑的 notebook 应隐藏代码并开启认证后再发布。</li></ul>

AI 应用场景

常见误区

面试题