CuPy API Reference 全景指南：从 ndarray 到 CUDA 底层，一文读懂 NumPy/SciPy GPU 版 API 导航

CuPy API Reference 全景指南从 ndarray 到 CUDA 底层一文读懂 NumPy/SciPy GPU 版 API 导航【免费下载链接】cupyNumPy SciPy for GPU项目地址: https://gitcode.com/GitHub_Trending/cu/cupy本指南以 CuPy 官方文档中的 API Reference 索引docs/source/reference/index.rst为骨架系统梳理 CuPy 对外暴露的全部 API 体系从核心的cupy.ndarray多维数组、ufunc 通用函数到 NumPy/SciPy 兼容例行函数、CuPy 特有扩展、底层 CUDA 封装、自定义内核与分布式计算。读完本文你将掌握 CuPy API 参考文档的组织脉络与查找方法理解每个 API 分类的适用场景、关键函数与源码级实现依据能够在自己的 GPU 计算项目中快速定位并使用正确的 CuPy 接口。API Reference 的定位与组织方式CuPy 是 NumPy 与 SciPy 的 GPU 对应实现其 API 参考文档即docs/source/reference/index.rst是整个官方文档体系中按函数逐个查手册的入口。该索引页通过 Sphinx 的toctree指令将 11 个 API 子页面组织成一张完整的地图子页面内容主题ndarrayN 维数组对象及其转换ufunc通用函数universal functionsroutinesNumPy 兼容例行函数routinesscipySciPy 兼容例行函数extCuPy 特有函数cupyx命名空间cuda底层 CUDA 支持kernel自定义内核Elementwise/Reduction/Raw/JITdistributed分布式计算environment运行时与安装环境变量comparisonNumPy/SciPy API 实现对比表array_apiArray API 标准兼容层理解该文档的一个关键约定在 index.rst 的注释中明确说明对于 NumPy/SciPy 兼容的 API如ndarray、ufunc、routines、scipy在 API 列表中省略模块名前缀遵循 NumPy/SciPy 文档的惯例对于 CuPy 特有的 API则使用全限定名如cupyx.scatter_add、cupy.cuda.Stream。这一约定帮助读者快速区分可以直接用 NumPy 经验套用的接口与CuPy 独有、需要单独学习的接口。ndarray驻留在 CUDA 设备上的 N 维数组核心对象与基本概念cupy.ndarray是 NumPynumpy.ndarray在 CuPy 中的对应物详见 docs/source/reference/ndarray.rst它提供了一种直观的接口来操作驻留在 CUDA 设备上的固定大小多维数组。所有 CuPy 计算的基石都是这个类。与 NumPy 数组的相互转换cupy.ndarray与numpy.ndarray不会隐式互转NumPy 函数不能直接接收cupy.ndarray作为输入反之亦然。官方文档明确了以下转换路径NumPy → CuPy使用cupy.array或cupy.asarrayCuPy → NumPy使用cupy.asnumpy或cupy.ndarray.get。需要特别注意的是这种转换会触发主机CPU与 GPU 设备之间的数据拷贝在性能上是昂贵的操作。因此在高性能代码路径中应尽量减少数组在两种世界之间的往返。编写 CPU/GPU 通用代码get_array_module由于数组可能来自 NumPy 也可能来自 CuPy文档特别引入了cupy.get_array_module来解决模块级函数如cupy.sum/numpy.sum该调哪个的问题。其源码位于 cupy/init.py#L866-L895def get_array_module(*args): Returns the array module for arguments. This function is used to implement CPU/GPU generic code. If at least one of the arguments is a :class:cupy.ndarray object, the :mod:cupy module is returned. ... import cupyx for arg in args: if isinstance(arg, (ndarray, cupyx.scipy.sparse._spbase, _core.fusion._FusionVarArray, _core.new_fusion._ArrayProxy)): return _cupy return _numpy从源码可以看出其判定逻辑只要任意一个参数是cupy.ndarray、cupyx.scipy.sparse稀疏矩阵基类或融合相关的数组代理类型就返回cupy模块否则返回numpy。官方文档给出的典型用法是编写一套代码、双端运行的通用函数def softplus(x): xp cupy.get_array_module(x) return xp.maximum(0, x) xp.log1p(xp.exp(-abs(x)))传入 CuPy 数组时xp为cupy传入 NumPy 数组时xp为numpy函数体无需任何改动即可在 CPU/GPU 间切换。此外cupyx.scipy.get_array_module提供了同样的能力用于 SciPy 兼容 API。ufunc支持广播与类型规则的通用函数CuPy 提供通用函数ufunc来支持各种逐元素elementwise运算详见 docs/source/reference/ufunc.rst完整复刻了 NumPy ufunc 的三大特性广播Broadcasting不同形状的数组按广播规则自动对齐参与运算输出类型判定Output type determination根据输入类型自动确定结果 dtype类型转换规则Casting rules遵循与 NumPy 一致的强制转换语义。ufunc 方法仅部分 ufunc 可用cupy.ufunc对象上定义了reduce、accumulate、reduceat、outer、at等方法但文档明确标注了当前各方法的可用范围方法支持的 ufuncufunc.reducecupy.add、cupy.multiplyufunc.accumulatecupy.add、cupy.multiplyufunc.reduceatcupy.addufunc.outer所有 ufuncufunc.atadd、subtract、maximum、minimum、bitwise_and、bitwise_or、bitwise_xor也就是说目前只有约半数 ufunc 支持reduce/accumulate/reduceat等归约类方法outer则是全部支持。如果业务代码需要其他 ufunc 的reduce能力文档提示应向 CuPy 项目提交带有使用场景的 feature request。可用 ufunc 分类清单参考文档按 NumPy 惯例将全部 ufunc 分为四大类数学运算Math operationsadd、subtract、multiply、matmul、divide、logaddexp、logaddexp2、true_divide、floor_divide、negative、positive、power、float_power、remainder、mod、fmod、divmod、absolute、fabs、rint、sign、heaviside、conj、conjugate、exp、exp2、log、log2、log10、expm1、log1p、sqrt、square、cbrt、reciprocal、gcd、lcm三角函数Trigonometric functionssin、cos、tan、arcsin、arccos、arctan、arctan2、hypot、sinh、cosh、tanh、arcsinh、arccosh、arctanh、degrees、radians、deg2rad、rad2deg位运算Bit-twiddling functionsbitwise_and、bitwise_or、bitwise_xor、invert、left_shift、right_shift比较函数Comparison functionsgreater、greater_equal、less、less_equal、not_equal、equal、logical_and、logical_or、logical_xor、logical_not、maximum、minimum、fmax、fmin浮点函数Floating functionsisfinite、isinf、isnan、fabs、signbit、copysign、nextafter、modf、ldexp、frexp、fmod、floor、ceil、trunc。GeneralizedUFunc广义通用函数除常规 ufunc 外CuPy 还在cupyx命名空间下提供GeneralizedUFunc包装类可将普通 CuPy 函数转换为类似 NumPy 的广义通用函数gufunc从而自动获得axes、order、dtype等关键字参数能力无需在包装的函数内部显式实现这些逻辑。routinesNumPy 兼容例行函数routines子页面docs/source/reference/routines.rst汇总了所有 NumPy 兼容例行函数覆盖 NumPy routines 的一个子集共 20 个分类creation创建、manipulation操作、binary二进制、dtype数据类型、fft傅里叶变换、functional函数式、indexing索引、io输入输出、linalg线性代数、logic逻辑、math数学、misc杂项、polynomials多项式、random随机数、set集合、sorting排序、statistics统计、testing测试、window窗函数。这些例程在仓库中均有对应实现模块例如 cupy/_creation、cupy/_manipulation、cupy/_math、cupy/_sorting、cupy/_statistics、cupy/_io、cupy/linalg、cupy/random 等读者可以按模块深入源码。scipySciPy 兼容例行函数scipy子页面docs/source/reference/scipy.rst在cupyx.scipy命名空间下提供 SciPy 兼容例程同样覆盖 SciPy routines 的一个子集包含 14 个模块scipy_fft、scipy_fftpack、scipy_interpolate、scipy_linalg、scipy_ndimage、scipy_signal、scipy_signal_windows、scipy_sparse、scipy_sparse_linalg、scipy_sparse_csgraph、scipy_spatial、scipy_spatial_distance、scipy_special、scipy_stats。对应实现在仓库的 cupyx/scipy 目录下其中 sparse稀疏矩阵、ndimage图像处理、signal信号处理、special特殊函数等是社区使用最频繁的模块。extCuPy 特有的扩展函数cupyx 命名空间CuPy 特有的函数统一放在cupyx命名空间下详见 docs/source/reference/ext.rst包括常用数值/归约扩展cupyx.rsqrt平方根倒数、cupyx.scatter_add、cupyx.scatter_max、cupyx.scatter_min散射式累加/取极值对应源码见 cupyx/_scatter.py固定内存pinned memory工具cupyx.empty_pinned、cupyx.empty_like_pinned、cupyx.zeros_pinned、cupyx.zeros_like_pinned用于分配主机端页锁定内存以加速与设备间的数据传输对应实现见 cupyx/_pinned_array.py非 SciPy 兼容的信号 APIcupyx.signal下的一组函数channelize_poly、convolve1d3o、pulse_compression、pulse_doppler、cfar_alpha、ca_cfar、freq_shift文档注明这是从 Nvidia cuSignal 移植而来经 cuSignal 团队许可定位于雷达信号处理等场景性能分析工具cupyx.profiler.benchmark、cupyx.profiler.time_range、cupyx.profiler.profile对应实现见 cupyx/profilerDLPack 工具cupy.from_dlpack可从 DLPack 张量或任何支持 DLPack 数据交换协议的对象创建cupy.ndarray自动内核参数优化cupyx.optimizing.optimize源码见 cupyx/optimizing/_optimize.py用于自动搜索并优化内核参数。cuda底层 CUDA 支持cuda子页面docs/source/reference/cuda.rst覆盖从设备管理到 Runtime API 的完整底层能力是理解 CuPy 内存、流、图等核心机制的地方共分为十大主题设备管理Device managementcupy.is_available用于探测 CUDA 是否可用cupy.cuda.Device用于切换、查询当前 GPU 设备。内存管理Memory management这是 CuPy 高性能的关键所在提供完整的池化内存体系cupy.get_default_memory_pool与cupy.get_default_pinned_memory_pool获取默认的显存/固定内存池cupy.cuda.Memory、cupy.cuda.MemoryAsync、cupy.cuda.ManagedMemory托管内存、cupy.cuda.UnownedMemory非托管等内存对象MemoryPool、MemoryAsyncPool、PinnedMemoryPool三种池以及cupy.cuda.alloc、cupy.cuda.alloc_pinned_memory、cupy.cuda.malloc_managed、cupy.cuda.malloc_async等分配入口。自定义分配策略可通过cupy.cuda.get_allocator/cupy.cuda.set_allocator/cupy.cuda.using_allocator/cupy.cuda.set_pinned_memory_allocator以及PythonFunctionAllocator/CFunctionAllocator实现。内存钩子Memory hookcupy.cuda.MemoryHook基类配合cupy.cuda.memory_hooks.DebugPrintHook调试打印与cupy.cuda.memory_hooks.LineProfileHook按行分析内存分配使用对应实现见 cupy/cuda/memory_hooks。流与事件Streams and eventscupy.cuda.Stream、cupy.cuda.ExternalStream、cupy.cuda.get_current_stream、cupy.cuda.Event、cupy.cuda.get_elapsed_time用于异步执行与计时实现见 cupy/cuda/stream.pyx。图Graphscupy.cuda.Graph支持 CUDA Graph 捕获与重放用于降低内核启动开销。纹理与表面内存Texture and surface memorycupy.cuda.texture下的ChannelFormatDescriptor、CUDAarray、ResourceDescriptor、TextureDescriptor、TextureObject、SurfaceObject封装 CUDA 纹理/表面内存接口。NVTX 性能标注cupy.cuda.nvtx.Mark、MarkC、RangePush、RangePushC、RangePop用于在 NVIDIA Nsight 等工具中标记代码段。NCCL 通信cupy.cuda.nccl.NcclCommunicator、get_build_version、get_version、get_unique_id、groupStart、groupEnd提供多 GPU 通信原语实现见 cupy/cuda/nccl.py。版本与 Runtime APIcupy.cuda.get_local_runtime_version返回本地 CUDA Runtime 版本。cupy.cuda.runtime则是对 CUDA Runtime API 的完整 Python 封装涵盖设备查询getDevice、getDeviceCount、deviceGetAttribute、getDeviceProperties、deviceGetByPCIBusId、deviceGetPCIBusId、内存操作malloc、free、memcpy、memset、memGetInfo、memPrefetchAsync、memAdvise、流与事件streamCreate、streamSynchronize、eventRecord等、图graphInstantiate、graphLaunch、graphDebugDotPrint、IPCipcGetMemHandle等以及 profiler 控制等接口语义与 CUDA Runtime API 一一对应。kernel自定义内核kernel子页面docs/source/reference/kernel.rst是 CuPy从高层 API 走向自定义 CUDA 代码的入口提供五类内核机制cupy.ElementwiseKernel逐元素自定义内核cupy.ReductionKernel自定义归约内核cupy.RawKernel直接封装 CUDA kernel 函数cupy.RawModule从 CUDA 源或 cubin 加载内核模块cupy.fusePython 函数的 JIT 融合装饰器对应实现见 cupy/_core/fusion.pyx。JIT 内核定义cupyx.jitcupyx.jit提供在 Python 中直接编写 CUDA 内核的 JIT 方案参考文档明确了两点关键信息支持的 Python 内置函数range、len、max、min循环展开注意如果需要循环展开应使用cupyx.jit.range而非内置range。完整的 JIT 内核编程原语包括线程索引threadIdx、blockIdx、blockDim、gridDim、grid、gridsize、warp 级操作laneid、warpsize、shfl_sync、shfl_up_sync、shfl_down_sync、shfl_xor_sync、syncwarp、块同步syncthreads、共享内存shared_memory、原子操作atomic_add、atomic_sub、atomic_exch、atomic_min、atomic_max、atomic_inc、atomic_dec、atomic_cas、atomic_and、atomic_or、atomic_xor以及协作组cupyx.jit.cg的this_grid、this_thread_block、sync、memcpy_async、wait、wait_prior。仓库中的 JIT 实现位于 cupyx/jit。内核二进制缓存Kernel binary memoizationcupy.memoize装饰器用于缓存内核编译产物cupy.clear_memo用于清空缓存避免重复编译带来的开销。distributed跨进程与跨设备分布式计算distributed子页面docs/source/reference/distributed.rst包含两层能力进程间通信cupyx.distributed.init_process_group初始化进程组cupyx.distributed.NCCLBackend提供基于 NCCL 的后端跨设备分布式 ndarraycupyx.distributed.array模块提供distributed_array、DistributedArray、make_2d_index_map、matmul支持将ndarray分布到多设备上并执行分布式矩阵乘法。对应实现见 cupyx/distributed含_comm.py、_nccl_comm.py、_store.py及array/子目录。environment运行时与安装环境变量environment子页面docs/source/reference/environment.rst是排查 CuPy 运行时行为与构建问题的权威配置清单分为运行时与安装期两组。运行时环境变量环境变量默认值作用说明CUDA_PATH含nvcc目录的父目录找不到nvcc时用/usr/local/cuda指向 CUDA 所在目录CUPY_CACHE_DIR${HOME}/.cupy/kernel_cache内核缓存目录CUPY_CACHE_SAVE_CUDA_SOURCE0设为1时在缓存目录中同时保存 CUDA 源码便于调试若二进制已缓存则不再保存源码CUPY_CACHE_IN_MEMORY0设为1时忽略CUPY_CACHE_DIR与CUPY_CACHE_SAVE_CUDA_SOURCE缓存驻留内存以降低磁盘 I/O使用nvcc编译后端时该选项无效CUPY_NVRTC_USE_PCH0设为1时对所有 NVRTC 编译传递--pch使用预编译头大幅加速大量内核编译如缓存为空或CUPY_CACHE_IN_MEMORY场景仅 CUDA 12.8 可用CUPY_DISABLE_JITIFY_CACHE0设为1时 Jitify 加载的头文件不落盘缓存到CUPY_CACHE_DIR默认总是缓存CUPY_DUMP_CUDA_SOURCE_ON_ERROR0设为1时内核编译失败将 CUDA 源码 dump 到标准错误CUPY_CUDA_COMPILE_WITH_DEBUG0设为1时以内核调试信息编译--device-debug与--generate-line-infoCUPY_GPU_MEMORY_LIMIT0不限每设备可分配显存上限支持绝对字节数或比例如90%详见 docs/source/user_guide/memory.rstCUPY_SEED无设置随机数生成器种子CUPY_EXPERIMENTAL_SLICE_COPY0设为1时启用cupy_ndarray[:] numpy_ndarray语法CUPY_ACCELERATORScubROCm/HIP 环境为逗号分隔的后端名cub、cutensor、cutensornet、cuda_compute按优先级降序排列cuda_compute需要cuda-cccl包目前加速cupy.cumsum与cupy.cumprodCUPY_TF320设为1时允许 CUDA 库对 32 位浮点计算使用 Tensor Core TF32CUPY_CUDA_ARRAY_INTERFACE_SYNC1作为 Consumer 时的流同步开关设为0时消费外部库提供的 CUDA Array Interface 设备数组不再执行流同步CUPY_CUDA_ARRAY_INTERFACE_EXPORT_VERSION3作为 Producer 时的导出版本设为2时不导出操作所在流Consumer 不会做流同步CUPY_DLPACK_EXPORT_VERSION0.6控制 DLPack 支持小于0.6时托管内存伪装为普通设备内存以兼容旧库0.6起正确识别 CUDA 托管内存NVCCnvcc编译 CUDA 源码用的编译器注意多数 CuPy 内核由 NVRTC 构建该变量仅对RawKernel/RawModule的nvcc后端及cub加速器生效CUPY_CUDA_PER_THREAD_DEFAULT_STREAM0设为1时使用 CUDA per-thread 默认流每个主机线程自动独立成流0时使用默认null流CUPY_COMPILE_WITH_PTX0默认直接编译为 SASSCUBIN以支持 CUDA Enhanced Compatibility设为1时编译为 PTX 交由驱动装配 SASS。仅 CUDA 11.1 且 NVRTC 后端生效NVCC 后端始终产出 SASS文档还补充了两点运行注意事项一是所有 CUDA Toolkit 环境变量同样被尊重如CUDA_VISIBLE_DEVICES等二是当设置CUPY_ACCELERATORS或NVCC时需要 g-6 或更高版本作为运行时主机编译器。安装期环境变量从源码构建时环境变量默认值作用说明CUTENSOR_PATH无cuTENSOR 根目录路径含lib与include实验性CUPY_INSTALL_USE_HIP0设为1时为 AMD ROCm 平台构建实验性CUPY_USE_CUDA_PYTHON0设为1时基于 CUDA Python 构建CUPY_NVCC_GENERATE_CODE支持所有架构为特定 CUDA 架构构建如CUPY_NVCC_GENERATE_CODEarchcompute_60,codesm_60多架构用;连接指定current则在构建时自动检测当前 GPU 架构CUPY_NUM_BUILD_JOBS4并行构建扩展使用的进程数CUPY_NUM_NVCC_THREADS2nvcc 并行编译文件使用的线程数此外CUDA_PATH与NVCC在构建期同样被尊重。comparisonNumPy/SciPy API 实现对比表comparison子页面docs/source/reference/comparison.rst维护了一张NumPy/SciPy API 与 CuPy 对应实现的对照表。表中 CuPy 列显示-表示该函数尚未提供实现官方文档明确欢迎社区为这些空缺函数提交贡献——这也是判断某个 NumPy 函数能否直接在 CuPy 中使用的权威依据。如何在项目中高效使用这份 API 参考结合以上全景梳理使用 CuPy API Reference 时建议遵循以下路径先判断 API 归属若目标函数在 NumPy/SciPy 中存在直接按 NumPy 惯例使用不带cupyx前缀并在comparison对比表确认 CuPy 已实现使用 CuPy 独有能力cupyx命名空间的扩展函数散射、pinned 内存、信号处理、内核参数优化等与cupy.cuda底层封装需要查阅对应子页面深入源码验证语义本文引用的 cupy/init.py、cupy/_core、cupy/cuda、cupyx/distributed、cupyx/jit 等目录即各 API 的落地实现遇到文档未覆盖的边界行为时可直接读源码确认用环境变量调优内存限制CUPY_GPU_MEMORY_LIMIT、内核缓存CUPY_CACHE_*系列、加速器开关CUPY_ACCELERATORS等运行时变量是性能调优与问题排查的第一站。API Reference 索引页docs/source/reference/index.rst作为整套文档的地图与各子页面一起构成了 CuPy 从NumPy 迁移用户到底层 CUDA 开发者的完整知识体系上层是即插即用的数组与函数中层是性能与内存控制底层是自定义内核与分布式原语。把握这张地图你就能在 CuPy 的庞大 API 中始终找到最准确、最高效的那条路径。【免费下载链接】cupyNumPy SciPy for GPU项目地址: https://gitcode.com/GitHub_Trending/cu/cupy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考