CuPy 环境变量完全指南从内核缓存、内存限制到源码构建的运行时调优【免费下载链接】cupyNumPy SciPy for GPU项目地址: https://gitcode.com/GitHub_Trending/cu/cupyCuPy 是面向 GPU 的 NumPy/SciPy 兼容实现其行为高度可配置。本文基于仓库文档 docs/source/reference/environment.rst 完整梳理 CuPy 支持的运行时环境变量与安装源码构建环境变量并深入对应源码cupy/_environment.py、cupy/cuda/_compiler_cache.py、cupy/cuda/memory.pyx 等讲解每个变量的实际生效机制与适用场景。读完本文你将掌握如何通过环境变量定制内核编译与缓存策略、控制显存上限、切换加速后端、调优数值精度与流同步行为以及如何控制 CuPy 从源码构建的全过程。概述CuPy 环境变量的两大类别CuPy 的环境变量分为两类类别用途生效时机运行时环境变量控制内核缓存、编译选项、显存管理、加速后端、数值精度、流与互操作行为等导入 CuPy / 首次编译 / 运行调用时读取安装环境变量控制从源码构建pip install/python setup.py时的架构、并行度、后端选型构建阶段读取此外CUDA_PATH与NVCC两个变量同时被运行时与构建期共同尊重详见下文。运行时环境变量的读取逻辑分散在多个模块路径探测集中在 cupy/_environment.py编译与缓存选项在 cupy/cuda/compiler.py 与 cupy/cuda/_compiler_cache.py互操作与切片行为在 cupy/_util.pyx随机种子在 cupy/random/_generator.py。理解这些文件的位置有助于排查环境变量不生效的问题。运行时环境变量详解CUDA 与编译器定位CUDA_PATH、NVCCCUDA_PATH指向包含 CUDA 的目录路径。默认值推导规则取包含nvcc的目录即CUDA_PATH/bin的父目录作为 CUDA 根目录当nvcc找不到时回退到/usr/local/cuda。源码依据在 cupy/_environment.py 的_get_cuda_path()中CuPy 依次尝试 conda 前缀路径、cuda.pathfinder会搜索 site-packages、conda、系统路径与CUDA_PATH、最后回退到/usr/local/cuda。_get_nvcc_path()则首先尊重NVCC环境变量其次通过 pathfinder 查找最后在CUDA_PATH/bin中查找nvcc。使用提示在 Windows 上若 DLL 加载失败官方诊断信息会提示尝试设置CUDA_PATH见 cupy/_environment.py 中_diagnose_import_error()的说明。Linux 上则可能需要配置LD_LIBRARY_PATH。NVCC定义编译 CUDA 源码时使用的编译器默认值为nvcc。注意CuPy 的多数内核由 NVRTC 编译NVCC变量仅对两类场景生效使用nvcc后端的cupy.RawKernel/cupy.RawModule以及将cub用作加速器时。使用提示可以设置类似NVCCccache nvcc的组合命令源码 cupy/_environment.py 的_get_nvcc_path()注释即给出了该示例。内核缓存与编译CUPY_CACHE_DIR、CUPY_CACHE_SAVE_CUDA_SOURCE、CUPY_CACHE_IN_MEMORY、CUPY_NVRTC_USE_PCH、CUPY_DISABLE_JITIFY_CACHECUPY_CACHE_DIR内核缓存目录路径默认${HOME}/.cupy/kernel_cache。源码依据在 cupy/cuda/_compiler_cache.py 中_default_cache_dir os.path.expanduser(~/.cupy/kernel_cache)磁盘缓存后端KernelCacheBackend优先读取CUPY_CACHE_DIR不存在时自动创建目录。使用场景将缓存目录迁移到高速 SSD 或共享缓存卷可显著改善多进程/多容器场景下的内核复用效率。CUPY_CACHE_SAVE_CUDA_SOURCE默认0。设为1时会在缓存目录中连同编译产物一起保存 CUDA 源码文件便于调试。注意若编译产物已命中缓存源码文件不会再次保存。源码依据cupy/cuda/_compiler_cache.py 第 97-98 行通过os.environ.get(CUPY_CACHE_SAVE_CUDA_SOURCE)读取该开关。CUPY_CACHE_IN_MEMORY默认0。设为1时忽略CUPY_CACHE_DIR与CUPY_CACHE_SAVE_CUDA_SOURCE内核缓存完全驻留内存。作用减少磁盘 I/O适合缓存目录位于慢速磁盘的场景。限制当nvcc被设为编译器后端时该变量被忽略因为 nvcc 后端必须写临时文件。CUPY_NVRTC_USE_PCH默认0。设为1时启用预编译头Precompiled Headers, PCH大幅加速“需要编译大量内核”的场景例如缓存刚清空或配合CUPY_CACHE_IN_MEMORY1使用。实现细节启用后 CuPy 会向所有 NVRTC 内核编译传递--pch选项。版本前提仅 CUDA 12.8 及以上版本可用。源码依据cupy/cuda/compiler.py 中_use_pch _get_bool_env_variable(CUPY_NVRTC_USE_PCH, False)。附加代价PCH 会产生临时文件可通过 NVRTC 的 PCH 相关选项进一步配置详见 NVIDIA NVRTC 文档中 Precompiled Header (PCH) 一节。CUPY_DISABLE_JITIFY_CACHE默认0。设为1时Jitify 加载的头文件不再缓存到磁盘默认总是缓存到CUPY_CACHE_DIR。适用场景Jitify 缓存带来的磁盘占用或 I/O 开销成为瓶颈时可关闭磁盘缓存。编译失败与调试CUPY_DUMP_CUDA_SOURCE_ON_ERROR、CUPY_CUDA_COMPILE_WITH_DEBUG、CUPY_COMPILE_WITH_PTXCUPY_DUMP_CUDA_SOURCE_ON_ERROR默认0。设为1时当 CUDA 内核编译失败CuPy 将内核代码 dump 到标准错误输出stderr。源码依据cupy/cuda/compiler.py 中无论是 Jitify 预处理、NVRTC 编译还是 nvcc 编译路径捕获到CompileException后都会检查该变量并调用e.dump(sys.stderr)。这是排查自定义 kernel 语法错误的得力助手。CUPY_CUDA_COMPILE_WITH_DEBUG默认0。设为1时内核将以调试信息编译即附加--device-debug与--generate-line-info选项便于使用 Nsight Compute 等工具进行行级调试。CUPY_COMPILE_WITH_PTX默认0。默认行为CuPy 直接将内核编译为 SASSCUBIN以支持 CUDA Enhanced Compatibility跨小版本向前兼容。设为1改为编译为 PTX由 CUDA Driver 在运行时从 PTX 汇编出 SASS。版本限制仅对 CUDA 11.1 及以上有效更早版本 CuPy 总是编译为 PTX且仅当选择 NVRTC 作为编译后端时生效NVCC 后端总是编译为 SASSCUBIN。源码依据cupy/cuda/compiler.py 中_use_ptx _get_bool_env_variable(CUPY_COMPILE_WITH_PTX, False)。显存与随机数CUPY_GPU_MEMORY_LIMIT、CUPY_SEEDCUPY_GPU_MEMORY_LIMIT默认0即不限制。设置每个设备可分配的内存上限支持两种写法绝对字节数如CUPY_GPU_MEMORY_LIMIT85899345928 GiB显存比例如CUPY_GPU_MEMORY_LIMIT90%表示每张 GPU 总显存的 90%。源码依据cupy/cuda/memory.pyx 中的_parse_limit_string()读取该变量以%结尾则解析为分数fraction否则解析为绝对字节数size。补充说明该环境变量设置的是每个设备的默认内存上限与cupy.cuda.MemoryPool的set_limit(sizeNone, fractionNone)方法等价但方法调用设置的限额会覆盖环境变量且方法只影响当前设备详见 cupy/cuda/memory.pyx 中set_limit的注释。set_limit是软限制内部通过cudaMemPoolAttrReleaseThreshold属性实现。更详细的池化内存策略请参考 docs/source/user_guide/memory.rst。CUPY_SEED为随机数生成器设置种子。未设置时每个设备首次访问随机数时以非确定性方式初始化。源码依据cupy/random/_generator.py 中创建每设备RandomState时读取CUPY_SEED并转换为numpy.uint64作为种子。使用场景需要复现随机实验时设置CUPY_SEED可保证脚本启动即获得可复现的随机序列注意若脚本内部手动调用cupy.random.seed()会覆盖该环境变量的作用。切片语法与加速后端CUPY_EXPERIMENTAL_SLICE_COPY、CUPY_ACCELERATORSCUPY_EXPERIMENTAL_SLICE_COPY默认0。设为1时启用以下赋值语法cupy_ndarray[:] numpy_ndarray源码依据cupy/_util.pyx 中ENABLE_SLICE_COPY bool(int(os.environ.get(CUPY_EXPERIMENTAL_SLICE_COPY, 0)))。该语法实现的是将 NumPy 数组切片赋值到 CuPy 数组的便捷操作。CUPY_ACCELERATORS指定 CuPy 运算使用的加速后端及其优先级逗号分隔、按优先级降序可选后端名称cubCUB 库默认启用cutensorcuTENSORcutensornetcuTensorNet用于einsum等张量网络收缩需要 cuQuantum Python v22.03见 cupy/linalg/_einsum.py 的说明cuda_compute基于cuda-cccl包的 CUDA 计算后端目前加速cupy.cumsum与cupy.cumprod。默认值CUDA 环境为cubROCm HIP 环境下默认为即不启用任何加速器。源码依据cupy/_core/_accelerator.pyx 的_set_default_accelerators()读取CUPY_ACCELERATORS在 HIP 环境下默认否则默认cub并将解析结果同步设置到 elementwise、reduction 与 routine 三类加速器。使用示例# 启用 CUB 与 cuTENSORCUB 优先级更高 export CUPY_ACCELERATORScub,cutensor # 仅使用 cuTensorNet 加速 einsum export CUPY_ACCELERATORScutensornet注意设置CUPY_ACCELERATORS时运行时宿主编译器需要 g-6 或更高版本见文档中的提示详情参考 docs/source/install.rst。数值精度与流行为CUPY_TF32、CUPY_CUDA_PER_THREAD_DEFAULT_STREAMCUPY_TF32默认0。设为1时允许 CUDA 库cuBLAS 等在 32 位浮点计算中使用 Tensor Cores 的 TF32 模式。源码依据cupy/_core/_routines_linalg.pyx 中对f/F单精度浮点dtype 计算计算类型时若int(os.getenv(CUPY_TF32, 0)) 0则选择COMPUTE_TYPE_TF32。使用场景在追求吞吐、对精度损失可接受的训练/推理场景中启用需要严格精度的数值计算请保持关闭。CUPY_CUDA_PER_THREAD_DEFAULT_STREAM默认0控制 CuPy 使用的默认流语义1使用 CUDAper-thread default streamptds每个宿主线程自动在独立流中执行除非显式指定 CUDA 默认null流或用户创建的流0默认使用 CUDA 默认null流除非显式指定 per-thread default stream 或用户创建的流。适用场景多线程各自提交 CUDA 运算且希望互不阻塞时可启用 per-thread 语义。CUDA Array Interface 与 DLPack 互操作CUPY_CUDA_ARRAY_INTERFACE_SYNC、CUPY_CUDA_ARRAY_INTERFACE_EXPORT_VERSION、CUPY_DLPACK_EXPORT_VERSION这三个变量控制 CuPy 与其他 GPU 库Numba、PyTorch 等之间零拷贝数据交换的同步语义。CUPY_CUDA_ARRAY_INTERFACE_SYNC默认1控制 CuPy 作为Consumer消费外部设备数组时的行为。设为0时消费实现了 CUDA Array Interface 的外部库设备数组时不再执行流同步。同步要求细节参考 CUDA Array Interface v3 文档中的 Synchronization 一节。源码依据cupy/_util.pyx 中CUDA_ARRAY_INTERFACE_SYNC bool(int(os.environ.get(CUPY_CUDA_ARRAY_INTERFACE_SYNC, 1)))。CUPY_CUDA_ARRAY_INTERFACE_EXPORT_VERSION默认3控制 CuPy 作为Producer向外部库导出设备数组时的行为。设为2时不导出 CuPy 操作数据的流因此外部 Consumer 不会执行任何流同步恢复 CUDA Array Interface v2 时代的行为。源码依据cupy/_core/core.pyx 中构造 CAI v3 描述符时若版本为2则跳过导出stream字段注释明确说明这是为了兼容缺少细粒度同步控制的旧库设置为其他值时抛出ValueError即该变量只接受2或3。适用场景当互操作的另一方库未正确实现 v3 同步语义导致死锁或异常同步时可降级到2。CUPY_DLPACK_EXPORT_VERSION默认0.6控制 CuPy 的 DLPack 支持版本。语义设置小于0.6的值会将托管内存managed memory伪装为普通设备内存从而能与尚未更新 DLPack 支持的库交换数据而 0.6 及以上版本中CUDA 托管内存会被正确识别为合法的设备类型。源码依据cupy/_util.pyx 中DLPACK_EXPORT_VERSION按0.6的格式按.拆分为整数元组。CUDA Toolkit 环境变量除上述变量外CuPy 与所有 CUDA 程序一样也会尊重 CUDA Toolkit 文档中列出的全部 CUDA 环境变量如CUDA_VISIBLE_DEVICES、CUDA_DEVICE_ORDER等。提示设置CUPY_ACCELERATORS或NVCC时运行时需要g-6 或更高版本作为宿主编译器ROCm/HIP 场景同理g 的安装方法参见 docs/source/install.rst 中的源码构建章节。安装源码构建环境变量详解以下变量在从源码构建 CuPy而非安装预编译 wheel时生效。后端与路径CUTENSOR_PATH、CUPY_INSTALL_USE_HIP、CUPY_USE_CUDA_PYTHONCUTENSOR_PATH实验性指向 cuTENSOR 根目录的路径该目录下应包含lib与include子目录。构建时据此链接 cuTENSOR。CUPY_INSTALL_USE_HIP默认0。设为1时CuPy 将为 AMD ROCm 平台构建实验性。关联构建流程ROCm 构建细节参见 docs/source/install.rst 中install_hip一节ci/versions.yml 中也维护了 ROCm 相关的版本矩阵。补充运行时在 HIP 环境下CUPY_ACCELERATORS默认值为空字符串且 CUB 加速器不可用cupy/_core/_accelerator.pyxCUB 头文件探测也切换到 ROCm 的 hipCUB见 cupy/_environment.py 的_get_cub_path()。CUPY_USE_CUDA_PYTHON默认0。设为1时CuPy 使用 CUDA PythonNVIDIA 官方 cuda-python 绑定进行构建。架构与并行度CUPY_NVCC_GENERATE_CODE、CUPY_NUM_BUILD_JOBS、CUPY_NUM_NVCC_THREADSCUPY_NVCC_GENERATE_CODE为特定的 CUDA 架构构建 CuPy。示例# 仅针对 compute_60 / sm_60Pascal 架构 export CUPY_NVCC_GENERATE_CODEarchcompute_60,codesm_60多个架构用分号;连接archcompute_60,codesm_60;archcompute_80,codesm_80。若指定current构建时自动探测当前已安装 GPU 的架构。未设置时默认支持所有架构编译产物更大、构建更慢。CUPY_NUM_BUILD_JOBS默认4。控制构建扩展时并行使用的进程数可通过设为1关闭并行构建用于排查构建环境问题或受限环境。CUPY_NUM_NVCC_THREADS默认2。控制 nvcc 并行编译时使用的线程数同样可设为1关闭 nvcc 级并行。另外CUDA_PATH与NVCC两个变量在构建期同样被尊重用于定位 CUDA 工具链。实战速查常见调优组合目标推荐配置内核首次编译更快export CUPY_NVRTC_USE_PCH1需 CUDA 12.8减少缓存磁盘 I/Oexport CUPY_CACHE_IN_MEMORY1定位自定义 kernel 编译错误export CUPY_DUMP_CUDA_SOURCE_ON_ERROR1限制每卡显存为 90%export CUPY_GPU_MEMORY_LIMIT90%启用 cuTENSOR 加速export CUPY_ACCELERATORScub,cutensor复现随机实验export CUPY_SEED42与旧版 CUDA Array Interface 库互操作export CUPY_CUDA_ARRAY_INTERFACE_EXPORT_VERSION2仅针对当前 GPU 架构构建export CUPY_NVCC_GENERATE_CODEcurrent关闭并行构建排查问题export CUPY_NUM_BUILD_JOBS1 CUPY_NUM_NVCC_THREADS1小结CuPy 通过一组设计清晰的环境变量把“运行时调优”与“构建期配置”彻底解耦运行时变量覆盖内核缓存与编译策略CUPY_CACHE_*、CUPY_NVRTC_USE_PCH、CUPY_COMPILE_WITH_PTX、显存与随机数CUPY_GPU_MEMORY_LIMIT、CUPY_SEED、加速后端与精度CUPY_ACCELERATORS、CUPY_TF32、流与互操作CUPY_CUDA_PER_THREAD_DEFAULT_STREAM、CUPY_CUDA_ARRAY_INTERFACE_*、CUPY_DLPACK_EXPORT_VERSION安装变量则控制架构目标与构建并行度CUPY_NVCC_GENERATE_CODE、CUPY_NUM_BUILD_JOBS、CUPY_NUM_NVCC_THREADS。所有变量的默认值与解析逻辑均可在 docs/source/reference/environment.rst 及上述源码文件中逐一对证。建议在修改环境变量前先确认对应的源码读取点如编译选项在 cupy/cuda/compiler.py、缓存后端在 cupy/cuda/_compiler_cache.py、内存池在 cupy/cuda/memory.pyx这能帮助你准确判断变量在什么时机生效、受哪些前提条件限制。【免费下载链接】cupyNumPy SciPy for GPU项目地址: https://gitcode.com/GitHub_Trending/cu/cupy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 CuPy 环境变量完全指南：从内核缓存、内存限制到源码构建的运行时调优
CuPy 环境变量完全指南从内核缓存、内存限制到源码构建的运行时调优【免费下载链接】cupyNumPy SciPy for GPU项目地址: https://gitcode.com/GitHub_Trending/cu/cupyCuPy 是面向 GPU 的 NumPy/SciPy 兼容实现其行为高度可配置。本文基于仓库文档 docs/source/reference/environment.rst 完整梳理 CuPy 支持的运行时环境变量与安装源码构建环境变量并深入对应源码cupy/_environment.py、cupy/cuda/_compiler_cache.py、cupy/cuda/memory.pyx 等讲解每个变量的实际生效机制与适用场景。读完本文你将掌握如何通过环境变量定制内核编译与缓存策略、控制显存上限、切换加速后端、调优数值精度与流同步行为以及如何控制 CuPy 从源码构建的全过程。概述CuPy 环境变量的两大类别CuPy 的环境变量分为两类类别用途生效时机运行时环境变量控制内核缓存、编译选项、显存管理、加速后端、数值精度、流与互操作行为等导入 CuPy / 首次编译 / 运行调用时读取安装环境变量控制从源码构建pip install/python setup.py时的架构、并行度、后端选型构建阶段读取此外CUDA_PATH与NVCC两个变量同时被运行时与构建期共同尊重详见下文。运行时环境变量的读取逻辑分散在多个模块路径探测集中在 cupy/_environment.py编译与缓存选项在 cupy/cuda/compiler.py 与 cupy/cuda/_compiler_cache.py互操作与切片行为在 cupy/_util.pyx随机种子在 cupy/random/_generator.py。理解这些文件的位置有助于排查环境变量不生效的问题。运行时环境变量详解CUDA 与编译器定位CUDA_PATH、NVCCCUDA_PATH指向包含 CUDA 的目录路径。默认值推导规则取包含nvcc的目录即CUDA_PATH/bin的父目录作为 CUDA 根目录当nvcc找不到时回退到/usr/local/cuda。源码依据在 cupy/_environment.py 的_get_cuda_path()中CuPy 依次尝试 conda 前缀路径、cuda.pathfinder会搜索 site-packages、conda、系统路径与CUDA_PATH、最后回退到/usr/local/cuda。_get_nvcc_path()则首先尊重NVCC环境变量其次通过 pathfinder 查找最后在CUDA_PATH/bin中查找nvcc。使用提示在 Windows 上若 DLL 加载失败官方诊断信息会提示尝试设置CUDA_PATH见 cupy/_environment.py 中_diagnose_import_error()的说明。Linux 上则可能需要配置LD_LIBRARY_PATH。NVCC定义编译 CUDA 源码时使用的编译器默认值为nvcc。注意CuPy 的多数内核由 NVRTC 编译NVCC变量仅对两类场景生效使用nvcc后端的cupy.RawKernel/cupy.RawModule以及将cub用作加速器时。使用提示可以设置类似NVCCccache nvcc的组合命令源码 cupy/_environment.py 的_get_nvcc_path()注释即给出了该示例。内核缓存与编译CUPY_CACHE_DIR、CUPY_CACHE_SAVE_CUDA_SOURCE、CUPY_CACHE_IN_MEMORY、CUPY_NVRTC_USE_PCH、CUPY_DISABLE_JITIFY_CACHECUPY_CACHE_DIR内核缓存目录路径默认${HOME}/.cupy/kernel_cache。源码依据在 cupy/cuda/_compiler_cache.py 中_default_cache_dir os.path.expanduser(~/.cupy/kernel_cache)磁盘缓存后端KernelCacheBackend优先读取CUPY_CACHE_DIR不存在时自动创建目录。使用场景将缓存目录迁移到高速 SSD 或共享缓存卷可显著改善多进程/多容器场景下的内核复用效率。CUPY_CACHE_SAVE_CUDA_SOURCE默认0。设为1时会在缓存目录中连同编译产物一起保存 CUDA 源码文件便于调试。注意若编译产物已命中缓存源码文件不会再次保存。源码依据cupy/cuda/_compiler_cache.py 第 97-98 行通过os.environ.get(CUPY_CACHE_SAVE_CUDA_SOURCE)读取该开关。CUPY_CACHE_IN_MEMORY默认0。设为1时忽略CUPY_CACHE_DIR与CUPY_CACHE_SAVE_CUDA_SOURCE内核缓存完全驻留内存。作用减少磁盘 I/O适合缓存目录位于慢速磁盘的场景。限制当nvcc被设为编译器后端时该变量被忽略因为 nvcc 后端必须写临时文件。CUPY_NVRTC_USE_PCH默认0。设为1时启用预编译头Precompiled Headers, PCH大幅加速“需要编译大量内核”的场景例如缓存刚清空或配合CUPY_CACHE_IN_MEMORY1使用。实现细节启用后 CuPy 会向所有 NVRTC 内核编译传递--pch选项。版本前提仅 CUDA 12.8 及以上版本可用。源码依据cupy/cuda/compiler.py 中_use_pch _get_bool_env_variable(CUPY_NVRTC_USE_PCH, False)。附加代价PCH 会产生临时文件可通过 NVRTC 的 PCH 相关选项进一步配置详见 NVIDIA NVRTC 文档中 Precompiled Header (PCH) 一节。CUPY_DISABLE_JITIFY_CACHE默认0。设为1时Jitify 加载的头文件不再缓存到磁盘默认总是缓存到CUPY_CACHE_DIR。适用场景Jitify 缓存带来的磁盘占用或 I/O 开销成为瓶颈时可关闭磁盘缓存。编译失败与调试CUPY_DUMP_CUDA_SOURCE_ON_ERROR、CUPY_CUDA_COMPILE_WITH_DEBUG、CUPY_COMPILE_WITH_PTXCUPY_DUMP_CUDA_SOURCE_ON_ERROR默认0。设为1时当 CUDA 内核编译失败CuPy 将内核代码 dump 到标准错误输出stderr。源码依据cupy/cuda/compiler.py 中无论是 Jitify 预处理、NVRTC 编译还是 nvcc 编译路径捕获到CompileException后都会检查该变量并调用e.dump(sys.stderr)。这是排查自定义 kernel 语法错误的得力助手。CUPY_CUDA_COMPILE_WITH_DEBUG默认0。设为1时内核将以调试信息编译即附加--device-debug与--generate-line-info选项便于使用 Nsight Compute 等工具进行行级调试。CUPY_COMPILE_WITH_PTX默认0。默认行为CuPy 直接将内核编译为 SASSCUBIN以支持 CUDA Enhanced Compatibility跨小版本向前兼容。设为1改为编译为 PTX由 CUDA Driver 在运行时从 PTX 汇编出 SASS。版本限制仅对 CUDA 11.1 及以上有效更早版本 CuPy 总是编译为 PTX且仅当选择 NVRTC 作为编译后端时生效NVCC 后端总是编译为 SASSCUBIN。源码依据cupy/cuda/compiler.py 中_use_ptx _get_bool_env_variable(CUPY_COMPILE_WITH_PTX, False)。显存与随机数CUPY_GPU_MEMORY_LIMIT、CUPY_SEEDCUPY_GPU_MEMORY_LIMIT默认0即不限制。设置每个设备可分配的内存上限支持两种写法绝对字节数如CUPY_GPU_MEMORY_LIMIT85899345928 GiB显存比例如CUPY_GPU_MEMORY_LIMIT90%表示每张 GPU 总显存的 90%。源码依据cupy/cuda/memory.pyx 中的_parse_limit_string()读取该变量以%结尾则解析为分数fraction否则解析为绝对字节数size。补充说明该环境变量设置的是每个设备的默认内存上限与cupy.cuda.MemoryPool的set_limit(sizeNone, fractionNone)方法等价但方法调用设置的限额会覆盖环境变量且方法只影响当前设备详见 cupy/cuda/memory.pyx 中set_limit的注释。set_limit是软限制内部通过cudaMemPoolAttrReleaseThreshold属性实现。更详细的池化内存策略请参考 docs/source/user_guide/memory.rst。CUPY_SEED为随机数生成器设置种子。未设置时每个设备首次访问随机数时以非确定性方式初始化。源码依据cupy/random/_generator.py 中创建每设备RandomState时读取CUPY_SEED并转换为numpy.uint64作为种子。使用场景需要复现随机实验时设置CUPY_SEED可保证脚本启动即获得可复现的随机序列注意若脚本内部手动调用cupy.random.seed()会覆盖该环境变量的作用。切片语法与加速后端CUPY_EXPERIMENTAL_SLICE_COPY、CUPY_ACCELERATORSCUPY_EXPERIMENTAL_SLICE_COPY默认0。设为1时启用以下赋值语法cupy_ndarray[:] numpy_ndarray源码依据cupy/_util.pyx 中ENABLE_SLICE_COPY bool(int(os.environ.get(CUPY_EXPERIMENTAL_SLICE_COPY, 0)))。该语法实现的是将 NumPy 数组切片赋值到 CuPy 数组的便捷操作。CUPY_ACCELERATORS指定 CuPy 运算使用的加速后端及其优先级逗号分隔、按优先级降序可选后端名称cubCUB 库默认启用cutensorcuTENSORcutensornetcuTensorNet用于einsum等张量网络收缩需要 cuQuantum Python v22.03见 cupy/linalg/_einsum.py 的说明cuda_compute基于cuda-cccl包的 CUDA 计算后端目前加速cupy.cumsum与cupy.cumprod。默认值CUDA 环境为cubROCm HIP 环境下默认为即不启用任何加速器。源码依据cupy/_core/_accelerator.pyx 的_set_default_accelerators()读取CUPY_ACCELERATORS在 HIP 环境下默认否则默认cub并将解析结果同步设置到 elementwise、reduction 与 routine 三类加速器。使用示例# 启用 CUB 与 cuTENSORCUB 优先级更高 export CUPY_ACCELERATORScub,cutensor # 仅使用 cuTensorNet 加速 einsum export CUPY_ACCELERATORScutensornet注意设置CUPY_ACCELERATORS时运行时宿主编译器需要 g-6 或更高版本见文档中的提示详情参考 docs/source/install.rst。数值精度与流行为CUPY_TF32、CUPY_CUDA_PER_THREAD_DEFAULT_STREAMCUPY_TF32默认0。设为1时允许 CUDA 库cuBLAS 等在 32 位浮点计算中使用 Tensor Cores 的 TF32 模式。源码依据cupy/_core/_routines_linalg.pyx 中对f/F单精度浮点dtype 计算计算类型时若int(os.getenv(CUPY_TF32, 0)) 0则选择COMPUTE_TYPE_TF32。使用场景在追求吞吐、对精度损失可接受的训练/推理场景中启用需要严格精度的数值计算请保持关闭。CUPY_CUDA_PER_THREAD_DEFAULT_STREAM默认0控制 CuPy 使用的默认流语义1使用 CUDAper-thread default streamptds每个宿主线程自动在独立流中执行除非显式指定 CUDA 默认null流或用户创建的流0默认使用 CUDA 默认null流除非显式指定 per-thread default stream 或用户创建的流。适用场景多线程各自提交 CUDA 运算且希望互不阻塞时可启用 per-thread 语义。CUDA Array Interface 与 DLPack 互操作CUPY_CUDA_ARRAY_INTERFACE_SYNC、CUPY_CUDA_ARRAY_INTERFACE_EXPORT_VERSION、CUPY_DLPACK_EXPORT_VERSION这三个变量控制 CuPy 与其他 GPU 库Numba、PyTorch 等之间零拷贝数据交换的同步语义。CUPY_CUDA_ARRAY_INTERFACE_SYNC默认1控制 CuPy 作为Consumer消费外部设备数组时的行为。设为0时消费实现了 CUDA Array Interface 的外部库设备数组时不再执行流同步。同步要求细节参考 CUDA Array Interface v3 文档中的 Synchronization 一节。源码依据cupy/_util.pyx 中CUDA_ARRAY_INTERFACE_SYNC bool(int(os.environ.get(CUPY_CUDA_ARRAY_INTERFACE_SYNC, 1)))。CUPY_CUDA_ARRAY_INTERFACE_EXPORT_VERSION默认3控制 CuPy 作为Producer向外部库导出设备数组时的行为。设为2时不导出 CuPy 操作数据的流因此外部 Consumer 不会执行任何流同步恢复 CUDA Array Interface v2 时代的行为。源码依据cupy/_core/core.pyx 中构造 CAI v3 描述符时若版本为2则跳过导出stream字段注释明确说明这是为了兼容缺少细粒度同步控制的旧库设置为其他值时抛出ValueError即该变量只接受2或3。适用场景当互操作的另一方库未正确实现 v3 同步语义导致死锁或异常同步时可降级到2。CUPY_DLPACK_EXPORT_VERSION默认0.6控制 CuPy 的 DLPack 支持版本。语义设置小于0.6的值会将托管内存managed memory伪装为普通设备内存从而能与尚未更新 DLPack 支持的库交换数据而 0.6 及以上版本中CUDA 托管内存会被正确识别为合法的设备类型。源码依据cupy/_util.pyx 中DLPACK_EXPORT_VERSION按0.6的格式按.拆分为整数元组。CUDA Toolkit 环境变量除上述变量外CuPy 与所有 CUDA 程序一样也会尊重 CUDA Toolkit 文档中列出的全部 CUDA 环境变量如CUDA_VISIBLE_DEVICES、CUDA_DEVICE_ORDER等。提示设置CUPY_ACCELERATORS或NVCC时运行时需要g-6 或更高版本作为宿主编译器ROCm/HIP 场景同理g 的安装方法参见 docs/source/install.rst 中的源码构建章节。安装源码构建环境变量详解以下变量在从源码构建 CuPy而非安装预编译 wheel时生效。后端与路径CUTENSOR_PATH、CUPY_INSTALL_USE_HIP、CUPY_USE_CUDA_PYTHONCUTENSOR_PATH实验性指向 cuTENSOR 根目录的路径该目录下应包含lib与include子目录。构建时据此链接 cuTENSOR。CUPY_INSTALL_USE_HIP默认0。设为1时CuPy 将为 AMD ROCm 平台构建实验性。关联构建流程ROCm 构建细节参见 docs/source/install.rst 中install_hip一节ci/versions.yml 中也维护了 ROCm 相关的版本矩阵。补充运行时在 HIP 环境下CUPY_ACCELERATORS默认值为空字符串且 CUB 加速器不可用cupy/_core/_accelerator.pyxCUB 头文件探测也切换到 ROCm 的 hipCUB见 cupy/_environment.py 的_get_cub_path()。CUPY_USE_CUDA_PYTHON默认0。设为1时CuPy 使用 CUDA PythonNVIDIA 官方 cuda-python 绑定进行构建。架构与并行度CUPY_NVCC_GENERATE_CODE、CUPY_NUM_BUILD_JOBS、CUPY_NUM_NVCC_THREADSCUPY_NVCC_GENERATE_CODE为特定的 CUDA 架构构建 CuPy。示例# 仅针对 compute_60 / sm_60Pascal 架构 export CUPY_NVCC_GENERATE_CODEarchcompute_60,codesm_60多个架构用分号;连接archcompute_60,codesm_60;archcompute_80,codesm_80。若指定current构建时自动探测当前已安装 GPU 的架构。未设置时默认支持所有架构编译产物更大、构建更慢。CUPY_NUM_BUILD_JOBS默认4。控制构建扩展时并行使用的进程数可通过设为1关闭并行构建用于排查构建环境问题或受限环境。CUPY_NUM_NVCC_THREADS默认2。控制 nvcc 并行编译时使用的线程数同样可设为1关闭 nvcc 级并行。另外CUDA_PATH与NVCC两个变量在构建期同样被尊重用于定位 CUDA 工具链。实战速查常见调优组合目标推荐配置内核首次编译更快export CUPY_NVRTC_USE_PCH1需 CUDA 12.8减少缓存磁盘 I/Oexport CUPY_CACHE_IN_MEMORY1定位自定义 kernel 编译错误export CUPY_DUMP_CUDA_SOURCE_ON_ERROR1限制每卡显存为 90%export CUPY_GPU_MEMORY_LIMIT90%启用 cuTENSOR 加速export CUPY_ACCELERATORScub,cutensor复现随机实验export CUPY_SEED42与旧版 CUDA Array Interface 库互操作export CUPY_CUDA_ARRAY_INTERFACE_EXPORT_VERSION2仅针对当前 GPU 架构构建export CUPY_NVCC_GENERATE_CODEcurrent关闭并行构建排查问题export CUPY_NUM_BUILD_JOBS1 CUPY_NUM_NVCC_THREADS1小结CuPy 通过一组设计清晰的环境变量把“运行时调优”与“构建期配置”彻底解耦运行时变量覆盖内核缓存与编译策略CUPY_CACHE_*、CUPY_NVRTC_USE_PCH、CUPY_COMPILE_WITH_PTX、显存与随机数CUPY_GPU_MEMORY_LIMIT、CUPY_SEED、加速后端与精度CUPY_ACCELERATORS、CUPY_TF32、流与互操作CUPY_CUDA_PER_THREAD_DEFAULT_STREAM、CUPY_CUDA_ARRAY_INTERFACE_*、CUPY_DLPACK_EXPORT_VERSION安装变量则控制架构目标与构建并行度CUPY_NVCC_GENERATE_CODE、CUPY_NUM_BUILD_JOBS、CUPY_NUM_NVCC_THREADS。所有变量的默认值与解析逻辑均可在 docs/source/reference/environment.rst 及上述源码文件中逐一对证。建议在修改环境变量前先确认对应的源码读取点如编译选项在 cupy/cuda/compiler.py、缓存后端在 cupy/cuda/_compiler_cache.py、内存池在 cupy/cuda/memory.pyx这能帮助你准确判断变量在什么时机生效、受哪些前提条件限制。【免费下载链接】cupyNumPy SciPy for GPU项目地址: https://gitcode.com/GitHub_Trending/cu/cupy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考