4.4 常见报错排查与性能调优

4.4 常见报错排查与性能调优

模型能跑起来只是开始。真正部署 INT4 模型时，你会遇到各种报错和性能问题——有些是量化特有的，有些是 llama.cpp 通用问题，还有些是硬件层面的。这一节把我积攒的常见报错和调优经验整理出来，按"症状-归因-处置"的方式呈现，让你遇到问题时能快速定位。

我处理过大量的"INT4 模型跑得不对"求助，发现绝大多数问题集中在几个固定类型上。掌握这几个类型的判断方法，能解决 80% 以上的故障。

报错一：加载阶段就失败

CUDA error: out of memory

这是最高频的报错，通常发生在加载大模型或设置长上下文时。根因是显存不够，但要分清是哪种不够。

第一种是权重本身就放不下。比如 70B 的 Q4_K_M 权重约 40GB，单张 24GB 的卡显然装不下。处置是用更小的模型、跨多卡部署、或者用部分 offload（-ngl 设小一些，剩余层放 CPU 内存）。

第二种是权重放得下，但加上 KV Cache 后超了。这种情况加载时可能成功，但一对话就 OOM。处置是减小 -c（上下文长度），给 KV Cache 留够空间。4.1 节的显存账算法在这里派上用场——提前算好权重加 KV Cache 的总占用，而不是拍脑袋设参数。

CUDA error: no kernel image is available for execution

这个报错意思是 GPU 算力和编译的 binary 不匹配。常见于用老架构的卡（比如 Maxwell、Pascal）跑为新一代架构编译的 llama.cpp。llama.cpp 默认会为多种算力编译，但如果你用了自定义编译版本或预编译包，可能没覆盖你的算力。

处置是重新编译 llama.cpp，确保 CMAKE_CUDA_ARCHITECTURES 包含你的 GPU 算力（比如 70 表示 Volta，80 表示 A100，89 表示 Ada）。用 nvidia-smi --query-gpu=compute_cap --format=csv 查你的算力版本。

模型文件格式不兼容

报错信息可能是 "invalid magic number" 或 "unsupported gguf version"。根因是 llama.cpp 版本和 GGUF 文件版本不匹配——GGUF 格式在演进，老版本 llama.cpp 读不了新版本 GGUF，反之亦然。

处置是确保 llama.cpp 和量化工具用同一版本。从 GitHub 拉最新源码重新编译，工具链保持一致，是最稳的做法。不要混用不同来源的预编译包和模型文件。

报错二：能加载但生成异常

输出乱码或重复

加载成功，但模型输出的内容是乱码、无限重复、或者完全不合逻辑。这是最让人头疼的一类问题，因为它"能跑"但"不能用"。

第一个怀疑是量化损坏。用 4.3 节的困惑度测量验证——如果 PPL 异常高，说明量化文件坏了，需要用量化前的中间文件重新量化。重新量化时检查校准集是否正确、量化方法是否匹配模型类型。

第二个怀疑是采样参数问题。温度（temp）设太高会导致输出随机化严重，设太低会导致重复。top-p 太接近 1 会让低概率 token 混入。建议的起步参数是 temp 0.7, top-p 0.9，跑通后再根据效果微调。

第三个怀疑是 prompt 格式问题。DeepSeek 系列模型有特定的对话模板（ChatML 或自定义），如果 llama-server 的 chat template 没正确加载，模型的输入就是错的，输出自然乱。检查 GGUF 文件里是否嵌入了正确的 chat template，启动时看日志里是否正确识别。

输出质量明显下降（但还能用）

模型能用但质量明显不如原始模型——回答变笨、推理能力下降、专业领域表现退化。这可能是正常的量化损失，也可能是量化方法选择不当。

判断方法还是困惑度对比。如果 Q4_K_M 的 PPL 比 F16 高 10% 以内，质量下降在正常范围，接受它（或者换更保守的量化档如 Q5_K_M）；如果高 20% 以上，说明这个模型对这个量化方法不友好，换方法（比如从 GPTQ 换 AWQ，或从 Q4 换 Q5）。

报错三：性能问题

速度比预期慢很多

加载和生成都正常，但速度明显比官方 benchmark 慢。这类问题排查要从几个方向入手。

首先确认 GPU 真的在用。nvidia-smi 看 GPU 利用率，如果跑模型时利用率是 0 或很低，说明实际跑在 CPU 上（-ngl 没生效）。这是最常见也最容易被忽视的原因。

其次看是不是部分 offload 太多。如果你因为显存不够只 offload 了一半层，另一半在 CPU，速度必然慢。这种情况下要么换更大的卡，要么接受慢，要么换更小的模型。

第三看是不是 batch 太小或并发太低。llama-server 默认单请求处理，如果有并发需求，看 -cb（continuous batching）是否开启。批处理能显著提升吞吐。

首字延迟（TTFT）过高

用户发消息后等很久才看到第一个字。TTFT 主要由 prefill 阶段决定——上下文越长，prefill 越慢。如果你每次请求都带很长的系统提示词和历史，prefill 开销就大。

优化方向是控制上下文长度（用本书百万 QPS 教程提到的对话历史压缩），以及开启 prefix caching（llama.cpp 的 --cache-reuse 选项），让相同前缀的 prefill 结果复用。对于固定系统提示词的场景，prefix caching 收益很大。

性能调优的几个杠杆

把常见的性能调优手段整理一下。

GPU 利用方面，-ngl 尽量设满（全量 offload），除非显存不够。上下文长度 -c 根据显存余量设，不要盲目开大。批处理用 -cb 开启 continuous batching 提升并发吞吐。线程数 -t 在纯 CPU 模式下调（设成物理核数），GPU 模式下影响小。

采样参数方面，温度和 top-p 影响质量而非速度，但极端值（temp=0 或 temp=2）可能触发异常行为，建议在 0.3 到 1.0 之间。repeat penalty 防止重复，但太高会破坏正常输出，建议 1.1 左右。

内存方面，确保系统有足够的内存（CPU 内存），因为部分 offload 时剩余层要放内存，KV Cache 也可能 spill 到内存。内存不足会触发 swap，性能断崖式下降。

建立自己的故障排查清单

每个人的硬件和模型组合不同，遇到的报错也会有差异。建议你把每次遇到的报错和解决方法记录下来，形成自己的排查清单。久而久之，这个清单会成为你最宝贵的运维资产——下次遇到同样问题，30 秒就能定位。

我的清单里记了几十条，从"GGUF magic number 错误→换 llama.cpp 版本"到"70B 在 4 卡上 tensor parallel 报错→检查 NCCL 配置"。每次新环境部署时先过一遍清单，能避免重复踩坑。

这一节的关键

INT4 部署的常见报错分三类：加载失败（OOM、算力不匹配、格式不兼容）、生成异常（乱码、重复、质量退化）、性能问题（速度慢、TTFT 高）。排查要从症状出发定位归因，多数问题集中在几个固定类型。性能调优的核心杠杆是 GPU 全量 offload、合理的上下文长度、批处理和 prefix caching。建立自己的故障排查清单，是长期运维的资产。

下一节 4.5 给一份可复用的部署 Checklist 和跨硬件迁移的注意事项——把这一章的实战经验固化成可操作的清单。