在 Mac M 系列上编译 llama.cpp 时，Metal 加速不是默认开启的。通过设置 CMAKE_ARGS=-DLLAMA_METAL=on 再执行 CMake 配置，可以启用 macOS 上的 Metal GPU 支持，让部分计算跑到 GPU 上。这个操作针对源码编译，对通过 Homebrew 直接安装的预编译包无效。下面按步骤配置，并给出验证方式。
在 Apple Silicon Mac 上，llama.cpp 需要先安装 Xcode Command Line Tools，然后在源码编译时给 CMake 传入
-DLLAMA_METAL=on。验证是否生效，可以看 CMake 输出、检查CMakeCache.txt，或在运行时观察日志中是否有ggml_metal相关记录。这个开关只影响 Metal 后端，不影响 CPU 回退逻辑。
环境准备：确认 Xcode Command Line Tools 已安装
Metal 编译依赖 macOS 的系统框架，这些框架随 Xcode Command Line Tools 提供。建议先确认工具链完整，避免配置阶段就报错。
# 检查已安装版本
xcode-select `--version`
# 如果提示未安装，执行下面的命令安装
xcode-select `--install`安装完成后，建议重启终端再进编译步骤。如果你从 App Store 安装的完整 Xcode，同样没问题，但普通用户只需 Command Line Tools 就够。
编译时启用 Metal：CMAKE_ARGS 的两种用法
llama.cpp 使用 CMake 构建，CMAKE_ARGS 是项目里专门用来给底层 GGML 库传参的环境变量，可以通过导出外部变量或直接作为 CMake 参数传入。两种方式最终效果一致，按习惯选择一种。
# 方式一：先设置环境变量，再配置
export CMAKE_ARGS="-DLLAMA_METAL=on"
cmake -B build -DCMAKE_BUILD_TYPE=Release
# 方式二：直接把参数加到 CMake 命令行
cmake -B build -DCMAKE_BUILD_TYPE=Release -DLLAMA_METAL=on配置完成后统一编译：
cmake `--build` build `--config` Release如果你的机器核数较多，可以加 -j 参数并行编译，例如 cmake `--build` build `--config` Release -j 8。注意不要为了省时间而省略配置步骤，直接编译不会自动触发 Metal 开关。
验证 Metal 是否真的启用
编译完成不等于 Metal 一定生效。建议按顺序检查三处信息，每步都能独立确认。
- 配置输出：CMake 执行时，日志里会出现与 Metal 相关的检查项，比如
Found Metal.framework或ggml_metal。如果完全没有相关字样，多半是参数没传进去。 - 构建缓存：打开
build/CMakeCache.txt，搜索LLAMA_METAL，看到LLAMA_METAL:BOOL=ON说明开关已写入。 - 运行日志：用编译出的可执行程序加载模型跑一次，例如
./build/bin/main -m your-model.gguf -p "Hello" -n 16。如果 Metal 生效，程序初始化阶段通常会输出类似ggml_metal_init或using Metal的日志。
如果第三步没有看到任何 Metal 相关输出，可以先用 ./build/bin/main `--help` 确认可执行文件正常，再检查模型路径是否填对。
常见问题
设置 CMAKE_ARGS 后重新编译，还是没启用 Metal
最常见原因是 CMake 缓存了之前的配置值。建议删除 build 目录（rm -rf build），重新执行 cmake -B build ... 和 cmake `--build` build。新设置的 CMAKE_ARGS 只对新的配置生效。
编译时报错找不到 Metal
确认你的 Mac 是 Apple Silicon 机型（M1/M2/M3 系列），并已安装至少 macOS 11 或更高版本的系统。另外，Metal 需要 Xcode Command Line Tools 的 SDK 支持，重新运行 xcode-select `--install` 或从开发者官网更新工具链后再试。
启用 Metal 后跑小模型速度没有变化
这是正常现象。Metal 加速对较大模型和较长上下文的计算收益更明显，小模型由于数据搬运到 GPU 的开销占比较高，可能感受不到差别。如果手头只有小型模型，可以先保留 Metal 开关，等以后换上更大模型时再对比。