编译 llama.cpp 时使用 Metal

#llama.cpp在Mac上的表现：Metal带来的优势

在 macOS 上，GPU 通过 Apple 的图形与计算 API Metal 来使用，llama.cpp 直接利用这一 API。项目 README 明确指出，Apple Silicon 是重点支持的平台，并通过 ARM NEON、Accelerate 和 Metal 进行了优化。实际而言，这意味着默认编译就会生成一个使用 GPU 的引擎，无需添加额外选项；统一内存也避免了处理器与 GPU 之间的任何数据传输：模型在内存中只保留一份。因此，Mac 上的限制因素是这块内存的容量和带宽。

#先决条件

一台搭载 Apple Silicon 芯片的 Mac

M1到M5：本指南的目标机型。搭载Intel处理器的Mac几乎无法获益。

Apple编译工具

使用 xcode-select --install 安装命令行工具。

CMake 和 Git

通过 Homebrew 可安装：brew install cmake git

模型所需内存

本站的参考值：Q4 量化的 8B 模型约占 5 GB，14B 约占 9 GB，32B 约占 19 至 20 GB，尚未计入上下文所需的内存。

xcode-select --install
brew install cmake git

#无需编译即可安装：Homebrew

如果不需要特殊的编译选项，最快的方法是使用 Homebrew。llama.cpp 的安装文档说明，项目每次发布新版本时，Homebrew 的 formula 软件包定义都会自动更新。您会获得相同的可执行程序，支持 Metal，开箱即用。

brew install llama.cpp

如需获取仓库最新版本、测试分支或修改编译选项，请自行编译。否则，使用Homebrew即可：可节省编译时间，更新通过brew upgrade完成。

#1. 使用Metal编译

git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp

cmake -B build
cmake --build build --config Release -j $(sysctl -n hw.ncpu)

构建文档说明清晰：在macOS上，Metal默认启用，并直接在GPU上执行计算，无需额外配置。原仓库（Georgi Gerganov账号）已重定向至ggml-org组织，该项目现位于该组织下。可执行文件位于build/bin目录中，包括用于终端的llama-cli和用于API的llama-server。

两个实用选项：文档说明，-DGGML_METAL=OFF 可在编译时禁用 Metal；编译包含 Metal 的二进制文件可通过 --n-gpu-layers 0 强制在处理器上运行，适用于性能对比。

#2. 启动首个模型

较新的引擎可自行下载模型。-hf 选项指定 Hugging Face 仓库名称，后缀表示量化方式；无后缀时默认采用 Q4_K_M。对于已下载的模型文件，请使用 -m 指定其路径。

./build/bin/llama-cli -hf UTILISATEUR/MODELE-GGUF:Q4_K_M

./build/bin/llama-cli -m ~/modeles/mon-modele-Q4_K_M.gguf

放在 GPU 上的层数可通过 -ngl 设置；其默认值为 auto，适用于采用统一内存的 Mac。您也可以指定 -ngl all，将所有层都加载到 GPU 上。不要到 Ollama 文件夹中寻找模型路径：它的文件采用内部格式存储，并不是可直接使用的 GGUF 文件。

#使用 llama-server 提供兼容 OpenAI 的 API

llama-server 提供与 OpenAI API 兼容的路由，支持聊天、回答和嵌入功能。默认情况下，它监听 127.0.0.1:8080，仅可在您的 Mac 上访问。若要开放网络访问，需显式指定 --host 参数，并需对访问进行保护。

./build/bin/llama-server -m ~/modeles/mon-modele-Q4_K_M.gguf --port 8080

• llama.cpp 是什么，需要放弃 Ollama 吗？
• Ollama vs llama.cpp：如何选择

#4. macOS GPU内存限制

在 Apple Silicon 上，macOS 只允许 GPU 使用统一内存的一部分。如果模型所需的内存超过这部分容量，就会被拒绝加载，或将超出的部分交由 CPU 处理，即使总内存足够也是如此。引擎会在启动时显示实际可用值：请在 llama-cli 或 llama-server 的日志中查找 ggml_metal_init: recommendedMaxWorkingSetSize 这一行。

