Imported from KAN-H/llama-cpp-windows-deployment-skill (SKILL.md). Install upstream with npx skills add KAN-H/llama-cpp-windows-deployment-skill. Copyright stays with the author.

llama.cpp Windows 多模型部署与优化集成技能

版本: v3.6.0 | 基准硬件: RTX 5060 Ti 16GB + Intel U7 270K / CPU-only (48GB DDR5) | 平台: Windows 10/11 + WSL2 | llama.cpp 版本: b10056 – b10713+ | 更新: 2026-09-13（references 目录重整为 sessions/ / guides/ / assets/ 三类 + 新增 reference index（路径索引，§5A 项目内 / §5B 部署侧 分开）；model-profiles.json 同步补入 moe 块；新增第五章 MoE 显存预算与卸载、内建 MTP head 嫁接手册）

📚 references 导航：先看 ./references/INDEX.md —— 目录结构、每份文档的用途，以及权威代码路径表（历史文档中的旧路径一律以该表为准）。

一、When to Use（触发词）

二、Prerequisites（前置条件）

2.1 硬件要求

2.2 软件要求

• llama.cpp 预编译包（llama-b10056+-bin-win-cuda-13.3-x64.zip，Blackwell sm_120 原生支持）
• 模型文件：GGUF 格式（标准 / QAT-UD / MTP）
• NVIDIA 驱动正常，nvidia-smi 可运行（GPU 场景）
• PowerShell + CMD（BAT 脚本兼容）

2.3 目录规范

C:\models\
├─ chat\                          # Router Mode 扫描的对话模型目录
│  ├─ gemma-4-12b-it-Q5_K_M\     # 无 preset.json → 继承全局参数
│  │  └── model.gguf
│  ├─ gemma-4-12B-it-qat-UD-Q4_K_XL\
│  │  ├── model.gguf
│  │  └── mmproj-F16.gguf        # 多模态投影文件
│  ├─ Qwen3.5-2B-Q4_K_M\
│  │  ├── model.gguf
│  │  └── preset.json            # ctx_size: 32768
│  └── Qwen3.6-35B-A3B-MTP-GGUF\
│     ├── model.gguf
│     └── preset.json
├─ embedding\                     # Embedding 模型独立目录
└─ gemma4_mtp\                    # MTP Draft 模型集中存放
   ├── mtp-gemma-4-12b-it-Q8_0.gguf
   └── mtp-gemma-4-26B-A4B-it-Q8_0.gguf

三、Core Concepts（核心概念）

四、Deployment Workflow（部署工作流）

Step 1：环境校验与版本指纹

每次换 build 或换模型族前必做，防止参数 silent fail：

# PowerShell（llama.cpp 目录下）
.\llama-server.exe --help | Select-String "spec-draft-n-max"
.\llama-server.exe --help | Select-String "spec-type"
.\llama-server.exe --help | Select-String "draft-"

Step 2：选择部署模式

模式 A：Router Mode（多模型热切换）⭐ 推荐

@echo off
chcp 65001 >nul
title llama.cpp Router - RTX 5060 Ti
cd /d C:\llama.cpp

llama-server.exe ^
  --models-dir C:\models\chat ^
  --host 0.0.0.0 ^
  --port 8080 ^
  -fa on ^
  -c 8192 ^           :: 全局默认，保护 12B+ 模型
  -np 1 ^
  -t 16 ^
  --cache-type-k q8_0 ^
  --cache-type-v q8_0 ^
  --metrics ^
  --timeout 600

pause

关键规则：

• 不要在 Router 全局参数中设置 -ngl / -t 等硬件参数→在单个模型 preset.json 中定义
• 小模型（≤3B）通过 preset.json 覆盖 ctx_size 释放长文本潜力
• 大模型（≥12B）不设 preset.json→自动继承全局 -c 8192 保显存

Preset 模板（放入模型目录）

小模型（0.8B–3B）长文本配置：C:\models\chat\<model-dir>\preset.json

