ZLUDA 入门：在 AMD GPU 上跑通未经修改的 CUDA 应用（附环境自检与排错清单）-编程实验室

ZLUDA 入门：在 AMD GPU 上跑通未经修改的 CUDA 应用（附环境自检与排错清单）

【免费下载链接】ZLUDACUDA on non-NVIDIA GPUs项目地址: https://gitcode.com/GitHub_Trending/zl/ZLUDA

手上只有 AMD 显卡，却需要跑为 NVIDIA 编译的 CUDA 应用（比如 CUDA 版 llama.cpp）？ZLUDA 就是为此设计的：它是 CUDA 在非 NVIDIA GPU 上的 drop-in 替换，运行时拦截 CUDA API 调用，再由自带的 PTX 编译器把内核代码编译到目标 GPU 上执行。

项目定位与适用场景

ZLUDA 用 Rust 实现了一套完整的 CUDA 驱动替代层：对外提供libcuda.so/nvcuda.dll接口，内部通过自研 PTX 编译器把内核代码编译到目标架构，并借助 HIP/ROCm 落地执行。

在 AMD GPU 上运行 CUDA 版 llama.cpp
验证 CUDA 程序在 NVIDIA 之外硬件的兼容性
用 trace 工具录制 CUDA API 调用序列
预编译内核代码，缩短应用首次启动时间

环境自检清单

检查项	最低要求	推荐
操作系统	Windows 或主流 Linux 发行版（macOS 不支持）	—
GPU	AMD Radeon RX 5000 系列（RDNA2）及更新的桌面/核显	RX 6000 系列及以上
GPU 驱动	较新版本 AMD 显卡驱动（Adrenalin Edition）	发布前最新的驱动版本
HIP/ROCm	Windows：官方 HIP SDK；Linux：ROCm HIP	Nightly HIP SDK（含 MIOpen，ML 场景必需）
编译依赖（仅源码构建）	Git、CMake、Python 3、较新版本 Rust、C++ 编译器	另装 Ninja

注意两点：Polaris、Vega 等老架构与服务器级 GPU 不支持；Intel GPU 目前不在支持范围内（项目当前聚焦 AMD 后端）。驱动或 SDK 版本不满足时，到 AMD 官方下载页获取最新的显卡驱动与 HIP SDK。

安装实录（分步）

Step 1：获取 ZLUDA

优先从 Releases 页下载最近的预编译包（项目迭代快，会定期把某个 pre-release 标记为 stable）。也可以源码构建，注意必须带--recursive拉取子模块：

git clone --recursive https://gitcode.com/GitHub_Trending/zl/ZLUDA

进入目录后执行cargo xtask --release（Release）或cargo xtask（Debug），耗时较长；产物在target/release/。

Step 2：安装驱动与 HIP SDK

Windows：先装 AMD 显卡驱动，再装 HIP SDK。跑 PyTorch/TensorFlow 等 ML 应用需要 nightly HIP SDK：下载therock-dist-windows-gfx<GPUARCH>...tar.gz解压，把HIP_PATH环境变量指向解压目录（其bin子目录里需有rocblas.dll等文件；<GPUARCH>可用包内hipInfo.exe查询）。

Linux：按 ROCm 官方说明安装 HIP 即可。

Step 3：运行应用

Windows（推荐启动器方式）：

<ZLUDA_DIRECTORY>\zluda.exe -- <应用程序> <参数>

也可以把 ZLUDA 全部文件（含nvcuda.dll）复制到应用加载 CUDA 的路径（通常是 exe 所在目录）。

Linux（推荐）：

LD_LIBRARY_PATH="<ZLUDA_DIRECTORY>:$LD_LIBRARY_PATH" <应用程序> <参数>

替代方式为LD_AUDIT="<ZLUDA_DIRECTORY>/zluda_ld:$LD_AUDIT"前缀。<ZLUDA_DIRECTORY>指预编译包中libcuda.so所在目录（源码构建则为target/release）。

上图为实际用法之一：在 Steam 启动项里填zluda.exe -- %command%，即可让游戏以 ZLUDA 驱动启动。

验证与高频排错

验证方式：运行 ZLUDA 自带的cuda_check（Windows 下zluda.exe -- cuda_check.exe，Linux 下用上面的LD_LIBRARY_PATH方式运行cuda_check）。输出中nvcuda、cublas13、cudnn9等条目均为OK并附底层 HIP 库路径，即环境就绪。

Q：cuda_check报cudnn8/cudnn9加载失败A：官方 HIP SDK 不含 MIOpen，属已知限制。改用 nightly HIP SDK 并正确设置HIP_PATH后重跑cuda_check确认。

Q：应用能启动但内核执行失败，提示某条 PTX 指令不被识别A：当前版本仍在快速迭代中，PTX 编译器未覆盖全部指令。先用 trace 录制调用序列定位问题指令：

zluda.exe --zluda-trace -- <应用程序>

日志目录：Windows 在%TEMP%\zluda；Linux 设ZLUDA_LOG_DIR（如/tmp/zluda），目录内含log.txt与module_*.ptx。

Q：大型应用首次启动很慢（内核现场 JIT 编译）A：先用zluda_precompile <PATH>扫描并预编译目录下的 GPU 代码写入缓存；它占满所有线程，但也可能编译多余代码，效果因应用而异。

进阶技巧与调优参数

llama.cpp 建议以-DGGML_CUDA=ON -DCMAKE_CUDA_ARCHITECTURES="86" -DGGML_CUDA_FORCE_CUBLAS=true编译可获得接近原生的速度；多架构编译时须包含 80/86/89 之一，关闭 cuBLAS 会明显降速。
预编译用zluda_precompile <PATH>（Windows 为zluda_precompile.exe），路径可以是目录或单个文件。
录制日志时 Linux 同时设置ZLUDA_CUDA_LIB=<ZLUDA_DIRECTORY>/libcuda.so，否则 trace 会落到 NVIDIA 驱动而非 ZLUDA。
若cuda_check显示的 HIP 库路径与你的HIP_PATH不一致，说明应用提前从其他路径加载了同名库，ZLUDA 会复用已加载的那个——检查应用目录下的库文件。
ZLUDA 处于重度开发期，部分应用可能跑不通；跑前先试最新 pre-release，不行再用 trace 记录后反馈。