sysctl iogpu.wired_limit_mb 命令可用于提高这一上限。它接受以兆字节为单位的数值，例如 60 GB 对应 61 440。llama.cpp 仓库的一位贡献者提醒，这项设置不具有持久性，因此每次启动后都要重新设置，并且不建议将上限提高到 100%：系统需要内存来处理所有未被 GPU 锁定的内容，如果留给系统的内存不足，就会出现问题。

# 56 Go pour le GPU sur un Mac de 64 Go (56 x 1024 = 57344)
sudo sysctl iogpu.wired_limit_mb=57344

# Relancez ensuite le modèle et relisez recommendedMaxWorkingSetSize

#不同统一内存容量适合哪些模型

统一内存由macOS、您的应用程序和模型共享，GPU只能使用其中一部分。本站的参考估算是：Q4量化下，8B模型的权重约占5 GB，14B约占9 GB，32B约占19至20 GB。还需加上上下文缓存。表格给出的是保守的粗略估算；应以引擎显示的 recommendedMaxWorkingSetSize 为准。

这些数量级只是保守估计，并非实测结果：较长的上下文、第二个模型或资源消耗较大的应用，都足以改变情况。专门介绍内存的指南提供了完整的计算方法。

• VRAM与内存：AI运行需要多少？
• 在MacBook Pro M4上使用哪个LLM

#5. 关键选项

Flash Attention 默认处于自动模式：大多数情况下无需手动启用。KV 缓存可通过 -ctk 和 -ctv 进行量化，但前提是 Flash Attention 已启用；相较于 f16，q8_0 可将缓存的内存占用大致减半，代价是轻微的精度损失，建议针对您的实际用途进行验证。专门的指南详细介绍了这一权衡。

• 量化 KV 缓存以节省 VRAM
• llama.cpp中的Flash Attention

#6. 各款芯片的性能：公开基准测试衡量的是什么

QuelLLM 不对这些机器进行实测。参考来源是 llama.cpp 仓库中的讨论“Performance of llama.cpp on Apple Silicon M-series”，其中每位贡献者都对 Q4_0 格式的 LLaMA 7B 模型运行同一项测试。下表选取了其中的几条记录，并列出每次测量所用的 llama.cpp 版本：M1 至 M4 芯片的测量使用的是同一版本，M5 的测量使用的版本则更新。

理论上限等于带宽除以模型大小（3.56 GiB，即 3.82 GB）。Pro 芯片能达到这一上限的 71% 至 82%，Max 芯片却只能达到 58%：达到一定水平后，内存不再是唯一瓶颈，花钱增加带宽所带来的收益也没有技术规格表暗示的那么大。

有三点值得注意。生成速度随带宽而变化：M3 Pro 的带宽为 150 GB/s，速度不及带宽为 200 GB/s 的 M2 Pro，尽管它采用的是更新一代的芯片。Max 系列芯片凭借高得多的带宽占据优势。最后，M5 系列的提示词处理速度有了飞跃：M5 Pro 达到 1 620.64 tokens/s，而 GPU 核心数量相同的 M4 Pro 为 439.78 tokens/s，前者是后者的 3.7 倍。这一差距对于长文档和 RAG 很重要，对聊天的影响则小得多。

在认定一台 Mac 运行缓慢之前，不妨养成一个好习惯：先用 -ngl 0 重新运行同一个模型，再用默认值运行，然后比较。两者的差距能显示 GPU 在您的机器上实际带来的提升，并确认计算确实通过 Metal 执行。也请记录所用的 llama.cpp 版本：Metal 优化进展很快，旧版二进制文件可能明显慢于较新的版本。

#故障排除：常见错误

• MLX 与 llama.cpp 在 Mac 上的对比：2026 年谁更胜一筹？
• 使用 CUDA 编译 llama.cpp
• 32 GB 内存适合运行哪些模型

• 来源：llama.cpp官方仓库
• 来源：llama.cpp 编译文档
• 来源：Apple Silicon 上的公开基准测试
• 来源：关于 Mac GPU 内存限制的讨论