{
    "ctx_size": 32768,
    "n_gpu_layers": 99,
    "n_threads": 16,
    "flash_attn": true
}

大模型（≥12B）无需创建 preset.json，继承全局参数。

📎 Router Mode 参考脚本：./references/assets/router-mode-preset.bat（--models-preset 版，最贴合 preset 优先级设计）、./references/assets/router-mode-simple.bat（--models-dir 简单版）。两者均为 ASCII 通用模板，改顶部 LLAMA_DIR/MODELS_DIR/PORT 即可。

模式 B：单模型实例（专用端口）

适用于需要独占 GPU 资源的高负载场景，每个模型开独立端口。

Step 3：模型族专项配置

3A：Gemma 4 系列（含 QAT + MTP）

硬件匹配矩阵（RTX 5060 Ti 16GB）

核心参数（所有 Gemma 4 共用）：

-ngl 99 -fa on -np 1 -t 10 --batch-size 1024
--cache-type-k q8_0 --cache-type-v q8_0  :: QAT 对 KV 精度敏感，不要降 q4
--no-mmap --host 0.0.0.0

MTP 专有参数（Gemma 4 外挂 draft）：

--model-draft <path_to_mtp_draft.gguf>
--spec-type draft-mtp
--spec-draft-n-max 2-3    :: 5060Ti 保守给 2-3，Unsloth 官方给 4
--gpu-layers-draft 60     :: Q5 主模型时给 60，Q8 时给 50

⚠️ QAT-UD 与 MTP 不推荐同开：QAT-UD 是多模态主（带 mmproj），MTP draft 是纯文本 arch，b10056 会因 arch 不对齐 silent skip。QAT-UD 走裸跑 + --mmproj。 参考脚本 gemma4-menu-scripts.bat 菜单 7/9 保留 QAT+MTP 组合仅作实验入口（菜单已标注 [!] QAT+MTP 不推荐），正常使用请选 QAT 裸跑项（5/6）或非 QAT 的 MTP 项（1/2）。

26B-A4B MoE 特殊处理（2026-08-16 更新）：

• ⭐ 优先用 --fit on --fit-ctx <ctx> 让 llama.cpp 自动分层（本 build fit 默认 on，但 -ngl 被显式设置时会 abort）。实测：16GB 下 51K 上下文从硬编码 ngl 的 10.6 t/s 提升到 72-93 t/s（~7 倍），根因是显存临界导致 CUDA graph 回退（详见 references/sessions/20260816-session-experience.md）
• 手工 -ngld（40-50）作为 fit 不可用时的后备方案
• MTP draft 必须用 A4B 专用 GGUF（不可复用 12B draft），且只认官方 Q8_0（第三方 Q4_0 在 server 加载路径必崩）
• Context：128K 是官方甜点（ctx_train=262144、MRCR 128K=44.1%）；SWA 使 KV 随 ctx 增长极小（128K 仅 ~1.0GB）

3B：Qwen 系列迁移

三档路线速查：

⚠️ 拿 30B-A3B 硬开 draft-mtp 会报 model does not support MTP；拿 35B-A3B-MTP 还写 --model-draft 会多占显存。

采样参数（区别于 Gemma 4 的默认值）：

--temp 0.7 --top-p 0.8 --top-k 20 --repeat-penalty 1.05
--chat-template-kwargs "{\"enable_thinking\":false}"

Qwen3.6-35B-A3B-MTP 脚本要点：

• 删除 --model-draft、--gpu-layers-draft
• --spec-draft-n-max 3（5060Ti 16GB 推荐，可试 4）
• context 上限 32K（拉 64K 需降 KV 到 q4_0）

3C：Phi-4-mini CPU 推理（9GB 内存受限场景）

@echo off
chcp 65001 >nul
title Phi-4-mini (CPU - 9GB Safe Mode)
cd /d C:\llama.cpp

set "MODEL_DIR=C:\models\chat\Phi-4-mini-instruct-Q4_K_M"
set "CTX_SIZE=32768"       :: 从 32K 起测，稳定后试 48K/64K
set "BATCH_SIZE=256"
set "THREADS=16"

