cuxfilter 完整实践指南：用 RAPIDS 构建 GPU 加速的交互式交叉筛选仪表盘

cuxfilter 完整实践指南：用 RAPIDS 构建 GPU 加速的交互式交叉筛选仪表盘

【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000+ scientists worldwide. 165 ready-to-use validated skills plus 100+ scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills

导读

cuxfilter 是 NVIDIA RAPIDS 生态中面向 GPU 加速交叉筛选仪表盘的专用库，它让开发者只需几行 Python 代码，就能在 Jupyter Notebook 中构建支持多图表联动的交互式探索性数据分析仪表盘——所有过滤、分组、聚合运算全部在 GPU 上通过 cuDF 完成，浏览器端只接收渲染结果。本文以 cuxfilter 参考文档 为主体，结合 optimize-for-gpu 技能 的决策框架、安装指引与代码转换模式，完整讲解 cuxfilter 的安装环境、数据加载、图表与控件体系、仪表盘构建、布局主题、图可视化、多 GPU 扩展及性能调优，并明确其"已停更"（sunset）的项目状态与替代方案，帮助你既能维护存量 26.06 应用，也能为新建项目做出正确的技术选型。

项目状态（务必先读）：cuxfilter 已经日落（sunset），v26.06 是最终版本，后续 RAPIDS 发行不再发布任何包。下文所有功能在 26.06 包上仍然可用；但对于新项目，RAPIDS 官方建议直接用受维护的库自行组合仪表盘：cuDF（GPU 数据加载/聚合）+HoloViews / hvPlot / Datashader（联动交叉筛选可视化），并用Panel、Plotly Dash、Streamlit 或 Bokeh 提供服务。详见 决策框架文档 与 安装文档。

一、cuxfilter 的定位与核心概念

cuxfilter 位于 RAPIDS 生态的可视化层：上游由 cuDF（数据层）、cuGraph（图分析）、cuML（机器学习）提供计算能力，下游整合 Bokeh、Datashader、Deck.gl 与 Panel 完成渲染与交互。它最大的特点是数据永不离开 GPU——每次筛选、groupby、聚合都在 GPU 上执行，仅把紧凑的绘图结果送往浏览器，因此能支撑数百万行数据的实时联动探索。

cuxfilter 由五个核心模块构成：

标准工作流始终是：加载数据 → 创建图表 → 构建仪表盘 → 展示。

二、安装与环境要求

cuxfilter 的安装遵循本仓库统一约定的uv add方式（若用户项目已配置包管理器，则跟随既有项目，不要重写其工具链）。注意 cuxfilter 依赖 cuDF，因此安装时会自动拉取cudf-cu12或cudf-cu13：

# CUDA 12.x uv add --extra-index-url=https://pypi.nvidia.com "cuxfilter-cu12==26.6.*" # CUDA 13.x uv add --extra-index-url=https://pypi.nvidia.com "cuxfilter-cu13==26.6.*"

两个命令安装的都是最终版 26.06 发行——之后不再有任何更新发布。cuxfilter 的 wheel 也直接存在于 PyPI 上，因此 NVIDIA extra index 是可选项。RAPIDS 包统一要求 Python >= 3.11、Linux 或 WSL2 平台（无原生 macOS/Windows），且需要支持 CUDA 12.x 或 13.x 的 NVIDIA GPU，详见 installation.md。

安装完成后建议立即验证 GPU 环境与包版本：

import cuxfilter import cudf print(cuxfilter.__version__) # 应输出 26.06 版本号 df = cudf.DataFrame({"x": [1, 2, 3], "y": [4, 5, 6]}) cux_df = cuxfilter.DataFrame.from_dataframe(df) print(cux_df.data.head()) # 应打印 GPU dataframe

环境前提：cuxfilter 的 GPU 执行必须依赖 NVIDIA CUDA 显卡；RAPIDS 26.06 的 wheel 仅支持 Linux/WSL2 与 CUDA 12/13，且安装需要网络访问（见 SKILL.md 兼容性声明）。

