# QWen 3.8 27B 新手部署指南 > Qwen3.8-27B 本地部署新手指南：llama.cpp router + pi 在 M4 Pro 上从下模型到跑通 agent，实测 11.4 tok/s。四个真踩进去的坑，以及当模型每秒只吐 11 个 token 时，prompt 该怎么写才能一次成型。 - 原文链接: https://laojin.blog/blog/20260826_local_qwen38_27b_pi_llamacpp - 作者: 老金 - 发布日期: 2026-08-26 - 标签: 本地大模型, llama.cpp, Qwen3, Apple Silicon, AI Agent --- ![QWen 3.8 27B 新手部署指南](https://pic-1258874139.cos.ap-hongkong.myqcloud.com/laojinblog/posts/20260826/00_cover.png) > 最近 Qwen 3.8-27B 很火，因为它几乎能达到近似 Opus 4.6 的效果。去年底，使用 Opus 4.6 可以干很多活了，如果将 Qwen 3.8-27B 部署在本地，相当于有了无限 token 的 Opus 4.6。但在部署过程中还是遇到一些曲折，老金将它们总结成这篇新手指南文章，供大家阅读。 --- ## 为什么是这套组合 老金本地部署的组合是 pi + llama.cpp + Qwen3.8-27B。 llama.cpp 负责把模型跑起来。相比 Ollama，它的 router 模式允许一个常驻进程管理多个 GGUF、按需装卸，并且暴露标准的 OpenAI 兼容接口，任何支持自定义 base URL 的客户端都能接。 pi 是 harness，把"模型"变成"能读写文件、能执行命令的 agent"的那一层。它自带 llama.cpp 的一等支持，这点后面会看到既是优势也是坑。 Qwen3.8-27B 在 Q4_K_M 量化下约 16.8 GB，64GB 内存的 M4 Pro 跑起来毫无压力。它带 vision projector 和原生 tool calling，后者是做 agent 的硬门槛。 > **前提**：本文假设你已经装好 Homebrew 和 Node 22.19+（pi 通过 npm 分发），以及 18 GB 以上的可用磁盘空间。 --- ## 部署三步：从下载到跑通 ![从模型下载到 pi agent 的部署链路](https://pic-1258874139.cos.ap-hongkong.myqcloud.com/laojinblog/posts/20260826/01_pipeline.png) ### 下载模型 要下两个文件：GGUF 本体（Q4_K_M 约 16.8 GB）和 vision projector（mmproj，约 1.4 GB）。后者别漏，router 靠它开多模态，缺了图片输入就是不可用。 别用浏览器点下载。17 GB 中途断一次网就得从头来，用官方 CLI 走，它自带断点续传和并发分片： ```bash pip install -U "huggingface_hub[cli]" mkdir -p ~/models/Qwen3.8-27B-Q4_K_M # 新版命令是 hf，老的 huggingface-cli 还能用但已标记废弃 hf download Qwen/Qwen3.8-27B-GGUF \ Qwen3.8-27B-Q4_K_M.gguf \ mmproj-F16.gguf \ --local-dir ~/models/Qwen3.8-27B-Q4_K_M ``` `--local-dir` 一定要加。不加的话文件会落进 `~/.cache/huggingface` 的哈希目录结构里，你拿到的路径是一堆摘要文件名，router 扫不出来，之后还得自己捞。 国内网络慢的话换个镜像端点，命令不用改： ```bash export HF_ENDPOINT=https://hf-mirror.com ``` 下完先确认它确实是 GGUF，顺便看一眼架构标识： ```bash head -c4 ~/models/Qwen3.8-27B-Q4_K_M/Qwen3.8-27B-Q4_K_M.gguf # → GGUF # 头部元数据里 general.architecture = qwen35 ls -lh ~/models/Qwen3.8-27B-Q4_K_M/ # Qwen3.8-27B-Q4_K_M.gguf 16.8G # mmproj-F16.gguf 1.4G ``` mmproj 的文件名必须以 `mmproj-` 开头，router 认的是这个前缀，不是文件内容。仓库里如果叫别的名字，下完自己 `mv` 一下。 ### 启动 llama.cpp router ```bash brew install llama.cpp ``` 装完先确认两件事。一是这个 build 认不认识 Qwen3.8 的架构标识 `qwen35`，新模型经常跑在旧版本前面；二是 Metal 后端在不在。 ```bash llama-server --list-devices # Available devices: # BLAS: Accelerate # MTL0: Apple M4 Pro (53084 MiB, 53083 MiB free) ← 要看到这行 ``` 然后以 router 模式启动。关键是不要传 `-m` 或 `--model`。一旦传了，它就退化成单模型模式，router 的按需装卸就没了。 ```bash llama-server \ --models-dir ~/models \ --no-models-autoload \ --jinja \ --host 127.0.0.1 --port 8081 \ -ngl 999 -c 32768 --flash-attn on ``` - `--jinja` 启用模型自带的 chat template，tool calling 依赖它 - `-ngl 999` 尽可能多的层交给 GPU - `-c 32768` 每个 slot 的上下文。这个模型原生支持 262144，但全开的话 KV cache 会吃掉大量内存 ```bash curl -X POST http://127.0.0.1:8081/models/load \ -H 'Content-Type: application/json' \ -d '{"model":"Qwen3.8-27B-Q4_K_M"}' # 27B 装载约 22 秒，轮询 GET /models 看 status ``` ### 接入 pi pi 通过 npm 全局安装。这里有两个容易踩的点：包名和命令名不一样，以及它对 Node 版本有硬要求（`engines` 写的是 22.19+），Node 20 上启动会直接被引擎检查拦掉。 ```bash node -v # 低于 v22.19 先升，nvm 用户记得 nvm use npm i -g @earendil-works/pi-coding-agent # 装的是 @earendil-works/pi-coding-agent，可执行文件叫 pi pi --version ``` pi 内置了 llama.cpp provider，文档里写的是进 TUI 后执行 `/login llama.cpp`，填入 router 地址，之后用 `/llama` 装卸模型、`/model` 选择模型。这条路是通的，而且能在 pi 里直接搜索下载 HuggingFace 上的 GGUF，体验最好。 > **坑： provider_not_found** > 但这个内置 provider 只在 TUI 里注册。一旦你想用 `pi -p` 做非交互调用，或者跑 `pi auth check --provider llama.cpp`，都会得到 `provider_not_found`。脚本化场景下这条路直接堵死。 解法是再配一份 `~/.pi/agent/models.json`，把 router 当作普通的 OpenAI 兼容服务接入。两条路指向同一个 router，互不冲突： ```json { "providers": { "llamacpp": { "baseUrl": "http://127.0.0.1:8081/v1", "api": "openai-completions", "apiKey": "local", "compat": { "supportsDeveloperRole": false, "supportsReasoningEffort": false, "thinkingFormat": "qwen-chat-template" }, "models": [{ "id": "Qwen3.8-27B-Q4_K_M", "reasoning": true, "input": ["text", "image"], "contextWindow": 32768, "maxTokens": 16384, "samplingParams": { "temperature": 1.0, "top_p": 0.95, "top_k": 20, "min_p": 0.0 } }] } } } ``` 几个字段值得解释： - `apiKey` 填个占位符就行，llama.cpp 不校验。但 pi 要求模型有 auth 配置才会在 `/model` 里显示，留空会导致模型"加载了但选不到"。 - `thinkingFormat: "qwen-chat-template"` 是关键。Qwen3.8 的 chat template 里带 `enable_thinking` / `preserve_thinking` 两个开关，这个格式会把 pi 的思考等级翻译成对应的 `chat_template_kwargs`。填错的话思考链要么关不掉，要么开不起来。 - `supportsReasoningEffort: false`，llama.cpp 不认 OpenAI 的 `reasoning_effort` 参数，不关掉会报错。 - `samplingParams` 直接用了 Qwen 官方推荐值（模型卡和仓库里的 `generation_config.json` 都有）。 配好之后验证： ```bash pi --list-models | grep llamacpp # llamacpp Qwen3.8-27B-Q4_K_M 32.8K 16.4K yes yes pi -p --model llamacpp/Qwen3.8-27B-Q4_K_M "读取 calc.py 并修复其中的 bug" ``` --- ## 性能实测：11.4 tok/s 意味着什么 同机对比，均为 4-bit 级别量化，均运行在 Metal 上： | 指标 | llama.cpp Q4_K_M | MLX 4-bit | | --- | ---: | ---: | | 解码速度 | 11.4 tok/s | 15.4 tok/s | | 预填充（11.6k prompt） | 88.7 tok/s | 95.9 tok/s | | 相同 prompt 重发 | 0.38 s | 需手动开启 | | 权重体积 | 16.8 GB | 16.1 GB | ### 解码慢 35%，但这不是配置问题 llama.cpp 在 Apple Silicon 上的解码确实不如 MLX，瓶颈在权重的内存带宽，不在内存容量。每生成一个 token 都要把 16.8 GB 权重完整读一遍，M4 Pro 约 273 GB/s 的带宽算下来上限就在 16 tok/s 附近。内存够用就行，富余多少不影响。 > **怎么确认真的跑在 GPU 上** > 除了 `--list-devices`，更直接的办法是生成过程中看进程 CPU 占用。老金实测是 3–7%。如果掉回 CPU 推理，这个数字会是 600% 以上。 ### prompt cache 比解码速度重要 ![同一 prompt 冷启动 131 秒，命中缓存后 0.38 秒](https://pic-1258874139.cos.ap-hongkong.myqcloud.com/laojinblog/posts/20260826/02_prompt_cache.png) 预填充两者几乎持平，因为这个阶段是计算受限而非带宽受限。11.6k token 的长 prompt 冷启动要 131 秒，这个数字在 agent 场景里相当致命，每轮对话都要重新吃一遍上下文的话根本没法用。 好在 llama.cpp 的 prompt cache 默认就开着，效果极好：同一个 prompt 重发，131 秒直接变成 0.38 秒（11623 / 11627 命中缓存）。多轮 agent 循环里，这个差距的分量远大于解码那 35%。 所以纯对话、单轮生成我会用 MLX。多轮 agent 还是 llama.cpp 划算。 --- ## 运行本地编码任务 老金用来测试的任务是让它写一个 AI 冥想应用的落地页。完整 prompt 如下： ```text 请作为一名前端专家，为一款名为 'Aura' 的 AI 冥想应用 编写一个现代、极简风格的 Landing Page（落地页）。 要求： 只输出一个单一的 index.html 文件，将 CSS 写在