1. 为什么 Jetson AGX Orin 上跑 llama.cpp 需要专门做 CUDA 环境对齐Jetson AGX Orin 是一块很有意思的板子。它跟桌面级显卡最大的区别在于GPU 和 CPU 共享同一块物理内存CUDA 架构是 ARM64 下的sm_87系统层面用的是 NVIDIA 自家维护的 JetPack SDK而不是你在 Ubuntu 上习惯的那套apt install nvidia-cuda-toolkit。这就导致一个很现实的问题——很多在 x86 服务器上跑得好好的 llama.cpp 编译流程搬到 Orin 上就会在 CMake 配置阶段或者链接阶段直接翻车。llama.cpp 本身对 CUDA 的支持是通过GGML_CUDA这个编译开关控制的它内部会调用 cuBLAS 做矩阵乘法加速。问题在于llama.cpp 的 CMake 脚本默认会去找系统里的 CUDA Toolkit而 Jetson 上的 CUDA Toolkit 路径、版本号、库文件命名规则跟标准 x86 发行版有细微但致命的差异。如果你不做环境对齐最常见的表现就是CMake 报Could NOT find CUDAToolkit或者编译通过了但运行时报libcudart.so.XX: cannot open shared object file再或者更隐蔽的——编译成功、运行也不报错但 GPU 利用率始终是 0推理速度跟纯 CPU 模式一模一样。这篇内容适合三类人看第一类是在 Jetson 上部署本地大模型推理的嵌入式工程师第二类是想把 llama.cpp 从 x86 迁移到 ARM64 CUDA 平台的算法部署人员第三类是对边缘端 LLM 推理性能有要求、正在做技术选型的技术负责人。我会把整个环境对齐的流程拆成可复现的步骤包括版本匹配逻辑、CMake 参数怎么传、编译完怎么验证 CUDA 真的生效了以及我在实际调试中踩过的几个坑。需要提前说明的是Jetson 平台的 CUDA 环境跟标准桌面版有本质区别你不能用nvidia-smi来看 CUDA 版本也不能用nvcc --version作为唯一判断依据。Orin 上的 CUDA 是随 JetPack 一起刷进去的版本号跟 JetPack 版本强绑定。比如 JetPack 5.1.x 对应 CUDA 11.4JetPack 6.x 对应 CUDA 12.x。这个对应关系如果搞错了后面所有步骤都是白费力气。2. 环境对齐前的版本关系梳理与检查清单2.1 JetPack、CUDA、cuBLAS、llama.cpp 四者的版本约束链在 Jetson 上做 CUDA 环境对齐核心不是“装一个 CUDA”而是“确认已有的 CUDA 能不能被 llama.cpp 正确调用”。这四者之间存在一条硬性的版本约束链JetPack 版本决定了 CUDA Toolkit 的主版本号这个是你刷机时就定死的后期很难单独升级 CUDA 而不动 JetPack。CUDA 版本决定了 cuBLAS 的 API 签名和库文件命名llama.cpp 在编译时会根据 CUDA 版本选择不同的代码路径。cuBLAS是 llama.cpp 实际调用的计算库它必须跟 CUDA Runtime 版本一致否则会出现符号未定义。llama.cpp的 CMake 脚本对 CUDA 版本有最低要求太老的版本比如 CUDA 10.x可能不支持某些 kernel 写法。我整理了一张实际调试中验证过的对应表你可以直接对照自己的板子JetPack 版本CUDA 版本cuBLAS 库路径llama.cpp 编译可行性JetPack 5.0.2CUDA 11.4/usr/local/cuda-11.4/lib64可行需指定 CUDA 路径JetPack 5.1.2CUDA 11.4/usr/local/cuda-11.4/lib64可行推荐版本JetPack 6.0CUDA 12.2/usr/local/cuda-12.2/lib64可行需较新 llama.cppJetPack 6.1CUDA 12.6/usr/local/cuda-12.6/lib64可行注意 CMake 版本注意如果你在 Orin 上看到/usr/local/cuda是一个软链接先别急着用一定要ls -l /usr/local/cuda确认它指向哪个实际版本目录。我遇到过软链接指向一个不存在的目录导致 CMake 找到了路径但找不到库文件的情况。2.2 刷机后必须做的三项基础检查在动 llama.cpp 之前先把板子本身的环境摸清楚。这三项检查花不了五分钟但能帮你省掉后面几个小时的排查时间。第一项确认 CUDA Toolkit 实际安装位置和版本。不要只信nvcc --version因为 nvcc 可能来自一个残留的旧版本。用下面这组命令交叉验证ls -l /usr/local/cuda cat /usr/local/cuda/version.json 2/dev/null || cat /usr/local/cuda/version.txt dpkg -l | grep cuda-toolkitversion.json是 JetPack 5.x 之后才有的里面会明确写出 CUDA 版本号和对应的 JetPack 版本。如果这个文件不存在说明你的 CUDA 安装可能不完整。第二项确认 cuBLAS 库文件是否存在且可链接。llama.cpp 的 CUDA 后端强依赖 cuBLAS缺了它编译能过但运行会崩ls /usr/local/cuda/lib64/libcublas* ls /usr/local/cuda/lib64/libcudart*正常应该看到libcublas.so、libcublasLt.so、libcudart.so以及对应的版本号软链接。如果只有.so.11而没有.so说明你缺了开发包需要补装cuda-libraries-dev。第三项确认系统架构和 GCC 版本。Orin 是 aarch64GCC 版本会影响 llama.cpp 的编译选项uname -m gcc --version cmake --versionJetPack 5.x 自带 GCC 9.xJetPack 6.x 自带 GCC 11.x。llama.cpp 对 GCC 9 以上都支持但如果你的 GCC 版本低于 9需要先升级工具链。2.3 环境变量配置的取舍逻辑很多人习惯在.bashrc里写一堆export PATH和export LD_LIBRARY_PATH但在 Jetson 上这样做有个隐患JetPack 自带的 CUDA 路径已经在系统级配置里了你手动再覆盖一遍可能导致 CMake 找到的库版本跟运行时加载的库版本不一致。我的建议是不要全局修改 LD_LIBRARY_PATH而是在编译 llama.cpp 时通过 CMake 参数显式指定 CUDA 路径。这样编译期和运行期的库来源是同一个不会出现版本错位。具体怎么传参下一节会详细说。如果你确实需要临时验证某个 CUDA 路径是否可用可以在当前 shell 会话里临时 export验证完就关掉终端不要写进配置文件。3. llama.cpp 编译阶段的 CUDA 参数配置实操3.1 源码获取与分支选择llama.cpp 的更新频率很高不同 commit 对 CUDA 的支持程度差异很大。在 Jetson 上我不建议直接用master分支的最新代码因为新代码可能引入了对更新 CUDA 特性的依赖而你的 JetPack 版本未必支持。比较稳妥的做法是先确认你的 CUDA 版本然后去 llama.cpp 的 release 页面找一个发布时间跟你的 JetPack 版本接近的 tag。比如 JetPack 5.1.2 对应 CUDA 11.42023 年底到 2024 年初的 release 版本兼容性最好。git clone https://github.com/ggerganov/llama.cpp.git cd llama.cpp git tag --list | tail -20 git checkout 你选定的tag如果你不想折腾 tag也可以用 master 但做好回退准备。我实测下来2024 年之后的 master 分支在 CUDA 11.4 上编译基本没问题但偶尔会遇到某个 commit 引入了 C17 特性导致 GCC 9 编译失败这时候回退一两个 commit 就好了。3.2 CMake 配置阶段的关键参数逐项拆解这是整个流程最核心的一步。llama.cpp 的 CMake 脚本提供了多个跟 CUDA 相关的开关每一个都有实际作用不能随便填。cmake -B build \ -DGGML_CUDAON \ -DCMAKE_CUDA_COMPILER/usr/local/cuda/bin/nvcc \ -DCUDAToolkit_ROOT/usr/local/cuda \ -DCMAKE_CUDA_ARCHITECTURES87 \ -DLLAMA_CUBLASON \ -DCMAKE_BUILD_TYPERelease逐项解释这些参数背后的逻辑-DGGML_CUDAON是总开关告诉 CMake 启用 CUDA 后端。注意在新版本里这个选项可能叫-DLLAMA_CUDAON取决于你 checkout 的版本两个都试一下哪个不报 warning 用哪个。-DCMAKE_CUDA_COMPILER显式指定 nvcc 路径。Jetson 上可能有多个 nvcc比如你之前装过其他版本不指定的话 CMake 可能找到错误的那个。-DCUDAToolkit_ROOT告诉 CMake 去哪里找 CUDA 的库和头文件。这个参数比设CUDA_PATH环境变量更可靠因为它只影响当前这个 build 目录。-DCMAKE_CUDA_ARCHITECTURES87是最关键的一个。Orin 的 GPU 架构是 Ampere计算能力 8.7对应的架构代号就是87。如果你不指定CMake 可能会编译出包含多种架构的 fat binary体积大不说在 Orin 上运行时还可能因为找不到匹配的 cubin 而回退到 JIT 编译拖慢首次推理速度。指定87之后编译出来的 kernel 就是原生适配 Orin 的。-DLLAMA_CUBLASON是旧版本里的选项新版本可能已经合并到GGML_CUDA里了。加上它不会有坏处但如果 CMake 报 “unknown option” 的 warning说明你的版本已经不需要它了去掉即可。-DCMAKE_BUILD_TYPERelease不用多说Debug 模式在 Jetson 上编译出来的二进制性能差很多而且体积巨大。实操心得如果你在 CMake 配置阶段看到Could NOT find CUDAToolkit先别急着装东西。90% 的情况是CUDAToolkit_ROOT没传对或者/usr/local/cuda软链接坏了。用ls -l /usr/local/cuda确认一下如果是坏的手动重建软链接指向实际版本目录即可。3.3 编译过程中的资源控制与加速技巧Jetson AGX Orin 的 CPU 核心数不少12 核但内存带宽是共享的。如果你用make -j12全速编译可能会因为内存带宽被占满导致编译过程卡顿甚至 OOM。我的经验是用-j6或者-j8留一些余量给系统。cmake --build build --config Release -j6编译时间方面Orin 上完整编译 llama.cpp 的 CUDA 后端大概需要 15 到 25 分钟取决于你的散热条件。如果板子温度过高触发降频时间会更长。建议编译时确保散热风扇正常运转或者放在通风良好的地方。另一个加速技巧是如果你之前已经编译过一次哪怕失败了第二次编译时 CMake 会复用一部分缓存。但如果你改了 CUDA 相关的参数建议先rm -rf build清掉缓存再重新配置否则可能出现参数不生效的诡异情况。4. 编译后验证 CUDA 是否真正生效的完整方法4.1 二进制层面的依赖检查编译完成后第一件事不是急着跑模型而是确认编译出来的二进制确实链接了 CUDA 库。ldd build/bin/llama-cli | grep -i cuda ldd build/bin/llama-cli | grep -i cublas正常输出应该能看到libcudart.so.11.0或libcudart.so.12以及libcublas.so.11或libcublas.so.12。如果这两条命令没有任何输出说明你的二进制根本没有链接 CUDA前面所有配置都白做了。还有一种情况是链接了但版本不对比如显示libcudart.so.10.2而你系统里是 CUDA 11.4。这说明 CMake 找到了一个残留的旧版本 CUDA需要检查/usr/local/下是否有多个 cuda 目录以及CUDAToolkit_ROOT是否指向了正确的那个。4.2 运行时 GPU 利用率的观测方法Jetson 上没有nvidia-smi需要用tegrastats来观测 GPU 利用率sudo tegrastats --interval 1000这个命令会每秒输出一行系统状态其中GR3D_FREQ就是 GPU 的实时频率百分比。如果你在跑 llama.cpp 推理时看到GR3D_FREQ在 0% 和 99% 之间跳动说明 CUDA 确实在参与计算。如果始终是 0%那 GPU 根本没被调用。另一个辅助判断方法是看推理速度。同一个模型纯 CPU 模式和 CUDA 加速模式的 token 生成速度差距通常在 3 到 8 倍。如果你测出来速度跟 CPU 模式差不多那 CUDA 大概率没生效。4.3 一个容易被忽略的验证细节cuBLAS 初始化日志llama.cpp 在启动时如果 CUDA 后端加载成功会在日志里输出类似ggml_cuda_init: found 1 CUDA devices的信息。如果你在运行llama-cli时没看到这行日志说明 CUDA 后端没有被正确初始化。有时候日志会显示ggml_cuda_init: failed to initialize CUDA这通常是因为运行时找不到libcudart.so。解决方法是在运行前临时设置LD_LIBRARY_PATHLD_LIBRARY_PATH/usr/local/cuda/lib64:$LD_LIBRARY_PATH ./build/bin/llama-cli -m model.gguf -ngl 99 -p test注意-ngl 99这个参数它表示把所有层都放到 GPU 上计算。如果你不传这个参数llama.cpp 默认只用 CPUCUDA 后端虽然加载了但不会参与推理。这是新手最容易踩的坑之一。5. 常见问题排查与避坑经验实录5.1 CMake 找不到 CUDA 的三种典型场景第一种/usr/local/cuda软链接指向错误。JetPack 刷机后有时会出现软链接指向一个不存在的目录或者指向了旧版本。用ls -l /usr/local/cuda确认如果是坏的用sudo ln -sf /usr/local/cuda-11.4 /usr/local/cuda重建。第二种CMake 版本太老。JetPack 5.x 自带的 CMake 是 3.16这个版本对 CUDA 的支持有一些 bug。建议手动装一个 CMake 3.22 以上版本可以从源码编译或者用 pip 安装pip install cmake3.22.1第三种CUDAToolkit_ROOT路径写错。有些人写成/usr/local/cuda/lib64这是不对的应该写到 CUDA 根目录/usr/local/cudaCMake 会自动去下面的lib64和include找。5.2 编译通过但运行报库文件找不到的解决思路这个问题的根源通常是编译期和运行期的库搜索路径不一致。编译时 CMake 通过CUDAToolkit_ROOT找到了库但运行时动态链接器不知道去哪里找。最直接的解决方法是把 CUDA 库路径加到系统级配置里echo /usr/local/cuda/lib64 | sudo tee /etc/ld.so.conf.d/cuda.conf sudo ldconfig这样所有程序运行时都能找到 CUDA 库不需要每次手动设LD_LIBRARY_PATH。但要注意如果你系统里有多个 CUDA 版本这样做会让所有程序都用同一个版本可能影响其他依赖不同 CUDA 版本的程序。5.3 GPU 利用率上不去、推理速度没提升的排查路径这个问题比前两个更隐蔽因为程序不报错只是“没效果”。排查路径如下先确认-ngl参数是否传了。这是最常见的原因很多人编译完 CUDA 后端就直接跑忘了加-ngl结果全程 CPU 推理。再确认模型格式是否支持 GPU 加速。llama.cpp 的 CUDA 后端对 GGUF 格式的量化模型支持最好如果你用的是其他格式转换过来的可能部分层无法放到 GPU 上。然后检查 Orin 的功耗模式。Jetson 默认可能是低功耗模式GPU 频率被限制。用sudo nvpmodel -q查看当前模式如果是 0 或 1建议切到最大性能模式sudo nvpmodel -m 0 sudo jetson_clocksnvpmodel -m 0是最大性能模式jetson_clocks会把 CPU 和 GPU 频率锁到最高。这两个命令配合使用能让 Orin 的推理性能提升 30% 以上。5.4 常见问题速查表现象可能原因解决方法CMake 报 Could NOT find CUDAToolkitCUDAToolkit_ROOT 未指定或路径错误传-DCUDAToolkit_ROOT/usr/local/cuda编译报 nvcc not foundCMAKE_CUDA_COMPILER 未指定传-DCMAKE_CUDA_COMPILER/usr/local/cuda/bin/nvcc运行报 libcudart.so 找不到运行时库路径未配置配置/etc/ld.so.conf.d/cuda.conf并ldconfigGPU 利用率始终为 0未传-ngl参数运行时加-ngl 99推理速度跟 CPU 模式一样功耗模式限制或模型未加载到 GPU切最大性能模式确认-ngl生效编译到一半 OOM并行编译任务数过多降低-j参数到 6 或 8避坑提示在 Jetson 上不要试图用apt安装nvidia-cuda-toolkit这个包是给 x86 桌面版用的装到 ARM64 上会破坏 JetPack 自带的 CUDA 环境。如果你已经误装了用sudo apt remove nvidia-cuda-toolkit卸载然后重新刷 JetPack 恢复。6. 性能调优与长期维护建议6.1 针对 Orin 内存架构的 batch size 调优Jetson AGX Orin 的内存是 CPU 和 GPU 共享的总容量有 32GB 和 64GB 两个版本。这个架构的好处是 GPU 可以直接访问系统内存不需要显式的数据拷贝坏处是如果 batch size 设得太大内存带宽会成为瓶颈反而拖慢推理速度。llama.cpp 的-b参数控制 batch size默认是 512。在 Orin 上我实测下来 256 到 512 之间比较合适。设成 1024 以上时内存带宽占用会明显上升token 生成速度反而下降。./build/bin/llama-cli -m model.gguf -ngl 99 -b 256 -p 你的提示词你可以用不同的 batch size 跑同一个提示词记录 token/s 的变化找到你板子上的最优值。这个值跟模型大小也有关系7B 模型和 13B 模型的最优 batch size 可能不同。6.2 模型量化格式的选择对 CUDA 加速的影响llama.cpp 支持多种量化格式从 Q4_0 到 Q8_0 再到 K 系列量化。在 Orin 上Q4_K_M 是性价比最高的选择模型体积适中推理速度快精度损失在可接受范围内。但要注意不是所有量化格式都能被 CUDA 后端完整加速。比如某些早期的 Q4_1 格式在 CUDA 上的 kernel 实现可能不完整部分计算会回退到 CPU。如果你发现某个量化模型跑起来特别慢可以换一个格式试试。6.3 长期维护JetPack 升级后的环境重建流程JetPack 升级比如从 5.1.2 升到 6.0会连带升级 CUDA 版本这时候之前编译好的 llama.cpp 二进制就不能用了需要重新编译。重建流程跟第一次编译基本一样但有几个额外注意点升级后先确认新的 CUDA 版本和路径/usr/local/cuda软链接可能变了。然后清理旧的 build 目录rm -rf build避免 CMake 缓存里残留旧版本的路径信息。最后重新跑一遍 CMake 配置和编译参数里的CMAKE_CUDA_ARCHITECTURES仍然是87这个不会因为 JetPack 升级而改变因为 Orin 的 GPU 架构没变。如果你在升级后遇到奇怪的链接错误先检查/etc/ld.so.conf.d/cuda.conf里的路径是否还指向旧版本。如果是更新路径并重新ldconfig。我个人在 Orin 上反复折腾 CUDA 环境对齐的体会是版本关系的确认比任何编译技巧都重要。先把 JetPack、CUDA、cuBLAS 三者的版本对应关系搞清楚后面的编译和调优就是顺水推舟的事。反过来如果版本关系没理清再多的编译参数也是碰运气。另外-ngl参数和功耗模式这两个点是我见过最多人忽略但又影响最大的建议你在第一次跑通之后就养成习惯把这两个配置固定下来。 
长河君 · 2026/9/24 12:50:48 · 阅读 1.2k Jetson AGX Orin 上 llama.cpp CUDA 环境对齐与编译调优实战
1. 为什么 Jetson AGX Orin 上跑 llama.cpp 需要专门做 CUDA 环境对齐Jetson AGX Orin 是一块很有意思的板子。它跟桌面级显卡最大的区别在于GPU 和 CPU 共享同一块物理内存CUDA 架构是 ARM64 下的sm_87系统层面用的是 NVIDIA 自家维护的 JetPack SDK而不是你在 Ubuntu 上习惯的那套apt install nvidia-cuda-toolkit。这就导致一个很现实的问题——很多在 x86 服务器上跑得好好的 llama.cpp 编译流程搬到 Orin 上就会在 CMake 配置阶段或者链接阶段直接翻车。llama.cpp 本身对 CUDA 的支持是通过GGML_CUDA这个编译开关控制的它内部会调用 cuBLAS 做矩阵乘法加速。问题在于llama.cpp 的 CMake 脚本默认会去找系统里的 CUDA Toolkit而 Jetson 上的 CUDA Toolkit 路径、版本号、库文件命名规则跟标准 x86 发行版有细微但致命的差异。如果你不做环境对齐最常见的表现就是CMake 报Could NOT find CUDAToolkit或者编译通过了但运行时报libcudart.so.XX: cannot open shared object file再或者更隐蔽的——编译成功、运行也不报错但 GPU 利用率始终是 0推理速度跟纯 CPU 模式一模一样。这篇内容适合三类人看第一类是在 Jetson 上部署本地大模型推理的嵌入式工程师第二类是想把 llama.cpp 从 x86 迁移到 ARM64 CUDA 平台的算法部署人员第三类是对边缘端 LLM 推理性能有要求、正在做技术选型的技术负责人。我会把整个环境对齐的流程拆成可复现的步骤包括版本匹配逻辑、CMake 参数怎么传、编译完怎么验证 CUDA 真的生效了以及我在实际调试中踩过的几个坑。需要提前说明的是Jetson 平台的 CUDA 环境跟标准桌面版有本质区别你不能用nvidia-smi来看 CUDA 版本也不能用nvcc --version作为唯一判断依据。Orin 上的 CUDA 是随 JetPack 一起刷进去的版本号跟 JetPack 版本强绑定。比如 JetPack 5.1.x 对应 CUDA 11.4JetPack 6.x 对应 CUDA 12.x。这个对应关系如果搞错了后面所有步骤都是白费力气。2. 环境对齐前的版本关系梳理与检查清单2.1 JetPack、CUDA、cuBLAS、llama.cpp 四者的版本约束链在 Jetson 上做 CUDA 环境对齐核心不是“装一个 CUDA”而是“确认已有的 CUDA 能不能被 llama.cpp 正确调用”。这四者之间存在一条硬性的版本约束链JetPack 版本决定了 CUDA Toolkit 的主版本号这个是你刷机时就定死的后期很难单独升级 CUDA 而不动 JetPack。CUDA 版本决定了 cuBLAS 的 API 签名和库文件命名llama.cpp 在编译时会根据 CUDA 版本选择不同的代码路径。cuBLAS是 llama.cpp 实际调用的计算库它必须跟 CUDA Runtime 版本一致否则会出现符号未定义。llama.cpp的 CMake 脚本对 CUDA 版本有最低要求太老的版本比如 CUDA 10.x可能不支持某些 kernel 写法。我整理了一张实际调试中验证过的对应表你可以直接对照自己的板子JetPack 版本CUDA 版本cuBLAS 库路径llama.cpp 编译可行性JetPack 5.0.2CUDA 11.4/usr/local/cuda-11.4/lib64可行需指定 CUDA 路径JetPack 5.1.2CUDA 11.4/usr/local/cuda-11.4/lib64可行推荐版本JetPack 6.0CUDA 12.2/usr/local/cuda-12.2/lib64可行需较新 llama.cppJetPack 6.1CUDA 12.6/usr/local/cuda-12.6/lib64可行注意 CMake 版本注意如果你在 Orin 上看到/usr/local/cuda是一个软链接先别急着用一定要ls -l /usr/local/cuda确认它指向哪个实际版本目录。我遇到过软链接指向一个不存在的目录导致 CMake 找到了路径但找不到库文件的情况。2.2 刷机后必须做的三项基础检查在动 llama.cpp 之前先把板子本身的环境摸清楚。这三项检查花不了五分钟但能帮你省掉后面几个小时的排查时间。第一项确认 CUDA Toolkit 实际安装位置和版本。不要只信nvcc --version因为 nvcc 可能来自一个残留的旧版本。用下面这组命令交叉验证ls -l /usr/local/cuda cat /usr/local/cuda/version.json 2/dev/null || cat /usr/local/cuda/version.txt dpkg -l | grep cuda-toolkitversion.json是 JetPack 5.x 之后才有的里面会明确写出 CUDA 版本号和对应的 JetPack 版本。如果这个文件不存在说明你的 CUDA 安装可能不完整。第二项确认 cuBLAS 库文件是否存在且可链接。llama.cpp 的 CUDA 后端强依赖 cuBLAS缺了它编译能过但运行会崩ls /usr/local/cuda/lib64/libcublas* ls /usr/local/cuda/lib64/libcudart*正常应该看到libcublas.so、libcublasLt.so、libcudart.so以及对应的版本号软链接。如果只有.so.11而没有.so说明你缺了开发包需要补装cuda-libraries-dev。第三项确认系统架构和 GCC 版本。Orin 是 aarch64GCC 版本会影响 llama.cpp 的编译选项uname -m gcc --version cmake --versionJetPack 5.x 自带 GCC 9.xJetPack 6.x 自带 GCC 11.x。llama.cpp 对 GCC 9 以上都支持但如果你的 GCC 版本低于 9需要先升级工具链。2.3 环境变量配置的取舍逻辑很多人习惯在.bashrc里写一堆export PATH和export LD_LIBRARY_PATH但在 Jetson 上这样做有个隐患JetPack 自带的 CUDA 路径已经在系统级配置里了你手动再覆盖一遍可能导致 CMake 找到的库版本跟运行时加载的库版本不一致。我的建议是不要全局修改 LD_LIBRARY_PATH而是在编译 llama.cpp 时通过 CMake 参数显式指定 CUDA 路径。这样编译期和运行期的库来源是同一个不会出现版本错位。具体怎么传参下一节会详细说。如果你确实需要临时验证某个 CUDA 路径是否可用可以在当前 shell 会话里临时 export验证完就关掉终端不要写进配置文件。3. llama.cpp 编译阶段的 CUDA 参数配置实操3.1 源码获取与分支选择llama.cpp 的更新频率很高不同 commit 对 CUDA 的支持程度差异很大。在 Jetson 上我不建议直接用master分支的最新代码因为新代码可能引入了对更新 CUDA 特性的依赖而你的 JetPack 版本未必支持。比较稳妥的做法是先确认你的 CUDA 版本然后去 llama.cpp 的 release 页面找一个发布时间跟你的 JetPack 版本接近的 tag。比如 JetPack 5.1.2 对应 CUDA 11.42023 年底到 2024 年初的 release 版本兼容性最好。git clone https://github.com/ggerganov/llama.cpp.git cd llama.cpp git tag --list | tail -20 git checkout 你选定的tag如果你不想折腾 tag也可以用 master 但做好回退准备。我实测下来2024 年之后的 master 分支在 CUDA 11.4 上编译基本没问题但偶尔会遇到某个 commit 引入了 C17 特性导致 GCC 9 编译失败这时候回退一两个 commit 就好了。3.2 CMake 配置阶段的关键参数逐项拆解这是整个流程最核心的一步。llama.cpp 的 CMake 脚本提供了多个跟 CUDA 相关的开关每一个都有实际作用不能随便填。cmake -B build \ -DGGML_CUDAON \ -DCMAKE_CUDA_COMPILER/usr/local/cuda/bin/nvcc \ -DCUDAToolkit_ROOT/usr/local/cuda \ -DCMAKE_CUDA_ARCHITECTURES87 \ -DLLAMA_CUBLASON \ -DCMAKE_BUILD_TYPERelease逐项解释这些参数背后的逻辑-DGGML_CUDAON是总开关告诉 CMake 启用 CUDA 后端。注意在新版本里这个选项可能叫-DLLAMA_CUDAON取决于你 checkout 的版本两个都试一下哪个不报 warning 用哪个。-DCMAKE_CUDA_COMPILER显式指定 nvcc 路径。Jetson 上可能有多个 nvcc比如你之前装过其他版本不指定的话 CMake 可能找到错误的那个。-DCUDAToolkit_ROOT告诉 CMake 去哪里找 CUDA 的库和头文件。这个参数比设CUDA_PATH环境变量更可靠因为它只影响当前这个 build 目录。-DCMAKE_CUDA_ARCHITECTURES87是最关键的一个。Orin 的 GPU 架构是 Ampere计算能力 8.7对应的架构代号就是87。如果你不指定CMake 可能会编译出包含多种架构的 fat binary体积大不说在 Orin 上运行时还可能因为找不到匹配的 cubin 而回退到 JIT 编译拖慢首次推理速度。指定87之后编译出来的 kernel 就是原生适配 Orin 的。-DLLAMA_CUBLASON是旧版本里的选项新版本可能已经合并到GGML_CUDA里了。加上它不会有坏处但如果 CMake 报 “unknown option” 的 warning说明你的版本已经不需要它了去掉即可。-DCMAKE_BUILD_TYPERelease不用多说Debug 模式在 Jetson 上编译出来的二进制性能差很多而且体积巨大。实操心得如果你在 CMake 配置阶段看到Could NOT find CUDAToolkit先别急着装东西。90% 的情况是CUDAToolkit_ROOT没传对或者/usr/local/cuda软链接坏了。用ls -l /usr/local/cuda确认一下如果是坏的手动重建软链接指向实际版本目录即可。3.3 编译过程中的资源控制与加速技巧Jetson AGX Orin 的 CPU 核心数不少12 核但内存带宽是共享的。如果你用make -j12全速编译可能会因为内存带宽被占满导致编译过程卡顿甚至 OOM。我的经验是用-j6或者-j8留一些余量给系统。cmake --build build --config Release -j6编译时间方面Orin 上完整编译 llama.cpp 的 CUDA 后端大概需要 15 到 25 分钟取决于你的散热条件。如果板子温度过高触发降频时间会更长。建议编译时确保散热风扇正常运转或者放在通风良好的地方。另一个加速技巧是如果你之前已经编译过一次哪怕失败了第二次编译时 CMake 会复用一部分缓存。但如果你改了 CUDA 相关的参数建议先rm -rf build清掉缓存再重新配置否则可能出现参数不生效的诡异情况。4. 编译后验证 CUDA 是否真正生效的完整方法4.1 二进制层面的依赖检查编译完成后第一件事不是急着跑模型而是确认编译出来的二进制确实链接了 CUDA 库。ldd build/bin/llama-cli | grep -i cuda ldd build/bin/llama-cli | grep -i cublas正常输出应该能看到libcudart.so.11.0或libcudart.so.12以及libcublas.so.11或libcublas.so.12。如果这两条命令没有任何输出说明你的二进制根本没有链接 CUDA前面所有配置都白做了。还有一种情况是链接了但版本不对比如显示libcudart.so.10.2而你系统里是 CUDA 11.4。这说明 CMake 找到了一个残留的旧版本 CUDA需要检查/usr/local/下是否有多个 cuda 目录以及CUDAToolkit_ROOT是否指向了正确的那个。4.2 运行时 GPU 利用率的观测方法Jetson 上没有nvidia-smi需要用tegrastats来观测 GPU 利用率sudo tegrastats --interval 1000这个命令会每秒输出一行系统状态其中GR3D_FREQ就是 GPU 的实时频率百分比。如果你在跑 llama.cpp 推理时看到GR3D_FREQ在 0% 和 99% 之间跳动说明 CUDA 确实在参与计算。如果始终是 0%那 GPU 根本没被调用。另一个辅助判断方法是看推理速度。同一个模型纯 CPU 模式和 CUDA 加速模式的 token 生成速度差距通常在 3 到 8 倍。如果你测出来速度跟 CPU 模式差不多那 CUDA 大概率没生效。4.3 一个容易被忽略的验证细节cuBLAS 初始化日志llama.cpp 在启动时如果 CUDA 后端加载成功会在日志里输出类似ggml_cuda_init: found 1 CUDA devices的信息。如果你在运行llama-cli时没看到这行日志说明 CUDA 后端没有被正确初始化。有时候日志会显示ggml_cuda_init: failed to initialize CUDA这通常是因为运行时找不到libcudart.so。解决方法是在运行前临时设置LD_LIBRARY_PATHLD_LIBRARY_PATH/usr/local/cuda/lib64:$LD_LIBRARY_PATH ./build/bin/llama-cli -m model.gguf -ngl 99 -p test注意-ngl 99这个参数它表示把所有层都放到 GPU 上计算。如果你不传这个参数llama.cpp 默认只用 CPUCUDA 后端虽然加载了但不会参与推理。这是新手最容易踩的坑之一。5. 常见问题排查与避坑经验实录5.1 CMake 找不到 CUDA 的三种典型场景第一种/usr/local/cuda软链接指向错误。JetPack 刷机后有时会出现软链接指向一个不存在的目录或者指向了旧版本。用ls -l /usr/local/cuda确认如果是坏的用sudo ln -sf /usr/local/cuda-11.4 /usr/local/cuda重建。第二种CMake 版本太老。JetPack 5.x 自带的 CMake 是 3.16这个版本对 CUDA 的支持有一些 bug。建议手动装一个 CMake 3.22 以上版本可以从源码编译或者用 pip 安装pip install cmake3.22.1第三种CUDAToolkit_ROOT路径写错。有些人写成/usr/local/cuda/lib64这是不对的应该写到 CUDA 根目录/usr/local/cudaCMake 会自动去下面的lib64和include找。5.2 编译通过但运行报库文件找不到的解决思路这个问题的根源通常是编译期和运行期的库搜索路径不一致。编译时 CMake 通过CUDAToolkit_ROOT找到了库但运行时动态链接器不知道去哪里找。最直接的解决方法是把 CUDA 库路径加到系统级配置里echo /usr/local/cuda/lib64 | sudo tee /etc/ld.so.conf.d/cuda.conf sudo ldconfig这样所有程序运行时都能找到 CUDA 库不需要每次手动设LD_LIBRARY_PATH。但要注意如果你系统里有多个 CUDA 版本这样做会让所有程序都用同一个版本可能影响其他依赖不同 CUDA 版本的程序。5.3 GPU 利用率上不去、推理速度没提升的排查路径这个问题比前两个更隐蔽因为程序不报错只是“没效果”。排查路径如下先确认-ngl参数是否传了。这是最常见的原因很多人编译完 CUDA 后端就直接跑忘了加-ngl结果全程 CPU 推理。再确认模型格式是否支持 GPU 加速。llama.cpp 的 CUDA 后端对 GGUF 格式的量化模型支持最好如果你用的是其他格式转换过来的可能部分层无法放到 GPU 上。然后检查 Orin 的功耗模式。Jetson 默认可能是低功耗模式GPU 频率被限制。用sudo nvpmodel -q查看当前模式如果是 0 或 1建议切到最大性能模式sudo nvpmodel -m 0 sudo jetson_clocksnvpmodel -m 0是最大性能模式jetson_clocks会把 CPU 和 GPU 频率锁到最高。这两个命令配合使用能让 Orin 的推理性能提升 30% 以上。5.4 常见问题速查表现象可能原因解决方法CMake 报 Could NOT find CUDAToolkitCUDAToolkit_ROOT 未指定或路径错误传-DCUDAToolkit_ROOT/usr/local/cuda编译报 nvcc not foundCMAKE_CUDA_COMPILER 未指定传-DCMAKE_CUDA_COMPILER/usr/local/cuda/bin/nvcc运行报 libcudart.so 找不到运行时库路径未配置配置/etc/ld.so.conf.d/cuda.conf并ldconfigGPU 利用率始终为 0未传-ngl参数运行时加-ngl 99推理速度跟 CPU 模式一样功耗模式限制或模型未加载到 GPU切最大性能模式确认-ngl生效编译到一半 OOM并行编译任务数过多降低-j参数到 6 或 8避坑提示在 Jetson 上不要试图用apt安装nvidia-cuda-toolkit这个包是给 x86 桌面版用的装到 ARM64 上会破坏 JetPack 自带的 CUDA 环境。如果你已经误装了用sudo apt remove nvidia-cuda-toolkit卸载然后重新刷 JetPack 恢复。6. 性能调优与长期维护建议6.1 针对 Orin 内存架构的 batch size 调优Jetson AGX Orin 的内存是 CPU 和 GPU 共享的总容量有 32GB 和 64GB 两个版本。这个架构的好处是 GPU 可以直接访问系统内存不需要显式的数据拷贝坏处是如果 batch size 设得太大内存带宽会成为瓶颈反而拖慢推理速度。llama.cpp 的-b参数控制 batch size默认是 512。在 Orin 上我实测下来 256 到 512 之间比较合适。设成 1024 以上时内存带宽占用会明显上升token 生成速度反而下降。./build/bin/llama-cli -m model.gguf -ngl 99 -b 256 -p 你的提示词你可以用不同的 batch size 跑同一个提示词记录 token/s 的变化找到你板子上的最优值。这个值跟模型大小也有关系7B 模型和 13B 模型的最优 batch size 可能不同。6.2 模型量化格式的选择对 CUDA 加速的影响llama.cpp 支持多种量化格式从 Q4_0 到 Q8_0 再到 K 系列量化。在 Orin 上Q4_K_M 是性价比最高的选择模型体积适中推理速度快精度损失在可接受范围内。但要注意不是所有量化格式都能被 CUDA 后端完整加速。比如某些早期的 Q4_1 格式在 CUDA 上的 kernel 实现可能不完整部分计算会回退到 CPU。如果你发现某个量化模型跑起来特别慢可以换一个格式试试。6.3 长期维护JetPack 升级后的环境重建流程JetPack 升级比如从 5.1.2 升到 6.0会连带升级 CUDA 版本这时候之前编译好的 llama.cpp 二进制就不能用了需要重新编译。重建流程跟第一次编译基本一样但有几个额外注意点升级后先确认新的 CUDA 版本和路径/usr/local/cuda软链接可能变了。然后清理旧的 build 目录rm -rf build避免 CMake 缓存里残留旧版本的路径信息。最后重新跑一遍 CMake 配置和编译参数里的CMAKE_CUDA_ARCHITECTURES仍然是87这个不会因为 JetPack 升级而改变因为 Orin 的 GPU 架构没变。如果你在升级后遇到奇怪的链接错误先检查/etc/ld.so.conf.d/cuda.conf里的路径是否还指向旧版本。如果是更新路径并重新ldconfig。我个人在 Orin 上反复折腾 CUDA 环境对齐的体会是版本关系的确认比任何编译技巧都重要。先把 JetPack、CUDA、cuBLAS 三者的版本对应关系搞清楚后面的编译和调优就是顺水推舟的事。反过来如果版本关系没理清再多的编译参数也是碰运气。另外-ngl参数和功耗模式这两个点是我见过最多人忽略但又影响最大的建议你在第一次跑通之后就养成习惯把这两个配置固定下来。