scientific-agent-skills 中的 GPU 代码转换模式NumPy/pandas/scikit-learn 到 CuPy/cuDF/cuML 的完整迁移实战指南【免费下载链接】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本文是 scientific-agent-skills 仓库中 optimize-for-gpu 技能skill的核心文档《Code Transformation Patterns》的深度展开。当 AI Agent 面对CPU 版 NumPy/SciPy、pandas、scikit-learn、NetworkX、scikit-image、Faiss 或scipy.sparse.linalg代码运行缓慢希望利用 NVIDIA GPU 加速这一类请求时本文提供了 12 组经过验证的Before/After转换模式覆盖数组计算、DataFrame 处理、自定义内核、图分析、机器学习、物理仿真、文件 IO、可视化、图像处理、地理空间、向量检索与稀疏特征值求解。读完本文你将掌握每一类工作负载的优先迁移路径、零代码加速开关、可复制的转换代码以及保证数值语义一致与正确计时的工程方法。转换前的三条铁律契约、基线、合适性optimize-for-gpu技能将 GPU 加速定位为证据驱动的优化而非自动重写。在动手替换任何 import 之前请先完成 SKILL.md 中定义的三件事定义契约与基线捕获代表性输入、期望输出和可接受的数值容差测量当前端到端耗时包含输入、传输、计算、输出全链路在改代码之前先用 CPU profiler 定位真正的瓶颈——是计算、内存带宽、分配、传输、同步还是存储。判断合适性只有当热点路径存在大量独立可并行的工作、运行频率足以摊薄初始化与传输开销、且工作集能放进显存并为临时变量留出余量时GPU 才值得投入。小负载、强顺序、以不受支持操作为主、或需要频繁主机-设备往返的负载应保留 CPU 路径。不要用固定的行数阈值当作该不该上 GPU的证据必须用用户真实形状与真实硬件去实测。选择最小的合适层次优先使用有维护的库实现其次才是自定义内核。技能给出的推荐顺序是先尝试加速器/后端模式cudf.pandas、cuml.accel、nx-cugraph覆盖不足时再迁移到原生 GPU API只有 profiling 证明某个操作没有现成库实现时才写自定义 kernel。每种 CPU 库对应的首选 GPU 路径可汇总为 decision_framework.md 中的选择表现有工作负载首选路径用途NumPy / SciPyCuPy数组、稀疏矩阵、线性代数、FFT、信号处理pandascudf.pandas然后cuDF先用加速器模式原生 API 获得更多控制scikit-learncuml.accel然后cuML先用加速器模式必要时用原生估计器NetworkXnx-cugraph然后cuGraph先用后端分发大规模用原生图 APIscikit-imagecuCIMGPU 图像处理与全切片影像Faiss / Annoy / k-NNcuVS精确与近似向量检索原始或远程文件 IOKvikIOGPU 缓冲区与 GPUDirect Storage自定义数组内核Numba-CUDA-MLIR新项目/Numba-CUDA存量代码显式 SIMT 内核与共享内存空间/可微内核Warp几何、仿真内核、机器人、自动微分高层物理仿真Newton取代已移除warp.sim模块的维护引擎底层 RAPIDS 原语RAFTpylibraft稀疏特征值求解器、资源、多 GPU 构件注意不要仅仅为了使用上述某个库就把代码从 PyTorch、JAX、TensorFlow 等其他 GPU 原生框架中搬出来应先在原框架内消除 CPU 往返利用框架自带的编译器、profiler、混合精度与批处理能力。环境准备按 CUDA 版本安装对应库所有转换代码都依赖正确的安装。本仓库的 installation.md 记录了与 RAPIDS 26.062026 年 6 月对齐的安装约定需要 Python 3.11、CUDA 12.x 或 13.x每个受维护的 RAPIDS 包都提供-cu12与-cu13两种 wheel 变体示例统一使用-cu12CUDA 13 系统请替换为-cu13。独立示例中推荐使用uv add与该仓库约定一致若用户项目已有其他包管理器则遵循原项目。# CuPy选择正确的 CUDA 版本CuPy 14 仅支持 CUDA 12/13 uv add cupy-cuda12x14.1.* # CUDA 12.x uv add cupy-cuda13x14.1.* # CUDA 13.x # Numba-CUDA 兼容路径维护模式自动安装 numba uv add numba-cuda[cu12]0.30.* # CUDA 13 用 [cu13] # Warp仿真、空间计算、可微编程 uv add warp-lang1.15.* # 内置 CUDA 12 运行时 # cuDFRAPIDS DataFrame uv add --extra-index-urlhttps://pypi.nvidia.com cudf-cu1226.6.* # cuMLRAPIDS 机器学习 uv add --extra-index-urlhttps://pypi.nvidia.com cuml-cu1226.6.* # cuGraphRAPIDS 图分析—— NVIDIA 索引仍然必需 uv add --extra-index-urlhttps://pypi.nvidia.com cugraph-cu1226.6.* uv add --extra-index-urlhttps://pypi.nvidia.com nx-cugraph-cu1226.6.* # KvikIO高性能 GPU 文件 IO uv add --extra-index-urlhttps://pypi.nvidia.com kvikio-cu1226.6.* # cuCIMRAPIDS 图像处理 uv add --extra-index-urlhttps://pypi.nvidia.com cucim-cu1226.6.* # cuVSRAPIDS 向量检索 uv add --extra-index-urlhttps://pypi.nvidia.com cuvs-cu1226.6.* # cuSpatial地理空间—— 已归档冻结在 25.04仅限独立环境 uv add --extra-index-urlhttps://pypi.nvidia.com cuspatial-cu1225.4.* # RAFT底层 GPU 原语 uv add --extra-index-urlhttps://pypi.nvidia.com pylibraft-cu1226.6.* uv add --extra-index-urlhttps://pypi.nvidia.com raft-dask-cu1226.6.* # 多 GPU 可选安装后可参考 installation.md 中给出的验证片段逐个确认环境CuPy 检查cp.cuda.runtime.getDeviceCount() 1Numba 检查cuda.is_available()Warp 用wp.init()KvikIO 用kvikio.cufile_driver.get(is_gds_available)确认 GPUDirect Storage 是否就绪。模式一NumPy → CuPy——通常只需改 importCuPy 是 NumPy/SciPy 兼容的 GPU 数组库底层封装了 NVIDIA 优化库cuBLAS、cuFFT、cuSOLVER、cuSPARSE、cuRAND因此大多数标准数组运算开箱即已调优。多数 NumPy 代码只需把import numpy as np换成import cupy as cp# Before (CPU) import numpy as np a np.random.rand(10_000_000) b np.fft.fft(a) c np.sort(b.real) # After (GPU) —— 常常只是改 import import cupy as cp a cp.random.rand(10_000_000) b cp.fft.fft(a) c cp.sort(b.real)从源码层面看cupy.md 详细说明了cupy.ndarray镜像numpy.ndarray的全部常用属性shape、dtype、ndim、size、strides、T并额外提供device属性标明数组所在 GPU。关键行为差异需要牢记两种数组不可隐式转换。cupy.ndarray与numpy.ndarray之间的每一次转换都伴随一次主机-设备数据传输cp.asarray(numpy_array)已在当前设备上时零拷贝与cp.array(numpy_array)总是拷贝回传用cp.asnumpy()或.get()。约简返回 0 维数组而非标量cp.sum(a)返回 0 维cupy.ndarray而非 Python float这是为避免隐式 GPU-CPU 同步需要标量时用.item()。越界索引静默回绕NumPy 抛IndexErrorCuPy 不回绕不报错。重复索引赋值结果未定义a[[0, 0]] [1, 2]在 NumPy 存最后一个值在 CuPy 是未定义GPU 竞争。随机数支持dtype参数float32/float64NumPy 总是返回 float64不需要双精度时用dtypecp.float32。CuPy 的函数覆盖了 NumPy 主体与 SciPy 的大块内容cupy.linalgcuBLAS/cuSOLVER 驱动、cupy.fftcuFFT 驱动、cupyx.scipy.sparseCSR/CSC/COOcuSPARSE 驱动v14 起支持 64 位维度的超大稀疏矩阵、cupyx.scipy.signal与cupyx.scipy.special。零拷贝互操作CuPy 数组实现了__cuda_array_interface__与 DLPack可与 Numba、PyTorch、cuDF 直接互传——torch.as_tensor(cupy_array, devicecuda)、cp.asarray(torch_tensor)都是零拷贝。还可以写 CPU/GPU 无关代码cp.get_array_module(x)会根据输入返回 numpy 或 cupy。模式二pandas → cuDF——零代码与原生 API 两条路cuDF 提供 pandas 风格 API全部在 GPU 上完成加载、连接、聚合、过滤与变换构建于 Apache Arrow 列式内存格式之上。转换有两种方式# Before (CPU) import pandas as pd df pd.read_parquet(large_data.parquet) result df.groupby(category)[value].mean() # After (GPU) —— 改 import import cudf df cudf.read_parquet(large_data.parquet) result df.groupby(category)[value].mean() # 或零代码python -m cudf.pandas your_script.pycudf.pandas加速器模式是本技能推荐的第一优先级。它把import pandas替换为同时包装 cuDF 与 pandas 的代理模块每个操作先在 GPUcuDF上尝试失败则自动回退 CPUpandas。激活方式有三种详见 cudf.md# Jupyter/IPython必须在任何 pandas import 之前 %load_ext cudf.pandas import pandas as pd # 从此 GPU 加速 # 命令行 # python -m cudf.pandas your_script.py # python -m cudf.pandas --profile your_script.py # 带 profiling # 编程方式 import cudf.pandas cudf.pandas.install() import pandas as pd # 从此 GPU 加速关键前提如果会话中已 import 过 pandas必须重启内核/进程。默认使用托管内存managed memory可以处理大于显存的数据集还可用%%cudf.pandas.profile查看每个 cell 的 GPU/CPU 操作占比用proxy_df.as_gpu_object()/as_cpu_object()取底层对象注意取出后自动回退即失效。若需强制 CPU-only设CUDF_PANDAS_FALLBACK_MODE1。原生 cuDF API 与 pandas 的差异迁移时必须处理结果顺序默认不确定groupby、join 等需要sortTrue或全局cudf.set_option(mode.pandas_compatible, True)cuDF 的 groupby 默认sortFalse与 pandas 相反。全部类型可空缺失值是NA而非 NaN使用独立 null mask整数列含缺失值时保持整型不做 float 强转。不支持迭代for val in seriesobjectdtype 只存字符串不允许任意 Python 对象。.apply()走 Numba JITUDF 内只支持数值类型与受限字符串操作含中间字符串时需set_malloc_heap_size()分配堆空间。浮点结果可能因 GPU 并行操作顺序不同而有微小差异——必须用基于容差的比较。迁移模式参考cudf.md 给出 6 种常见迁移模式包括零成本cudf.pandas、直接改 import、用向量化替换iterrows()、GPU 处理 CPU 边界只在绘图/导出时to_pandas()、以及cuDF 不支持的行级数学交给 CuPydf[[x,y,z]].to_cupy()→cp.linalg.norm。IO 上优先 Parquet 而非 CSVGPU 读取更快、支持谓词下推、压缩好文件格式矩阵中 Avro/Text 为 GPU 加速只读HDF5/Feather 回退 pandas。大规模数据用 Dask-cuDFdask_cudf.read_parquet(path/).compute()/.persist()。模式三自定义 Python 循环 → Numba CUDA 内核当代码中存在无法映射为数组运算的逐元素自定义逻辑时把 Python 循环改写为 CUDA 内核。示例是把含math.sin/math.exp的串行循环改写为 SIMT 内核# Before (CPU) —— 慢速 Python 循环 def process(data, out): for i in range(len(data)): out[i] math.sin(data[i]) * math.exp(-data[i]) # After (GPU) —— Numba 内核 from numba import cuda import math cuda.jit def process(data, out): i cuda.grid(1) if i data.size: out[i] math.sin(data[i]) * math.exp(-data[i]) d_data cuda.to_device(data) d_out cuda.device_array(d_data.shape, dtyped_data.dtype) threads 256 blocks (len(data) threads - 1) // threads processblocks, threads out d_out.copy_to_host()结合 numba.md 的源码级说明写内核时要注意层次模型Grid块集合→ Block线程组最多 1024 线程/块可共享片上内存并同步→ Thread。cuda.grid(ndim)取线程的全局索引永远做边界检查if i array.size否则越界线程静默破坏内存。内核不能返回值只能写入作为参数传入的输出数组。内核启动是异步的CPU 端读取结果前必须cuda.synchronize()。线程定位内建函数cuda.threadIdx、cuda.blockIdx、cuda.blockDim、cuda.gridDim、cuda.grid()、cuda.gridsize()用grid-stride 循环for i in range(cuda.grid(1), data.shape[0], cuda.gridsize(1))将网格尺寸与问题尺寸解耦。数据复用用共享内存cuda.shared.array静态或动态cuda.syncthreads()屏障块内树形约简、Hillis-Steele 扫描、带 halo 的 stencil 模式在 reference 中均有完整实现。原子操作cuda.atomic.add/sub/max/min/nanmax/nanmin/and_/or_/xor/exch/cas全部返回旧值add仅支持 int32/float32/float64。设备函数用cuda.jit(deviceTrue)可返回值fastmathTrue在不需要 IEEE-754 严格性时启用 FMA 与快速近似。性能与调试vectorize/guvectorize可把标量函数广播成 GPU ufunc块大小 1D 取 128–256、2D 取 (16,16)/(32,32)NUMBA_ENABLE_CUDASIM1可在 CPU 上模拟调试内核。工具链现状Numba-CUDA 已进入维护模式NVIDIA 新特性开发转向Numba-CUDA-MLIR。对既有numba.cuda代码、兼容性工作或 MLIR 尚未覆盖的特性继续用numba-cuda新内核项目请先评估 MLIR 及其迁移指南。不要在没有 profiling 排除 CuPy 等调优库之前贸然投资自定义内核。模式四NetworkX → cuGraph——原生 API 与零代码后端图分析PageRank、介数中心性、社区发现、最短路径在大网络上应迁移到 cuGraph# Before (CPU) import networkx as nx G nx.read_edgelist(edges.csv, delimiter,, nodetypeint) pr nx.pagerank(G) bc nx.betweenness_centrality(G) # After (GPU) —— 直接 cuGraph API import cugraph import cudf edges cudf.read_csv(edges.csv, names[src, dst], dtype[int32, int32]) G cugraph.Graph() G.from_cudf_edgelist(edges, sourcesrc, destinationdst) pr cugraph.pagerank(G) bc cugraph.betweenness_centrality(G) # 或零代码NX_CUGRAPH_AUTOCONFIGTrue python your_script.py决策框架decision_framework.md建议先启用nx-cugraph后端并检查回退行为当后端覆盖不足或有实测性能理由时再迁移到带 cuDF 边列表的原生 cuGraph API端到端基准必须包含图构建与主机-设备转换成本。cuGraph 的典型适用规模是 1 万条边以上的网络PageRank、介数中心性、Louvain/Leiden 社区检测、BFS/SSSP、连通分量、链接预测与 GNN 采样均在其覆盖范围。模式五scikit-learn → cuML——先 cuml.accel 再原生估计器机器学习训练、推理、预处理与超参搜索均可通过 cuML 加速。转换只需改 import注意train_test_split也要换# Before (CPU) from sklearn.ensemble import RandomForestClassifier from sklearn.preprocessing import StandardScaler from sklearn.model_selection import train_test_split X_train, X_test, y_train, y_test train_test_split(X, y, test_size0.2) scaler StandardScaler() X_train scaler.fit_transform(X_train) model RandomForestClassifier(n_estimators100) model.fit(X_train, y_train) # After (GPU) —— 改 import from cuml.ensemble import RandomForestClassifier from cuml.preprocessing import StandardScaler from cuml.model_selection import train_test_split X_train, X_test, y_train, y_test train_test_split(X, y, test_size0.2) scaler StandardScaler() X_train scaler.fit_transform(X_train) model RandomForestClassifier(n_estimators100) model.fit(X_train, y_train) # 或零代码python -m cuml.accel your_script.pycuml.accel加速器模式在兼容性允许时优先尝试零代码 sklearn 加速迁移到原生 cuML API 的时机是估计器不受支持、需要显式输出控制、或有实测性能理由。决策框架特别强调不要依赖宣传中的加速倍数区间要对用户的具体估计器、维度与端到端管线做基准。cuML 覆盖分类、回归、聚类、降维、预处理管线、模型推理以及 UMAP、t-SNE、HDBSCAN、KNN 等大数据集场景也支持直接接收 cuDF DataFrame。模式六物理仿真循环 → Warp 内核Warp 专为空间计算设计——物理仿真、几何处理、机器人学与可微编程。它把wp.kernel修饰的 Python 函数 JIT 编译为 CUDA内置vec3、quat、transform等空间类型以及 Mesh、Volume、HashGrid、BVH 等空间原语。把粒子积分循环改写为 Warp 内核# Before (CPU) —— 对粒子做慢速 Python 循环 import numpy as np def integrate(positions, velocities, forces, dt): for i in range(len(positions)): velocities[i] forces[i] * dt positions[i] velocities[i] * dt # After (GPU) —— Warp 内核JIT 编译到 CUDA import warp as wp wp.kernel def integrate(positions: wp.array(dtypewp.vec3), velocities: wp.array(dtypewp.vec3), forces: wp.array(dtypewp.vec3), dt: float): tid wp.tid() velocities[tid] velocities[tid] forces[tid] * dt positions[tid] positions[tid] velocities[tid] * dt wp.launch(integrate, dimnum_particles, inputs[positions, velocities, forces, 0.01], devicecuda)结合 warp.md 的关键要点内核参数必须有类型注解Warp 从注解推断类型wp.tid()只在内核中可用wp.func用户函数需显式传线程索引。2D/3D 启动wp.launch(kernel, dim(nx, ny), ...)内核内i, j wp.tid()。可微性Warp 自动生成前向与反向伴随内核参与梯度的数组须requires_gradTrue用wp.Tape()记录并tape.backward(loss)可与 PyTorch autograd / JAX JIT 集成。注意in-place 数组修改不可微需写独立输出数组。CUDA Graph 捕获反复启动同一内核序列时用wp.ScopedCapture()捕获后wp.capture_launch(capture.graph)近乎零 CPU 开销回放——非常适合仿真主循环。空间原语生命周期Mesh / HashGrid / Volume / BVH 的 Python 对象必须在其.id被内核使用期间保持存活GC 过早回收会导致未定义行为。tile 编程wp.launch_tiledwp.tile_load/matmul/store/sum提供类 Triton 的块级协作操作共享内存 Tensor Core并支持wp.tile_bvh_query_aabb等空间查询。高层物理引擎请用Newtonwarp.sim模块在 Warp 1.10 已移除Warp 本身用于自定义内核与领域原语。模式七文件 IO → KvikIO——绕过 CPU 的 GPUDirect Storage当 IO 是存储与 GPU 之间瓶颈时用 KvikIOcuFile 的 Python 绑定让数据从 NVMe 或远程存储直接流入显存# Before —— CPU 中转磁盘 → CPU → GPU import numpy as np import cupy as cp data np.fromfile(data.bin, dtypenp.float32) gpu_data cp.asarray(data) # 额外经过一次 CPU 内存 # After —— 直达 GPU磁盘 → GPU经 GDS import cupy as cp import kvikio gpu_data cp.empty(1_000_000, dtypecp.float32) with kvikio.CuFile(data.bin, r) as f: f.read(gpu_data) # 用 GPUDirect Storage 绕过 CPU 内存 # 从 S3 直接读到 GPU with kvikio.RemoteFile.open_s3_url(s3://bucket/data.bin) as f: buf cp.empty(f.nbytes() // 4, dtypecp.float32) f.read(buf)kvikio.md 补充了完整 APICuFile的阻塞方法read/write非阻塞并行方法pread/pwrite返回IOFuture可重叠 IO 与计算以及设备专用raw_read/raw_write系列文件模式r/w/a/。GDS 不可用时自动透明回退 POSIX IO。注意适用范围何时用大二进制数据直读显存、显存数组直写磁盘、S3/HTTP/WebHDFS 直读 GPU、Zarr 数组 GPU 后端GDSStore或需要 IO 与计算流水线重叠。何时不用数据小于 1 MB内核启动与 GDS 开销占主导读取结构化格式CSV/Parquet/JSON应用 cuDF 自带的优化 reader只需主机内存就用标准 Python IO。安装后可用kvikio.cufile_driver.get(is_gds_available)确认 GDS 是否配置。模式八GPU 数据准备 维护中的仪表盘栈替代已停运的 cuxfiltercuxfilter 在 RAPIDS 26.06 发布了最终版本后停运。不要用 cuxfilter 启动新应用。正确的现代做法是在 cuDF 中完成大批量变换与聚合然后在显式可视化边界上只传输紧凑的展示数据# Before —— 静态 matplotlib/seaborn 图无交互 import pandas as pd import matplotlib.pyplot as plt df pd.read_parquet(large_dataset.parquet) fig, axes plt.subplots(1, 2) df.plot.scatter(xfeature1, yfeature2, axaxes[0]) df[category].value_counts().plot.bar(axaxes[1]) plt.show() # After —— 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_indexFalse) .agg({value_col: mean}) ) display_summary gpu_summary.to_pandas() # 只传输约简后的结果 dashboard pn.Column( # Interactive Explorer, display_summary.hvplot.bar(xcategory, yvalue_col), ) dashboard.servable()对于需要在大数据点上做联动选择linked selections的场景使用 HoloViews/hvPlot Datashader Panel。实践原则过滤/聚合回调尽量留在 GPU 上执行文档记录每一次到 pandas 的转换只有维护既有 26.06 应用时才阅读 cuxfilter 参考文档。模式九scikit-image → cuCIM——改 import 加一次 cp.asarray图像处理滤波、形态学、分割、特征检测用 cuCIM 加速。cucim.skimage镜像 scikit-image API200 个 GPU 加速函数全部函数直接操作 CuPy 数组零拷贝、全程在 GPU# Before (CPU) from skimage.filters import gaussian, sobel, threshold_otsu from skimage.morphology import binary_opening, disk from skimage.measure import label, regionprops_table import numpy as np blurred gaussian(image, sigma3) binary blurred threshold_otsu(blurred) cleaned binary_opening(binary, footprintdisk(3)) labels label(cleaned) props regionprops_table(labels, image, properties[area, centroid]) # After (GPU) —— 改 import用 cp.asarray 包裹输入 from cucim.skimage.filters import gaussian, sobel, threshold_otsu from cucim.skimage.morphology import binary_opening, disk from cucim.skimage.measure import label, regionprops_table import cupy as cp image_gpu cp.asarray(image) # 只传输一次 blurred gaussian(image_gpu, sigma3) binary blurred threshold_otsu(blurred) cleaned binary_opening(binary, footprintdisk(3)) labels label(cleaned) props regionprops_table(labels, image_gpu, properties[area, centroid])适用场景Gaussian/Sobel/Frangi 等滤波、形态学、阈值、连通分量标记、region properties、颜色空间转换、图像配准、去噪以及数字病理中的全切片影像WSI读取与预处理管线图像在 512×512 及以上的管道收益明显。cuCIM 还提供高性能 WSI readerCuImage。可与 CuPy 链式处理cuCIM 原生操作 CuPy 数组也可经 DLPack 零拷贝直通 PyTorch。模式十GeoPandas 点面包含 → cuSpatial仅限 legacy 25.04cuSpatial 已归档与当前 RAPIDS 包不兼容。仅在独立、固定到 25.04 的隔离环境中使用。point_in_polygon返回布尔成员矩阵不是geopandas.sjoin的直接替代品# Before (CPU) import geopandas as gpd import numpy as np from shapely.geometry import Point points gpd.GeoSeries([Point(x, y) for x, y in coords], crsEPSG:4326) polygons gpd.read_file(regions.geojson).geometry.iloc[:31] membership_cpu np.column_stack( [points.within(polygon).to_numpy() for polygon in polygons] ) # After (GPU, legacy) —— 相同的逐点-逐多边形成员语义 import cuspatial points_gpu cuspatial.from_geopandas(points) polygons_gpu cuspatial.from_geopandas(polygons) membership_gpu cuspatial.point_in_polygon(points_gpu, polygons_gpu)cuSpatial 的官方定位decision_framework.md仓库自 2025 年 7 月只读最终版本 25.04固定cudf-cu1225.4.*因而与当前 RAPIDS 发行版冲突没有官方继任者。新工作不要把它当作现行 GeoPandas 替代品——正确做法是把几何运算留在 GeoPandas/ShapelyCPU用 cuDF 加速工作流中兼容的表格阶段。模式十一Faiss 精确检索 → cuVS 精确检索——先对齐算法语义再谈基准向量检索迁移的纪律先匹配算法语义再做基准测试。用 cuVS 的 brute force 匹配 FaissIndexFlatL2的精确基线只有当可接受近似结果时才用 CAGRA并对照精确真值报告 recallk——绝不把精确 CPU 算法与近似 GPU 算法当作等价物比较# Before (CPU) —— Faiss import faiss import numpy as np rng np.random.default_rng(42) embeddings rng.random((1_000_000, 128), dtypenp.float32) queries rng.random((1_000, 128), dtypenp.float32) index faiss.IndexFlatL2(128) index.add(embeddings) distances, neighbors index.search(queries, k10) # After (GPU) —— cuVS 精确暴力检索 import cupy as cp from cuvs.neighbors import brute_force embeddings_gpu cp.asarray(embeddings) queries_gpu cp.asarray(queries) index_gpu brute_force.build(embeddings_gpu, metricsqeuclidean) distances_gpu, neighbors_gpu brute_force.search(index_gpu, queries_gpu, k10)cuvs.md 的索引选择指南CAGRA 是首选 ANN 候选图结构、GPU 原生、最快IVF-Flat 适合不做向量压缩的高召回 ANNIVF-PQ 适合放不进显存的大数据集压缩存储Brute Force 适合小数据集或作真值HNSW 用于由 GPU 构建索引、CPU 侧服务。度量支持sqeuclidean、inner_product、cosine等。不要用 RAFT 做向量检索——k-NN/IVFPQ/CAGRA 已全部迁往 cuVS。独立基准应分别测量 build、search、transfer 与序列化成本。模式十二scipy.sparse.linalg → RAFT——GPU 稀疏特征值求解对大型稀疏对称矩阵的特征值问题谱方法、图划分、大规模稀疏哈密顿量、结构振动模态用 RAFT 的 GPU Lanczos 求解器替换scipy.sparse.linalg.eigsh# Before (CPU) import numpy as np from scipy.sparse import random as sparse_random from scipy.sparse.linalg import eigsh A sparse_random(10000, 10000, density0.01, formatcsr, dtypenp.float32) A A A.T # 构造对称矩阵 eigenvalues, eigenvectors eigsh(A, k10, whichLM) # After (GPU) —— RAFT 稀疏特征值求解器 import cupy as cp import cupyx.scipy.sparse as sp_gpu from pylibraft.sparse.linalg import eigsh as gpu_eigsh A_gpu sp_gpu.csr_matrix(A) # 传输到 GPU eigenvalues, eigenvectors gpu_eigsh(A_gpu, k10, whichLM)raft.md 给出了求解器的完整参数契约迁移时应逐项核对参数说明A稀疏对称 CSR 矩阵cupyx.scipy.sparse.csr_matrixk要计算的特征值个数默认 6必须1 k nwhichLM最大模默认、LA最大代数、SA最小代数、SM最小模v0起始向量可选默认随机ncvLanczos 向量数须k 1 ncv nmaxiter最大迭代次数tol收敛容差0 机器精度seed随机种子可复现性handle可选的DeviceResources句柄RAF T 的关键工程点DeviceResources是 CUDA 资源句柄管理 stream、stream 池、cuBLAS/cuSOLVER 库句柄创建一次并在多次调用间复用可传入 CuPy streamDeviceResources(streamcupy_stream.ptr)。RAF T 调用默认异步——必须在读取 CPU 侧结果前handle.sync()不传handle时 RAF T 内部临时分配资源并在返回前同步方便但重复调用更慢。错误稀疏格式eigsh只接受cupyx.scipy.sparse.csr_matrixCOO/CSC 需先转换仅限实对称/Hermitian 矩阵dtype 必须显式float32/float64不要依赖隐式转换。互操作device_ndarray实现__cuda_array_interface__CuPy、PyTorch、cuDF 数组可直接传入输出类型可用pylibraft.config.set_output_as(cupy)/torch全局配置。RAF T 还提供 R-MAT 随机图生成pylibraft.random.rmat适合图算法基准与raft-dask的多节点多 GPU 通信Comms类管理 NCCL/UCX。性能建议复用DeviceResources、批量同步、优先 float32、预分配输出、数据全程留在 GPU。贯穿所有模式的工程原则1. 保持连贯的 GPU 数据路径。输入只传输一次中间结果保持设备驻留复用分配、优先out或 in-place 形式批量小操作、融合逐元素工作以消除中间数组只有 profiling 证明传输重叠带来收益时才使用 pinned host memory 与非默认 stream契约允许时才选 float32/混合精度。2. 先验证语义再谈速度。在小而确定的 fixture 与代表性数据上对比 CPU/GPU 输出浮点结果用显式容差测试边界情况、NaN、排序与 dtype对近似最近邻索引报告 recallk检查加速器警告与日志中的 CPU 回退。3. 正确测量 GPU 代码。GPU 工作是异步的CPU 定时器测量的是入队时间而非执行时间。预热上下文创建与 JIT 编译后用 CUDA 事件或库感知计时器from cupyx.profiler import benchmark print(benchmark(gpu_function, (arg1, arg2), n_warmup10, n_repeat100))Notebook 中用%gpu_timeit端到端时间线用 Nsight Systemsnsys内核分析用 Nsight Computencu。同时报告同步内核时间与真实端到端延迟生产环境需要承担传输与转换成本时把它们计入。4. 保留、修订或拒绝移植。只有通过正确性检查并在代表性数据上改善了用户关心的指标时才保留 GPU 路径否则要解释限制因素到底是问题规模、传输、不支持回退、显存压力、启动粒度还是算法本身。需要可移植性时提供 CPU 回退测试数值正确性GPU 浮点可能因操作顺序与 CPU 略有不同数据大于显存时考虑分块或 RAPIDS Dask 多 GPU。不同 GPU 库之间通过 CUDA Array Interface / DLPack 零拷贝互操作——组合使用如 cuDF cuML、cuGraph cuML、cuCIM PyTorch、KvikIO CuPy、RAFT CuPy时确认 device、dtype、连续性、所有权与 stream 语义不要假设任何转换都是免费的。完整的分库决策何时是错误选择、如何组合见 decision_framework.md逐库安装与验证见 installation.md各库的深入 API 参考CuPy 内核融合与内存池、cuDF 字符串与 UDF、Warp tile 与可微编程、RAFT 设备内存管理等可从 SKILL.md 的 Reference Files 索引进入。把这 12 组转换模式与最小合适层次 证据驱动基准的方法论结合AI Agent 即可在保持数值契约的前提下安全地把 CPU 科学计算工作负载迁上 NVIDIA 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/11 17:31:17 · 阅读 1.2k scientific-agent-skills 中的 GPU 代码转换模式：NumPy/pandas/scikit-learn 到 CuPy/cuDF/cuML 的完整迁移实战指南
scientific-agent-skills 中的 GPU 代码转换模式NumPy/pandas/scikit-learn 到 CuPy/cuDF/cuML 的完整迁移实战指南【免费下载链接】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本文是 scientific-agent-skills 仓库中 optimize-for-gpu 技能skill的核心文档《Code Transformation Patterns》的深度展开。当 AI Agent 面对CPU 版 NumPy/SciPy、pandas、scikit-learn、NetworkX、scikit-image、Faiss 或scipy.sparse.linalg代码运行缓慢希望利用 NVIDIA GPU 加速这一类请求时本文提供了 12 组经过验证的Before/After转换模式覆盖数组计算、DataFrame 处理、自定义内核、图分析、机器学习、物理仿真、文件 IO、可视化、图像处理、地理空间、向量检索与稀疏特征值求解。读完本文你将掌握每一类工作负载的优先迁移路径、零代码加速开关、可复制的转换代码以及保证数值语义一致与正确计时的工程方法。转换前的三条铁律契约、基线、合适性optimize-for-gpu技能将 GPU 加速定位为证据驱动的优化而非自动重写。在动手替换任何 import 之前请先完成 SKILL.md 中定义的三件事定义契约与基线捕获代表性输入、期望输出和可接受的数值容差测量当前端到端耗时包含输入、传输、计算、输出全链路在改代码之前先用 CPU profiler 定位真正的瓶颈——是计算、内存带宽、分配、传输、同步还是存储。判断合适性只有当热点路径存在大量独立可并行的工作、运行频率足以摊薄初始化与传输开销、且工作集能放进显存并为临时变量留出余量时GPU 才值得投入。小负载、强顺序、以不受支持操作为主、或需要频繁主机-设备往返的负载应保留 CPU 路径。不要用固定的行数阈值当作该不该上 GPU的证据必须用用户真实形状与真实硬件去实测。选择最小的合适层次优先使用有维护的库实现其次才是自定义内核。技能给出的推荐顺序是先尝试加速器/后端模式cudf.pandas、cuml.accel、nx-cugraph覆盖不足时再迁移到原生 GPU API只有 profiling 证明某个操作没有现成库实现时才写自定义 kernel。每种 CPU 库对应的首选 GPU 路径可汇总为 decision_framework.md 中的选择表现有工作负载首选路径用途NumPy / SciPyCuPy数组、稀疏矩阵、线性代数、FFT、信号处理pandascudf.pandas然后cuDF先用加速器模式原生 API 获得更多控制scikit-learncuml.accel然后cuML先用加速器模式必要时用原生估计器NetworkXnx-cugraph然后cuGraph先用后端分发大规模用原生图 APIscikit-imagecuCIMGPU 图像处理与全切片影像Faiss / Annoy / k-NNcuVS精确与近似向量检索原始或远程文件 IOKvikIOGPU 缓冲区与 GPUDirect Storage自定义数组内核Numba-CUDA-MLIR新项目/Numba-CUDA存量代码显式 SIMT 内核与共享内存空间/可微内核Warp几何、仿真内核、机器人、自动微分高层物理仿真Newton取代已移除warp.sim模块的维护引擎底层 RAPIDS 原语RAFTpylibraft稀疏特征值求解器、资源、多 GPU 构件注意不要仅仅为了使用上述某个库就把代码从 PyTorch、JAX、TensorFlow 等其他 GPU 原生框架中搬出来应先在原框架内消除 CPU 往返利用框架自带的编译器、profiler、混合精度与批处理能力。环境准备按 CUDA 版本安装对应库所有转换代码都依赖正确的安装。本仓库的 installation.md 记录了与 RAPIDS 26.062026 年 6 月对齐的安装约定需要 Python 3.11、CUDA 12.x 或 13.x每个受维护的 RAPIDS 包都提供-cu12与-cu13两种 wheel 变体示例统一使用-cu12CUDA 13 系统请替换为-cu13。独立示例中推荐使用uv add与该仓库约定一致若用户项目已有其他包管理器则遵循原项目。# CuPy选择正确的 CUDA 版本CuPy 14 仅支持 CUDA 12/13 uv add cupy-cuda12x14.1.* # CUDA 12.x uv add cupy-cuda13x14.1.* # CUDA 13.x # Numba-CUDA 兼容路径维护模式自动安装 numba uv add numba-cuda[cu12]0.30.* # CUDA 13 用 [cu13] # Warp仿真、空间计算、可微编程 uv add warp-lang1.15.* # 内置 CUDA 12 运行时 # cuDFRAPIDS DataFrame uv add --extra-index-urlhttps://pypi.nvidia.com cudf-cu1226.6.* # cuMLRAPIDS 机器学习 uv add --extra-index-urlhttps://pypi.nvidia.com cuml-cu1226.6.* # cuGraphRAPIDS 图分析—— NVIDIA 索引仍然必需 uv add --extra-index-urlhttps://pypi.nvidia.com cugraph-cu1226.6.* uv add --extra-index-urlhttps://pypi.nvidia.com nx-cugraph-cu1226.6.* # KvikIO高性能 GPU 文件 IO uv add --extra-index-urlhttps://pypi.nvidia.com kvikio-cu1226.6.* # cuCIMRAPIDS 图像处理 uv add --extra-index-urlhttps://pypi.nvidia.com cucim-cu1226.6.* # cuVSRAPIDS 向量检索 uv add --extra-index-urlhttps://pypi.nvidia.com cuvs-cu1226.6.* # cuSpatial地理空间—— 已归档冻结在 25.04仅限独立环境 uv add --extra-index-urlhttps://pypi.nvidia.com cuspatial-cu1225.4.* # RAFT底层 GPU 原语 uv add --extra-index-urlhttps://pypi.nvidia.com pylibraft-cu1226.6.* uv add --extra-index-urlhttps://pypi.nvidia.com raft-dask-cu1226.6.* # 多 GPU 可选安装后可参考 installation.md 中给出的验证片段逐个确认环境CuPy 检查cp.cuda.runtime.getDeviceCount() 1Numba 检查cuda.is_available()Warp 用wp.init()KvikIO 用kvikio.cufile_driver.get(is_gds_available)确认 GPUDirect Storage 是否就绪。模式一NumPy → CuPy——通常只需改 importCuPy 是 NumPy/SciPy 兼容的 GPU 数组库底层封装了 NVIDIA 优化库cuBLAS、cuFFT、cuSOLVER、cuSPARSE、cuRAND因此大多数标准数组运算开箱即已调优。多数 NumPy 代码只需把import numpy as np换成import cupy as cp# Before (CPU) import numpy as np a np.random.rand(10_000_000) b np.fft.fft(a) c np.sort(b.real) # After (GPU) —— 常常只是改 import import cupy as cp a cp.random.rand(10_000_000) b cp.fft.fft(a) c cp.sort(b.real)从源码层面看cupy.md 详细说明了cupy.ndarray镜像numpy.ndarray的全部常用属性shape、dtype、ndim、size、strides、T并额外提供device属性标明数组所在 GPU。关键行为差异需要牢记两种数组不可隐式转换。cupy.ndarray与numpy.ndarray之间的每一次转换都伴随一次主机-设备数据传输cp.asarray(numpy_array)已在当前设备上时零拷贝与cp.array(numpy_array)总是拷贝回传用cp.asnumpy()或.get()。约简返回 0 维数组而非标量cp.sum(a)返回 0 维cupy.ndarray而非 Python float这是为避免隐式 GPU-CPU 同步需要标量时用.item()。越界索引静默回绕NumPy 抛IndexErrorCuPy 不回绕不报错。重复索引赋值结果未定义a[[0, 0]] [1, 2]在 NumPy 存最后一个值在 CuPy 是未定义GPU 竞争。随机数支持dtype参数float32/float64NumPy 总是返回 float64不需要双精度时用dtypecp.float32。CuPy 的函数覆盖了 NumPy 主体与 SciPy 的大块内容cupy.linalgcuBLAS/cuSOLVER 驱动、cupy.fftcuFFT 驱动、cupyx.scipy.sparseCSR/CSC/COOcuSPARSE 驱动v14 起支持 64 位维度的超大稀疏矩阵、cupyx.scipy.signal与cupyx.scipy.special。零拷贝互操作CuPy 数组实现了__cuda_array_interface__与 DLPack可与 Numba、PyTorch、cuDF 直接互传——torch.as_tensor(cupy_array, devicecuda)、cp.asarray(torch_tensor)都是零拷贝。还可以写 CPU/GPU 无关代码cp.get_array_module(x)会根据输入返回 numpy 或 cupy。模式二pandas → cuDF——零代码与原生 API 两条路cuDF 提供 pandas 风格 API全部在 GPU 上完成加载、连接、聚合、过滤与变换构建于 Apache Arrow 列式内存格式之上。转换有两种方式# Before (CPU) import pandas as pd df pd.read_parquet(large_data.parquet) result df.groupby(category)[value].mean() # After (GPU) —— 改 import import cudf df cudf.read_parquet(large_data.parquet) result df.groupby(category)[value].mean() # 或零代码python -m cudf.pandas your_script.pycudf.pandas加速器模式是本技能推荐的第一优先级。它把import pandas替换为同时包装 cuDF 与 pandas 的代理模块每个操作先在 GPUcuDF上尝试失败则自动回退 CPUpandas。激活方式有三种详见 cudf.md# Jupyter/IPython必须在任何 pandas import 之前 %load_ext cudf.pandas import pandas as pd # 从此 GPU 加速 # 命令行 # python -m cudf.pandas your_script.py # python -m cudf.pandas --profile your_script.py # 带 profiling # 编程方式 import cudf.pandas cudf.pandas.install() import pandas as pd # 从此 GPU 加速关键前提如果会话中已 import 过 pandas必须重启内核/进程。默认使用托管内存managed memory可以处理大于显存的数据集还可用%%cudf.pandas.profile查看每个 cell 的 GPU/CPU 操作占比用proxy_df.as_gpu_object()/as_cpu_object()取底层对象注意取出后自动回退即失效。若需强制 CPU-only设CUDF_PANDAS_FALLBACK_MODE1。原生 cuDF API 与 pandas 的差异迁移时必须处理结果顺序默认不确定groupby、join 等需要sortTrue或全局cudf.set_option(mode.pandas_compatible, True)cuDF 的 groupby 默认sortFalse与 pandas 相反。全部类型可空缺失值是NA而非 NaN使用独立 null mask整数列含缺失值时保持整型不做 float 强转。不支持迭代for val in seriesobjectdtype 只存字符串不允许任意 Python 对象。.apply()走 Numba JITUDF 内只支持数值类型与受限字符串操作含中间字符串时需set_malloc_heap_size()分配堆空间。浮点结果可能因 GPU 并行操作顺序不同而有微小差异——必须用基于容差的比较。迁移模式参考cudf.md 给出 6 种常见迁移模式包括零成本cudf.pandas、直接改 import、用向量化替换iterrows()、GPU 处理 CPU 边界只在绘图/导出时to_pandas()、以及cuDF 不支持的行级数学交给 CuPydf[[x,y,z]].to_cupy()→cp.linalg.norm。IO 上优先 Parquet 而非 CSVGPU 读取更快、支持谓词下推、压缩好文件格式矩阵中 Avro/Text 为 GPU 加速只读HDF5/Feather 回退 pandas。大规模数据用 Dask-cuDFdask_cudf.read_parquet(path/).compute()/.persist()。模式三自定义 Python 循环 → Numba CUDA 内核当代码中存在无法映射为数组运算的逐元素自定义逻辑时把 Python 循环改写为 CUDA 内核。示例是把含math.sin/math.exp的串行循环改写为 SIMT 内核# Before (CPU) —— 慢速 Python 循环 def process(data, out): for i in range(len(data)): out[i] math.sin(data[i]) * math.exp(-data[i]) # After (GPU) —— Numba 内核 from numba import cuda import math cuda.jit def process(data, out): i cuda.grid(1) if i data.size: out[i] math.sin(data[i]) * math.exp(-data[i]) d_data cuda.to_device(data) d_out cuda.device_array(d_data.shape, dtyped_data.dtype) threads 256 blocks (len(data) threads - 1) // threads processblocks, threads out d_out.copy_to_host()结合 numba.md 的源码级说明写内核时要注意层次模型Grid块集合→ Block线程组最多 1024 线程/块可共享片上内存并同步→ Thread。cuda.grid(ndim)取线程的全局索引永远做边界检查if i array.size否则越界线程静默破坏内存。内核不能返回值只能写入作为参数传入的输出数组。内核启动是异步的CPU 端读取结果前必须cuda.synchronize()。线程定位内建函数cuda.threadIdx、cuda.blockIdx、cuda.blockDim、cuda.gridDim、cuda.grid()、cuda.gridsize()用grid-stride 循环for i in range(cuda.grid(1), data.shape[0], cuda.gridsize(1))将网格尺寸与问题尺寸解耦。数据复用用共享内存cuda.shared.array静态或动态cuda.syncthreads()屏障块内树形约简、Hillis-Steele 扫描、带 halo 的 stencil 模式在 reference 中均有完整实现。原子操作cuda.atomic.add/sub/max/min/nanmax/nanmin/and_/or_/xor/exch/cas全部返回旧值add仅支持 int32/float32/float64。设备函数用cuda.jit(deviceTrue)可返回值fastmathTrue在不需要 IEEE-754 严格性时启用 FMA 与快速近似。性能与调试vectorize/guvectorize可把标量函数广播成 GPU ufunc块大小 1D 取 128–256、2D 取 (16,16)/(32,32)NUMBA_ENABLE_CUDASIM1可在 CPU 上模拟调试内核。工具链现状Numba-CUDA 已进入维护模式NVIDIA 新特性开发转向Numba-CUDA-MLIR。对既有numba.cuda代码、兼容性工作或 MLIR 尚未覆盖的特性继续用numba-cuda新内核项目请先评估 MLIR 及其迁移指南。不要在没有 profiling 排除 CuPy 等调优库之前贸然投资自定义内核。模式四NetworkX → cuGraph——原生 API 与零代码后端图分析PageRank、介数中心性、社区发现、最短路径在大网络上应迁移到 cuGraph# Before (CPU) import networkx as nx G nx.read_edgelist(edges.csv, delimiter,, nodetypeint) pr nx.pagerank(G) bc nx.betweenness_centrality(G) # After (GPU) —— 直接 cuGraph API import cugraph import cudf edges cudf.read_csv(edges.csv, names[src, dst], dtype[int32, int32]) G cugraph.Graph() G.from_cudf_edgelist(edges, sourcesrc, destinationdst) pr cugraph.pagerank(G) bc cugraph.betweenness_centrality(G) # 或零代码NX_CUGRAPH_AUTOCONFIGTrue python your_script.py决策框架decision_framework.md建议先启用nx-cugraph后端并检查回退行为当后端覆盖不足或有实测性能理由时再迁移到带 cuDF 边列表的原生 cuGraph API端到端基准必须包含图构建与主机-设备转换成本。cuGraph 的典型适用规模是 1 万条边以上的网络PageRank、介数中心性、Louvain/Leiden 社区检测、BFS/SSSP、连通分量、链接预测与 GNN 采样均在其覆盖范围。模式五scikit-learn → cuML——先 cuml.accel 再原生估计器机器学习训练、推理、预处理与超参搜索均可通过 cuML 加速。转换只需改 import注意train_test_split也要换# Before (CPU) from sklearn.ensemble import RandomForestClassifier from sklearn.preprocessing import StandardScaler from sklearn.model_selection import train_test_split X_train, X_test, y_train, y_test train_test_split(X, y, test_size0.2) scaler StandardScaler() X_train scaler.fit_transform(X_train) model RandomForestClassifier(n_estimators100) model.fit(X_train, y_train) # After (GPU) —— 改 import from cuml.ensemble import RandomForestClassifier from cuml.preprocessing import StandardScaler from cuml.model_selection import train_test_split X_train, X_test, y_train, y_test train_test_split(X, y, test_size0.2) scaler StandardScaler() X_train scaler.fit_transform(X_train) model RandomForestClassifier(n_estimators100) model.fit(X_train, y_train) # 或零代码python -m cuml.accel your_script.pycuml.accel加速器模式在兼容性允许时优先尝试零代码 sklearn 加速迁移到原生 cuML API 的时机是估计器不受支持、需要显式输出控制、或有实测性能理由。决策框架特别强调不要依赖宣传中的加速倍数区间要对用户的具体估计器、维度与端到端管线做基准。cuML 覆盖分类、回归、聚类、降维、预处理管线、模型推理以及 UMAP、t-SNE、HDBSCAN、KNN 等大数据集场景也支持直接接收 cuDF DataFrame。模式六物理仿真循环 → Warp 内核Warp 专为空间计算设计——物理仿真、几何处理、机器人学与可微编程。它把wp.kernel修饰的 Python 函数 JIT 编译为 CUDA内置vec3、quat、transform等空间类型以及 Mesh、Volume、HashGrid、BVH 等空间原语。把粒子积分循环改写为 Warp 内核# Before (CPU) —— 对粒子做慢速 Python 循环 import numpy as np def integrate(positions, velocities, forces, dt): for i in range(len(positions)): velocities[i] forces[i] * dt positions[i] velocities[i] * dt # After (GPU) —— Warp 内核JIT 编译到 CUDA import warp as wp wp.kernel def integrate(positions: wp.array(dtypewp.vec3), velocities: wp.array(dtypewp.vec3), forces: wp.array(dtypewp.vec3), dt: float): tid wp.tid() velocities[tid] velocities[tid] forces[tid] * dt positions[tid] positions[tid] velocities[tid] * dt wp.launch(integrate, dimnum_particles, inputs[positions, velocities, forces, 0.01], devicecuda)结合 warp.md 的关键要点内核参数必须有类型注解Warp 从注解推断类型wp.tid()只在内核中可用wp.func用户函数需显式传线程索引。2D/3D 启动wp.launch(kernel, dim(nx, ny), ...)内核内i, j wp.tid()。可微性Warp 自动生成前向与反向伴随内核参与梯度的数组须requires_gradTrue用wp.Tape()记录并tape.backward(loss)可与 PyTorch autograd / JAX JIT 集成。注意in-place 数组修改不可微需写独立输出数组。CUDA Graph 捕获反复启动同一内核序列时用wp.ScopedCapture()捕获后wp.capture_launch(capture.graph)近乎零 CPU 开销回放——非常适合仿真主循环。空间原语生命周期Mesh / HashGrid / Volume / BVH 的 Python 对象必须在其.id被内核使用期间保持存活GC 过早回收会导致未定义行为。tile 编程wp.launch_tiledwp.tile_load/matmul/store/sum提供类 Triton 的块级协作操作共享内存 Tensor Core并支持wp.tile_bvh_query_aabb等空间查询。高层物理引擎请用Newtonwarp.sim模块在 Warp 1.10 已移除Warp 本身用于自定义内核与领域原语。模式七文件 IO → KvikIO——绕过 CPU 的 GPUDirect Storage当 IO 是存储与 GPU 之间瓶颈时用 KvikIOcuFile 的 Python 绑定让数据从 NVMe 或远程存储直接流入显存# Before —— CPU 中转磁盘 → CPU → GPU import numpy as np import cupy as cp data np.fromfile(data.bin, dtypenp.float32) gpu_data cp.asarray(data) # 额外经过一次 CPU 内存 # After —— 直达 GPU磁盘 → GPU经 GDS import cupy as cp import kvikio gpu_data cp.empty(1_000_000, dtypecp.float32) with kvikio.CuFile(data.bin, r) as f: f.read(gpu_data) # 用 GPUDirect Storage 绕过 CPU 内存 # 从 S3 直接读到 GPU with kvikio.RemoteFile.open_s3_url(s3://bucket/data.bin) as f: buf cp.empty(f.nbytes() // 4, dtypecp.float32) f.read(buf)kvikio.md 补充了完整 APICuFile的阻塞方法read/write非阻塞并行方法pread/pwrite返回IOFuture可重叠 IO 与计算以及设备专用raw_read/raw_write系列文件模式r/w/a/。GDS 不可用时自动透明回退 POSIX IO。注意适用范围何时用大二进制数据直读显存、显存数组直写磁盘、S3/HTTP/WebHDFS 直读 GPU、Zarr 数组 GPU 后端GDSStore或需要 IO 与计算流水线重叠。何时不用数据小于 1 MB内核启动与 GDS 开销占主导读取结构化格式CSV/Parquet/JSON应用 cuDF 自带的优化 reader只需主机内存就用标准 Python IO。安装后可用kvikio.cufile_driver.get(is_gds_available)确认 GDS 是否配置。模式八GPU 数据准备 维护中的仪表盘栈替代已停运的 cuxfiltercuxfilter 在 RAPIDS 26.06 发布了最终版本后停运。不要用 cuxfilter 启动新应用。正确的现代做法是在 cuDF 中完成大批量变换与聚合然后在显式可视化边界上只传输紧凑的展示数据# Before —— 静态 matplotlib/seaborn 图无交互 import pandas as pd import matplotlib.pyplot as plt df pd.read_parquet(large_dataset.parquet) fig, axes plt.subplots(1, 2) df.plot.scatter(xfeature1, yfeature2, axaxes[0]) df[category].value_counts().plot.bar(axaxes[1]) plt.show() # After —— 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_indexFalse) .agg({value_col: mean}) ) display_summary gpu_summary.to_pandas() # 只传输约简后的结果 dashboard pn.Column( # Interactive Explorer, display_summary.hvplot.bar(xcategory, yvalue_col), ) dashboard.servable()对于需要在大数据点上做联动选择linked selections的场景使用 HoloViews/hvPlot Datashader Panel。实践原则过滤/聚合回调尽量留在 GPU 上执行文档记录每一次到 pandas 的转换只有维护既有 26.06 应用时才阅读 cuxfilter 参考文档。模式九scikit-image → cuCIM——改 import 加一次 cp.asarray图像处理滤波、形态学、分割、特征检测用 cuCIM 加速。cucim.skimage镜像 scikit-image API200 个 GPU 加速函数全部函数直接操作 CuPy 数组零拷贝、全程在 GPU# Before (CPU) from skimage.filters import gaussian, sobel, threshold_otsu from skimage.morphology import binary_opening, disk from skimage.measure import label, regionprops_table import numpy as np blurred gaussian(image, sigma3) binary blurred threshold_otsu(blurred) cleaned binary_opening(binary, footprintdisk(3)) labels label(cleaned) props regionprops_table(labels, image, properties[area, centroid]) # After (GPU) —— 改 import用 cp.asarray 包裹输入 from cucim.skimage.filters import gaussian, sobel, threshold_otsu from cucim.skimage.morphology import binary_opening, disk from cucim.skimage.measure import label, regionprops_table import cupy as cp image_gpu cp.asarray(image) # 只传输一次 blurred gaussian(image_gpu, sigma3) binary blurred threshold_otsu(blurred) cleaned binary_opening(binary, footprintdisk(3)) labels label(cleaned) props regionprops_table(labels, image_gpu, properties[area, centroid])适用场景Gaussian/Sobel/Frangi 等滤波、形态学、阈值、连通分量标记、region properties、颜色空间转换、图像配准、去噪以及数字病理中的全切片影像WSI读取与预处理管线图像在 512×512 及以上的管道收益明显。cuCIM 还提供高性能 WSI readerCuImage。可与 CuPy 链式处理cuCIM 原生操作 CuPy 数组也可经 DLPack 零拷贝直通 PyTorch。模式十GeoPandas 点面包含 → cuSpatial仅限 legacy 25.04cuSpatial 已归档与当前 RAPIDS 包不兼容。仅在独立、固定到 25.04 的隔离环境中使用。point_in_polygon返回布尔成员矩阵不是geopandas.sjoin的直接替代品# Before (CPU) import geopandas as gpd import numpy as np from shapely.geometry import Point points gpd.GeoSeries([Point(x, y) for x, y in coords], crsEPSG:4326) polygons gpd.read_file(regions.geojson).geometry.iloc[:31] membership_cpu np.column_stack( [points.within(polygon).to_numpy() for polygon in polygons] ) # After (GPU, legacy) —— 相同的逐点-逐多边形成员语义 import cuspatial points_gpu cuspatial.from_geopandas(points) polygons_gpu cuspatial.from_geopandas(polygons) membership_gpu cuspatial.point_in_polygon(points_gpu, polygons_gpu)cuSpatial 的官方定位decision_framework.md仓库自 2025 年 7 月只读最终版本 25.04固定cudf-cu1225.4.*因而与当前 RAPIDS 发行版冲突没有官方继任者。新工作不要把它当作现行 GeoPandas 替代品——正确做法是把几何运算留在 GeoPandas/ShapelyCPU用 cuDF 加速工作流中兼容的表格阶段。模式十一Faiss 精确检索 → cuVS 精确检索——先对齐算法语义再谈基准向量检索迁移的纪律先匹配算法语义再做基准测试。用 cuVS 的 brute force 匹配 FaissIndexFlatL2的精确基线只有当可接受近似结果时才用 CAGRA并对照精确真值报告 recallk——绝不把精确 CPU 算法与近似 GPU 算法当作等价物比较# Before (CPU) —— Faiss import faiss import numpy as np rng np.random.default_rng(42) embeddings rng.random((1_000_000, 128), dtypenp.float32) queries rng.random((1_000, 128), dtypenp.float32) index faiss.IndexFlatL2(128) index.add(embeddings) distances, neighbors index.search(queries, k10) # After (GPU) —— cuVS 精确暴力检索 import cupy as cp from cuvs.neighbors import brute_force embeddings_gpu cp.asarray(embeddings) queries_gpu cp.asarray(queries) index_gpu brute_force.build(embeddings_gpu, metricsqeuclidean) distances_gpu, neighbors_gpu brute_force.search(index_gpu, queries_gpu, k10)cuvs.md 的索引选择指南CAGRA 是首选 ANN 候选图结构、GPU 原生、最快IVF-Flat 适合不做向量压缩的高召回 ANNIVF-PQ 适合放不进显存的大数据集压缩存储Brute Force 适合小数据集或作真值HNSW 用于由 GPU 构建索引、CPU 侧服务。度量支持sqeuclidean、inner_product、cosine等。不要用 RAFT 做向量检索——k-NN/IVFPQ/CAGRA 已全部迁往 cuVS。独立基准应分别测量 build、search、transfer 与序列化成本。模式十二scipy.sparse.linalg → RAFT——GPU 稀疏特征值求解对大型稀疏对称矩阵的特征值问题谱方法、图划分、大规模稀疏哈密顿量、结构振动模态用 RAFT 的 GPU Lanczos 求解器替换scipy.sparse.linalg.eigsh# Before (CPU) import numpy as np from scipy.sparse import random as sparse_random from scipy.sparse.linalg import eigsh A sparse_random(10000, 10000, density0.01, formatcsr, dtypenp.float32) A A A.T # 构造对称矩阵 eigenvalues, eigenvectors eigsh(A, k10, whichLM) # After (GPU) —— RAFT 稀疏特征值求解器 import cupy as cp import cupyx.scipy.sparse as sp_gpu from pylibraft.sparse.linalg import eigsh as gpu_eigsh A_gpu sp_gpu.csr_matrix(A) # 传输到 GPU eigenvalues, eigenvectors gpu_eigsh(A_gpu, k10, whichLM)raft.md 给出了求解器的完整参数契约迁移时应逐项核对参数说明A稀疏对称 CSR 矩阵cupyx.scipy.sparse.csr_matrixk要计算的特征值个数默认 6必须1 k nwhichLM最大模默认、LA最大代数、SA最小代数、SM最小模v0起始向量可选默认随机ncvLanczos 向量数须k 1 ncv nmaxiter最大迭代次数tol收敛容差0 机器精度seed随机种子可复现性handle可选的DeviceResources句柄RAF T 的关键工程点DeviceResources是 CUDA 资源句柄管理 stream、stream 池、cuBLAS/cuSOLVER 库句柄创建一次并在多次调用间复用可传入 CuPy streamDeviceResources(streamcupy_stream.ptr)。RAF T 调用默认异步——必须在读取 CPU 侧结果前handle.sync()不传handle时 RAF T 内部临时分配资源并在返回前同步方便但重复调用更慢。错误稀疏格式eigsh只接受cupyx.scipy.sparse.csr_matrixCOO/CSC 需先转换仅限实对称/Hermitian 矩阵dtype 必须显式float32/float64不要依赖隐式转换。互操作device_ndarray实现__cuda_array_interface__CuPy、PyTorch、cuDF 数组可直接传入输出类型可用pylibraft.config.set_output_as(cupy)/torch全局配置。RAF T 还提供 R-MAT 随机图生成pylibraft.random.rmat适合图算法基准与raft-dask的多节点多 GPU 通信Comms类管理 NCCL/UCX。性能建议复用DeviceResources、批量同步、优先 float32、预分配输出、数据全程留在 GPU。贯穿所有模式的工程原则1. 保持连贯的 GPU 数据路径。输入只传输一次中间结果保持设备驻留复用分配、优先out或 in-place 形式批量小操作、融合逐元素工作以消除中间数组只有 profiling 证明传输重叠带来收益时才使用 pinned host memory 与非默认 stream契约允许时才选 float32/混合精度。2. 先验证语义再谈速度。在小而确定的 fixture 与代表性数据上对比 CPU/GPU 输出浮点结果用显式容差测试边界情况、NaN、排序与 dtype对近似最近邻索引报告 recallk检查加速器警告与日志中的 CPU 回退。3. 正确测量 GPU 代码。GPU 工作是异步的CPU 定时器测量的是入队时间而非执行时间。预热上下文创建与 JIT 编译后用 CUDA 事件或库感知计时器from cupyx.profiler import benchmark print(benchmark(gpu_function, (arg1, arg2), n_warmup10, n_repeat100))Notebook 中用%gpu_timeit端到端时间线用 Nsight Systemsnsys内核分析用 Nsight Computencu。同时报告同步内核时间与真实端到端延迟生产环境需要承担传输与转换成本时把它们计入。4. 保留、修订或拒绝移植。只有通过正确性检查并在代表性数据上改善了用户关心的指标时才保留 GPU 路径否则要解释限制因素到底是问题规模、传输、不支持回退、显存压力、启动粒度还是算法本身。需要可移植性时提供 CPU 回退测试数值正确性GPU 浮点可能因操作顺序与 CPU 略有不同数据大于显存时考虑分块或 RAPIDS Dask 多 GPU。不同 GPU 库之间通过 CUDA Array Interface / DLPack 零拷贝互操作——组合使用如 cuDF cuML、cuGraph cuML、cuCIM PyTorch、KvikIO CuPy、RAFT CuPy时确认 device、dtype、连续性、所有权与 stream 语义不要假设任何转换都是免费的。完整的分库决策何时是错误选择、如何组合见 decision_framework.md逐库安装与验证见 installation.md各库的深入 API 参考CuPy 内核融合与内存池、cuDF 字符串与 UDF、Warp tile 与可微编程、RAFT 设备内存管理等可从 SKILL.md 的 Reference Files 索引进入。把这 12 组转换模式与最小合适层次 证据驱动基准的方法论结合AI Agent 即可在保持数值契约的前提下安全地把 CPU 科学计算工作负载迁上 NVIDIA 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考