跳转到内容
Jason's Study

Panel — 把 notebook 一键变交互式 web app

是什么

Panel 是一个 Python 库，把任何已有的图（Bokeh / Plotly / matplotlib / Vega-Altair / Folium…）包一层、加几个滑块下拉框，就变成一个能跑在浏览器里的 app。日常类比：像给已经做好的菜配了个旋转餐桌——菜不变，你只要拼一个能让菜动起来的台子。

写一个最小 dashboard 就这几行：

import panel as pn
import numpy as np
import matplotlib.pyplot as plt


pn.extension()


slider = pn.widgets.IntSlider(name='频率', start=1, end=10, value=3)


def plot(freq):
    fig, ax = plt.subplots()
    x = np.linspace(0, 10, 200)
    ax.plot(x, np.sin(freq * x))
    return fig


pn.Column(slider, pn.bind(plot, slider)).servable()

panel serve app.py 就起一个网页，拖滑块图实时重画。

为什么重要

不理解 Panel，下面这些事都没法解释：

  • 为什么数据科学家不用学 React / Flask 也能做出”内部工具”水准的 dashboard
  • 为什么同一份代码可以直接在 Jupyter 里看，也能 panel serve 起线上服务，还能 panel convert 编译成纯浏览器跑的 WASM
  • 为什么 Streamlit 火了之后还有人选 Panel——细粒度反应式（只重画变了的组件）vs Streamlit 的”全脚本重跑”
  • 为什么 HoloViz 这套（Bokeh / HoloViews / Datashader / Panel）能在科研圈和工业圈同时活下来

核心要点

Panel 的世界观只有 三种零件 + 一个胶水：

  1. Pane（面板）：把一个”能看的东西”包成组件。matplotlib Figure / Plotly graph / Vega 规格 / DataFrame / 字符串 / 图片 URL，丢进 pn.panel(obj) 就行。
  2. Widget（控件）：交互控件——Slider / Select / TextInput / DatePicker。每个 widget 的值都是 Param（同作者另一个库）的 Parameter，能被监听。
  3. Layout（布局）：Row / Column / Tabs / GridSpec。把 Pane 和 Widget 拼成页面。
  4. pn.bind（胶水）：pn.bind(fn, w1, w2) 让函数在任意 widget 变化时自动重算并把结果塞回 Pane。这就是反应式。

合在一起的心智模型：写一个把 widget 当输入、把图当输出的纯函数，然后用 pn.bind 把两端粘起来。

实践案例

案例 1：多后端混搭（Panel 真正的杀手锏）

import panel as pn
import plotly.express as px
import matplotlib.pyplot as plt
import altair as alt
from vega_datasets import data


pn.extension('plotly', 'vega')
cars = data.cars()


plotly_pane = pn.pane.Plotly(px.scatter(cars, x='Horsepower', y='Miles_per_Gallon'))
vega_pane = pn.pane.Vega(alt.Chart(cars).mark_circle().encode(x='Acceleration', y='Weight_in_lbs'))


fig, ax = plt.subplots()
cars['Cylinders'].hist(ax=ax)
mpl_pane = pn.pane.Matplotlib(fig)


pn.Tabs(('Plotly', plotly_pane), ('Vega', vega_pane), ('Matplotlib', mpl_pane)).servable()

同一份代码里 三套画图库共存，统一用 pn.Tabs 切换。Streamlit / Dash 做不到这种灵活度。

案例 2：反应式 ML 模型评估面板

threshold = pn.widgets.FloatSlider(name='阈值', start=0, end=1, step=0.01, value=0.5)


def metrics(t):
    pred = (scores > t).astype(int)
    return f'Precision: {precision(y, pred):.3f} | Recall: {recall(y, pred):.3f}'


pn.Column(threshold, pn.bind(metrics, threshold)).servable()

拖滑块 → 只有指标那一行重算，不会全脚本重跑。在大数据集上这点比 Streamlit 显著节省。

案例 3：从 notebook 到生产的三档部署

