常见错误与排障索引

学习 AI 最常卡住的地方往往不是概念，而是环境、依赖、数据格式、接口、模型输入输出和工程边界。排障时先不要急着复制报错去搜索，而是先判断问题属于哪一层：环境、代码、数据、模型、检索、工具调用、部署还是缓存。

排障总流程

遇到错误时，按这个顺序检查：先保存完整报错和执行命令，再确认当前目录和运行环境，然后用最小输入复现问题，接着定位是依赖、路径、数据、参数还是业务逻辑，最后把解决方法写回学习日志或项目 README。

不要只看最后一行错误。很多 Python、Node、Docusaurus、RAG 或 Agent 错误的关键线索在报错中间，例如实际读取的路径、使用的 Python 解释器、请求的模型名、工具参数 schema 或命中的文档片段。

环境与工具错误定位树

看到的现象	先检查什么	最小复现方式	推荐回看
`command not found` 或命令找不到	当前终端、PATH、依赖是否安装、是否在项目根目录	运行 `pwd`、`which 命令名`、查看 package.json 或 requirements	开发者工具基础、环境准备
`ModuleNotFoundError` / `ImportError`	是否激活了正确 Python 环境，pip 是否装到同一个解释器	运行 `python -c "import 包名"` 和 `python -m pip show 包名`	Python 环境、包管理器
`docusaurus: command not found`	是否执行过 `npm install`，是否在项目根目录运行 npm scripts	运行 `npm run start` 而不是直接运行 `docusaurus`	环境准备、课程维护流程
Docusaurus 页面还是旧内容	`.docusaurus`、`build`、浏览器缓存、启动目录	运行 `npm run clean` 后重新启动	本页、课程维护流程
Git push 失败	远程地址、权限、网络代理、分支名、登录状态	运行 `git remote -v` 和 `git branch --show-current`	Git 与版本管理

Python 与数据错误定位树

看到的现象	先检查什么	最小复现方式	推荐回看
文件读不到	当前工作目录、相对路径、文件名大小写、编码	运行 `pwd`，再用最小脚本 `open("路径")` 测试	Python 文件读写
JSON 解析失败	文件是否是合法 JSON，是否一行一个 JSONL，是否有中文编码问题	复制一小段数据单独 `json.loads`	Python 文件与数据结构
DataFrame 列不存在	列名空格、大小写、header 行、读取分隔符	打印 `df.columns.tolist()`	Pandas 数据读取与清洗
图表中文乱码	字体配置、保存格式、运行环境	用最小中文标题图测试	数据可视化
SQL 查询为空	表名、过滤条件、连接库、事务是否提交	先查询前 5 行，再逐步加条件	数据库基础

机器学习与深度学习错误定位树

看到的现象	先检查什么	最小复现方式	推荐回看
模型分数异常高	是否数据泄漏，训练集和测试集是否重复，特征是否包含答案	只保留少量特征重新训练 baseline	特征工程、模型评估
训练分数高但验证差	过拟合、数据量、正则化、数据增强、划分方式	固定随机种子，对比训练/验证曲线	深度学习训练技巧
模型不收敛	学习率、数据归一化、标签格式、loss 是否匹配任务	用小数据集过拟合测试	PyTorch 训练循环
PyTorch shape mismatch	batch 维、通道维、序列长度、loss 输入格式	每层打印 tensor shape	PyTorch 基础、CNN/Transformer
GPU 不工作	驱动、CUDA、PyTorch 版本、device 设置	运行 `torch.cuda.is_available()`	深度学习环境

LLM 与 RAG 错误定位树

看到的现象	先检查什么	最小复现方式	推荐回看
API 调用失败	API Key、模型名、额度、网络、请求格式、超时	用一个最短 prompt 单独请求	LLM API 实践
输出格式不稳定	Prompt 是否明确 schema，是否有校验和重试	让模型只返回一个最小 JSON	结构化输出
RAG 答非所问	query、chunk、embedding、top-k、rerank、文档范围	只打印检索结果，不调用模型	RAG 基础与检索策略
检索不到相关文档	文档是否导入、metadata 是否保留、chunk 是否太大或太小	用原文关键词直接检索	文档处理与向量数据库
引用不可信	答案是否真的由命中文档支持，引用路径是否记录	对比答案句子和引用片段	RAG 评估
成本突然升高	上下文过长、重试过多、循环调用、模型选择	记录 token、请求次数和每步耗时	LLM 工程化

Agent 错误定位树

看到的现象	先检查什么	最小复现方式	推荐回看
Agent 无限循环	停止条件、最大步数、工具返回是否清晰、目标是否过宽	限制 3 步并打印每步计划	Agent 推理与规划
工具参数错误	schema 字段名、类型、必填项、示例是否清楚	直接手写一次工具参数调用	工具调用与 Function Calling
工具调用成功但结果不可用	工具返回格式、错误码、空结果处理	用固定输入调用工具并打印原始返回	Agent 工具策略
记忆污染	是否把错误信息或临时上下文长期保存	清空记忆后重跑同一任务	Agent 记忆工程
高风险操作失控	是否有人类确认、权限限制、审计日志	把工具改成 dry-run 模式测试	Agent 安全与 Guardrails
无法复盘失败	是否记录 trace、工具输入输出、状态和错误	对一次失败任务做 replay	Agent 可观测性

部署与工程化错误定位树

看到的现象	先检查什么	最小复现方式	推荐回看
本地能跑，部署不能跑	环境变量、文件路径、依赖版本、启动命令	在干净环境按 README 重跑	Docker 与部署
端口访问失败	服务是否启动、端口映射、防火墙、host 配置	本机 curl 健康检查接口	API 设计与部署
日志看不到关键错误	日志级别、异常捕获、请求 ID	人为触发一个错误并检查日志	日志与监控
线上结果和本地不同	模型版本、配置、数据索引、缓存	打印关键配置和版本	工程化最佳实践

排障记录模板

每次遇到问题，建议记录下面这些内容。长期积累后，它会变成你自己的工程经验库。

## 问题标题

### 错误现象
我执行了什么命令，看到什么错误。

### 完整报错
粘贴关键报错，不只贴最后一行。

### 复现步骤
1. 进入哪个目录
2. 执行什么命令
3. 使用什么输入或配置

### 排查过程
我检查了环境、路径、依赖、数据、参数或日志中的哪些内容。

### 最终解决方法
具体改了什么，为什么有效。

### 下次如何避免
README、脚本、验证命令或测试样例需要补什么。

排障的目标不是“尽快把这次错误压下去”，而是让下一次同类错误更容易定位。每解决一个真实错误，都应该把它沉淀为项目文档、验证脚本、日志字段或测试样例。

排障总流程​

环境与工具错误定位树​

Python 与数据错误定位树​

机器学习与深度学习错误定位树​

LLM 与 RAG 错误定位树​

Agent 错误定位树​

部署与工程化错误定位树​

排障记录模板​