llama-server.exe ^
  --model "%MODEL_DIR%\Phi-4-mini-instruct-Q4_K_M.gguf" ^
  --ctx-size %CTX_SIZE% ^
  --batch-size %BATCH_SIZE% ^
  --threads %THREADS% ^
  --cache-type-k q4_0 ^     :: CPU 场景降 KV 精度保内存
  --host 0.0.0.0 ^
  --port 8083 ^
  --cors-origins localhost ^
  --no-mmap ^
  --no-metrics

pause

CPU 优化黄金法则：

• KV Cache 必须量化（q4_0 或 q2_k），否则 64K = 12.8GB 超 9GB 内存
• --batch-size 256，降低瞬时内存峰值
• 支持 --no-metrics 节省少量内存
• 不支持参数：--memory-limit、--max-batch-size、--numa

⚠️ BAT 注释提示：行末 :: 注释在 if() (...) 括号块内可能导致解析错误，如需在括号块内注释请改用 REM 语句。

📎 完整脚本参考：./references/assets/gemma4-menu-scripts.bat（Gemma 4 10 选项菜单）、./references/assets/qwen-scripts.bat（Qwen 三档部署脚本）、./references/assets/preset-templates.json（各场景 Preset 模板集合）、./references/sessions/20260803-session-experience.md（全量实测数据与经验沉淀）

3D：Qwen3.6-27B 稠密模型专项（64K + 高 ngl 提速）⭐ 2026-08-03 实测

架构关键：Qwen3.6-27B 实际是 64 层（48 层 Gated DeltaNet 线性注意力 + 16 层 Gated Attention）。KV 缓存极小（64K q8_0 仅 ~0.5GB），权重才是显存大头。

核心结论：128K 配置在 16GB 显存下必 OOM；改 64K + 更高 ngl 反而更快：

要点：

• ngl40 时 24 层在 CPU → 提升到 ngl48-52 后仅 12 层在 CPU，速度显著提升
• 统一参数：-c 65536 --cache-type-k/v q8_0 -t 12 --batch-size 256
• 27B MTP 实测健康度：draft acceptance = 0.921 / graphs reused = 15 / mean len = 2.59 ✅
• 对比：Gemma 4 26B-A4B 是 MoE（128 专家/8 活跃/4B active），解码每 token 只算 4B → 天然快 3-4 倍（55+ t/s），无需此优化

3E：纯 CPU 工具调用脚本（12B 以下，不占 GPU）

菜单式一键脚本 start-CPU-Toolcall-Launcher.bat（端口 8086，脚本顶部 PORT 变量可改；参考脚本），全部 -ngl 0、128K 上下文：

CPU 参数要点：

• -ngl 0 强制不占 GPU（可用 nvidia-smi 验证无 llama 进程）
• --cache-type-k/v q4_0（fast 档）或 q8_0（quality 档）
• -t <物理核数>、--batch-size 256 降低内存峰值
• 菜单标题直接标注实测速度（[57 t/s]）与能力（[!] NO tool calls），便于用户选型

新增模型已知问题（2026-08-16）：

• ⚠️ LFM2.5 工具调用：llama.cpp issue #26658——工具参数含引号/转义可能解析失败（规避：要求双引号无转义）
• ⚠️ llama-cli 单次测试必须加 -st（--single-turn）：-no-cnv 在 b10158 仍进交互模式等 stdin，用管道/Select-Object 时看似卡死（实为等输入），勿误判为 hang
• ✅ MTP 在 CPU 上实测生效：QwenPaw-heretic-MTP 27.3 vs 非 MTP 15.7 t/s（+74%），draft acceptance = 0.725；内置 MTP head 模型不要传 --model-draft
• 完整实测见 ./references/sessions/20260816-session-experience.md

3F：Qwen3.8-27B 专项（qwen35 架构 + 长会话 + 128K）⭐ 2026-08-29 实测

