面向 macOS Apple Silicon 用户的本地大模型部署教程:基于 M5 Pro / 48GB 实测,覆盖 Ollama + MLX 与 GGUF 量化方案对比、MTP 投机解码加速、国内镜像下载与完整避坑。
最后验证:2026-09-15 · Ollama 0.33.3 · macOS 26(M5 Pro / 48GB 实测) 适用版本:Ollama ≥ 0.30。更早版本存在 MLX 大上下文超时 bug(问题 2),动手前先确认版本。
| 你的内存 | 推荐方案 | 文件大小 | 速度* | 质量 |
|---|---|---|---|---|
| 16GB | GGUF Q3_K_XL(应急) | ~12 GB | 较慢 | 中等 |
| 16-24GB | GSQ-RCO IQ3_S(省显存均衡) | ~12 GB | ~12.6 tok/s | 基本无损 |
| 24GB | GGUF Q4_K_M / Q5_K_M | 15-18 GB | ~22-30 tok/s | 中-高 |
| 32GB+ | MLX 原生版(推荐) | ~18 GB | ~40 tok/s | 高 |
| 48GB+ | Q8_K_XL(极致质量)或 MLX | ~29 GB | ~25 tok/s | 极高 |
* 速度均为 M5 Pro / 48GB 实测值,各代芯片内存带宽不同,请勿直接套用。24GB 内存跑 MLX 时权重 + KV 缓存余量极小,需下调
num_ctx否则触发 swap——32GB 起步才能获得上表体验,48GB 是本文完整实测环境。
| 量化档位 | 文件大小 | 内存占用 | 相对fp16劣化 | 推荐场景 |
|---|---|---|---|---|
| Q3_K_XL | ~12 GB | ~14 GB | - | 16GB内存应急 |
| Q4_K_M | ~15 GB | ~17 GB | +4.0% | 平衡选择 |
| Q5_K_M | ~18 GB | ~20 GB | +1.8% | 推荐甜点 |
| Q6_K_XL | ~23 GB | ~26 GB | +2.5% | 追求质量 |
| Q8_K_XL | ~29 GB | ~33 GB | +0.5% | 极致质量 |
| MLX nvfp4 | ~18 GB | ~21 GB | +3.2% | 速度优先 |
| GSQ IQ3_S | ~12 GB | ~13 GB | 基本无损 | 省内存均衡(见下) |
| GSQ IQ3_XXS | ~10 GB | ~11 GB | GPQA ~-1 分 | 极致省显存 |
| 模型 | 量化 | 体积 | 早期短基准·代码生成¹ | 严格 12 题·平均 decode² | 12 题质量 | 内存占用 |
|---|---|---|---|---|---|---|
| MLX 4-bit | NVFP4 | 18 GB | 40.8 tok/s | 29.9 tok/s | 12/12 全对 | ~21 GB |
| Q5_K_M | GGUF 5.6bpw | 20 GB | 22.4 tok/s | 14.9 tok/s | 12/12 全对 | ~20 GB |
| GSQ IQ3_S | 3.5bpw 混合 | 12 GB | 16.2 tok/s | 12.6 tok/s | 12/12 全对 | ~12 GB |
| GSQ IQ3_XXS | 3.0bpw 混合 | 10 GB | — | 12.5 tok/s | 12/12 全对 | ~10 GB |
¹ 早期短基准:短上下文、未统一温度、不含 MTP 叠加效应,单任务峰值速度(MLX 早期分项:写作 29.0 / 结构化 34.2 tok/s)。 ² 严格 12 题 A/B:temperature=0、12 题统一对照、四模型均开 MTP、串行跑完即卸载,更可控。两种测法口径不同,倍数不能直接相除,仅作量级参考。 补充:首 token 延迟均 3-4 秒(常驻);图片理解 MLX ~17s / Q5 ~24s(GGUF 需挂 mmproj)。
MLX 原生版(qwen3.8:27b-mlx) 是当前最优选择:速度快约 2 倍,首字延迟秒级。MTP 投机解码须手动开启(draft_num_predict 3),GGUF 与 MLX 通用,非 MLX 独占。
如果追求极致质量且内存充足,可选择 Q8_K_XL(8 位量化,几乎无损)。
详细对比请参考:性能对比与量化指南.md
# 查看内存
sysctl hw.memsize | awk '{printf "内存: %.0f GB\n", $2/1024/1024/1024}'
# 检测代理
for port in 7890 7897 1087 1080; do
curl -s -x http://127.0.0.1:$port -o /dev/null -w "%{http_code}" https://huggingface.co | grep -q 200 && echo "代理端口: $port" && break
done
| 内存 | 推荐版本 | 文件大小 | 生成速度(M5 Pro 实测) |
|---|---|---|---|
| 16GB | Q3_K_XL / Q4_K_M | 12-16 GB | 未实测(低于 Q5 档) |
| 24GB+ | MLX nvfp4(MLX 原生版)(推荐) | 18 GB | ~29.9 tok/s(12题A/B)/ ~40 tok/s(短基准) |
| 24GB+ | Q5_K_M | 18-20 GB | ~14.9 tok/s(12题A/B) |
| 24GB+ | GSQ IQ3_S | 12 GB | ~12.6 tok/s |
| 24GB+ | GSQ IQ3_XXS | 10 GB | ~12.5 tok/s |
| 36GB+ | Q6_K_XL | 23.56 GB | 未实测 |
| 48GB+ | Q8_K_XL | 29.30 GB | 未实测 |
速度列优先采用 2026-09-15 同条件 A/B(
temperature=0、12 题)数据;MLX nvfp4 在短上下文基准下冲到 ~40 tok/s。IQ 系列为 ISTA-DASLab GSQ-RCO 混合精度量化,省显存、质量基本无损(IQ3_XXS 在大规模知识基准上有 ~1 分边际退化)。MLX nvfp4 与 GGUF Q5_K_M 均需在 Modelfile 写draft_num_predict 3开启 MTP 才达上表速度。
# 方式一:Homebrew(推荐)
brew install ollama
# 方式二:直接下载
# https://ollama.com/download
# 方案一(推荐):MLX 原生版,速度快、自带视觉
export HF_ENDPOINT=https://hf-mirror.com # 国内镜像,可不设
ollama pull qwen3.8:27b-mlx
# 方案二(并发/长 agent 备选):GGUF Q5_K_M,llama.cpp 并发更稳
# ollama pull unsloth/Qwen3.8-27B-GGUF:Qwen3.8-27B-UD-Q5_K_M
nvfp4:一种 4-bit 浮点量化格式,把 27B 权重从 50 多 GB 压到 18GB 出头,精度损失克制,是 MLX 版又小又快的基础。
网络慢或 HuggingFace 访问不了,改用国内镜像:
# 镜像 A:走 hf-mirror.com
export HF_ENDPOINT=https://hf-mirror.com
ollama pull qwen3.8:27b-mlx
# 镜像 B:ModelScope(魔搭社区)
pip install modelscope
python -c "from modelscope import snapshot_download; snapshot_download('Qwen/Qwen3.8-27B', cache_dir='./models')"
# 再用仓库内 Modelfile 创建本地模型(见第五步)
更省显存(≥16GB):GSQ-RCO IQ3_S / IQ3_XXS
pip install -U "huggingface_hub[cli]"
hf download ISTA-DASLab/Qwen3.8-27B-GSQ-RCO-GGUF \
Qwen3.8-27B-GSQ-RCO-IQ3_S-mtp.gguf mmproj-Qwen3.8-27B-BF16.gguf --local-dir .
# 用第五步的 Modelfile 创建(FROM 换成本地 .gguf 路径)
GSQ-RCO 是 ISTA-DASLab 的学习式混合精度量化:IQ3_S 把 27B 压到 ~12GB 且质量基本无损(GPQA 仅差 0.5 分),比 Q4_K_M 更小更稳;IQ3_XXS(~10GB)更省,但知识题有 ~1 分边际风险。MLX 原生版速度约为 GSQ 混合精度的 2.4 倍;同机还要跑 MiniMax H3 等视频模型、显存吃紧时,GSQ IQ3_S 是省显存均衡首选。
MLX 原生版 ollama pull 后即为可用模型;GGUF(Q5 / GSQ IQ3)路线需显式写 Modelfile,挂上多模态模板与 MTP 投机解码——否则发图报错、且浪费模型自带的加速。
MLX 原生版(FROM 官方标签):
FROM qwen3.8:27b-mlx
PARAMETER num_ctx 262144
PARAMETER draft_num_predict 3 # MTP 投机解码(Qwen3.8 自带加速)
PARAMETER temperature 0.7
PARAMETER top_p 0.95
PARAMETER top_k 20
GGUF Q5_K_M(FROM Ollama 标签,需补多模态模板 + MTP + 视觉投影):
FROM unsloth/Qwen3.8-27B-GGUF:Qwen3.8-27B-UD-Q5_K_M
FROM ./mmproj-F16.gguf # 视觉投影(多模态必需,需单独下载)
TEMPLATE """<|system|>
<|end|>
<|user|>
<|end|>
<|assistant|>
<|reserved_special_token_145|><|end|>
<|end|>
<|assistant|>
<|reserved_special_token_145|><|end|>
"""
PARAMETER num_ctx 262144
PARAMETER draft_num_predict 3
GSQ-RCO IQ3_S / IQ3_XXS(FROM 本地 GGUF,结构同上,仅换 FROM 与 mmproj):
FROM ./Qwen3.8-27B-GSQ-RCO-IQ3_S-mtp.gguf # 换成 IQ3_XXS 用同名 -IQ3_XXS- 文件
FROM ./mmproj-Qwen3.8-27B-BF16.gguf
TEMPLATE """(与上方 GGUF Q5 完全一致的多模态模板)"""
PARAMETER num_ctx 262144
PARAMETER draft_num_predict 3
# GGUF / GSQ 路线创建模型
ollama create qwen3.8-q5 -f Modelfile.q5
ollama create qwen3.8-gsq-iq3s -f Modelfile.gsq
# macOS 用户级全局配置(Ollama 以用户 LaunchAgent 运行,无需 sudo)
launchctl setenv OLLAMA_CONTEXT_LENGTH 262144
launchctl setenv OLLAMA_NUM_PARALLEL 1
launchctl setenv OLLAMA_FLASH_ATTENTION 1
launchctl setenv OLLAMA_KV_CACHE_TYPE q8_0
launchctl setenv OLLAMA_KEEP_ALIVE 30m
# 生效配置:重启 Ollama 使环境变量生效
pkill -f "ollama serve" && sleep 2 && open -a Ollama
每个变量的作用:
| 变量 | 作用 | 不设置的后果 |
|---|---|---|
OLLAMA_CONTEXT_LENGTH=262144 |
全局默认 256K 上下文(生产值;131072 为省内存可选项) | 模型退回 4096 默认值,长文档被静默截断 |
OLLAMA_NUM_PARALLEL=1 |
并发槽位数(262144 时必须为 1,否则 KV 叠加触发 swap) | 多会话轮跑靠串行 FIFO,无需调大 |
OLLAMA_FLASH_ATTENTION=1 |
长上下文推理提速 30–50% | 速度慢 |
OLLAMA_KV_CACHE_TYPE=q8_0 |
KV 缓存量化,内存占用减半 | 内存占用高,可能触发 swap |
OLLAMA_KEEP_ALIVE=30m |
模型驻留内存 30 分钟 | 每次调用等约 6 秒冷启动 |
KV 缓存:模型生成时为「已处理过的文字」记录的临时存储,上下文越长占用越大。q8_0 把这块也压缩一档,省显存且精度几乎无损。
launchctl setenv在重启 Mac 后会失效,重启后重跑一遍即可;想一劳永逸,把变量写进 Ollama 的 LaunchAgent plist。
多会话轮跑(2026-11-07 复核):
OLLAMA_NUM_PARALLEL必须与OLLAMA_CONTEXT_LENGTH配套——262144 时只能为 1(262144×2 槽 KV≈20GB,叠加权重逼近 48GB 触发 swap);131072 时可设 2(总 KV 与 262144×1 相同)。实测 ollama 0.40.15 的 MLX runner + Qwen3_5 架构仍是单序列串行解码,但这不影响多会话轮跑——串行按请求 FIFO 轮换本身就是「每个会话执行一会再轮下一个」,配合有界上下文即可多会话互不饿死。客户端侧(Hermesmodel.ollama_num_ctx)可随时按需调整,会逐请求覆盖服务端 env。本机 launchd 服务实际路径是~/Library/LaunchAgents/com.user.ollama-serve-main.plist(KeepAlive 带环境变量拉起 serve),登录时com.user.ollama-loopback会把同一组值 setenv 进会话环境(兜底 App 自起 serve 的场景);验证实际生效值看ollama ps的 CONTEXT 列。不要并排放两个 ollama serve 的 plist(没重启机器时新写的那个永远不会被加载,改它等于改空气);通过 Ollama.app 更新后要留意 App 是否抢跑了 serve(它的环境没有 CONTEXT_LENGTH,会回落 32768)。详见《调优与避坑指南》2026-11-07 节。
# 查看模型信息
ollama show qwen3.8:27b-mlx
# 确认上下文长度已生效(应输出 262144,不是 4096)
ollama show qwen3.8:27b-mlx | grep num_ctx
# 测试对话
ollama run qwen3.8:27b-mlx "你好,简单介绍一下你自己"
也可以用仓库内的自动化脚本一次性跑完上述检查:
./verify-ollama.sh
测试图片理解(MLX 自带视觉;GGUF / GSQ 需 Modelfile 已挂 mmproj):
ollama run qwen3.8:27b-mlx "描述这张图片的内容" --images image.jpg
如需直接调用 /v1 接口验证(base64 编码图片):
python3 -c "
import base64, json, urllib.request
b64 = base64.b64encode(open('/path/to/image.png','rb').read()).decode()
p = {'model':'qwen3.8:27b-mlx','messages':[{'role':'user','content':[
{'type':'text','text':'描述这张图。'},
{'type':'image_url','image_url':{'url':f'data:image/png;base64,{b64}'}}
]}], 'max_tokens':4000, 'stream':False}
r = urllib.request.urlopen(urllib.request.Request(
'http://127.0.0.1:11434/v1/chat/completions', data=json.dumps(p).encode(),
headers={'Content-Type':'application/json'}), timeout=300)
print(json.loads(r.read())['choices'][0]['message']['content'])
"
下面以 MLX 原生版为例;若你选了 GGUF Q5 或 GSQ IQ3,把模型名换成
qwen3.8-q5/qwen3.8-gsq-iq3s即可。
# 测试对话
ollama run qwen3.8:27b-mlx "你好,请用一句话介绍你自己"
# 测试代码生成
ollama run qwen3.8:27b-mlx "写一个 Python 快速排序算法"
# 测试图片理解(MLX 自带视觉;GGUF/GSQ 需 Modelfile 已挂 mmproj)
ollama run qwen3.8:27b-mlx "描述这张图片的内容" --images image.jpg
Ollama 提供 OpenAI 兼容的 API:
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:11434/v1",
api_key="ollama"
)
response = client.chat.completions.create(
model="qwen3.8:27b-mlx", # 换成 qwen3.8-q5 / qwen3.8-gsq-iq3s 等你创建的模型名
messages=[{"role": "user", "content": "你好"}],
temperature=0.7,
max_tokens=2000
)
print(response.choices[0].message.content)
完整速度、体积与质量对比见上方「四模型性能总表」。严格 12 题 A/B 的原始数据、逐题校验与硬件对照见 A_B实测对比报告.md。
ISTA-DASLab 的 GSQ-RCO 把 Qwen3.8-27B 压到 IQ3_S(≈12 GB)/ IQ3_XXS(≈10 GB)且基本无损。我们在本机(M5 Pro / 48GB / Ollama 0.33.3)跑了 4 模型严格对照:temperature=0、统一 12 道题(agentic coding / 数学 / 知识 GPQA / 长上下文 / 严格 JSON / 中文写作),逐模型串行、跑完即卸载避免显存叠加。
| 模型 | 量化 | 体积 | 平均 decode | 质量(12 题严格校验) |
|---|---|---|---|---|
| MLX 4-bit(现状) | NVFP4 均匀 4.0bpw | 18 GB | 29.9 tok/s | 12/12 全对 |
| Q5_K_M | GGUF 5.6bpw 均匀 | 20 GB | 14.9 tok/s | 12/12 全对 |
| GSQ IQ3_S | 3.5bpw 混合 | 12 GB | 12.6 tok/s | 12/12 全对 |
| GSQ IQ3_XXS | 3.0bpw 混合 | 10 GB | 12.5 tok/s | 12/12 全对 |
注:上方「性能数据」里的 ~40.8 tok/s 是早期不同测法(短上下文/不同提示)的结果;本表为 temperature=0、12 题统一对照,更可控。两表都来自本机实测。
三个维度的结论:
选型建议(48GB Mac,主用 agentic coding + 长推理):
完整数据见 A_B实测对比报告.md 与 性能对比与量化指南.md。
这是补充实测,不是主推荐路线。结论:继续用 Ollama。
有读者问「本地推理工具里那个投机解码引擎(MTPLX)能不能把 Ollama 换掉」。
我们把它装进来跟 Ollama 硬碰了一场:同一份 27B MLX 权重、同一条 900 字长文 prompt、max_tokens=1200、各 3 轮取中位数。
| 引擎 | 首 token | 解码 tok/s | 峰值内存 |
|---|---|---|---|
Ollama 0.34.1(qwen3.8:27b-mlx) |
0.17 s | 26.61 | ~32 GB |
MTPLX 2.12.2 turbo + MTP |
1.10 s | 23.04 | 22.7 GB |
MTPLX 2.12.2 turbo --no-mtp |
2.17 s | 11.41 | 21.4 GB |
(口径:长文生成、单并发、num_ctx 131072。跟上面「四模型性能总表」的 ~30 tok/s 不冲突,那个是短上下文短输出的测法。)
关键在最后一行。 把投机解码关掉,MTPLX 只剩 11.41 tok/s,是 Ollama 的四成 —— 它裸解码比 Ollama 慢 57%; 全靠 MTP 拉回 23.04,还是差 14%。所以:
MTPLX 只吃 MLX 档案、Apple Silicon 专用;官方标的 87.6 tok/s 本机复现不出来(人家是 M5 Max + “重写刚写完的文件” + stock 设置)。
什么时候值得考虑它:内存紧张时(峰值低 10 GB),以及短输出 + 高接受率的 workload(代码续写、固定格式生成)。 长文生成用它基本白给。
完整数据、机制拆解(一个验证轮 84.6 ms 换 3 个 token = 28 ms/token,跟裸解码 30 ms/token 打平)
和六个部署坑(含「分片下坏了但文件大小完全正确 → 全词表 NaN」)见
MTPLX引擎实测-vs-Ollama.md。想自己复现用 local_bench.py。
把本地模型接进 Hermes / Claude Code / Codex 这类 agent 框架(长会话、多工具调用)时,很多人会撞上一个怪现象:
随便聊 1-2 轮,会话体积就涨到 1MB+、触发上下文超限告警;换远程 API 模型聊好几轮才 300KB,稳得很。
这不是模型笨,也不是 thinking 开关的错——是「拿不到真实 token 计数 + 窗口分母偏小 + 压缩摘要自己压自己超时失败 + 旧工具返回不裁」四个机制叠加。关掉 thinking 治不了超限(thinking 默认不进入发送账本),真正要修的是压缩和裁剪。
修法分两档:
micro_compact 每轮折叠旧工具结果 + 把压缩超时放宽到 300s。诊断顺序(换任何本地模型都通用:Qwen / GLM / Llama / Mistral…):
ollama ps 看真实 num_ctx;2. 框架发的是流式吗(流式 Ollama 不返 usage);3. 框架配置里的 context_length 是真键还是死键;4. 压缩摘要是 auto 还是外部模型、有没有 summary failed 日志;5. 有没有开裁剪旧工具结果。完整根因、实测证据、可直接复制的 config 键、自检清单见 本地模型会话语境膨胀避坑.md。
按现象索引的完整排查手册(9 个常见问题 + 根因 + 修复命令)见 TROUBLESHOOTING.md,以下为高频简答。
生产用 num_ctx 262144(见下方「多会话轮跑 2026-11-07 复核」);若内存吃紧可降到 131072 或 65536,仍不足再换更小量化(Q4_K_M)。
检查是否开启了 Swap,确保模型完全加载到内存。
MLX 原生版 qwen3.8:27b-mlx 自带视觉投影,直接发图即可,无需额外视觉模型。GGUF / GSQ 路线(Q5、GSQ IQ3 等)同属 GGUF 格式,需在 Modelfile 写入 Qwen 多模态模板并挂 mmproj(见弯路3)。
不需要。本地模型完全离线运行,无需联网。
单跑不会。2026-09-10 的 A/B 实测中,MLX 在 131072 上下文 + MTP 下 5 维题 2 轮 10/10 全过、零 OOM;GSQ / GGUF 路线(Q5、IQ3 等)同属 llama.cpp 引擎,单跑 131K 上下文同样稳定。之前偶发的「间歇性显存溢出」,根因是多个会话/进程同时调同一个 MLX 模型,KV 缓存显存叠加——不是 128K 上下文太大。
qwen3.8:27b-mlx(MLX,满血 131k + MTP),最快最稳。qwen3.8-q5(GGUF + llama.cpp,并发更稳);GSQ IQ3 同为 llama.cpp 路径,并发表现与 Q5 一致,但体积更小、速度更慢。感谢 Qwen 团队开源高质量模型;感谢 unsloth 提供优化的 GGUF 量化版本;特别感谢 ISTA-DASLab 的 GSQ-RCO 学习式混合精度量化,让 27B 模型在 ~12GB 显存下保持基本无损,是本文「省显存均衡」方案的基础。
完整踩坑过程与选型思路叙述(含三个弯路的根因复盘),仓库内提供两种格式:
欢迎提交 Issue / PR,补充其他硬件(M1–M4、不同内存档位)的实测数据,一起完善硬件对照表。
到 2026-10-05 为止,本仓库主动提进社区目录列表的 PR 一共 3 个,3 个都还没被合并:
| 列表 | PR | 状态 | 列表活跃度 |
|---|---|---|---|
| rafska/awesome-local-llm | #229 | 待合并 | ★2.9k,2 天前还在更新 |
| awesome-ai-tools/curated-local-ai | #5 | 待合并 | ★7,2026-03 后无人维护 |
| iCHAIT/awesome-macOS | #1139 | 待合并 | ★19k,43 天前更新 |
另外两条实测结论,记录在此免得后来人重踩:
sindresorhus/awesome),仓库描述里自己写着「Pull requests are temporarily disabled until I have a chance to catch up with the existing ones」——PR 入口是关着的,星再高也不收。顺带一句:PR 进目录只是「多一条外链」的信任票,不是「被权威认证」。gh pr create 用的是你自己账号,代提、代撤都行,但结果要自己盯。