3. macOS（Apple Silicon）编译与Metal支持

任务目标

在Apple Silicon Mac上从源码编译llama.cpp，启用Metal GPU加速，并通过一次短文本推理验证Metal后端生效且能观察到加速效果。

环境与依赖

• Apple Silicon Mac（M1/M2/M3系列），macOS 13+
• Xcode Command Line Tools：xcode-select --install
• CMake 3.14+：brew install cmake
• Git：brew install git

编译步骤

1. 克隆仓库并进入目录：

git clone https://github.com/ggerganov/llama.cpp.git
cd llama.cpp

2. 创建构建目录并启用Metal：

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

编译完成后，可执行文件位于 build/bin/ 下。Metal框架在Apple Silicon上是默认启用的，若需确认，可在CMake缓存中检查 GGML_METAL 是否为 ON。

模型准备

下载一个量化后的公开模型用于测试（以TinyLlama 1.1B Q4_K_M为例，约670MB）：

curl -L -o models/tinyllama-q4.gguf \
  https://huggingface.co/TheBloke/TinyLlama-1.1B-Chat-v1.0-GGUF/resolve/main/tinyllama-1.1b-chat-v1.0.Q4_K_M.gguf

运行与验证

执行一次短文本生成，观察日志中的后端加载信息：

./build/bin/llama-cli -m models/tinyllama-q4.gguf \
  -p "Hello, my name is" -n 32 --no-display-prompt

验证通过条件：

• 启动日志中出现 llama_model_load: offloading 20 layers to Metal 或类似字样，表明Metal后端已加载。
• 生成过程无报错，输出32个左右的自然文本。
• 对比CPU-only编译（-DGGML_METAL=OFF）的耗时，Metal版本在Apple Silicon上通常有2～5倍加速（具体数值因芯片型号和模型大小而异，以实际观察到的tok/s提升为准）。

常见问题

• 编译报错找不到Metal：确认已安装Xcode Command Line Tools，并执行 sudo xcode-select -s /Applications/Xcode.app/Contents/Developer 指定开发者目录。
• 运行时提示 Metal device not found：确认当前设备为Apple Silicon（uname -m 应输出 arm64），且macOS版本不低于13.0。
• 显存不足：若模型较大导致Metal分配失败，可添加 -ngl 20 参数减少offload层数，或改用更小的量化模型。