模型特性（GGUF 元数据实测）：

• arch=qwen35、65 层（blk.64 为 MTP/nextn 专用）、KV head 4×256、ctx_train=262144、内置 MTP（nextn_predict_layers=1，勿传 --model-draft）
• SWA 混合注意力：full_attention_interval=4（每 4 层 1 层全注意力，其余滑动窗口 4096）→ KV 增长慢：64K q8_0≈2.85GB / 128K≈5.28GB
• 官方采样：thinking temp 1.0/top-p 0.95/top-k 20/min-p 0.0/presence 0.0/repeat 1.0；non-thinking temp 0.7/top-p 0.80/top-k 20/presence 1.5
• reasoning_effort 经 --chat-template-kwargs "{\"reasoning_effort\":\"medium\"}" 传递（cmd 已验证）

16GB 部署速度矩阵（实测）：

128K 提速方法论（关键）：fit 在 128K 下偏保守；手工 -ngl 扫描可显著超过 fit（IQ3_S：fit 16.0 → ngl58+batch512 18.8，+17.5%）。ngl 过高会使显存打满（<200MB 余量）触发 CUDA graph 回退反而降速（ngl60=15.7）。流程：fit 基线 → -ngl 递减试探 → 取显存余量 ≥400MB 的最快档。

长会话稳定参数（实测 45K 上下文 5 轮零降速）：--reasoning-budget 8192 + --reasoning-format deepseek（防无限思考，Gemma 经验复用）+ --reasoning-preserve + --metrics；KV 保持 q8_0 不降精度；--cache-reuse 不支持（当前 context 自动禁用，勿加）。

Step 4：安全配置（WSL2 + Agent 对接）

set "API_KEY=sk-local-001"
set "CORS_ORIGINS=http://localhost:* https://localhost:*"

Agent 接入示例：

from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
    base_url="http://<宿主机IP>:8080/v1",
    api_key="sk-local-001",
    model="Qwen3.5-2B-Q4_K_M",
)

VS Code 自定义模型接入（customendpoint / chat-completions，2026-08-29 实测）：

• URL 用 http://<宿主机IP>:8084/v1：VS Code 跑在 WSL 远程时 localhost 指 WSL 内部，NAT 模式与 Windows 宿主隔离 → ECONNREFUSED 127.0.0.1:8084；或 .wslconfig 开 networkingMode=mirrored（Win11 22H2+）后可直接 localhost
• ECONNREFUSED 双根因排查：① 端口无服务（先启动启动器，netstat -ano | findstr :8084）② 跨主机 localhost 隔离（URL 改宿主机 IP）
• 宿主机 IP 获取：WSL 内 cat /etc/resolv.conf | grep nameserver 或 ip route | grep default
• 配置要点：maxInputTokens 必须 ≤ 服务端 -c（64K→约 60000，128K→128000）；settings 键名须与模型 id/name 一致；supportsReasoningEffort 勿含 llama-server 不支持的 "none"（建议 low/medium/high）；apiKey 与启动器 --api-key 一致
• 服务端须 --host 0.0.0.0 + --api-key（见上表）

Step 5：Tool Calling 工具调用（内置，无需安装）⭐ 2026-08-03 实测

llama.cpp 工具调用是内置功能，无需安装任何额外 tools。存在两套完全独立的机制：

关键结论（实测验证）：

• 通过 OpenAI API 连 VS Code 或 WSL2 Hermes：不需要 --tools all，工具由客户端自己驱动，无需额外参数
• --tools all 仅给 Web UI / 服务端 agent 场景使用
• 脚本配置方式：

set "AGENT_TOOLS=off"   :: off=关闭(默认) | all=启用全部内置工具
if "%AGENT_TOOLS%"=="all" ( set "TOOLS_ARG=--tools all" ) else ( set "TOOLS_ARG=" )

工具调用测试方案（11/11 模型全部 PASS，b10158）：