三、DataFrame：加载数据

cuxfilter.DataFrame是一切操作的起点，它包装 cuDF 或 dask_cudf DataFrame。

3.1 从 cuDF DataFrame（最常见）

import cudf import cuxfilter cudf_df = cudf.DataFrame({ "x": [0, 1, 2, 3, 4], "y": [10.0, 11.0, 12.0, 13.0, 14.0], "category": ["A", "B", "A", "B", "A"] }) cux_df = cuxfilter.DataFrame.from_dataframe(cudf_df)

3.2 从磁盘上的 Arrow 文件

cux_df = cuxfilter.DataFrame.from_arrow("data/my_dataset.arrow")

3.3 从图（节点 + 边）

既可以先构造 cuGraph 图对象再加载，也可以直接用 cuDF DataFrame 描述节点与边：

import cugraph edges = cudf.DataFrame({"source": [0, 1, 2], "target": [1, 2, 3], "weight": [1.0, 2.0, 3.0]}) G = cugraph.Graph() G.from_cudf_edgelist(edges, source="source", destination="target", edge_attr="weight") cux_df = cuxfilter.DataFrame.load_graph((G.nodes(), G.edges()))

# 或直接用 cuDF DataFrame nodes = cudf.DataFrame({"vertex": [0, 1, 2, 3], "x": [0, 1, 2, 3], "y": [4, 4, 2, 6], "attr": [0, 1, 1, 1]}) edges = cudf.DataFrame({"source": [0, 1, 2], "target": [1, 2, 3], "weight": [1.0, 2.0, 3.0]}) cux_df = cuxfilter.DataFrame.load_graph((nodes, edges))

3.4 访问底层数据

cux_df.data # cuDF DataFrame cux_df.data["new_col"] = cux_df.data["x"] * 2 # 在创建仪表盘前新增派生列

从源码结构看，from_dataframe与load_graph是 DataFrame 层仅有的两个加载入口：前者面向普通表数据，后者面向图结构数据，二者最终都维护一个data属性供图表读取。

四、图表（Charts）

所有图表工厂函数都通过cuxfilter.charts顶层简写访问——不需要直接导入cuxfilter.charts.bokeh或cuxfilter.charts.datashader这类子模块。

4.1 柱状图（Bokeh）

