故障排查：症状 → 原因 → 修法
本地推理按模式失败。同样十来个症状占了几乎每个求助请求、每个都有一个无聊的原因和一个两分钟的修法。扫表、应用修法、然后读数字确认你真的修好了。
诊断表
| 症状 | 可能原因 | 修法 |
|---|---|---|
输出包含角色词元（user:、`< |
im_start | >`） |
| 瞬间空回复 | 模板渲染出“已完成”的对话、或 EOS 词元错了 | 修模板；查 EOS：提示词 |
| 重复你的问题而不回答 | 基座模型、不是 instruct 模型 | 用 instruct/chat GGUF |
| 加载时内存不足 | 权重 + 量化超过显存 | 更小的量化或更小的模型：显存计算 |
| 生成中途内存不足 | KV 缓存长过余量 | 更短上下文、KV 缓存 q8_0：KV 缓存 |
| 明明有 GPU 却 1–3 tok/s | 层还在 CPU 上 | 全量卸载（n_gpu_layers）：引擎参数 |
| 首词元慢、之后流快 | 预填充受限：提示词很长 | 缩短提示词、批处理、更快预填充：速度 |
| 无尽重复、短语循环 | 采样器太宽松、惩罚关着 | temp ≤ 0.8、repeat_penalty 1.05–1.1：采样 |
| 韩语输出乱码或生硬 | 模型韩语弱 | 多语种家族（Qwen、Gemma）：模型家族 |
| 输出句中截断 | 上下文窗口满或 max_tokens 太低 | 修剪上下文或抬高输出上限 |
| 好模型出非法 JSON | 自由形式采样 | 约束解码：结构化输出 |
| 模型无视你的指令 | 长提示词的迷失中段 | 目标在前、载荷在后、重复请求：提示词 |
| 加载即崩溃或 coredump | 下载损坏 | 校验校验和、重新下载 |
按症状先读、不按原因先读：对上你看到的、应用修法、再测一次。多数“我的模型坏了”的帖子止步于第 1、2、6 行。
五分钟起飞前检查
深入调试之前、收集事实：
nvidia-smi --query-gpu=name,memory.total,memory.used --format=csv # GPU + 显存
ls -lh model.gguf # 尺寸 vs 显存
llama-server --version # 引擎构建
如果模型文件大于空闲显存、第 4 行就是你的答案、任何标志都救不了你。如果 memory.used 在生成期间稳步爬升、那是 KV 缓存、不是泄漏。
正常长什么样
调试性能之前、先知道大概范围。7–8B Q4_K_M 模型、批 1 的解码速度：
| 硬件 | 解码 tok/s |
|---|---|
| 中档 GPU（RTX 3060/4060 级） | 30–60 |
| 高端 GPU（RTX 3090/4090 级） | 100–150 |
| Apple M 系列（统一内存） | 20–40 |
| 仅 CPU（现代 8 核） | 3–8 |
两条公式解释其中大部分：
decode tok/s ≈ memory bandwidth (GB/s) ÷ model size (GB)
VRAM needed ≈ weights + KV cache + 1–2 GB overhead
288 GB/s 卡上 4.5 GB 的 7B 量化理论上封顶在 64 tok/s 附近；现实预期 ~45–55。如果你在表的 2 倍以内、你的硬件不是 bug。
首词元时间（TTFT）短提示词应远低于一秒；它随提示词长度除以预填充吞吐增长（预填充跑解码速度的 10–100 倍）。一个 10k 词元提示词在首词元前花 20 秒是预填充受限、不是坏了。
显存记账：权重加载得好好的但之后 OOM、那是 KV 缓存或上下文长度、不是量化——KV 缓存。
工作流：一次换一个变量
一次改两样东西时 bug 会藏起来。沿这条链隔离——模型 → 引擎 → 配置 → 提示词：
- **基线。**已知好的模型、已知好的引擎、默认标志。聊天能用吗？那栈没问题。
- 换模型（同引擎、同标志）。坏了？是文件或它的模板。
- 换引擎（同模型）。坏了？引擎 bug 或标志翻译。
- **二分你的标志。**恢复默认、一次加回一个标志直到它坏。
- **转储渲染后的提示词。**当输出怪但能跑、渲染后的模板是真相所在。
边走边记笔记——“temp 0.8 能用、min_p 0.2 就坏”是诊断；“试了一堆、还是坏”不是。
如何好好求助
一个好的求助帖是一份实验报告。包括：
- 模型文件：确切名字、量化、和来源（
qwen2.5-7b-instruct-q4_k_m.gguf、哪个仓库）。 - 引擎和版本：llama.cpp 构建日期、Ollama 版本、vLLM 发布——引擎每周在变。
- 确切的标志或 API 调用：整条命令行或请求体、不是转述。
- 硬件：GPU + 显存（或 Mac + 内存）、如果 CPU 在扛层也写上。
- 观察到的数字：tok/s、TTFT、显存占用、和确切的错误文本（如有）。
- 你已经试过什么、结果变了什么。
复制粘贴骨架：
Model: qwen2.5-7b-instruct-q4_k_m.gguf (bartowski repo)
Engine: llama.cpp b4321 (llama-server)
Flags: -ngl 99 -c 8192 --temp 0.7
Hardware: RTX 4060 8GB / Ryzen 7 / 32GB RAM
Observed: loads in 21s, ~35 tok/s, TTFT ~1.2s, then OOM at ~6k ctx
Tried: -c 4096 → no crash; q8_0 KV → no crash
有这六个事实、多数问题一次回复就能映射到上表的某一行。本论坛正是为这类帖子存在的——带上实验报告、你会得到修法。