• Phase 1 能力探测：发带 tools 的请求，确认模型返回 tool_call
• Phase 2 两轮工具循环：调用 → 客户端执行 → 回传结果 → 模型基于结果继续作答
• 测试工具示例：get_current_weather {"location":"Beijing"} → 26°C 晴朗 ✅
• ⚠️ Phi-4-mini 不支持工具调用（实测确认）

Step 6：启动脚本工程化经验（2026-08-03/04 实战沉淀）

• 备份先行：任何脚本修改前先复制到 backup\（如 start-Gemma4-Launcher-WSL.bat.bak-20260803），确认字节数一致再改动，可随时回滚
• 按模型族拆分脚本：Gemma 专用 / Qwen 专用 / CPU 工具调用专用，端口独立（默认 8080 / 8083 / 8086，脚本顶部 PORT 变量可改，与现有服务冲突时调整）
• 菜单标注：实测速度标注到标题后（[57 t/s]）、破限模型特殊标注、不同 B 参数量化版写清（如 12B-Q5_K_M）
• 编码选择：见 Troubleshooting「脚本闪退」——新脚本推荐 UTF-8 + 全英文；既有 GBK 脚本保留并在编辑器中手动选 GBK

6A：模型清单自动同步器 update-launchers（2026-08-16 新增，2026-09-17 随技能发布）

• 位置：生成器随本技能发布 —— ./scripts/launcher_gen/ （update_launchers.py Python 3.11 纯标准库 + update-launchers.bat 纯 ASCII 入口 + llama_hub.py 交互门面）
• 怎么跑：在你自己的部署目录里设两个环境变量 —— LAUNCHER_DIR（缺省=脚本所在目录）与 CHAT_DIR（模型目录，无默认值，缺失即报错退出 2）；冷启动见 scripts/launcher_gen/README.md
• 运行时数据（写在 LAUNCHER_DIR 下）：launcher-models.json 注册表（UTF-8）、preset-overrides.json 参数源、backup/ 自动备份
• 作用：扫描 <models-dir>，自动同步 4 个工件——start-CPU-Toolcall-Launcher.bat / start-Gemma4-Launcher.bat / start-Qwen-Launcher.bat / models-config.ini（Router preset）
  • 模型目录被删 → 自动移除对应变量/菜单/启动块并重编号菜单；ini 僵尸段同步清除
  • 新模型目录出现 → 按家族自动生成默认参数条目（菜单标 [NEW]）：gemma→Gemma4 启动器（自动配对 gemma4_mtp draft 生成 +MTP 条目）/ qwen→Qwen / lfm→CPU / 其他→Qwen
  • 每次写入前自动备份 backup\<名>.bak-YYYYMMDD-HHMMSS
• 用法：双击（报告+确认）| --check 干跑（预览写 backup\preview\）| --yes 全自动 | --extract 从 3 脚本重建注册表 | --no-scan 按注册表原样渲染（回归）
• 要点：手工调参改注册表 JSON 而非直接改 3 个启动脚本（会被覆盖）；生成器严格按各脚本编码写出（Gemma4/Qwen=GBK 无 BOM、CPU/ini=ASCII、CRLF）；ini 相比旧 generate_ini.bat 修复了「文件名含 mtp 即被排除」的 bug（内置 MTP heads 模型现在也能进 Router）

工程缺陷修复经验（2026-08-29 实测）：

• make_auto 生成 group 必须带 "t":"group"；build_varmap/render_launcher/main 三处遍历 region 均须 .get("t") 防御——缺 t 键会 KeyError: 't'，第二次同步必崩（--audit 也在对应启动器前中断，掩盖后续所有问题）
• 多行参数串（layer_seg/extra）内嵌 \n 与 CRLF join 混合 → body 产生孤立 LF（bat 字节级污染）→ 构造 body 时先 s.split("\n") 扁平化再 "\r\n".join
• 字符串 replace 注入参数会静默失败（行顺序假设错误时）：注入后必须断言验证（统计 --reasoning-budget 8192 出现次数）；曾仅 --metrics 落地、budget/format/ubatch 全部漏掉
• render_launcher 增加重复 goto 断言（拦截手工漂移块/重复标签回归，goto 只命中第一个块导致旧参数生效）
• QUANT_RE 需覆盖新量化名（IQ\d_S 等），否则菜单量化显示 ?
• mmproj dtype（F16/F32/BF16）编码在文件名：--fix-mmproj 把静态引用同步到磁盘最新文件；自动条目按 mtime 最新优先