chart = cuxfilter.charts.bar( x="column_name", # 必填：x 轴列 y=None, # 可选：y 轴列（默认统计计数） data_points=None, # 分箱数量（None = 唯一值个数） add_interaction=True, # 启用交叉筛选交互 aggregate_fn="count", # 'count' 或 'mean' step_size=None, # 范围滑块的步长 title="", # 图表标题 autoscaling=True, # 数据更新时自动缩放 y 轴 )

4.2 折线图（Bokeh）

chart = cuxfilter.charts.line( x="x_col", y="y_col", data_points=100, add_interaction=True, )

4.3 散点图（Datashader——可处理百万级点）

chart = cuxfilter.charts.scatter( x="x_col", y="y_col", aggregate_col=None, # 用于颜色聚合的列 aggregate_fn="count", # 'count', 'mean', 'max', 'min' color_palette=None, # Bokeh 调色板或十六进制颜色列表 point_size=15, pixel_shade_type="eq_hist", # 'eq_hist', 'linear', 'log', 'cbrt' pixel_density=0.5, # [0, 1]，越大越密集 pixel_spread="dynspread", # 'dynspread' 或 'spread' tile_provider=None, # 地图瓦片（如 "CartoLight" 用于地理数据） title="", unselected_alpha=0.2, # 未选中点的透明度 )

4.4 热力图（Datashader）

chart = cuxfilter.charts.heatmap( x="x_col", y="y_col", aggregate_col="value_col", aggregate_fn="mean", # 'count', 'mean', 'max', 'min' color_palette=None, point_size=10, point_shape="rect_vertical", # 'circle', 'square', 'rect_vertical', 'rect_horizontal' title="", )

4.5 堆叠折线（Datashader）

chart = cuxfilter.charts.stacked_lines( x="time_col", y=["series_a", "series_b", "series_c"], # y 列列表 colors=["red", "green", "blue"], )

4.6 等值区域图（Deck.gl——2D 与 3D 地图）

chart = cuxfilter.charts.choropleth( x="zip_code", color_column="metric_col", color_aggregate_fn="mean", # 'count', 'mean', 'sum', 'min', 'max', 'std' elevation_column="value_col", # 设置该参数即启用 3D，省略则为 2D elevation_factor=0.00001, elevation_aggregate_fn="sum", geoJSONSource="https://url/to/geojson", geo_color_palette=None, # 默认：Inferno256 nan_color="#d3d3d3", tooltip=True, tooltip_include_cols=["zip_code", "metric_col"], title="", )

4.7 图可视化（Datashader——节点-边图）

chart = cuxfilter.charts.datashader.graph( node_x="x", # 默认 "x" node_y="y", # 默认 "y" node_id="vertex", # 默认 "vertex" edge_source="source", # 默认 "source" edge_target="target", # 默认 "target" node_aggregate_col=None, node_color_palette=None, edge_color_palette=["#000000"], node_point_size=15, node_pixel_shade_type="eq_hist", edge_render_type="direct", # 'direct' 或 'curved'（curved 为实验性） edge_transparency=0, # [0, 1] tile_provider=None, title="", unselected_alpha=0.2, )

图表与数据规模匹配原则：Bokeh 类图表（bar、line）适合小数据量；Datashader 类图表（scatter、heatmap）通过服务端栅格化可高效处理 10K 到 1 亿行以上的数据。这一"按数据量选图表"的规则与 决策框架文档 中"cuxfilter 最适合在数百万行数据上做交互式交叉筛选"的定位完全一致。

五、控件（Widgets）

控件提供交互式过滤操作，通常放在侧边栏。

5.1 各类筛选控件

widget = cuxfilter.charts.range_slider("numeric_col", step_size=1) # 数值范围 widget = cuxfilter.charts.date_range_slider("datetime_col") # 日期范围 widget = cuxfilter.charts.float_slider("float_col", step_size=0.5) # 浮点滑块 widget = cuxfilter.charts.int_slider("int_col", step_size=1) # 整数滑块 widget = cuxfilter.charts.drop_down("category_col") # 下拉框 widget = cuxfilter.charts.multi_select("category_col") # 多选

5.2 数值指示器（KPI）

widget = cuxfilter.charts.number( expression="column_name", # 或计算表达式，如 "(x + y) / 2" aggregate_fn="mean", # 'count', 'mean', 'min', 'max', 'sum', 'std' title="Average Value", format="{value:.2f}", # Python 格式化字符串 colors=[(33, "green"), (66, "gold"), (100, "red")], # 阈值着色 font_size="18pt", )

5.3 卡片（Markdown 内容）

import panel as pn widget = cuxfilter.charts.card(pn.pane.Markdown("## My Dashboard\nSome description text"))

六、仪表盘创建

在 cuxfilter DataFrame 上调用.dashboard()即可创建仪表盘：

# 定义图表与控件 chart1 = cuxfilter.charts.scatter(x="x_col", y="y_col") chart2 = cuxfilter.charts.bar("category_col") sidebar_widget = cuxfilter.charts.range_slider("value_col") number_widget = cuxfilter.charts.number(expression="value_col", aggregate_fn="mean", title="Mean Value") # 构建仪表盘 d = cux_df.dashboard( charts=[chart1, chart2], # 主区域图表 sidebar=[sidebar_widget, number_widget], # 侧边栏控件 layout=cuxfilter.layouts.feature_and_base, theme=cuxfilter.themes.rapids_dark, title="My Dashboard", data_size_widget=True, # 显示当前数据条数 )

6.1 创建后追加图表

new_chart = cuxfilter.charts.line("x_col", "y_col") d.add_charts(charts=[new_chart]) # 或 d.add_charts(sidebar=[cuxfilter.charts.card(pn.pane.Markdown("# Note"))])

七、布局（Layouts）

7.1 预设布局

7.2 自定义布局（layout_array）

layout_array提供完全控制权：它是一个列表的列表，每个内层列表代表一行，数字对应图表索引（从 1 开始）：

# 图表 1 占据左上 2x2 区域，图表 2、3 位于右侧 d = cux_df.dashboard( charts_list, layout_array=[[1, 1, 2, 2], [1, 1, 3, 4]], theme=cuxfilter.themes.rapids_dark, )

规则：

• 每个数字对应一个图表（1 = 第一个图表，2 = 第二个，依此类推）；
• 数字在多个单元格中重复出现时，该图表将跨这些单元格；
• 数组会自动缩放以适配屏幕。

八、主题（Themes）

内置四种主题：

d = cux_df.dashboard(charts, theme=cuxfilter.themes.rapids_dark)

九、仪表盘展示与导出

9.1 Notebook 内联展示

d.app(sidebar_width=280, width=1200, height=800)

9.2 独立 Web 应用（打开新浏览器标签页）

d.show() # 或自定义 URL/端口 d.show(notebook_url="http://localhost:8888", port=8050)

9.3 JupyterHub 部署

d.show(service_proxy="jupyterhub")

9.4 停止服务

d.stop()

9.5 导出筛选后的数据

与仪表盘交互（选择范围、过滤）后，可导出当前筛选状态对应的 DataFrame：

filtered_df = d.export() # 返回与当前筛选状态一致的 cuDF DataFrame # 同时打印查询字符串，例如："2 <= key <= 4"

9.6 访问仪表盘图表

d.charts # 图表对象字典

十、图可视化（cuGraph 集成）

cuxfilter 与 cuGraph 集成，支持交互式图可视化。加载图数据时需要节点坐标——通常用force_atlas2等布局算法生成：

import cuxfilter import cudf import cugraph # 创建图 edges = cudf.DataFrame({ "source": [0, 0, 1, 1, 2], "target": [1, 2, 2, 3, 3] }) G = cugraph.Graph() G.from_cudf_edgelist(edges, source="source", destination="target") # 加载进 cuxfilter（需要节点坐标，用 force_atlas2 等布局生成） positions = cugraph.force_atlas2(G) nodes = positions.rename(columns={"vertex": "vertex", "x": "x", "y": "y"}) cux_df = cuxfilter.DataFrame.load_graph((nodes, G.edges())) # 创建图图表 chart = cuxfilter.charts.datashader.graph( node_pixel_shade_type="linear", unselected_alpha=0.2, ) d = cux_df.dashboard([chart], layout=cuxfilter.layouts.single_feature) d.app()

十一、多 GPU：Dask-cuDF

cuxfilter 无缝支持dask_cudf.DataFrame——直接传入即可替代 cuDF DataFrame：

import dask_cudf ddf = dask_cudf.read_parquet("large_dataset/*.parquet") cux_df = cuxfilter.DataFrame.from_dataframe(ddf) # 其余用法完全相同 chart = cuxfilter.charts.scatter(x="x", y="y") d = cux_df.dashboard([chart]) d.app()

适合使用 dask_cudf 的场景：

• 数据超出单块 GPU 显存；
• 希望跨多块 GPU 分布式处理；
• 需要一次性处理大量文件。

dask_cudf 支持的图表类型：

• bokeh：bar、line
• datashader：scatter、line、stacked_lines、heatmap、graph（边渲染能力有限）
• panel_widgets：全部控件
• deckgl：choropleth（2D 与 3D）

这也与 SKILL.md 优化工作流 的提示呼应：GPU 显存有限，当数据集超过显存时应考虑分块或使用 RAPIDS Dask 进行多 GPU 扩展。

十二、互操作性：RAPIDS 全栈管线

cuxfilter 位于 RAPIDS 生态的可视化层，与上下游库的互操作关系如下：

• cuDF— 数据层，cuxfilter.DataFrame包装 cuDF DataFrame；
• cuGraph— 图分析，用cuxfilter.DataFrame.load_graph()可视化 cuGraph 结果；
• cuML— 先运行 cuML，再用 cuxfilter 可视化结果（如 UMAP 嵌入、聚类标签）；
• HoloViz 生态— 基于 Panel、Bokeh、Datashader 与 HoloViews 构建；
• Deck.gl— WebGL 驱动的等值区域图。

12.1 典型 RAPIDS + cuxfilter 管线

import cudf import cuml import cuxfilter # 用 cuDF 加载与预处理 df = cudf.read_parquet("data.parquet") df = df.dropna().reset_index(drop=True) # 用 cuML 跑机器学习（如 UMAP 降维） from cuml.manifold import UMAP umap = UMAP(n_components=2) embedding = umap.fit_transform(df[["feature1", "feature2", "feature3"]]) df["umap_x"] = embedding[:, 0] df["umap_y"] = embedding[:, 1] # 用 cuxfilter 可视化 cux_df = cuxfilter.DataFrame.from_dataframe(df) scatter = cuxfilter.charts.scatter( x="umap_x", y="umap_y", aggregate_col="cluster_label", aggregate_fn="mean", pixel_shade_type="linear", ) bar = cuxfilter.charts.bar("cluster_label") d = cux_df.dashboard([scatter, bar], layout=cuxfilter.layouts.feature_and_base) d.app()

这条"cuML 产出嵌入 → cuxfilter 联动可视化"的链路，在 决策框架文档 中被明确标记为cuML + cuxfilter（仅 legacy 26.06）的维护型组合——适用于存量应用，而非新项目选型。

十三、性能优化技巧

1. 让数据始终留在 GPU。用cudf.read_parquet()或cudf.read_csv()加载，再用cuxfilter.DataFrame.from_dataframe()包装，避免与 pandas 来回转换。这与 SKILL.md 中"一次性传输输入、让中间结果驻留设备端"的 GPU 数据路径原则一致。

2. 按数据规模选择图表类型：

   • < 10K 点：Bokeh 图表（bar、line）表现良好；
   • 10K–100M+ 点：Datashader 图表（scatter、heatmap）通过服务端栅格化高效处理大数据集。

3. 限制柱状图的data_points。对唯一值很多的列设置data_points进行分箱，例如bar("col", data_points=50)。

4. 尽可能使用float32。GPU 对 32 位浮点运算更快，加载前先转换：df["col"] = df["col"].astype("float32")。参考 SKILL.md 的建议，只有在契约允许时才选择float32、混合精度或降低精度存储。

5. 预先计算派生列。在创建仪表盘之前算好，不要放在图表回调里执行。

6. 复杂仪表盘用layout_array。精确控制每个图表的出现位置。

7. 超大数据集上缩放卡顿可调大timeout。针对 datashader 图表。

另外注意验证环节：cuxfilter 的筛选/聚合在 GPU 上执行，若要与 CPU 结果对照验证，应使用显式容差（GPU 浮点结果可能因运算顺序略有差异），此为本仓库 SKILL.md 验证流程 的通用要求。

十四、常见模式

14.1 探索性数据分析仪表盘

import cudf import cuxfilter df = cudf.read_parquet("dataset.parquet") cux_df = cuxfilter.DataFrame.from_dataframe(df) # 概览图表 scatter = cuxfilter.charts.scatter(x="feature1", y="feature2", pixel_shade_type="linear") hist1 = cuxfilter.charts.bar("feature1", data_points=50) hist2 = cuxfilter.charts.bar("category") # 侧边栏筛选器 slider = cuxfilter.charts.range_slider("value_col") dropdown = cuxfilter.charts.drop_down("category") kpi = cuxfilter.charts.number(expression="value_col", aggregate_fn="mean", title="Mean Value") d = cux_df.dashboard( [scatter, hist1, hist2], sidebar=[slider, dropdown, kpi], layout=cuxfilter.layouts.feature_and_double_base, theme=cuxfilter.themes.rapids_dark, title="Data Explorer", ) d.app()

14.2 地图瓦片上的地理散点

chart = cuxfilter.charts.scatter( x="longitude", y="latitude", aggregate_col="value", aggregate_fn="mean", color_palette=["#3182bd", "#6baed6", "#ff0068"], tile_provider="CartoLight", pixel_shade_type="linear", title="Geo Scatter", )

14.3 时间序列仪表盘

line_chart = cuxfilter.charts.line("timestamp", "metric") bar_chart = cuxfilter.charts.bar("hour_of_day") date_slider = cuxfilter.charts.date_range_slider("timestamp") d = cux_df.dashboard( [line_chart, bar_chart], sidebar=[date_slider], layout=cuxfilter.layouts.feature_and_base, )

14.4 导出筛选后的子集继续分析

# 用户与仪表盘交互后，导出当前选区 d.app() # ... 用户在仪表盘中筛选数据 ... filtered = d.export() # 当前可见/已选数据的 cuDF DataFrame # 继续用 cuDF、cuML 等做进一步分析

十五、维护与迁移：何时继续用 cuxfilter，何时换栈

综合 decision_framework.md 与 code_transformation_patterns.md，本仓库给出如下判定：

存量维护（可以使用）——当现有应用需要以下能力时，维持 cuxfilter：

• 在大型数据集（数百万行）上做交互式交叉筛选仪表盘；
• 带联动图表的探索性数据分析（图表之间互相过滤）；
• GPU 加速的散点、柱状、热力、等值区域或图可视化；
• 从 Jupyter Notebook 用最少代码快速原型化仪表盘；
• 可视化 cuDF、cuML、cuGraph 管线的结果。

新建项目（不要用）——cuxfilter 已停更，不要在 26.06 之后开启新的依赖。替代方案是"cuDF 负责 GPU 数据准备 + HoloViews/hvPlot/Datashader 负责联动可视化，用 Panel/Dash/Streamlit/Bokeh 提供服务"。其代码转换模式为：在 GPU 上完成分组聚合，只在显式的可视化边界传输紧凑的展示数据：

import cudf import hvplot.pandas # 为 pandas 对象注册 .hvplot import panel as pn gpu_df = cudf.read_parquet("large_dataset.parquet") gpu_summary = ( gpu_df.groupby("category", as_index=False) .agg({"value_col": "mean"}) ) display_summary = gpu_summary.to_pandas() # 只传输精简后的结果 dashboard = pn.Column( "# Interactive Explorer", display_summary.hvplot.bar(x="category", y="value_col"), ) dashboard.servable()

对于需要逐点级联动选择（linked selections）的场景，官方推荐用 HoloViews/hvPlot + Datashader + Panel 组合，把筛选/聚合回调尽量留在 GPU 上，并对每次转 pandas 的转换做好记录（见 code_transformation_patterns.md）。

相关仓库资源导航

• 技能总览与选型矩阵：SKILL.md
• 安装与环境配置（含各 RAPIDS 库的 CUDA 12/13 安装命令）：references/installation.md
• 库选型决策框架（cuxfilter 定位与维护场景）：references/decision_framework.md
• 从静态 matplotlib 到 GPU 仪表盘的代码转换模式：references/code_transformation_patterns.md
• 本参考文档原文：references/cuxfilter.md
• 测试与依赖约束（RAPIDS wheel 仅 Linux + CUDA，整体组不可用于无 GPU 环境）：tests/skill-requirements.toml

【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000+ scientists worldwide. 165 ready-to-use validated skills plus 100+ scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills