排障索引

先按现象定位，再回到对应实验页。不要一开始就重装环境。

现象	先看什么	常见原因	回看章节
CUDA 找不到	nvidia-smi、CMake 日志	驱动可见但开发库缺失	Ubuntu 环境
llama-cli 不存在	build/bin	构建失败或路径不对	Qwen 基线推理
模型加载失败	文件名、文件大小、来源	GGUF 下载不完整或版本不兼容	Qwen 量化对比
首 token 很慢	prompt eval、prompt 长度	prefill 成本、冷启动、长上下文	机器学习推理基础
tokens/s 很低	eval time、GPU 是否参与	CPU fallback、低比特 kernel 不匹配	推理加速实验
Q4 更小但不更快	offload 日志、kernel 支持	反量化开销或瓶颈不在权重读取	推理加速基础
显存或内存爆	ctx-size、KV Cache	上下文过长、模型过大、系统进程占用	大模型量化与 KV Cache
输出乱码或风格异常	tokenizer、chat template	模型不是 instruct 版或模板不一致	Transformer 与 LLM 基础
API 无响应	server 日志、端口、host	服务未启动、端口不一致、防火墙	本地 API
Jetson 速度越跑越慢	tegrastats、温度、功耗模式	热降频、电源或散热不足	Jetson 环境

排障顺序

1. 保存原始日志。
2. 判断是环境、模型、runtime、参数还是服务层问题。
3. 只改变一个变量重试。
4. 在报告中记录失败现象和下一步。

失败日志不是脏数据。端侧部署报告需要失败样例来说明边界。