6B：参数知识库 + 26B 长会话降速实测修复（2026-08-16）

参数参考集（三源治理）：

• model-profiles.json：官方/实测参数卡片（Gemma4 全系含 QAT、Qwen3.6/3.5、GLM、Devstral、LFM、Phi 等，含采样/ctx/KV/MTP 规则/来源 URL/verified 级别）。官方 Gemma4：temp 1.0/top-p 0.95/top-k 64、256K ctx、QAT 唯一官方量化 UD-Q4_K_XL、MTP n-max 2 起步+2GB 内存；Qwen3.6 精确编码 temp 0.6/通用 1.0

📎 参数参考集：./references/assets/model-profiles.json。 ⚠️ 它只是一份参考集，不是任何东西的快照：verified: official 的来源 URL 采集自厂商文档，本技能未逐一复核，用前请自行确认可达性；verified: measured 是作者本机实测（硬件相关，只是参考点，不是保证）。生成器读的是你自己的那一份。

• 新模型自动条目三源合并：家族模板 → 知识库匹配覆盖 → 用户注册表最终覆盖；报告标注 profile 来源
• update-launchers.bat --audit：GGUF 头解析（arch/层数/SWA/KV 维度）+ KV 内存估算 + 采样对比 + 16GB 显存红绿灯，只读

26B-A4B QAT 长会话降速根因（实测，2026-08-16）：

• 真相：Gemma 4 是 SWA 混合注意力（30 层中 28 层滑动窗口 1024）→ KV 极小（64K 仅 ~0.4GB），KV 膨胀论不成立；瓶颈是 14.25GB 权重 + draft + mmproj 使 16GB 极度临界
• 实测基准（51K 上下文 tg t/s）：旧基线（ngl 硬编码+draft 层 24）10.6；draft 全 CPU 26.9；--fit on --fit-ctx 65536（权重留 ~2.4GB 在 host）+ draft 层 8 72-93（~7 倍）
• 关键证据：S1 日志 offloaded 31/31 layers to GPU（13,573 MiB）+ KV 839MiB + draft 425MiB + mmproj ≈ 超过 16GB → CUDA graph 回退 → 解码阶梯下降；--fit 自动分层后恢复
• 修复已写入启动脚本：菜单 6/8/17 与新增菜单 9「纯文本 Agent」：移除硬编码 -ngl（fit 自动分层；本 build fit 默认 on 但 ngl 被用户设置时会 abort）+ --fit-ctx 65536 + --gpu-layers-draft 8 + --keep 8192 + --metrics；agent 变体块内预算 2048
• 带 mmproj 时 ctx_shift 被自动禁用（源码）；纯文本 + --context-shift 仅对 n_predict=-1 无限生成生效（b10158 实测：有限 n_predict 仍在 64K 截断）。纯文本项核心收益是前缀缓存复用（实测第二轮 prompt_n=7，不再全量重算历史）
• 128K 上探可行：26B-A4B ctx_train=262144；SWA 使 KV 随 ctx 增长极小（128K 仅 ~1.0GB）；128K 是官方甜点（MRCR 128K 八针 26B=44.1%，256K 质量衰减）。实测 100K 上下文 pp=1480/tg=45.5 无 OOM 无截断。已新增菜单 9「26B-QAT + MTP 128K 多模态」并将纯文本 Agent 项升 128K（-c 131072 --fit-ctx 131072 --timeout 300）；26B 破限版菜单 14/15 已 fit 化（删硬 ngl + gld 8 + metrics，实测 tg=70）

五、MoE 显存预算与卸载 ⭐ 2026-09-13 新增

