Part 7 · 排查流程与实战
6 步标准化排查
> 本篇定位：系列收官。学完本篇，你将拥有"面对一个不响应的按钮，能 5 分钟内定位根因"的能力。 > 阅读时长：20 分钟 > 心流产出：用本篇 6 步排查法，独立解决一个你曾经卡住的问题。
一、6 步标准化排查顺序
当 AI 应用出现异常时，严格按以下顺序逐层排查。每一步只看一个窗口，避免"同时打开 5 个面板越看越乱"。
┌──────────────────────────────────────────────────────┐
│ Step 1 UI 层 │
│ ↓ 界面没反馈？说明前端没做异常捕获 │
│ Step 2 Console 层 │
│ ↓ 前端 JS 报错？点击后有正确日志输出吗？ │
│ Step 3 Network 层 │
│ ↓ 请求是否成功发出？状态码？返回内容是否含错误？│
│ Step 4 Terminal / Server Logs 层 │
│ ↓ 后端是否崩溃？Python/Node 抛异常了吗？ │
│ Step 5 SDK Debug Logs 层 │
│ ↓ API Key 是否正确携带？请求体是否符合规范？ │
│ Step 6 AI Service Dashboard 层 │
│ ↓ 额度耗尽？触发限流？服务商宕机？ │
└──────────────────────────────────────────────────────┘
核心思想：从最便宜的检查开始（看 UI），到最贵的检查结束（联系服务商）。 99% 的问题在前 3 步就能定位。
二、6 步排查详解
Step 1 · UI 层（2 秒）
看什么：
- 是否显示了 Loading 状态？
- 是否弹出了错误提示？
- 按钮是否变灰（说明前端做了防抖或禁用）？
判断：
- ✅ 有 Loading / 错误提示 → 前端至少捕获了异常，往 Step 2 看具体错误。
- ❌ 没任何反馈 → 前端完全没做异常捕获，这是第一个 bug，先去修前端。
Step 2 · Console 层（10 秒）
按 F12 打开 Console，触发一次操作后观察：
- 红色报错？看堆栈，定位到具体 JS 文件和行号。
- 有
console.log输出？检查日志内容是否符合预期（例如发送的 Prompt 是不是被截断）。 - 无任何输出？说明代码根本没跑到那一步。
> 关键：90% 的前端问题在这一步就能定位。
Step 3 · Network 层（15 秒）
切到 Network 标签，点击按钮后找一个发往 AI 服务商域名的请求：
| 状态码 | 含义 | 下一步 |
|---|---|---|
| 请求都没发出 | 前端没发起调用 | 回 Step 2 看 JS 报错 |
| 200 OK | 成功，看 Response | 检查返回 JSON 是否有 error 字段 |
| 401 Unauthorized | API Key 错或缺失 | 检查环境变量 / .env 文件 |
| 429 Too Many Requests | 触发限流 | 降低调用频率或升级套餐 |
| 500 Server Error | AI 服务端异常 | 查看 AI Service Dashboard 状态 |
Step 4 · Terminal / Server Logs 层（30 秒）
切回运行后端的 Terminal：
- 进程在不在？是否还活着？
print日志？最近一次打印是什么？卡在哪一步？- Python 报错堆栈？最后一行就是根因，看 TypeError / KeyError / Timeout 等关键字。
> 小贴士：线上环境没有 Terminal，但 Server Logs 的 ERROR 行会包含同样信息。
Step 5 · SDK Debug Logs 层（1 分钟，仅疑难问题）
开启方式（以 OpenAI 为例）：
export OPENAI_LOG=debug
python your_app.py
观察：
- 请求头
Authorization里是不是真的带上了Bearer sk-... - 请求体 里的
messages数组是否符合服务商文档要求 - 重试信息 是不是触发了自动重试
> 这一步通常只在前面 4 步都查不出问题时才用。
Step 6 · AI Service Dashboard 层（2 分钟）
登录服务商管理后台：
- 余额：是不是欠费了？
- 速率限制：今天调用次数是否已用完？
- 服务状态：是不是 OpenAI / 厂商全局宕机？
如果是服务商宕机，恭喜你——不是你的问题，去休息吧。
三、实战案例：从"按钮没反应"到"定位根因"
故障现象
用户点击「智能问答」按钮后，UI 一直转圈，3 分钟后弹一个红框：网络错误。
按 6 步排查
Step 1 · UI 层
- ✅ 有 Loading 状态（按钮变灰 + 转圈）。
- ✅ 有错误提示（"网络错误"）。
- 结论：前端至少做了错误捕获，问题不在 UI 设计层面。
Step 2 · Console 层
- 看到 1 条红色报错：
TypeError: Cannot read properties of undefined (reading 'content') - 定位到
chat.js第 87 行。 - 结论：前端解析返回 JSON 时崩溃。是后端返回结构不对，还是前端没做防御？继续看 Step 3。
Step 3 · Network 层
- 找到发往
/api/chat的请求。 - 状态码 200（说明后端没崩）。
- Response 内容：
{"data": null, "error": "AI service timeout"}
- 结论：后端正确捕获了 AI 服务的超时错误并返回了结构化响应，但前端没处理
data为null的情况。 - 根因定位：前端代码健壮性问题。
修复：在 chat.js 第 87 行前加防御：
const content = response.data?.choices?.[0]?.message?.content ?? "AI 暂未返回内容";
问题解决。
复盘
- 故障层级：前端代码
- 关键证据：
TypeError堆栈 + Network 返回的data: null - 典型耗时的步骤：实际只用了 Step 1+2+3，约 1 分钟内完成。
- 后端与 AI 服务 一切正常，无需查看 Terminal / SDK / Dashboard。
四、心流收官：6 条排查守则
- 严格按顺序排查，不要"5 个面板一起看"，会被信息淹没。
- 每一步先问"看到了吗"，再决定是否进入下一步。
- 保留现场：报错时第一时间截屏，包括完整堆栈和状态码。
- 修复一处后重测，不要批量改 5 处再运行——容易引入新 bug。
- 建立自己的"常见错误清单"，比如
401几乎总是 API Key 问题。 - 把"外部服务商宕机"放在最后——大多数时候，不是他们的错。
五、动手任务（30 分钟）
任务 A：复盘你最近一次卡住的问题
回想你最近一次写 AI 应用被卡住超过 30 分钟的经历，用本篇 6 步法重新走一遍，写出每一步的观察和结论。你会发现：当初如果按这个顺序查，本可以 5 分钟搞定。
任务 B：建立你的个人排查清单
把任务 A 的复盘结果整理成一份 markdown 文档，永久保存：
# 我的常见问题速查表
## 401 Unauthorized
- 现象：Network 状态码 401
- 原因：API Key 缺失/错误
- 修复：检查环境变量
## (继续补充)
六、系列完结
至此，AI 编程基本概念 7 篇系列已全部完成。回顾你的成长：
| 你已掌握 | 数量 |
|---|---|
| 5 星核心概念 | 8 个（API、Prompt、Token、Model、Context Window、RAG、Console、Network、Terminal） |
| 4 星重要概念 | 7 个（SDK、System Prompt、Embedding、Vector Database、UI Feedback、Server Logs、AI Service Dashboard） |
| 3 星进阶概念 | 3 个（Streaming、Temperature、SDK Debug Logs） |
| 编程语法基础 | 变量、函数、判断、循环、类 |
| 排查能力 | 6 步标准化流程 |
接下来怎么走？
- 实战派：拿一个真实需求（周报生成、客服机器人），从零搭一个端到端 AI 应用。
- 原理派：去读 LangChain / LlamaIndex 源码，看它们怎么把本系列的概念"工程化"。
- 业务派：调研你所在行业的 AI 应用场景，思考哪些能用本系列方法快速落地。
你已经具备了"独立完成一个 AI 应用开发与调试"的能力。 剩下的，是不断动手、不断踩坑、不断精进。
系列总目录：返回 main.md