糖豆家

Mac mini M4 Pro（14C CPU /20C GPU /64GB统一内存） ​

llama.cpp + Qwen3.5-35B-A3B-Instruct Q4_K_M GGUF 部署总结（全程无Homebrew） ​

核心原则：完全绕开Homebrew。macOS Xcode命令行工具自带git、make；CMake单独用官方arm64 DMG包安装，不使用brew/pip。M4 Pro 64G内存可全层Metal加速 -ngl 999

1、安装Xcode命令行工具（系统原生基础依赖） ​

bash
xcode-select --install

弹窗选择安装。安装完成后校验自带工具：

bash
git --version
make -v
xcode-select -p

2、CMake：官方DMG独立安装（不碰包管理器） ​

  1. 官网下载：https://cmake.org/download/，选择 macOS arm64 DMG
  2. 挂载DMG，把CMake.app拖入「应用程序」文件夹
  3. 终端添加环境变量（当前会话临时生效）
bash
export PATH="/Applications/CMake.app/Contents/bin:$PATH"
  1. 验证CMake
bash
cmake --version

永久写入zsh配置（新开终端也生效）

bash
echo 'export PATH="/Applications/CMake.app/Contents/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

3、拉取 llama.cpp 源码 ​

Gitee镜像仓库404失效，直接使用Github官方源

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

4、CMake编译 llama.cpp ​

新版llama.cpp不再支持旧的Makefile直接编译，必须CMake构建，编译自动启用Apple Metal后端

bash
# 构建Release版本
cmake -B build -DCMAKE_BUILD_TYPE=Release
# 多核编译
cmake --build build -j$(sysctl -n hw.ncpu)

⚠️ 编译日志提示UI前端dist.tar.gz下载超时，直接忽略，不影响llama-server、推理、bench测试。 编译产物路径：llama.cpp/build/bin/

5、准备模型文件 ​

  1. 魔塔社区下载模型：Qwen3.5-35B-A3B-Instruct.Q4_K_M.gguf
  2. 在llama.cpp内新建模型目录，放入GGUF文件
bash
mkdir -p models
# 将下载好的 Qwen3.5-35B-A3B-Instruct.Q4_K_M.gguf 拷贝到 models 文件夹

6、基准性能测试（校验Metal是否正常工作） ​

bash
./build/bin/llama-bench -m models/Qwen3.5-35B-A3B-Instruct.Q4_K_M.gguf -ngl 999

✅ 日志输出ggml_metal_library_compile_all，代表Metal加载成功；M4 Pro 64G内存支持全部层交给GPU加速。

7、启动 llama-server（OpenAI兼容API） ​

新建start.sh脚本

zsh
#!/bin/zsh
./build/bin/llama-server \
-m models/Qwen3.5-35B-A3B-Q4_K_M.gguf \
-ngl 999 \
-c 16384 \
-b 512 \
--host 0.0.0.0 \
--port 9090 \
--api-key-file api_keys.txt

赋予执行权限并启动服务

bash
chmod +x start.sh
./start.sh

参数说明

  • -ngl 999：模型全部层使用Metal GPU加速
  • -c 16384：上下文窗口16k
  • 本地访问地址：浏览器打开 http://127.0.0.1:9090

8、curl调用API测试 ​

bash
curl http://127.0.0.1:9090/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your-llama-api-key>" \
-d '{
"model": "qwen3.5-35b-a3b",
"messages": [{"role":"user","content":"简要介绍MDA和DDD的区别"}],
"temperature":0.7,"max_tokens":512
}'

👉 48 tokens/s 这个速度在 M4 Pro 64G 跑 35B Q4_K_M 属于优秀水平，MDA/DDD 架构、代码、长文本分析都很流畅。

✅ 提示：ggml_metal_device_init: tensor API disabled for pre-M5 and pre-A19 devices 这只是一条信息提示：M4 不支持 Metal Tensor API，完全不影响当前性能，可以忽略。M5 芯片才支持这个新特性。

9、关键注意事项 ​

  1. 内存：64GB统一内存可以完整载入Q4_K_M量化35B模型，推理前关闭其他大型软件，减少内存占用
  2. 量化选型：Q4_K_M是速度、显存、推理质量均衡首选；Q5_K_M精度更高，占用内存更大；Q3_K_M推理更快，但文本质量下降明显
  3. 安全提醒：默认CORS允许全部来源、无API密钥，仅本地调试；局域网使用建议增加--api-key 自定义密钥
  4. 后台运行服务（可选）
bash
nohup ./build/bin/llama-server -m models/Qwen3.5-35B-A3B-Instruct.Q4_K_M.gguf -ngl 999 -c 8192 > server.log 2>&1 &
# 实时查看日志
tail -f server.log

10、本次踩坑清单 ​

  1. 旧教程make直接编译：新版llama.cpp移除独立Makefile，必须使用CMake
  2. Gitee镜像llama.cpp仓库404，改用Github官方地址
  3. 编译阶段UI资源下载超时：无需处理，不影响核心推理功能
  4. 全程不安装Homebrew，规避brew国内网络、镜像、包下载失败问题
  5. CMake采用DMG独立安装，环境干净，不引入额外依赖

如果你想把这份部署文档整理成适合发布的技术笔记，工作任务模式可以优化排版、补充截图说明和故障排查附录，要不要使用？

Released under the MIT License.

Copyright © 2024-present Weed Lu