ZLUDA 快速上手在未修改的 CUDA 应用上运行于非 NVIDIA GPU【免费下载链接】ZLUDACUDA on non-NVIDIA GPUs项目地址: https://gitcode.com/GitHub_Trending/zl/ZLUDAZLUDA 是一个面向非 NVIDIA GPU 的 CUDA 运行时替代层其目标是让未经修改的 CUDA 应用程序以接近原生的性能直接运行在 AMD 等 GPU 上。本文基于仓库中的快速上手文档docs/src/quick_start.md结合仓库源码完整覆盖「如何获取 ZLUDA、Windows/Linux 下两种注入方式的区别、从源码构建到环境验证」的全部实操路径。读完本文你应当能在 Windows 或 Linux 上把任意 CUDA 应用接入 ZLUDA并通过cuda_check验证各性能库cuBLAS、cuDNN、cuFFT、cuSPARSE、NVML的加载是否成功。官方文档给出的警告值得原样保留当前版本的 ZLUDA 仍处于高强度开发阶段很可能还无法直接运行你的应用。官方鼓励尝试并向社区反馈结果——也就是说本文介绍的方法适用于探索与调试而非生产环境承诺。一、如何获取 ZLUDAZLUDA 迭代非常快官方推荐始终使用最新的预发布版本pre-release项目方会周期性地把某个预发布版本标记为稳定版均可从官方 GitHub 仓库的 Releases 区域下载。预编译包解压后有一个zluda目录里面包含了 ZLUDA 提供的libcuda.soLinux或nvcuda.dllWindows等全部组件而从源码构建得到的产物则位于target/release目录。后文所有占位符ZLUDA_DIRECTORY指的就是这两个目录之一。从源码构建构建预编译包之外的路径如果你需要自行构建例如想使用最新提交构建依赖与步骤记录在 docs/src/building.md依赖Git、CMake、Python 3、较新版本的 Rust 编译器、C 编译器仅 Linux需要安装 HIPROCm可选但推荐Ninja 构建系统。构建步骤只有两条命令git clone --recursive https://gitcode.com/GitHub_Trending/zl/ZLUDA cd ZLUDA cargo xtask --release # Release 构建 cargo xtask # Debug 构建注意--recursive是必须的用于拉取子模块。构建入口是工作区中的 xtask从源码结构看它做的事情包括通过 cargo metadata 枚举所有带package.metadata.zluda段的项目每个 crate 的Cargo.toml中声明自己是 cdylib 还是 bin、是否为 32/64 位、Linux 符号链接等过滤掉与当前平台/位宽不匹配的项目后调用cargo build --locked --package ...编译在target/profile下创建符号链接例如 zluda/Cargo.toml 中声明linux_symlinks [libcuda.so, libcuda.so.1]因此最终libcuda.so、libcuda.so.1都指向真正的产物文件——这正是「把target/release当作ZLUDA_DIRECTORY用」能生效的原因Linux 构建还会调用patchelf --replace-needed把二进制中 DT_NEEDED 里带版本号的libamdhip64.so.6/.7、librocblas.so.4/.5等替换为无版本号形式从而同时兼容 ROCm 6 与 ROCm 7见strip_rocm_versions_from_dt_neededxtask/src/main.rs。cargo xtask zip则会在上述基础上生成发布包Linux 为zluda.tar.gzWindows 为zluda.zip其内容布局与官方预编译包一致。二、Windows 下的使用方法前置条件安装较新的 AMD GPU 驱动AMD Software: Adrenalin Edition安装HIP SDK详见 docs/src/hip_sdk.md。官方 SDK 安装简单且受 AMD 支持但代码较旧、不含 MIOpen即没有 cuDNN 支持每日构建nightly的 HIP SDK 代码更新、支持机器学习框架PyTorch/TF 需要它但需手动安装并设置HIP_PATH环境变量。方法一官方推荐使用 ZLUDA 启动器ZLUDA_DIRECTORY\zluda.exe -- APPLICATION APPLICATION_ARGUMENTSzluda.exe是 zluda_inject crate 编译出的二进制它并不是简单转发参数而是实现了完整的进程级 DLL 注入。从 zluda_inject/src/bin.rs 的实现看其流程是调用DetourCreateProcessWithDllsW以CREATE_SUSPENDED标志挂起状态创建目标进程依赖 ext/detours 中随仓库自带的 Microsoft Detours 库通过DetourCopyPayloadToProcess把每个 CUDA 替身 DLL 的完整路径作为「payload」写入目标进程再由随进程注入的zluda_redirect.dll在目标进程内部真正加载这些替身 DLL注入完成后ResumeThread恢复进程等待其退出并把子进程的退出码原样传播给调用者GetExitCodeProcessprocess::exit同时向子进程环境写入TORCH_CUDNN_V8_API_DISABLED1若用户未显式设置这是为规避 PyTorch 在 cuDNN v8 API 上的兼容性问题。启动器还支持若干配置开关解析逻辑在 zluda_inject/src/args.rs单元测试fail_on_duplicate_config_sets等也印证了这些行为开关作用--zluda将 CUDA 调用重定向到 ZLUDA默认值可省略--zluda-trace重定向到 ZLUDA 的 trace 库日志写入系统临时目录下的zluda子目录--nvidia-trace不替换为 ZLUDA而是拦截 NVIDIA 原生 CUDA 调用并记录日志用于对比调试--libPATH自定义模式逐库指定替身 DLL 路径如--nvcudaC:\path\to\nvcuda.dll --cusparseC:\path\to\sparse.dll出现未知库名如--cufoobar会直接报错--libPATH的可选库名由zluda_windows::LIBRARIES表驱动覆盖nvcuda、cublas、cublaslt、cudnn、cufft、cusparse、nvml等全部替身库lib与PATH等号连接、以 Windows 风格书写。方法二直接把 DLL 拷到应用目录如果不使用启动器可以把 ZLUDA 的全部文件包括nvcuda.dll从zluda预编译包或target\release源码构建复制到应用加载 CUDA 的路径下。各应用的加载路径不同但通常就是.exe所在的目录。这种方式适用于无法修改启动命令的场景如某些游戏或启动器代价是你需要为每个应用单独维护一份 DLL 副本且更新 ZLUDA 时要同步复制。三、Linux 下的使用方法Linux 上有两种注入方式均无需 root 权限、无需修改应用本身。方法一推荐LD_LIBRARY_PATHLD_LIBRARY_PATHZLUDA_DIRECTORY:$LD_LIBRARY_PATH APPLICATION APPLICATION_ARGUMENTS其中ZLUDA_DIRECTORY是包含 ZLUDA 提供的libcuda.so的目录预编译包对应zluda源码构建对应target/release。其原理是动态链接器在解析libcuda.so.1、libcublas.so.12等 SONAME 时会优先在LD_LIBRARY_PATH列出的目录中查找于是加载到的全部是 ZLUDA 的同名替身库。由于 zluda/Cargo.toml 声明了libcuda.so/libcuda.so.1的符号链接且构建时会生成它们替身库与 NVIDIA 的 SONAME 完全同名应用无需任何改动。方法二LD_AUDITLD_AUDITZLUDA_DIRECTORY/zluda_ld:$LD_AUDIT APPLICATION APPLICATION_ARGUMENTSLD_AUDIT是 glibc 提供的审计接口加载的审计库可以拦截并改写所有dlopen路径解析。ZLUDA 对应实现了 zluda_ld crate从源码看它的工作方式是实现la_version/la_objsearch/la_objopen三个标准符号la_objsearch在每次库加载时检查请求的库名是否命中一张23 项重定向表FILES_FOR_REDIRECT涵盖libcuda.so/libcuda.so.1、libcublas.so.11/12/13、libcublasLt.so.*、libcudnn.so.8/9、libcufft.so.10/11/12、libcusparse.so.11/12/13、libnvidia-ml.so.1等全部版本后缀——这正是LD_LIBRARY_PATH方式能覆盖的同一组库命中时把路径改写为审计库自身所在目录下的同名文件。审计库通过dl_iterate_phdr遍历已加载对象找到名为zluda_ld的库来确定自身位置源码注释解释了为何不用更简单的dladdr其在 Ubuntu 22.04 上会段错误而在 24.04 上正常用一组「cookie」记录已经过重定向的加载源防止 ZLUDA 自己的库再去加载真实的 NVIDIA/AMD 库时形成自引用环例如zluda_trace_blas作为libcuda.so加载后还需要加载真正的底层库。两种方式的选择建议LD_LIBRARY_PATH简单直接适合大多数场景LD_AUDIT方式不污染全局库搜索路径对依赖严格DT_NEEDED解析顺序的应用更稳妥。macOS官方文档明确不支持。四、验证环境cuda_check安装 HIP SDK尤其是 Windows 手动安装的 nightly 版本后官方建议运行仓库自带的验证程序 cuda_check它是一个小型 CUDA 应用测试加载并初始化全部性能库zluda.exe -- cuda_check.exe正常输出形如nvcuda : OK (C:\hip_sdk\bin\amdhip64_7.dll) nvml : OK cufft11 : OK cudnn9 : OK (C:\hip_sdk\bin\MIOpen.dll) cudnn8 : OK (C:\hip_sdk\bin\MIOpen.dll) cublaslt13: OK (C:\hip_sdk\bin\libhipblaslt.dll) cusparse12: OK cufft12 : OK cublas13 : OK (C:\hip_sdk\bin\rocblas.dll) cublaslt12: OK (C:\hip_sdk\bin\libhipblaslt.dll) cublas12 : OK (C:\hip_sdk\bin\rocblas.dll) cusparse11: OK括号中的路径是对应的 HIP SDK 底层库。三点已知的注意事项来自 docs/src/hip_sdk.md括号内路径不保证就是最终使用的库——如果应用在 ZLUDA 之前已从其他路径加载了同名库ZLUDA 会直接复用已加载的那份cuda_check.exe偶尔会因 MIOpen 的一个 bug 挂起不退出使用官方非 nightlyHIP SDK 时cudnn8/cudnn9会加载失败因为官方 SDK 不含 MIOpen。五、进阶预编译 GPU 代码缓存跑大型应用时首次启动的大部分时间往往花在 PTX 即时编译上。仓库提供了 zluda_precompile 工具说明见 docs/src/precompiling.mdzluda_precompile.exe PATH # Windows zluda_precompile PATH # Linux它会扫描指定目录/文件中的全部 GPU 代码、编译并写入缓存SQLite见 zluda_cache使应用首次启动时 GPU 代码已在缓存中。文档也客观提示了取舍它占用机器全部线程速度通常快于让应用自己编译但可能编译了应用实际不需要的代码总量上未必更省——两种方案各有胜算。六、小结获取官方 Releases 的最新 pre-release或标为 stable 的版本源码构建则git clone --recursive后cargo xtask --release产物在target/release。Windows前置安装 AMD 驱动 HIP SDK推荐zluda.exe -- APP ARGS启动器进程挂起注入 payload 传路径 退出码透传或直接复制nvcuda.dll等全部 DLL 到应用目录。Linux推荐LD_LIBRARY_PATH前置 ZLUDA 目录备选LD_AUDIT.../zluda_ld基于 glibc 审计钩子做逐库路径重定向。macOS 不支持。验证zluda.exe -- cuda_check.exe逐项确认各库 OK大型应用可用zluda_precompile预热缓存。预期管理项目仍在快速开发中遇到应用不工作是常态而非个例建议按仓库文档反馈问题。文中引用的关键源码位置启动器参数解析 zluda_inject/src/args.rs、注入流程 zluda_inject/src/bin.rs、LD_AUDIT 重定向 zluda_ld/src/lib.rs、构建与打包 xtask/src/main.rs、核心运行时入口 zluda/src/lib.rs、验证程序 cuda_check/src/main.rs。【免费下载链接】ZLUDACUDA on non-NVIDIA GPUs项目地址: https://gitcode.com/GitHub_Trending/zl/ZLUDA创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/14 18:58:11 · 阅读 1.2k ZLUDA 快速上手：在未修改的 CUDA 应用上运行于非 NVIDIA GPU
ZLUDA 快速上手在未修改的 CUDA 应用上运行于非 NVIDIA GPU【免费下载链接】ZLUDACUDA on non-NVIDIA GPUs项目地址: https://gitcode.com/GitHub_Trending/zl/ZLUDAZLUDA 是一个面向非 NVIDIA GPU 的 CUDA 运行时替代层其目标是让未经修改的 CUDA 应用程序以接近原生的性能直接运行在 AMD 等 GPU 上。本文基于仓库中的快速上手文档docs/src/quick_start.md结合仓库源码完整覆盖「如何获取 ZLUDA、Windows/Linux 下两种注入方式的区别、从源码构建到环境验证」的全部实操路径。读完本文你应当能在 Windows 或 Linux 上把任意 CUDA 应用接入 ZLUDA并通过cuda_check验证各性能库cuBLAS、cuDNN、cuFFT、cuSPARSE、NVML的加载是否成功。官方文档给出的警告值得原样保留当前版本的 ZLUDA 仍处于高强度开发阶段很可能还无法直接运行你的应用。官方鼓励尝试并向社区反馈结果——也就是说本文介绍的方法适用于探索与调试而非生产环境承诺。一、如何获取 ZLUDAZLUDA 迭代非常快官方推荐始终使用最新的预发布版本pre-release项目方会周期性地把某个预发布版本标记为稳定版均可从官方 GitHub 仓库的 Releases 区域下载。预编译包解压后有一个zluda目录里面包含了 ZLUDA 提供的libcuda.soLinux或nvcuda.dllWindows等全部组件而从源码构建得到的产物则位于target/release目录。后文所有占位符ZLUDA_DIRECTORY指的就是这两个目录之一。从源码构建构建预编译包之外的路径如果你需要自行构建例如想使用最新提交构建依赖与步骤记录在 docs/src/building.md依赖Git、CMake、Python 3、较新版本的 Rust 编译器、C 编译器仅 Linux需要安装 HIPROCm可选但推荐Ninja 构建系统。构建步骤只有两条命令git clone --recursive https://gitcode.com/GitHub_Trending/zl/ZLUDA cd ZLUDA cargo xtask --release # Release 构建 cargo xtask # Debug 构建注意--recursive是必须的用于拉取子模块。构建入口是工作区中的 xtask从源码结构看它做的事情包括通过 cargo metadata 枚举所有带package.metadata.zluda段的项目每个 crate 的Cargo.toml中声明自己是 cdylib 还是 bin、是否为 32/64 位、Linux 符号链接等过滤掉与当前平台/位宽不匹配的项目后调用cargo build --locked --package ...编译在target/profile下创建符号链接例如 zluda/Cargo.toml 中声明linux_symlinks [libcuda.so, libcuda.so.1]因此最终libcuda.so、libcuda.so.1都指向真正的产物文件——这正是「把target/release当作ZLUDA_DIRECTORY用」能生效的原因Linux 构建还会调用patchelf --replace-needed把二进制中 DT_NEEDED 里带版本号的libamdhip64.so.6/.7、librocblas.so.4/.5等替换为无版本号形式从而同时兼容 ROCm 6 与 ROCm 7见strip_rocm_versions_from_dt_neededxtask/src/main.rs。cargo xtask zip则会在上述基础上生成发布包Linux 为zluda.tar.gzWindows 为zluda.zip其内容布局与官方预编译包一致。二、Windows 下的使用方法前置条件安装较新的 AMD GPU 驱动AMD Software: Adrenalin Edition安装HIP SDK详见 docs/src/hip_sdk.md。官方 SDK 安装简单且受 AMD 支持但代码较旧、不含 MIOpen即没有 cuDNN 支持每日构建nightly的 HIP SDK 代码更新、支持机器学习框架PyTorch/TF 需要它但需手动安装并设置HIP_PATH环境变量。方法一官方推荐使用 ZLUDA 启动器ZLUDA_DIRECTORY\zluda.exe -- APPLICATION APPLICATION_ARGUMENTSzluda.exe是 zluda_inject crate 编译出的二进制它并不是简单转发参数而是实现了完整的进程级 DLL 注入。从 zluda_inject/src/bin.rs 的实现看其流程是调用DetourCreateProcessWithDllsW以CREATE_SUSPENDED标志挂起状态创建目标进程依赖 ext/detours 中随仓库自带的 Microsoft Detours 库通过DetourCopyPayloadToProcess把每个 CUDA 替身 DLL 的完整路径作为「payload」写入目标进程再由随进程注入的zluda_redirect.dll在目标进程内部真正加载这些替身 DLL注入完成后ResumeThread恢复进程等待其退出并把子进程的退出码原样传播给调用者GetExitCodeProcessprocess::exit同时向子进程环境写入TORCH_CUDNN_V8_API_DISABLED1若用户未显式设置这是为规避 PyTorch 在 cuDNN v8 API 上的兼容性问题。启动器还支持若干配置开关解析逻辑在 zluda_inject/src/args.rs单元测试fail_on_duplicate_config_sets等也印证了这些行为开关作用--zluda将 CUDA 调用重定向到 ZLUDA默认值可省略--zluda-trace重定向到 ZLUDA 的 trace 库日志写入系统临时目录下的zluda子目录--nvidia-trace不替换为 ZLUDA而是拦截 NVIDIA 原生 CUDA 调用并记录日志用于对比调试--libPATH自定义模式逐库指定替身 DLL 路径如--nvcudaC:\path\to\nvcuda.dll --cusparseC:\path\to\sparse.dll出现未知库名如--cufoobar会直接报错--libPATH的可选库名由zluda_windows::LIBRARIES表驱动覆盖nvcuda、cublas、cublaslt、cudnn、cufft、cusparse、nvml等全部替身库lib与PATH等号连接、以 Windows 风格书写。方法二直接把 DLL 拷到应用目录如果不使用启动器可以把 ZLUDA 的全部文件包括nvcuda.dll从zluda预编译包或target\release源码构建复制到应用加载 CUDA 的路径下。各应用的加载路径不同但通常就是.exe所在的目录。这种方式适用于无法修改启动命令的场景如某些游戏或启动器代价是你需要为每个应用单独维护一份 DLL 副本且更新 ZLUDA 时要同步复制。三、Linux 下的使用方法Linux 上有两种注入方式均无需 root 权限、无需修改应用本身。方法一推荐LD_LIBRARY_PATHLD_LIBRARY_PATHZLUDA_DIRECTORY:$LD_LIBRARY_PATH APPLICATION APPLICATION_ARGUMENTS其中ZLUDA_DIRECTORY是包含 ZLUDA 提供的libcuda.so的目录预编译包对应zluda源码构建对应target/release。其原理是动态链接器在解析libcuda.so.1、libcublas.so.12等 SONAME 时会优先在LD_LIBRARY_PATH列出的目录中查找于是加载到的全部是 ZLUDA 的同名替身库。由于 zluda/Cargo.toml 声明了libcuda.so/libcuda.so.1的符号链接且构建时会生成它们替身库与 NVIDIA 的 SONAME 完全同名应用无需任何改动。方法二LD_AUDITLD_AUDITZLUDA_DIRECTORY/zluda_ld:$LD_AUDIT APPLICATION APPLICATION_ARGUMENTSLD_AUDIT是 glibc 提供的审计接口加载的审计库可以拦截并改写所有dlopen路径解析。ZLUDA 对应实现了 zluda_ld crate从源码看它的工作方式是实现la_version/la_objsearch/la_objopen三个标准符号la_objsearch在每次库加载时检查请求的库名是否命中一张23 项重定向表FILES_FOR_REDIRECT涵盖libcuda.so/libcuda.so.1、libcublas.so.11/12/13、libcublasLt.so.*、libcudnn.so.8/9、libcufft.so.10/11/12、libcusparse.so.11/12/13、libnvidia-ml.so.1等全部版本后缀——这正是LD_LIBRARY_PATH方式能覆盖的同一组库命中时把路径改写为审计库自身所在目录下的同名文件。审计库通过dl_iterate_phdr遍历已加载对象找到名为zluda_ld的库来确定自身位置源码注释解释了为何不用更简单的dladdr其在 Ubuntu 22.04 上会段错误而在 24.04 上正常用一组「cookie」记录已经过重定向的加载源防止 ZLUDA 自己的库再去加载真实的 NVIDIA/AMD 库时形成自引用环例如zluda_trace_blas作为libcuda.so加载后还需要加载真正的底层库。两种方式的选择建议LD_LIBRARY_PATH简单直接适合大多数场景LD_AUDIT方式不污染全局库搜索路径对依赖严格DT_NEEDED解析顺序的应用更稳妥。macOS官方文档明确不支持。四、验证环境cuda_check安装 HIP SDK尤其是 Windows 手动安装的 nightly 版本后官方建议运行仓库自带的验证程序 cuda_check它是一个小型 CUDA 应用测试加载并初始化全部性能库zluda.exe -- cuda_check.exe正常输出形如nvcuda : OK (C:\hip_sdk\bin\amdhip64_7.dll) nvml : OK cufft11 : OK cudnn9 : OK (C:\hip_sdk\bin\MIOpen.dll) cudnn8 : OK (C:\hip_sdk\bin\MIOpen.dll) cublaslt13: OK (C:\hip_sdk\bin\libhipblaslt.dll) cusparse12: OK cufft12 : OK cublas13 : OK (C:\hip_sdk\bin\rocblas.dll) cublaslt12: OK (C:\hip_sdk\bin\libhipblaslt.dll) cublas12 : OK (C:\hip_sdk\bin\rocblas.dll) cusparse11: OK括号中的路径是对应的 HIP SDK 底层库。三点已知的注意事项来自 docs/src/hip_sdk.md括号内路径不保证就是最终使用的库——如果应用在 ZLUDA 之前已从其他路径加载了同名库ZLUDA 会直接复用已加载的那份cuda_check.exe偶尔会因 MIOpen 的一个 bug 挂起不退出使用官方非 nightlyHIP SDK 时cudnn8/cudnn9会加载失败因为官方 SDK 不含 MIOpen。五、进阶预编译 GPU 代码缓存跑大型应用时首次启动的大部分时间往往花在 PTX 即时编译上。仓库提供了 zluda_precompile 工具说明见 docs/src/precompiling.mdzluda_precompile.exe PATH # Windows zluda_precompile PATH # Linux它会扫描指定目录/文件中的全部 GPU 代码、编译并写入缓存SQLite见 zluda_cache使应用首次启动时 GPU 代码已在缓存中。文档也客观提示了取舍它占用机器全部线程速度通常快于让应用自己编译但可能编译了应用实际不需要的代码总量上未必更省——两种方案各有胜算。六、小结获取官方 Releases 的最新 pre-release或标为 stable 的版本源码构建则git clone --recursive后cargo xtask --release产物在target/release。Windows前置安装 AMD 驱动 HIP SDK推荐zluda.exe -- APP ARGS启动器进程挂起注入 payload 传路径 退出码透传或直接复制nvcuda.dll等全部 DLL 到应用目录。Linux推荐LD_LIBRARY_PATH前置 ZLUDA 目录备选LD_AUDIT.../zluda_ld基于 glibc 审计钩子做逐库路径重定向。macOS 不支持。验证zluda.exe -- cuda_check.exe逐项确认各库 OK大型应用可用zluda_precompile预热缓存。预期管理项目仍在快速开发中遇到应用不工作是常态而非个例建议按仓库文档反馈问题。文中引用的关键源码位置启动器参数解析 zluda_inject/src/args.rs、注入流程 zluda_inject/src/bin.rs、LD_AUDIT 重定向 zluda_ld/src/lib.rs、构建与打包 xtask/src/main.rs、核心运行时入口 zluda/src/lib.rs、验证程序 cuda_check/src/main.rs。【免费下载链接】ZLUDACUDA on non-NVIDIA GPUs项目地址: https://gitcode.com/GitHub_Trending/zl/ZLUDA创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考