面向 16GB 卡跑 20GB+ MoE 模型（Qwen3.6-35B-A3B / Gemma4-26B-A4B 等）。 详细实测数据与推导见 ./references/guides/20260913-moe-offload-community-research.md。

5.1 ★★★ --fit 与 --n-cpu-moe 互斥（最易踩的机制坑）

--n-cpu-moe N 内部就是编译成一组 -ot 张量覆盖（blk.0..N-1 的 ffn_*_exps = CPU）， 而 common_fit_params() 只要发现 tensor_buft_overrides 非空就直接放弃 fit。

正确写法：MoE 条目只输出 --n-cpu-moe N，不要同时挂 --fit。

5.2 显存预算方程（替代粗糙的固定比例）

N = ceil( (W_non + KV + mmproj + draft + compute_buf − (VRAM − margin)) / E_layer )    0 ≤ N ≤ L

• W_non / E_layer 从 GGUF 张量表直读（ffn_*_exps 归专家，ffn_gate_inp/ffn_*_shexp 不算）
• N 不是 ceil(层数 × 固定比例)：专家字节按层非均匀（实测层间极差 0% / 17% / 17% / 31%） ⇒ 必须用真实累积曲线 cum(N) = Σ per_layer[0..N-1]
• 输出区间 [N_opt, N_safe]：N_safe 写进 params，N_opt..N_safe 作为实测阶梯
• ⚠️ 单点标定推不出斜率 —— 没有标定数据时明说「未标定」，不要编系数

两条独立方法互证（可信度依据）：GPU 行为反推 531 MiB/层 vs 张量表直算 518 MiB/层 ⇒ 差 2.5%。

5.3 ★★ prefill 免费杠杆：--batch-size / --ubatch-size 必须成对提升

⚠️ 陷阱：llama.cpp 要求 n_ubatch ≤ n_batch，超出部分静默 clamp，不警告。 只改 -ub 完全无效（实测 512/512 与 512/2048 的 VRAM 一 MiB 不差）。

机制：CPU 侧专家张量每层每个 ubatch 搬运一次，与 ubatch 大小无关 ⇒ ubatch 越大摊得越薄；解码不受影响。 代价：compute buffer 增大（标定斜率 ≈0.16 MiB / batch 单位）。

5.4 --load-mode none 不是「顺手换新写法」

社区实测：mmap + --n-cpu-moe 会掉 60% prefill（同一二进制 22.7K 上下文 1,293 → 2,145 t/s）。 ⇒ --no-mmap → --load-mode none 是性能修复，不是废弃改名。

5.5 n-cpu-moe 实测参考

⚠️ 任何「最优 n-cpu-moe」结论都必须同时标注模型和测量 ctx** —— 小 ctx（llama-bench 的 512）与真实 ctx 下不只是数值不同，连最优位置都可能不同。 下表刻意带全两列，不要跨行横比：

⇒ 同模型同 ctx 下，卸载层数越多越慢（Q5：n=20 → 68.8 vs n=27 → 62.0） ⇒ 卸载量应贴住显存判据下限，而不是「越保守越好」。

5.6 ⚠️ 两条路径必须同步（FND-064 会复发）

菜单启动器（.bat）与 Router（models-config.ini）是两套独立生成路径。 手动改了 override 后必须跑一次更新器，否则 .bat 侧仍是旧值 —— 不走 Router 直接双击启动器 = 再次 OOM。（本会话断言上线后立刻抓到此复发。）

六、MTP Health Diagnostics（健康诊断）

服务启动后，从 slot print_timing 日志提取三维度：

实测参考（Q5 + Q8 draft）：A=0.549 / L=2.10 / n-max=2 / R=283 → ✅ 全线绿。

嫁接版实测参考（社区微调 + 从 UD 量化版嫁接的 head）：A=0.736 / L=2.47 / n-max=2，解码 64.28 → 86.51 t/s（+34.6%），代价 +1,652 MiB。

内置 MTP head（nextn_predict_layers）

