4.4 报错排错实录：六个翻车现场与处置手册
4.4 报错排错实录：六个翻车现场与处置手册
本节摘要：本地推理的报错九成能归入三大类——文件问题、显存问题、配置问题。本节把首航过程中最常见的六个翻车现场逐一复盘：症状是什么、根因在哪里、修法有几步。读完这一节，遇到报错的第一反应不再是搜索，而是对号入座。
排错的正确姿势
先给方法论再给手册。llama.cpp 的报错信息偏底层，直接把报错文本粘进搜索框常常搜到一堆过期 issue。更高效的路径是三段式：先看报错发生在哪个阶段（编译、加载、生成），阶段锁定范围；再问最近改了什么（新文件、新参数、新版本）；最后用小模型复现——0.5B 文件能否跑通是区分「环境坏了」与「文件坏了」的试金石。下面六个现场按这个框架复盘。
现场一：编译阶段报错，找不到构建工具
症状：配置阶段直接失败，日志提示找不到编译器或生成器。根因：工具链没装全或没进环境变量——最常见的是只装了 Visual Studio 界面版而没勾 C++ 工作负载，或者装了 CMake 但没刷新终端环境。修法：回到 4.1 节的三条验证命令逐条执行，哪条没过补哪条。预防：装机后先跑一遍工具链验证再拉源码。
现场 two：加载阶段崩溃，日志戛然而止
症状：加载模型时程序异常退出，日志停在读取张量的中途。根因：文件不完整或损坏——下载截断、传输错位、磁盘坏块都会中招。二进制容器对完整性极其敏感。修法：重跑 2.3 节三关校验，哈希对不上就重下；哈希过了仍崩，用头部分析工具确认张量数量与规格一致。经验：加载崩溃优先怀疑文件，其次怀疑显存，最后才怀疑版本——顺序别搞反。
现场 three：显存不足，卸载失败或驱动重置
症状：日志报显存分配失败，或者运行中画面驱动重置。根因：-ngl 给得太满，权重加 KV 缓存加计算缓冲的总账超出显存——注意是三本账，新手只算了权重那一本。修法：把层数下调（例如从 99 降到 28 再二分试探），或者缩小上下文窗口。第 5.3 节的显存账本会教你精确预算，这里先记住应急口诀：降层数或降窗口，二选一先试。预防：运行前用 5.3 的公式预估，别拿最大参数赌运气。
现场 four：输出乱码或答非所问
症状：模型流畅地产出不知所云的文字，或中英混杂怪词。根因：对话模板错配——拿 base 版模型当聊天用，或者强制指定了错误的模板；另一种可能是文件损坏的隐性表现（2.3 节提过截断文件可能安静地产出乱码）。修法：确认下载的是 instruct 或 chat 后缀的对话版；让程序自动使用文件内置模板，别手动覆盖；仍乱码就回哈希校验。经验：乱码问题的排查优先级是模板、文件、版本。
现场 five：速度异常慢
症状：生成速度只有个位数每秒，或者远低于同硬件的公开数据。根因：按概率排序——一是显存只装下一部分，每生成一词都在跨总线搬运（第 5.2 节的实验证明这比纯 CPU 好不了多少）；二是构建时后端没编进去，GPU 在睡大觉；三是笔记本没插电或温控降频。修法：逐条验证——看启动日志 offloaded 行数、看配置日志后端是否启用、查电源模式与温度。经验：速度问题三成是搬运、三成是后端、其余是电源与温控。
现场 six：长中文输出出现截断或异常符号
症状：中文长回答中出现零星乱码字符，或个别词输出为空白。根因：中文的 token 化密度高（1.2 节讲过换算），同样的窗口额度中文实际容量更小，长对话逼近上限时尾部 token 被异常切分；低概率是极低比特量化在生僻字上的损失。修法：调大 -c，或清理对话历史；Q4 以下档位遇到生僻字异常可换 Q5 以上对照验证。
排错决策总览
图 4-3 报错对号入座决策树
一份排错 checklist
收束成一张可打印的清单，按顺序走完能解决绝大多数问题：
- 用 0.5B 小模型复现，分清环境问题还是文件问题；
- 文件侧：哈希、头部分析、规格比对三关重跑；
- 显存侧：核对权重、KV 缓存、计算缓冲三本账（详见 5.3）；
- 配置侧：确认后端编译进去了、层数与窗口组合在预算内、模板未手动覆盖；
- 环境侧：插电、性能模式、温度与降频；
- 全部通过仍异常：固定种子最小参数复现，然后升级版本重试。
现场七：服务模式下端口被占或无法访问
症状：服务启动报端口绑定失败，或本机能访问、局域网其他设备不行。根因：前者是端口已被别的进程占用（上一场实验的服务没关干净是惯犯）；后者是服务默认只监听本机回环地址，没开对外监听。修法：换端口或找到占用进程；需要局域网访问时把监听地址改为通配地址，并同步配置访问密钥——对外监听与裸奔是同义词，第 7 章会展开安全基线。经验：网络类问题先分清「监听侧」与「访问侧」，两侧分别验证比笼统重启有效。
现场八：中文乱码与编码疑云
症状：命令行窗口里中文输出变成问号或方块。根因：多数不是模型问题，而是终端编码——传统命令行窗口默认的编码与模型输出的不符；少数是模型词表本身不含中文（选错模型）。修法：把终端切到新式终端并设为 UTF-8 编码；确认下载的是支持中文的模型。经验：编码问题的判别试金石是「同一命令换个终端是否复现」——换了就好是终端问题，依旧乱才是文件问题。
自查三问
一问：排错的第一反应为什么是小模型而不是搜索？答：0.5B 复现能一次区分环境问题与文件问题，搜索到的多半是别人的环境。二问：显存不足报错为什么不能只降层数？答：层数与窗口共同决定总账，有时降窗口一档比降十层更有效——账本思维直接决定排错路径。三问：什么时候该停止折腾？答：同一假设三试无果就换分支；全清单走完仍异常，升级版本或求助社区，时间成本也是成本。
排错的心态建设
手册之外给三点心态建议。别在错误的方向上勤奋：同一处报错反复试同类方法三次仍无果，说明假设错了，回到决策树换分支。留现场快照：改动生效前的参数与日志各存一份，回滚比回忆可靠。把解法写回自己的手册：每次排完错，用三行把「症状、根因、修法」记进自己的笔记——这本实验志的方法论，最终要长在你自己的文档里。
常见问题
报错信息是英文且很底层，有必读优先级吗？
有。错误类别的关键词优先级最高（显存、文件、权限），其次是出错的模块名，最后才是具体细节。先抓类别关键词对应本节的现场编号，再回日志找模块上下文，效率最高。
问题排查到「玄学」层级怎么办？
重启大法在本地推理里真的有效：清后台、重插电（笔记本完全断电一次）、重跑。显存状态残留与驱动瞬时异常真实存在，玄学一次之后若复现，再回到系统性排查。
哪些问题值得上报社区？
先自查清单走完、最小复现做出来、版本信息与日志摘录备齐——满足这三条的报错帖是社区欢迎的优质帖子；在此之前，大概率只是自己环境的问题。
本节要点回顾
- 三段式定位：先看阶段、再问变更、小模型复现，比盲目搜索高效得多；
- 加载崩溃先怀疑文件，显存不足先算三本账，速度异常先查分层与后端；
- 乱码的排查顺序是模板、文件、版本，绝大多数是模板错配；
- 排错 checklist 建议打印随手放，六步走完解决九成问题；
- 至此基线环境彻底立稳，第 5 章开始在这台机器上做真正的调参实验。