CuPy 升级指南：从 v2 到 v14 的完整迁移手册

CuPy 升级指南从 v2 到 v14 的完整迁移手册【免费下载链接】cupyNumPy SciPy for GPU项目地址: https://gitcode.com/GitHub_Trending/cu/cupy本文是 CuPyNumPy SciPy for GPU 的开源实现的官方升级指南的中文深度解读。文章以仓库 docs/source/upgrade.rst 为骨架逐版本梳理从 v2 到 v14 的重大行为变更、版本支持边界与 API 迁移路径并结合当前仓库源码当前仓库版本号为14.3.0.dev0见 cupy/_version.py给出可验证的实现细节。读完本文你将掌握如何判断自己的环境是否符合某个 CuPy 大版本的要求、升级后哪些代码行为会悄悄变化、以及每个大版本中「必须改代码」与「只需知晓」的变更分别是什么。兼容性矩阵一眼看清各版本支持范围升级前最重要的事是确认目标版本的依赖环境。下表完整复刻自升级指南末尾的 Compatibility Matrix.. _compatibility_matrix:锚点列出了 CuPy v4–v15 各版本对 CUDA 算力CC、CUDA、ROCm、cuTENSOR、NCCL、cuDNN、Python、NumPy、SciPy 的支持范围以及各版本所遵循的 Baseline API 规范即 CuPy 以哪个版本的 NumPy/SciPy 行为为准。CuPyCCCUDAROCmcuTENSORNCCLcuDNNPythonNumPySciPyBaseline API Spec.v155.0-12.0-7.0-2.3-2.18-n/a3.10-2.0-1.14-NumPy 2.3 SciPy 1.16v145.0-12.0-7.0-2.3-2.18-n/a3.10-2.0-1.14-NumPy 2.3 SciPy 1.16v133.5-12.x11.2-13.x4.3-6.x2.02.16-2.268.83.9-3.131.22-2.31.7-1.14NumPy 1.26 SciPy 1.11v123.0-9.010.2-12.x4.3 5.01.4-1.72.8-2.177.6-8.83.8-3.121.21-1.261.7-1.11NumPy 1.24 SciPy 1.9v113.0-9.010.2-12.04.3 5.01.4-1.62.8-2.167.6-8.73.7-3.111.20-1.241.6-1.9NumPy 1.23 SciPy 1.8v103.0-8.x10.2-11.74.0 4.2 4.3 5.01.3-1.52.8-2.117.6-8.43.7-3.101.18-1.221.4-1.8NumPy 1.21 SciPy 1.7v93.0-8.x9.2-11.53.5-4.31.2-1.32.4 2.6-2.117.6-8.23.6-3.91.17-1.211.4-1.7NumPy 1.20 SciPy 1.6v83.0-8.x9.0 9.2-11.23.x1.22.0-2.87.0-8.13.5-3.91.16-1.201.3-1.6NumPy 1.19 SciPy 1.5v73.0-8.x8.0-11.02.x1.01.3-2.75.0-8.03.5-3.81.9-1.19未指定未指定v63.0-7.x8.0-10.1n/an/a1.3-2.45.0-7.52.7 3.4-3.81.9-1.17未指定未指定v53.0-7.x8.0-10.1n/an/a1.3-2.45.0-7.52.7 3.4-3.71.9-1.16未指定未指定v43.0-7.x7.0-9.2n/an/a1.3-2.24.0-7.12.7 3.4-3.61.9-1.14未指定未指定注 1CC 指 CUDA Compute CapabilityCUDA 计算能力。注 2ROCm 列中标为「3.x」「2.x」的版本为高度实验性支持功能受限。从上表可以清晰看出两条主线其一随着版本推进Python/NumPy/SciPy 的最低要求一路抬高到 v14 时代基线直接对齐 NumPy 2.3 与 SciPy 1.16其二cuDNN 列在 v14/v15 变为n/a——cuDNN 支持被彻底移除详见下文。各版本对应的官方文档版本latest / stable / v13.6.0 / v12.3.0 等可在 docs/source/index.rst 中找到文档入口。CuPy v14CUDA 组件轮子与 NumPy 2 时代v14 是当前仓库所在的大版本仓库内__version__ 14.3.0.dev0也是变化最密集的一个版本几乎涵盖了从安装方式、数值行为到底层编译标准的全方位调整。支持 NVIDIA CUDA 组件轮子[ctk]extraCuPy v14 允许与来自 PyPI 的最小化 CUDA 安装一起使用pip install cupy-cuda13x[ctk]这意味着只需系统中有 CUDA 驱动就能快速搭建一个全新的虚拟环境无需预先安装完整 CUDA Toolkit。该方案的收益是更小的安装体积以及与其他 Python GPU 库之间更好的互操作性。详细安装说明见 docs/source/install.rst。cuDNN 支持被彻底移除CuPy v14 不再支持 cuDNN所有与 cuDNN 相关的功能已从 CuPy 中完全移除。如果需要在 Python 中访问 cuDNN 功能官方建议改用 NVIDIA cuDNN Frontend一个同时提供 C 与 Python 接口、可直连 cuDNN 库的项目。这与兼容性矩阵中 v14/v15 的 cuDNN 列为n/a完全一致。全面对齐 NumPy 2 的类型提升规则NEP 50CuPy v14 在绝大多数行为上跟随 NumPy 2类型提升type promotion规则随之发生多处变化。大部分代码可能无感但部分代码需要显式调整标量的类型尽量使用 Python 标量如果标量不应提升数组的类型请使用 Python 原生标量。例如cp.ones(3, dtypefloat32) cp.float64(3.)现在返回float64。允许不安全转换时显式指定整数类型例如uint8_arr[0] cp.int8(-1)这类赋值需要显式转型。更多细节可参考 NumPy 官方文档与 NEP 50NumPy 2 的类型提升规范。bfloat16 的初步支持CuPy v14 通过ml_dtypes.bfloat16提供对 bfloat16 的初步支持。大多数 CuPy 功能可以正常工作但在cupyx中仍存在少量缺口。使用前提有两个需要 NumPy 2.1.2 及以上版本在 CUDA 12.1 下使用 bfloat16 可能引发编译问题。结构化 dtype 的最小支持CuPy v14 在从 NumPy 转换或通过empty、zeros创建数组时可以接受大多数结构化 dtype但唯一支持的操作是访问单个字段arr[field_name] arr[field_name] value截至 v14.0任何携带结构化 dtype 的内核启动都会失败包括arr.copy()。此外arr[field_name]必须满足 GPU 的对齐要求——即使 NumPy 设置了alignTrue由于 GPU 的对齐要求更大也无法保证这一点。升级到 v14 后如果代码里大量使用结构化数组需要特别留意这一限制。新的 cuFFT LTO 回调支持CuPy v14 支持 cuFFT 新的 LTO链接时优化回调机制。相比旧机制LTO 回调在回调的编译与执行上都有明显性能提升并且跨平台支持 Linux/Windows。启用方式是将cb_verjit传给cupy.fft.config.set_cufft_callbackswith cp.fft.config.set_cufft_callbacks(cb_loadcode, cb_verjit): out_arr cp.fft.fft(in_arr)新回调要求 CUDA 12.2 的 nvJitLink 与 cuFFTnvJitLink 属于 CUDA Toolkit 的一部分也可通过 pip 和 conda 安装。与之一同引入的两个新参数是cb_load_data/cb_store_data而原有的cb_load_aux_arr/cb_store_aux_arr被标记为弃用旧的 legacy 回调可通过cb_verlegacy继续启用已被弃用将在未来版本移除。从源码可以完整看到这一 API 的签名。在 cupy/fft/_callback.pyx 中set_cufft_callbacks被实现为一个上下文管理器类其参数包括cb_loadload 回调的设备内核字符串必须定义d_loadCallbackPtr、cb_storestore 回调内核必须定义d_storeCallbackPtr、已弃用的cb_load_aux_arr/cb_store_aux_arr、仅cb_verjit时需要的cb_load_name/cb_store_name不传则尝试从cb_load/cb_store推断函数名、新参数cb_load_data/cb_store_dataMemoryPointer类型承载回调使用的数据块以及cb_ver默认legacyCUDA 12.2 起支持jit。源码注释还提醒回调只对连续轴上的变换生效非连续变换行为未定义。对应的配置对象cupy.fft.config在 cupy/fft/_config.py 中定义并在 ROCm 平台上将set_cufft_callbacks替换为直接抛出RuntimeError的桩函数。多个已弃用模块迁移至cupyx以下cupy子模块已在 v14 中移除请改用cupyx中的替代品已移除替代弃用起始版本cupy.sparsecupyx.scipy.sparsev8cupy.profcupyx.profilerv10cupy.cusolvercupyx.scipy.linalg.cusolverv12未文档化的 APIcupy.cusparsecupyx.scipy.sparse.cusparsev12未文档化的 APIcupy.cutensorcupyx.scipy.linalg.cutensorv12未文档化的 APIcupy.cuda.is_available行为变化cupy.cuda.is_available现在会捕获所有 CUDA 错误返回False而不是抛出异常。这改善了 CUDA 部分配置或不可用环境下某些边界情况会抛异常的兼容性在 v14 中该函数保证始终返回布尔值、绝不抛异常。源码印证cupy/cuda/init.py 中is_available()的实现将结果缓存在模块级变量_available中首次调用时置为False随后在try块中通过runtime.getDeviceCount() 0探测设备任何Exception都会被吞掉并保持False。RTC 默认 C 标准变化运行时编译Runtime Compilation, RTC的默认 C 标准从 C11 改为ROCm 平台 C14、CUDA 平台 C17。依赖旧默认值的现有代码通常不受影响因为 C14/C17 向后兼容 C11。cupy.cuda.nccl.get_unique_id返回类型变化cupy.cuda.nccl.get_unique_id现在返回bytes 字符串而不是整数元组。这一变化简化了 API并规避了与 char 有无符号相关的平台差异问题。之前解包元组的代码需要改为直接使用 bytes。源码印证cupy_backends/cuda/libs/nccl.pyx 中该函数调用ncclGetUniqueId(uniqueId)后直接返回uniqueId.internal[:NCCL_UNIQUE_ID_BYTES]docstring 中标注.. versionchanged:: 14.0明确说明此前返回整数元组。cupy.random.choice返回类型变化向cupy.random.choice传入int并搭配size与replaceFalse时现在执行更快且行为更一致在所有平台上恒返回int64dtype 的数组。对应实现入口见 cupy/random/_sample.py实际逻辑委托给RandomState.choice。注意源码注释中的限制p参数在replaceFalse时暂不支持。更严格的 dtype 校验CuPy 现在会在数组创建时更严格地校验 dtype不支持的类型会直接报错而不是等到更晚的阶段才暴露难以理解的错误 cp.empty(3, dtypedatetime64[ns]) ValueError: Unsupported dtype datetime64[ns]作为变通方案无结构的 void 类型Vitemsize如V8仍然被接受arr.view()也仍可以以不安全的方式使用。可以预期未来版本会为Vitemsize类型支持部分内核主要是拷贝类操作。需求版本变化CuPy v14 不再支持以下版本CUDA 11.x 及更早现在要求 CUDA 12.0 或更新Python 3.9 及更早现在要求 Python 3.10 或更新NumPy 1.x现在要求 NumPy 2.0 或更新SciPy 1.13 及更早现在要求 SciPy 1.14 或更新ROCm 6.x 及更早现在要求 ROCm 7.0 或更新NCCL 2.17 及更早现在要求 NCCL 2.18 或更新cuSPARSELt 0.8.0 及更早现在要求 cuSPARSELt 0.8.1Baseline API 更新Baseline API 从 NumPy 1.26 / SciPy 1.11 提升到NumPy 2.3 / SciPy 1.16。CuPy v14 将遵循这两个上游版本的行为规范。其他 API 变化在 NumPy v2 中移除的 APICuPy v14 出于平滑过渡的目的有意保留但视为已弃用将在 CuPy v15 移除。cupyx.scipy.linalg.{tri,tril,triu}已移除以遵循最新 SciPy 规范请改用cupy.{tri,tril,triu}。旧的 DLPack APIcupy.toDlpack与cupy.fromDlpack标记为弃用请改用cupy.from_dlpack。NumPy fallback 模式cupyx.fallback_mode已被移除。cupyx.tools.install_library工具已弃用将在未来版本移除cuTENSOR/NCCL 的安装请参见 docs/source/install.rst。cupy.testing模块已随 NumPy 的 testing API 变化更新部分测试工具的行为或签名有所不同。cupy.fft.config现在是线程与上下文安全的。但这也意味着配置不再被线程继承基于contextvars实现Python 未来可能对新建线程改变这一行为。cupy.fft.config.enable_nd_planning已弃用将在未来版本移除planning 将始终启用。源码 cupy/fft/_config.py 中该属性的 getter/setter 都会发出DeprecationWarning。Jitify 支持已弃用将在未来版本移除。不要在cupy.RawModule/cupy.RawKernel中传jitifyTrue也不要设置-DCUPY_USE_JITIFY未文档化的内部宏。大多数情况下不设置也能正常工作。实验性命名空间cupy.array_api已被移除。Docker 镜像更新CuPy 官方 Docker 镜像详见 docs/source/install.rst更新为使用CUDA 13.x 与 Ubuntu 24.04。CuPy v13CCCL 捆绑与现代化的依赖现代化的 CCCL 支持与要求NVIDIA 的 CUDA C Core LibrariesCCCL是随 CUDA Toolkit 11.0 一起分发的 Thrust、CUB 和 libcu 这三个相互依赖库的新家。从 CuPy v13 起CuPy 在源码版和二进制版pip/conda中捆绑 CCCL并且构建期与运行期JIT 编译内核时使用同一版本的 CCCL从而保证行为一致、避免意外并兑现 CCCL 承诺的双 CUDA 支持目前为 CUDA 11 与 12。但这带来几个与过去不同的后果升级后首次执行某些 CuPy 功能可能比平时耗时更长本地 CUDA 安装中的 CCCL 在构建期与运行期都会被有意忽略想要实验本地 CCCL 改动的用户需要更新 CCCL 子模块并从源码构建 CuPy仓库中 CCCL 位于 third_party/cccl。因此CuPy v13 起与 CCCL进而与 CUDA Toolkit保持相同的编译器要求最低 C 标准为C11CCCL 预期不久将迁移到 C17。需求版本变化CuPy v13 不再支持CUDA 11.1 及更早cuDNN 8.7 及更早cuTENSOR 1.x自 v13 起支持 cuTENSOR 2.0cuTENSOR 1.x 与 2.0 的 API 差异巨大从维护角度不可能同时支持两套 APIPython 3.8 及更早NumPy 1.21 及更早Ubuntu 18.04Baseline API 更新Baseline API 从 NumPy 1.24 / SciPy 1.9 提升到NumPy 1.26 / SciPy 1.11。cupy.asnumpy/cupy.ndarray.get行为变化将 CuPy 数组从 GPU 传回 CPU转成 NumPy 数组时过去在非默认流下传输可能是非阻塞且未正确排序的若拷贝开始后立即在主机端修改结果数组可能引发数据竞争。v13 起默认行为改为始终阻塞并新增可选参数blocking设为False可恢复旧的非阻塞行为但此时用户需自行保证流顺序正确。cupy.array/cupy.asarray/cupy.asanyarray行为变化将 NumPy 数组从 CPU 传到 GPU 时过去即使源数组由 pinned memory 支撑传输也总是阻塞的。v13 起当源数组是 pinned 内存时默认改为异步传输以提升性能新增可选参数blocking设为True可恢复旧的阻塞行为。如果你有可能在传输完成前于 CPU 端覆盖源数组建议设置该参数。cupy-wheel包被移除cupy-wheel是一个「元」包用于为用户环境挑选并安装正确的 CuPy 二进制包但在 v13 中已被移除原因是新版 Pip 不再允许动态修改依赖。相关讨论见 cupy/cupy issue #7628。API 变化内部且未文档化的 APIcupy.cuda.compile_with_cachev10 起标记弃用已被移除。官方鼓励下游库与用户迁移到公开 APIcupy.RawModulev7 引入或cupy.RawKernelv5 引入教程见 docs/source/user_guide/kernel.rst。CUDA Runtime API 改为静态链接CuPy 现在随包静态链接 CUDA Runtime。因此cupy.cuda.runtime.runtimeGetVersion无论本地安装的 CUDA Runtime 是什么版本都始终返回 CuPy 构建时所用的 CUDA Runtime 版本。需要获取本地安装的 CUDA Runtime 共享库版本时请改用cupy.cuda.get_local_runtime_version——该函数在 cupy/cuda/init.py 中定义docstring 明确说明它与runtimeGetVersion的区别。Docker 镜像更新官方 Docker 镜像更新为使用CUDA 12.2。CuPy v12设备上下文管理器行为回归cupy.cuda.Device行为变化在 CUDA 当前设备通过cupy.cuda.Device.use()或cudaSetDevice()设置上退出设备上下文管理器时会重新激活该设备。这一变化回退了 v10 引入的行为见下文 v10 章节使 v12 与 v9 及更早版本保持一致其动机是更好地与其他可能改动当前 CUDA 设备的库互操作。考虑以下代码def do_preprocess_cupy(): with cupy.cuda.Device(2): # ... pass torch.cuda.set_device(1) do_preprocess_cupy() print(torch.cuda.get_device()) # - ???在 v10 和 v11 中这段代码打印0对用户来说很意外在 v12 中打印1让多设备场景下的用户与库开发者都能更容易地维护「当前设备」状态。源码印证cupy/cuda/device.pyx 中Device.__enter__将进入前的设备 id 压入线程本地栈__exit__则从栈中弹出并恢复该设备——v12 的实现恰好保证「进入前是谁、退出后还是谁」。cupy.ndarray.scatter_{add,max,min}弃用这三个 API 已标记弃用因为cupy.{add,maximum,minimum}.at这些 ufunc 方法已经实现且行为等价、与 NumPy 兼容。需求版本变化CuPy v12 不再支持Python 3.7 及更早NumPy 1.20 及更早SciPy 1.6 及更早Baseline API 更新Baseline API 从 NumPy 1.23 / SciPy 1.8 提升到NumPy 1.24 / SciPy 1.9。Docker 镜像更新官方 Docker 镜像更新为使用CUDA 11.8。CuPy v11统一 CUDA 11.2 二进制包CUDA 11.2 统一二进制包CuPy v11 提供名为cupy-cuda11x的统一二进制包支持所有 CUDA 11.2 版本取代了过去按 CUDA 小版本区分的cupy-cuda112–cupy-cuda117。注意 CUDA 11.1 及更早版本仍需要按 CUDA 版本区分的二进制包cupy-cuda102、cupy-cuda110、cupy-cuda111分别对应 CUDA 10.2、11.0、11.1。需求版本变化CuPy v11 不再支持ROCm 4.2 及更早NumPy 1.19 及更早SciPy 1.5 及更早CUB 默认启用CuPy v11 默认使用 CUB 加速计算。需要关闭时将环境变量CUPY_ACCELERATORS设为空字符串即可。Baseline API 更新Baseline API 从 NumPy 1.21 / SciPy 1.7 提升到NumPy 1.23 / SciPy 1.8。Docker 镜像更新官方 Docker 镜像更新为使用CUDA 11.7 与 ROCm 5.0。CuPy v10流与设备管理的革新版本支持下限的全面抬升不再支持 CUDA 10.1 及更早请使用 CUDA 10.2 或更新不再支持 NCCL v2.4 / v2.6 / v2.7不再支持 Python 3.6不再支持 NumPy 1.17。cupy.cuda.Device行为变化v12 已回退v10 中通过cupy.cuda.Device.use()设置的当前设备在退出设备上下文管理器时不会被重新激活。混用with device:块与device.use()的代码在 v10 与 v9 之间可能得到不同结果cupy.cuda.Device(1).use() with cupy.cuda.Device(0): pass cupy.cuda.Device() # - CuPy v10 返回 device 0 而不是 device 1官方在 v10 章节中特别说明这个决定是为了更好地服务 CuPy用户但可能让依赖 CuPy 的下游开发者感到意外因为本质上 CuPy 的Device上下文管理器不再尊重 CUDAcudaSetDevice()API。混用不同库的设备管理功能尤其是上下文管理器高度不鼓励。对于仍希望尊重cudaGetDevice()/cudaSetDevice()API 的下游库应避免用with Device上下文管理器管理当前设备而是显式调用这些 API参见 cupy/cupy PR #5963 的讨论。重要提示本节所述变化已在CuPy v12 中回退v12 起行为与 v9 及更早版本一致见上文 v12 章节。cupy.cuda.Stream行为变化Stream 改为按设备管理过去用户需要自行保持当前流与当前 CUDA 设备一致例如以下代码在 v9 及更早版本会报错import cupy with cupy.cuda.Device(0): # 在 device 0 上创建流 s0 cupy.cuda.Stream() with cupy.cuda.Device(1): with s0: # 尝试在 device 1 上使用该流 cupy.arange(10) # - CUDA_ERROR_INVALID_HANDLE: invalid resource handlev10 起当前流按设备管理创建流时会自动与当前设备关联切换设备时会被忽略。因此在 v10 中上述代码在 device 1 中会忽略s0改用 device 1 的默认流不再报错。use()设置的当前流在退出with块时不会被恢复——与Device的变化类似s1 cupy.cuda.Stream() s2 cupy.cuda.Stream() s3 cupy.cuda.Stream() with s1: s2.use() with s3: pass cupy.cuda.get_current_stream() # - CuPy v10 返回 s1 而不是 s2Stream 可以在线程间共享同一个cupy.cuda.Stream实例现在可以安全地在多个线程间共享。为此如果某个流是任意线程的当前流v10 不会销毁该流不调用cudaStreamDestroy。源码中Stream类见 cupy/cuda/stream.pyx支持null空流即默认流、ptds每线程默认流、non_blocking、priority等构造参数。大端数组自动转换为小端cupy.array、cupy.asarray及其变体现在总是以小端字节序将数据传到 GPU。过去 CuPy 会按原样把numpy.ndarray拷贝到 GPU无论端序v10 起大端数组在传输前会被转换为小端GPU 的原生字节序从而省去手动调整数组端序的步骤。Baseline API 更新Baseline API 从 NumPy 1.20 / SciPy 1.6 提升到NumPy 1.21 / SciPy 1.7。API 变化设备同步检测 APIcupyx.allow_synchronize与cupyx.DeviceSynchronizedv8 作为实验特性引入已标记弃用因为可靠地检测同步是不可能的。内部 APIcupy.cuda.compile_with_cache标记弃用推荐改用RawModule/RawKernel。DLPack 例程cupy.fromDlpack弃用改用cupy.from_dlpack后者解决潜在的数据竞争问题。新增cupyx.profiler模块承载所有 profiling API旧例程迁移如下旧版本弃用cupy.prof.TimeRangeDecorator→cupyx.profiler.time_rangecupy.prof.time_range→cupyx.profiler.time_rangecupy.cuda.profile→cupyx.profiler.profilecupyx.time.repeat→cupyx.profiler.benchmarkcupy.ndarray.__pos__现在返回副本与cupy.positive一致而不是返回self。注意弃用的 API 可能在未来的 CuPy 版本中被移除。Docker 镜像更新官方 Docker 镜像更新为使用CUDA 11.4 与 ROCm 4.3。CuPy v9明确模块导入与 wheel 精简版本支持下限不再支持 CUDA 9.0请使用 CUDA 9.2 或更新不再支持 cuDNN v7.5及更早与 NCCL v2.3及更早不再支持 NumPy 1.16 与 SciPy 1.3不再支持 Python 3.5。NCCL 与 cuDNN 不再包含在 wheel 中NCCL 和 cuDNN 共享库不再随 wheel 分发讨论见 cupy/cupy issue #4850。如果之前没有安装过安装 wheel 后需要手动安装它们参见 docs/source/install.rst。cuTENSOR 在 wheel 中启用通过 wheel 安装 CuPy 时现在可以使用 cuTENSOR。cupy.cuda.{nccl,cudnn}需要显式导入过去cupy.cuda.nccl与cupy.cuda.cudnn会被自动导入从 v9 起需要显式导入即import cupy.cuda.nccl/import cupy.cuda.cudnn。Baseline API 更新与标量别名弃用Baseline API 从 NumPy 1.19 / SciPy 1.5 提升到NumPy 1.20 / SciPy 1.6。跟随 NumPy 1.20Python 标量类型的别名cupy.bool、cupy.int、cupy.float、cupy.complex已弃用需要时应改用cupy.bool_、cupy.int_、cupy.float_、cupy.complex_。Docker 镜像更新官方 Docker 镜像更新为使用CUDA 11.2 与 Python 3.8。更早版本回顾v8–v2CuPy v8版本支持不再支持 CUDA 8.0 与 9.1不再支持 NumPy 1.15及更早与 SciPy 1.2及更早。CUB 支持与编译器要求CUB 模块默认构建。通过设置CUPY_ACCELERATORScub启用 CUB由于这一变化从源码构建 CuPy 需要g-6 或更新。以下环境变量不再生效CUB_DISABLED改用CUPY_ACCELERATORS、CUB_PATHCuPy 使用随 CUDA 11.0 捆绑的 CUB 源码或 CuPy 发行版自带的 CUB不再需要。API 变化cupy.scatter_addv4 弃用被移除改用cupyx.scatter_addcupy.sparse模块弃用改用cupyx.scipy.sparsecupy.ndarray.min/max的dtype参数被移除以对齐 NumPy 规范cupy.allclose现在返回 0 维 GPU 数组而非 Python bool避免设备同步cupy.RawModule延迟到首次调用才编译与cupy.RawKernel对齐cupy.cuda.*_enabled标志如nccl_enabled、nvtx_enabled弃用改用cupy.cuda.*.available如cupy.cuda.nccl.availableCHAINER_SEED环境变量不再生效改用CUPY_SEED。Docker 镜像更新为 CUDA 10.2 与 Python 3.6并预装 SciPy 与 Optuna。CuPy v7不再支持 Python 2.7 与 3.4分别于 2020 年 1 月与 2019 年 3 月到达 EOL。Python 3.5.1 是 CuPy v7 支持的最低 Python 版本。CuPy v6二进制包忽略LD_LIBRARY_PATHv6 之前可以通过LD_LIBRARY_PATH覆盖二进制发行版wheel中捆绑的 cuDNN/NCCL 库v6 起在 cuDNN/NCCL 的查找过程中忽略LD_LIBRARY_PATH二进制发行版始终使用随包附带的库以避免意外覆盖导致的错误。CuPy v5引入cupyx.scipy命名空间提供 CUDA 化的 SciPy 函数cupy.sparse更名为cupyx.scipy.sparsecupy.sparse保留为向后兼容别名。不再支持 CUDA 7.0 / 7.5。Docker 镜像更新为 CUDA 9.2 与 cuDNN 7使用这些镜像可能需要升级宿主机的 NVIDIA 驱动。CuPy v4注意版本号从 v2 直接跳到 v4是为了与 Chainer 的版本号对齐因此CuPy v3 不存在。默认内存池v4 之前内存池仅在 CuPy 与 Chainer 一起使用时默认启用v4 起即使单独使用 CuPy 也默认启用内存池通过缓解内存分配与 CPU/GPU 同步的开销显著提升性能。注意用nvidia-smi监控 GPU 内存时即使数组实例已超出作用域GPU 内存可能也不会被释放——这是预期行为默认内存池会「缓存」已分配的内存块。可以通过get_default_memory_pool与get_default_pinned_memory_pool访问内存池实例查看统计信息并释放缓存import cupy a cupy.ndarray(100, dtypecupy.float32) mempool cupy.get_default_memory_pool() # 为了性能实际分配的大小可能大于请求的数组大小 print(mempool.used_bytes()) # 512 print(mempool.total_bytes()) # 512 # 即使数组超出作用域其内存块仍保留在池中 a None print(mempool.used_bytes()) # 0 print(mempool.total_bytes()) # 512 # 可以通过 free_all_blocks 清除内存块 mempool.free_all_blocks() print(mempool.used_bytes()) # 0 print(mempool.total_bytes()) # 0也可以禁用默认内存池务必在任何其他 CuPy 操作之前执行import cupy cupy.cuda.set_allocator(None) cupy.cuda.set_pinned_memory_allocator(None)计算能力CuPy v4 要求 NVIDIA GPU 具备 Compute Capability 3.0 及以上。CUDA Stream由于 v4 完整支持 CUDA Streamcupy.cuda.RandomState.set_stream用于切换随机数生成器所用流的函数被移除请改用cupy.cuda.Stream.use。cupyx命名空间为提供 CuPy 特有即 NumPy 未提供的功能并避免未来冲突而引入。cupy.scatter_add因此迁移到cupyx.scatter_add原位置仍可用作别名但建议使用新位置。Docker 镜像更新为 CUDA 8.0 与 cuDNN 6.0因为 CUDA 7.5 不支持 NVIDIA Pascal GPU。CuPy v2出于性能原因cupy.count_nonzero在axisNone时改为返回零维ndarray而不是int讨论见 cupy/cupy PR #154。升级行动清单从旧版本平滑迁移综合上述各版本变更可以把升级路径上的关键行动归纳为以下几点先对照兼容性矩阵确认目标版本对 CUDA/ROCm、Python、NumPy、SciPy、NCCL、cuTENSOR 的最低要求逐一核对本机环境。v14 起还要额外确认 cuDNN 依赖已被移除、CCCL 由 CuPy 自带。检查数值行为v14 全面采用 NumPy 2 的类型提升规则NEP 50涉及标量类型时优先使用 Python 标量bfloat16 需要 NumPy 2.1.2。扫描 API 迁移点重点搜索cupy.sparse、cupy.prof、cupy.cusolver、cupy.cusparse、cupy.cutensor、cupy.fromDlpack/toDlpack、scatter_add/max/min、cupyx.fallback_mode、cupy.array_api等已移除/弃用 API并对照上文各版本的迁移表逐一替换。留意异步语义v13 起 GPU→CPU 传输默认阻塞可用blockingFalse恢复pinned 内存的 CPU→GPU 传输默认异步可用blockingTrue恢复不要在主线程上假定旧的同步语义。检查返回值类型nccl.get_unique_id返回 bytes、random.choice恒返回int64数组、allclose返回 0 维 GPU 数组、count_nonzeroaxisNone 时返回 0 维数组这些类型变化可能影响下游逻辑。关注多设备/多流语义v12 已回退 v10 的Device上下文管理器行为混用use()与with块的代码在 v10/v11 与 v12 之间结果不同v10 起 Stream 按设备管理且可跨线程共享。内存观测差异v4 起默认内存池会缓存显存nvidia-smi观察到的「未释放」是预期行为可用free_all_blocks()手动释放。通过以上清单逐项核对再配合 docs/source/install.rst 的安装说明与 docs/source/upgrade.rst 原文即可将升级过程中的意外降到最低。【免费下载链接】cupyNumPy SciPy for GPU项目地址: https://gitcode.com/GitHub_Trending/cu/cupy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考