Terminal window
# 1. 开发：Jupyter 里 cell 跑完直接 .servable() 看效果
# 2. 测试：panel serve app.py --autoreload
# 3. 部署 A（有服务器）：panel serve app.py --port 5006 --address 0.0.0.0
# 4. 部署 B（纯静态 CDN）：panel convert app.py --to pyodide-worker --out dist/

第 4 档把 Python 编译成 WebAssembly 跑在浏览器里——没有后端，纯 GitHub Pages 就能托管。这是 Streamlit / Dash 都做不到的。

踩过的坑

  1. panel serve 启动慢：每次起服务都重新 import 全部依赖，开发务必加 --autoreload，省 80% 时间。
  2. matplotlib Pane 不自动重画：要么把 pn.bind 直接接到 plot() 返回新 figure，要么对 Pane 调 .param.trigger('object') 显式触发。
  3. Plotly hover 事件 + Panel watcher 偶尔双触发：同一次鼠标移动可能让回调跑两次。解决办法是用 pn.bind 而不是 @watch 装饰器。
  4. Param 两套写法易混：pn.bind(fn, w)（推荐）和 @param.depends('w.value', watch=True)（高级）做的事差不多，混用会导致依赖追踪不一致。新手只用前者。

适用 vs 不适用场景

适用：

  • 数据探索 dashboard——DataFrame + 几个 widget 控制 filter / 分组
  • ML / 实验评估面板——参数滑块实时重画 ROC、混淆矩阵、loss 曲线
  • 地理 + 时间双维度可视化——Folium / pydeck + 时间滑块
  • 把单张 notebook 一键部署成内部工具（panel serve）

不适用：

  • 纯静态报告 → 用 Quarto / Jupyter Book 更轻
  • 复杂业务前端（多页路由、表单校验、权限） → 用真前端 + 后端
  • 多用户有状态后端（session 隔离、并发权限） → Panel 能跑但不是强项
  • 不想学 Param 反应式 → 选 Streamlit，全脚本重跑更直观

历史小故事（可跳过）

  • 2018：Anaconda 公司的 HoloViz 团队（Philipp Rudiger / James Bednar）注意到 Bokeh server 已经能做交互，但缺一个统一抽象包住 matplotlib / Plotly / Vega 等其他生态。
  • 2019：Panel 0.5 公开发布，定位是”多后端、笔记本友好”。
  • 2020-2022：Streamlit 爆火，但 Panel 守住”反应式 + 多后端”的中间生态位。
  • 2023-06：Panel 1.0 GA，统一 API，加 WASM 部署（PyScript / pyodide），加 ReactiveHTML 让用户写自定义 Web Component。
  • 同一作者的 Param 库（2003 年起）是反应式心脏——比 React hooks 早十年。

学到什么

  1. “包一层、加滑块”是低门槛交互的通用配方——前端不必自己写
  2. 反应式 vs 全重跑 是 dashboard 框架的核心选型分歧——细粒度更省，但要学依赖追踪
  3. Pane / Widget / Layout / bind 四件套覆盖 90% 场景，剩下 10% 用 Template / ReactiveHTML
  4. 从笔记本到 WASM 一条线——同一份代码三档部署是 Panel 区别于 Streamlit / Dash 的最大筹码

延伸阅读

关联

  • vega-lite —— Panel 可以直接包 Vega-Lite spec 当 Pane，三段式 grammar 在 dashboard 里复用
  • fastapi —— 想把数据 API 和面板分开时常见的搭配，FastAPI 出 JSON、Panel 消费
  • pytorch-lightning —— ML 训练循环抽象，Panel 常用来做训练监控面板
  • starlight —— 静态文档站点路线对照，Panel 是动态交互路线

反向链接

  • fastapi —— FastAPI — 用 Python 类型注解写 API
  • pytorch-lightning —— PyTorch Lightning — PyTorch 训练循环抽象
  • starlight —— Starlight — Astro 文档站点主题
  • vega-lite —— Vega-Lite — 三段式 JSON 把复合图收口