部分模型（如 Qwen3.6-35B-A3B 系）自带 MTP head：block_count 比普通层多 1（如 41 层 = 40 注意力层 + blk.40 head）， 且带 nextn_predict_layers=1。

⚠️ “模型能加载” ≠ “投机在跑” —— 缺少 nextn_predict_layers 时模型照样加载成功， 但那 20 个张量是死重量，永远不触发且不报错。 判断依据只有一个：acceptance 计数器非 null 且 > 0.3。

🔧 自动化诊断：运行 ./scripts/detect.ps1（Windows 原生 PowerShell）或 ./scripts/detect.py（跨平台 Python，Windows/Linux/macOS 通用，Python 3.7+）一键检测 CUDA 架构、MTP 指纹、驱动版本、模型文件和显存状态。两者功能一致，改动时需同步。

故障快速排查（30 秒版）⭐ 2026-08-29 新增

连接失败 / 启动异常时按序执行：

七、Troubleshooting（常见故障排查）

参考脚本编码现状说明（2026-08-05 修订）：references/assets/gemma4-menu-scripts.bat、qwen-scripts.bat、start-CPU-Toolcall-Launcher.bat 已统一为 UTF-8 + 全英文（纯 ASCII）+ 无 chcp，任意 Windows cmd 可直接运行无乱码（方案 B）。实测教训：UTF-8 中文注释 + chcp 65001 的混合脚本在中文 Windows cmd 下会被 GBK 误解析导致命令错乱（如 llama-server.exe 被截断成 erver.exe 报错），因此参考脚本不再使用中文。用户自建脚本若需中文界面，请用方案 A（GBK 编码 + 删 chcp + 去 emoji）。

八、Version Upgrade Notes（版本升级说明）

spec→draft 参数映射表（build 迁移到 --draft-* 命名时）

迁移后用 llama-server.exe --help 验证新参数存在（Step 1 指纹检测），并在日志确认 draft acceptance 健康。

九、Verification Checklist（验证清单）

部署完成后，Agent 自动校验以下八项：

• ctx 数值验证：日志 n_ctx_slot = <目标值>（128K→131072 / 64K→65536 / 32K→32768）
• 推理速度：tg ≥ 60 t/s（12B 标准）/ tg ≥ 85 t/s（12B QAT 128K）/ tg ≥ 1500 t/s prompt（26B）
• MTP 健康：draft acceptance > 0.5（如适用）
• WSL2 连通：curl http://<宿主机IP>:<port>/health → {"status":"ok"}
• 安全配置：无 API Key → 401；跨域仅允许配置来源
• 工具调用：Phase 1 探测 + Phase 2 两轮工具循环（如适用；Phi-4-mini 预期不支持）
• 脚本可启动：双击 .bat 不闪退（中文 Windows 注意编码，见 Troubleshooting）
• CPU 模式：-ngl 0 时 nvidia-smi 无 llama 进程（确认不占 GPU）

十、技能版本维护 SOP（2026-08-29 新增）

每次对技能内容做实质改动后，按序执行并勾选：

• 1. 更新 SKILL.md 头部版本行（**版本**: vX.Y）与更新日期/一句话摘要
• 2. 在 CHANGELOG.md 顶部追加版本条目（Added/Changed/Fixed 三段）
• 3. 同步 .agents 部署副本 —— 只同步技能载荷：SKILL.md、references/、scripts/。 docs/ 与 scripts/mtp-graft-package/ 不同步（见 references/INDEX.md §7）
• 4. 记录 one-line reason（可选写入 repo memory）
• 5. 验证副本逐字节一致（载荷范围）；若新文档引入了本机绝对路径，先改占位符再同步

⚠️ 禁止往技能载荷里写本机绝对路径（D:\...）。技能要能「换一台机器照样跑」—— 部署侧路径一律用 <llama-cpp-dir> / <models-dir> 这类占位符。

Skill End Agent 执行完成后应输出《部署验证报告》，包含以上八项指标及模型加载状态。