① 三秒速览
整条链路只有四个角色，每个角色一个决定性事实。
硬件
RTX 5090 32GB
Blackwell 架构 · CUDA 13.4。整卡 32,607 MB，UE 编辑器同开时占约 7.5 GB 桌面+引擎基础，留给模型的预算 ~21 GB。
模型
Bonsai-2 27B PQ2_0
三值量化底座（1.71-bit），qwen35 混合注意力：65 层里只有 16 层参与 KV cache，其余是固定大小的线性注意力——这就是能开 26 万上下文的原因。
推理栈
llama.cpp b10754
自己 CMake 编译起家，现用上游预编译 prism-b10754。KV cache 双 q4_0 量化，Flash Attention 常开，参数全部集中在 start_local_llm.bat 一处。
客户端
ZCode 直连 :11435
openai-chat-completions 原生协议 + 原生 tool_calls，不经任何 proxy（少一层就少一类故障）。空闲 180 秒显存还给 UE，再用时 7.6 秒唤醒。
② 架构全景
一条主干、一条旁路。关键决定：ZCode 不经 proxy，直连 llama-server。
最终系统结构：ZCode 直连 llama-server（OpenAI 兼容协议，tool_calls 原生）；proxy 只为 CherryStudio 的 Ollama 协议存在，不占显存。
为什么不走代理：ZCode 用的就是 openai-chat-completions，llama-server 原生支持，工具调用也是原生的（实测 finish_reason: tool_calls + 原生 JSON arguments + 结果回灌第二轮）。proxy 存在的唯一理由是 CherryStudio 的 Ollama provider 走 /api/chat——少一层就少一类故障。
③ 关键数字（全部实测，不是估算）
六个数字撑起整套方案的判断依据。
262,144
服务端 ctx（-c）
190,000
ZCode contextWindow
≈ 服务端 ctx 的 72%
68–74
真实负载 decode 速度 t/s
（KV4 + 无 MTP）
7.6s
休眠 → 满血唤醒
（显存 2.4 → 20.6 GB）
−4.35 GB
KV4 量化显存收益
质量 7/7 零退化
99.7%
prompt cache 命中率
（18,385 / 18,445）
④ 最终配置快速参考
两处配置 + 一条配对公式，当前生效版本（2026-10-04）。
llama-server 启动参数（由 start_local_llm.bat 统一维护，参数只有这一处）：
llama-server.exe -m Ternary-Bonsai-2-27B-PQ2_0.gguf ^ --host 127.0.0.1 --port 11435 ^ -c 262144 ^ -ngl 999 -np 1 ^ --no-webui ^ -fa on ^ -ctk q4_0 -ctv q4_0 ^ -b 2048 -ub 512 ^ --no-reasoning-preserve ^ --reasoning-budget 1000 ^ --mmproj Ternary-Bonsai-2-27B-mmproj-Q8_0.gguf ^ --sleep-idle-seconds 180 ^ --chat-template-file D:\_Qwen3.8-27b\_zcode_setup\qwen35_chat_template.jinja ^ -a "local,qwen3.8:27b,qwen3.8:27b-nvfp4,qwen3.8:27b-offload" ^ --metrics --log-file D:\_Qwen3.8-27b\_zcode_setup\llama_server.log
ZCode provider 配置（.zcode\v2\provider_config.json，能力声明部分）：
{
"api": { "type": "openai-chat-completions",
"baseUrl": "http://127.0.0.1:11435/v1" },
"model": { "properties": {
"contextWindow": 190000,
"supportsToolCall": true,
"supportsMidConversationSystem": false,
"inputFormat": { "supportsText": true, "supportsImage": true },
"outputFormat": { "supportsText": true }
}}
}
→ 190,000 × 1.26 + 2,563 ≈ 241,563 ≤ 262,144 ✓ 改一边必须改另一边。
⑤ 踩坑时间线（23 天）
从编译到 1.71-bit 换底座：每个节点都是一次真实事故或一次实测定案，详情见各子页面。
09-12
VS2026 + CUDA 13.4 编译 llama.cpp
09-13
NVFP4 模型下载完，llama-server 首启，66 t/s
09-15
CherryStudio 踩坑链：ctx 爆了、双进程抢显存
09-16
ctx 65536 + cont-batching 稳定；prefill 快 70%
09-17
ZCode 直连 :11435；假 ctx / 256 夹子 / 双实例全修
09-20
LF 行尾事故：22 个脚本静默失效，全量转 CRLF
09-22
换模型 Ternary Bonsai 2（三值量化）直切 :11435
09-26
--reasoning-budget 1000：思考 −76%，正文 0 → 4,820 字
09-29
mmproj 视觉启用：真实截图逐字读出
10-02
27 t/s 之谜 = UE 视口抢 GPU（非模型退化）
10-04
KV4 采纳（−4.35 GB）；MTP 实测负收益撤下
⑥ 十一条真因速览
排查结论一句话版——十一条里没有一条是"模型不行"，全是"喂给它的东西 / 启动它的方式"不对。逐条展开见排障页。
| # | 症状 | 真因 | 修法 |
|---|---|---|---|
| 1 | 只有一句话就没下文 | proxy 注入 max_tokens=256 | 删掉注入 |
| 2 | 反复无效响应 | contextWindow: 1000000 是假数据 | 改成真实值 |
| 3 | 压缩失败 12 分钟 | 38 万 token 云端老会话切过来 | 用本地模型就开新会话 |
| 4 | 重新连接 9/10 | reasoning_effort: high 模板拒绝 | 补丁模板 / LLM_THINK=0 |
| 5 | 开机后连不上 | 开机脚本 -c 16384 | 开机走统一启动脚本 |
| 6 | 新会话也压缩失败 | contextWindow 余量只剩 1,100 token | 降到 49152 起步 |
| 7 | 压缩 3 次后被放弃 | 窗口太小 + 工具输出大（抓整页网页） | 开大窗口 |
| 8 | context_exceeded 400 | ZCode 估算低估 26%，冲过服务端上限 | 服务端 ctx 做绝对缓冲 |
| 9 | 每天首次开机连不上 | .bat 是 LF 行尾，cmd.exe 执行不了 | 统一转 CRLF |
| 10 | 带截图的消息重连 | 模型无视觉却声明 supportsImage: true | 改 false（后启用 mmproj 再改 true） |
| 11 | 图片去掉仍重连 | 模板拒绝对话中间的 system 消息 | 模板改为渲染成 system 回合 |
⑥→ 深入阅读（四个子页面）
按问题域拆分：栈怎么搭、客户端怎么接、坏了怎么修、快不快为什么。
LLAMA-SERVER 栈
模型与推理服务
硬件基线 · 量化选型 · 编译与启动参数逐项解释 · 显存标定公式 · ctx 调优历史（8192 → 262144）· 休眠机制
ZCODE 接入
客户端配置与开机链路
provider 配置 · 两个数字配对 · 压缩线 65% 的算术 · 修改清单 · 开机自启双路径 · 6 个 UE 子智能体
排障手册
速查表与十三个真因
"又不响应了"先跑什么 · 症状→根因→修法→验证 · 压缩失败三种形态 · 每条都可展开
性能与调优
实测数据与优化全程
速度-上下文曲线 · UE 抢 GPU 归因 · token 估算偏差 · reasoning-budget · KV4 与 MTP 的完整复盘
能力边界（先记住再上手）：
- 啃大网页 / 大文档 → 用云端模型。实测总结一篇公众号文章（3.5 MB 页面），43 分钟任务里压缩 8 次占 17.6 分钟——是任务体量与窗口不匹配，不是配置问题。
- 看到"已自动压缩"就准备新开会话——压缩摘要在历史里累积（每压一次永久多 2~3.5K token），是唯一清不掉的固定成本。
- 旧云端会话不要切成本地模型——历史动辄几十万 token，必然触发压缩死锁。