llama.cpp CUDA 编译报错排查5 个根因定位与修复路径【免费下载链接】llama.cppLLM inference in C/C项目地址: https://gitcode.com/GitHub_Trending/ll/llama.cpp你刚敲下cmake -B build -DGGML_CUDAON终端吐出一串红色报错构建直接中断——llama.cpp 的 CUDA 编译卡在了环境、架构或参数上。别反复删 build 目录碰运气下面按为什么失败而不是报什么错来定位10 分钟内跑通。图 1llama.cpp 项目横幅含自定义 CUDA 内核的 LLM 推理引擎图 2llama.cpp 矩阵乘法路径示意mmq 自定义 CUDA 内核与 cuBLAS 的取舍依据nvcc 找不到的三种原因环境缺失不是 CMake 的锅CMake 只是替你调 nvcc找不到就说明它压根不在当前 shell 的环境里。典型报错# 注释这是 shell 层面报的错与项目代码无关 nvcc: command not found或 CMake 配置阶段# 注释CMake 找不到 CUDA 编译器时的标准报错 CMake Error: The following variables are used in this project, but they are set to NOTFOUND.真实原因只有一个CMake 在$PATH和常见安装路径里都没找到 CUDA Toolkit 的nvcc。分三种情况处理# 注释确认 nvcc 到底装没装预期输出 CUDA 版本如 12.4 nvcc --version如果命令直接报command not foundToolkit 没装或装了但 bin 目录不在 PATH。装了的话执行export PATH/usr/local/cuda/bin:$PATH后重跑配置。如果nvcc --version有输出但 CMake 仍 NOTFOUNDCMake 缓存了上一次的搜索失败结果rm -rf build后重新配置即可不要只删 CMakeCache 里的个别变量。如果机器上有多个 CUDA 版本用下面命令锁定其中一个配置与运行都绑定同一版本# 注释显式指定 nvcc 路径把运行时 rpath 一并锁到对应版本 cmake -B build -DGGML_CUDAON -DCMAKE_CUDA_COMPILER/opt/cuda-11.7/bin/nvcc \ -DCMAKE_INSTALL_RPATH/opt/cuda-11.7/lib64;\$ORIGIN -DCMAKE_BUILD_WITH_INSTALL_RPATHONFedora AtomicSilverblue/Kinoite主机没有受支持的 CUDA 软件源直接在宿主机装会卡死在这个阶段参考docs/backend/CUDA-FEDORA.md用 toolbox 容器把 Toolkit 装进容器宿主机只留 NVIDIA 驱动。-archnative 警告编译机检测不到你的 GPU配置能过但警告刷屏# 注释nvcc 探测不到当前架构时回退到默认架构 nvcc warning : Cannot find valid GPU for -archnative, default arch is used背后原因默认行为GGML_NATIVEON且 CUDA ≥ 11.6是拿构建时刻插着的 GPU决定目标架构。编译服务器没插显卡、容器里没透传设备、驱动没加载都会触发这条警告且回退的默认架构可能和你的显卡对不上。两条修复路径# 注释显式列出目标计算能力RTX 3080 Ti 对应 86RTX 4090 对应 89 cmake -B build -DGGML_CUDAON -DCMAKE_CUDA_ARCHITECTURES86;89常用架构值对照来自ggml/src/ggml-cuda/CMakeLists.txt的注释GPU 代际架构值最低 CUDA 版本PascalP100 等6010.xTuringRTX 20007511.0AmpereA100/RTX 300080 / 8686 需 11.1AdaRTX 40008911.8HopperH1009011.8BlackwellRTX 50 系120a12.8另一个分支如果这个二进制要发到多台不同显卡的机器上跑用cmake -B build -DGGML_CUDAON -DGGML_NATIVEOFF产物覆盖全部架构代价是编译时间和二进制体积明显增大。老 CUDA 撞上新 glibcexception specification 报错CUDA 11.x 配新系统新 glibc编译时报错长这样# 注释CUDA 11.7 头文件与新版 glibc 冲突时的典型报错 /usr/include/bits/mathcalls.h(83): error: exception specification is incompatible with that of previous function cospi /opt/cuda-11.7/bin/../targets/x86_64-linux/include/crt/math_functions.h(5545): here真实原因CUDA 11.x 的math_functions.h里cospi、rsqrt等 6 个函数声明缺少noexcept与新 glibc 的声明冲突。最干净的解法是升 CUDA 12.x。暂时不想升级的话按docs/build.md的方法给这 6 个函数补noexcept (true)// 注释替换 math_functions.h 中原声明共 6 行每行末尾加 noexcept (true) extern __DEVICE_FUNCTIONS_DECL__ __device_builtin__ double cospi(double x) noexcept (true); extern __DEVICE_FUNCTIONS_DECL__ __device_builtin__ float cospif(float x) noexcept (true); extern __DEVICE_FUNCTIONS_DECL__ __device_builtin__ double sinpi(double x) noexcept (true); extern __DEVICE_FUNCTIONS_DECL__ __device_builtin__ float sinpif(float x) noexcept (true); extern __DEVICE_FUNCTIONS_DECL__ __device_builtin__ double rsqrt(double x) noexcept (true); extern __DEVICE_FUNCTIONS_DECL__ __device_builtin__ float rsqrtf(float x) noexcept (true);文件位置/path/to/your/cuda/installation/targets/x86_64-linux/include/crt/math_functions.h。FORCE_MMQ 与 FORCE_CUBLAS参数语义冲突和多 GPU 配置矩阵乘法走哪条内核路径是二选一两个开关同时打开等于自相矛盾配置能通过但性能行为不可预期参数默认值作用适用场景GGML_CUDA_FORCE_MMQOFF强制量化模型用 mmq 自定义内核低显存设备大 batch 略慢但省 VRAMGGML_CUDA_FORCE_CUBLASOFF强制用 FP16 cuBLAS 替代自定义内核数据中心 GPUprefill 更快、显存更高GGML_CUDA_PEER_MAX_BATCH_SIZE128多 GPU peer access 的批大小上限有 NVLink 时可设为 256决策逻辑如果显卡是消费级RTX 30/40 系且显存紧张则保持默认int8 tensor core 上 mmq 默认开启否则如果显存宽裕且追求 prefill 吞吐则只开GGML_CUDA_FORCE_CUBLASON两个 FORCE 选项永远只选一个。多卡场景的运行时环境变量不用重新编译# 注释VRAM 不足时回退到系统内存避免直接崩溃 export GGML_CUDA_ENABLE_UNIFIED_MEMORY1 # 注释NVLink 多卡提升 GPU 间批处理阈值 export GGML_CUDA_PEER_MAX_BATCH_SIZE256⚠️ 统一内存只救急不提速生产部署仍应以显存够用为前提GGML_CUDA_P2P1在部分主板/BIOSIOMMU 场景会导致崩溃或输出损坏开之前确认驱动支持。验证闭环一条命令确认跑在 GPU 上# 注释跑一个短生成观察启动日志里的后端初始化信息 ./build/bin/llama-cli --model model.gguf -p hello -n 16启动日志里应出现CUDA0: 你的显卡名设备枚举行和 CUDA 后端初始化信息同时另开终端# 注释确认进程占用显存看到 llama-cli 进程名和显存占用即正常 nvidia-smi✅ 看到设备枚举 nvidia-smi 有显存占用说明修好了。如果生成时反而报no kernel image is available for execution on the device说明二进制里根本没有你这张卡的架构回到架构值一节重配如果日志里只有AVX等 CPU 行、完全没有 CUDA 行说明GGML_CUDA实际没生效检查配置阶段是否打印了CUDA Toolkit found。边界陷阱看似跑通了其实没有⚠️改了参数但 CMake 缓存没变。-DCMAKE_CUDA_ARCHITECTURES等选项在 CMakeCache.txt 里有残留只重跑cmake --build不会重新取新值。改任何-D选项后必须rm -rf build重新配置否则你会拿着旧架构的二进制怀疑人生。⚠️编译机和运行机不是同一台。native只针对构建时刻插着的 GPU在无 GPU 的构建服务器上CMake 拿到的 native 架构列表是无效值ggml-cuda的 CMakeLists 里对此有专门防护但你若手动指定了错误架构值则不会拦截。交付给他人或跨机部署一律显式列架构或GGML_NATIVEOFF。⚠️容器里的设备映射。Docker 跑 CUDA 必须加--gpus all或nvidia-docker运行时容器内nvcc --version正常但nvidia-smi看不到卡是缺设备映射不是缺 ToolkitCUDA_VISIBLE_DEVICES在容器内外各映射一次索引含义不同排查时先看容器内的nvidia-smi -L。仍卡住的话把完整的cmake -B build配置段输出和启动日志前 50 行贴出来对照docs/build.md的 CUDA 章节逐条核对或在项目讨论区搜索同样的报错原文绝大多数情况能找到现成解法。【免费下载链接】llama.cppLLM inference in C/C项目地址: https://gitcode.com/GitHub_Trending/ll/llama.cpp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 llama.cpp CUDA 编译报错排查：5 个根因定位与修复路径
llama.cpp CUDA 编译报错排查5 个根因定位与修复路径【免费下载链接】llama.cppLLM inference in C/C项目地址: https://gitcode.com/GitHub_Trending/ll/llama.cpp你刚敲下cmake -B build -DGGML_CUDAON终端吐出一串红色报错构建直接中断——llama.cpp 的 CUDA 编译卡在了环境、架构或参数上。别反复删 build 目录碰运气下面按为什么失败而不是报什么错来定位10 分钟内跑通。图 1llama.cpp 项目横幅含自定义 CUDA 内核的 LLM 推理引擎图 2llama.cpp 矩阵乘法路径示意mmq 自定义 CUDA 内核与 cuBLAS 的取舍依据nvcc 找不到的三种原因环境缺失不是 CMake 的锅CMake 只是替你调 nvcc找不到就说明它压根不在当前 shell 的环境里。典型报错# 注释这是 shell 层面报的错与项目代码无关 nvcc: command not found或 CMake 配置阶段# 注释CMake 找不到 CUDA 编译器时的标准报错 CMake Error: The following variables are used in this project, but they are set to NOTFOUND.真实原因只有一个CMake 在$PATH和常见安装路径里都没找到 CUDA Toolkit 的nvcc。分三种情况处理# 注释确认 nvcc 到底装没装预期输出 CUDA 版本如 12.4 nvcc --version如果命令直接报command not foundToolkit 没装或装了但 bin 目录不在 PATH。装了的话执行export PATH/usr/local/cuda/bin:$PATH后重跑配置。如果nvcc --version有输出但 CMake 仍 NOTFOUNDCMake 缓存了上一次的搜索失败结果rm -rf build后重新配置即可不要只删 CMakeCache 里的个别变量。如果机器上有多个 CUDA 版本用下面命令锁定其中一个配置与运行都绑定同一版本# 注释显式指定 nvcc 路径把运行时 rpath 一并锁到对应版本 cmake -B build -DGGML_CUDAON -DCMAKE_CUDA_COMPILER/opt/cuda-11.7/bin/nvcc \ -DCMAKE_INSTALL_RPATH/opt/cuda-11.7/lib64;\$ORIGIN -DCMAKE_BUILD_WITH_INSTALL_RPATHONFedora AtomicSilverblue/Kinoite主机没有受支持的 CUDA 软件源直接在宿主机装会卡死在这个阶段参考docs/backend/CUDA-FEDORA.md用 toolbox 容器把 Toolkit 装进容器宿主机只留 NVIDIA 驱动。-archnative 警告编译机检测不到你的 GPU配置能过但警告刷屏# 注释nvcc 探测不到当前架构时回退到默认架构 nvcc warning : Cannot find valid GPU for -archnative, default arch is used背后原因默认行为GGML_NATIVEON且 CUDA ≥ 11.6是拿构建时刻插着的 GPU决定目标架构。编译服务器没插显卡、容器里没透传设备、驱动没加载都会触发这条警告且回退的默认架构可能和你的显卡对不上。两条修复路径# 注释显式列出目标计算能力RTX 3080 Ti 对应 86RTX 4090 对应 89 cmake -B build -DGGML_CUDAON -DCMAKE_CUDA_ARCHITECTURES86;89常用架构值对照来自ggml/src/ggml-cuda/CMakeLists.txt的注释GPU 代际架构值最低 CUDA 版本PascalP100 等6010.xTuringRTX 20007511.0AmpereA100/RTX 300080 / 8686 需 11.1AdaRTX 40008911.8HopperH1009011.8BlackwellRTX 50 系120a12.8另一个分支如果这个二进制要发到多台不同显卡的机器上跑用cmake -B build -DGGML_CUDAON -DGGML_NATIVEOFF产物覆盖全部架构代价是编译时间和二进制体积明显增大。老 CUDA 撞上新 glibcexception specification 报错CUDA 11.x 配新系统新 glibc编译时报错长这样# 注释CUDA 11.7 头文件与新版 glibc 冲突时的典型报错 /usr/include/bits/mathcalls.h(83): error: exception specification is incompatible with that of previous function cospi /opt/cuda-11.7/bin/../targets/x86_64-linux/include/crt/math_functions.h(5545): here真实原因CUDA 11.x 的math_functions.h里cospi、rsqrt等 6 个函数声明缺少noexcept与新 glibc 的声明冲突。最干净的解法是升 CUDA 12.x。暂时不想升级的话按docs/build.md的方法给这 6 个函数补noexcept (true)// 注释替换 math_functions.h 中原声明共 6 行每行末尾加 noexcept (true) extern __DEVICE_FUNCTIONS_DECL__ __device_builtin__ double cospi(double x) noexcept (true); extern __DEVICE_FUNCTIONS_DECL__ __device_builtin__ float cospif(float x) noexcept (true); extern __DEVICE_FUNCTIONS_DECL__ __device_builtin__ double sinpi(double x) noexcept (true); extern __DEVICE_FUNCTIONS_DECL__ __device_builtin__ float sinpif(float x) noexcept (true); extern __DEVICE_FUNCTIONS_DECL__ __device_builtin__ double rsqrt(double x) noexcept (true); extern __DEVICE_FUNCTIONS_DECL__ __device_builtin__ float rsqrtf(float x) noexcept (true);文件位置/path/to/your/cuda/installation/targets/x86_64-linux/include/crt/math_functions.h。FORCE_MMQ 与 FORCE_CUBLAS参数语义冲突和多 GPU 配置矩阵乘法走哪条内核路径是二选一两个开关同时打开等于自相矛盾配置能通过但性能行为不可预期参数默认值作用适用场景GGML_CUDA_FORCE_MMQOFF强制量化模型用 mmq 自定义内核低显存设备大 batch 略慢但省 VRAMGGML_CUDA_FORCE_CUBLASOFF强制用 FP16 cuBLAS 替代自定义内核数据中心 GPUprefill 更快、显存更高GGML_CUDA_PEER_MAX_BATCH_SIZE128多 GPU peer access 的批大小上限有 NVLink 时可设为 256决策逻辑如果显卡是消费级RTX 30/40 系且显存紧张则保持默认int8 tensor core 上 mmq 默认开启否则如果显存宽裕且追求 prefill 吞吐则只开GGML_CUDA_FORCE_CUBLASON两个 FORCE 选项永远只选一个。多卡场景的运行时环境变量不用重新编译# 注释VRAM 不足时回退到系统内存避免直接崩溃 export GGML_CUDA_ENABLE_UNIFIED_MEMORY1 # 注释NVLink 多卡提升 GPU 间批处理阈值 export GGML_CUDA_PEER_MAX_BATCH_SIZE256⚠️ 统一内存只救急不提速生产部署仍应以显存够用为前提GGML_CUDA_P2P1在部分主板/BIOSIOMMU 场景会导致崩溃或输出损坏开之前确认驱动支持。验证闭环一条命令确认跑在 GPU 上# 注释跑一个短生成观察启动日志里的后端初始化信息 ./build/bin/llama-cli --model model.gguf -p hello -n 16启动日志里应出现CUDA0: 你的显卡名设备枚举行和 CUDA 后端初始化信息同时另开终端# 注释确认进程占用显存看到 llama-cli 进程名和显存占用即正常 nvidia-smi✅ 看到设备枚举 nvidia-smi 有显存占用说明修好了。如果生成时反而报no kernel image is available for execution on the device说明二进制里根本没有你这张卡的架构回到架构值一节重配如果日志里只有AVX等 CPU 行、完全没有 CUDA 行说明GGML_CUDA实际没生效检查配置阶段是否打印了CUDA Toolkit found。边界陷阱看似跑通了其实没有⚠️改了参数但 CMake 缓存没变。-DCMAKE_CUDA_ARCHITECTURES等选项在 CMakeCache.txt 里有残留只重跑cmake --build不会重新取新值。改任何-D选项后必须rm -rf build重新配置否则你会拿着旧架构的二进制怀疑人生。⚠️编译机和运行机不是同一台。native只针对构建时刻插着的 GPU在无 GPU 的构建服务器上CMake 拿到的 native 架构列表是无效值ggml-cuda的 CMakeLists 里对此有专门防护但你若手动指定了错误架构值则不会拦截。交付给他人或跨机部署一律显式列架构或GGML_NATIVEOFF。⚠️容器里的设备映射。Docker 跑 CUDA 必须加--gpus all或nvidia-docker运行时容器内nvcc --version正常但nvidia-smi看不到卡是缺设备映射不是缺 ToolkitCUDA_VISIBLE_DEVICES在容器内外各映射一次索引含义不同排查时先看容器内的nvidia-smi -L。仍卡住的话把完整的cmake -B build配置段输出和启动日志前 50 行贴出来对照docs/build.md的 CUDA 章节逐条核对或在项目讨论区搜索同样的报错原文绝大多数情况能找到现成解法。【免费下载链接】llama.cppLLM inference in C/C项目地址: https://gitcode.com/GitHub_Trending/ll/llama.cpp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考