# Part 7 · 标准化排查流程 + 实战：拥有程序员的"透视眼"

> **本篇定位**：系列收官。学完本篇，你将拥有"面对一个不响应的按钮，能 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 为例）：

```bash
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 内容：
  ```json
  {"data": null, "error": "AI service timeout"}
  ```
- 结论：后端正确捕获了 AI 服务的超时错误并返回了结构化响应，但**前端没处理 `data` 为 `null` 的情况**。
- 根因定位：前端代码健壮性问题。

**修复**：在 `chat.js` 第 87 行前加防御：

```javascript
const content = response.data?.choices?.[0]?.message?.content ?? "AI 暂未返回内容";
```

**问题解决**。

### 复盘

- **故障层级**：前端代码
- **关键证据**：`TypeError` 堆栈 + Network 返回的 `data: null`
- **典型耗时的步骤**：实际只用了 Step 1+2+3，约 1 分钟内完成。
- **后端与 AI 服务** 一切正常，无需查看 Terminal / SDK / Dashboard。

---

## 四、心流收官：6 条排查守则

1. **严格按顺序排查**，不要"5 个面板一起看"，会被信息淹没。
2. **每一步先问"看到了吗"**，再决定是否进入下一步。
3. **保留现场**：报错时第一时间截屏，包括完整堆栈和状态码。
4. **修复一处后重测**，不要批量改 5 处再运行——容易引入新 bug。
5. **建立自己的"常见错误清单"**，比如 `401` 几乎总是 API Key 问题。
6. **把"外部服务商宕机"放在最后**——大多数时候，**不是他们的错**。

---

## 五、动手任务（30 分钟）

### 任务 A：复盘你最近一次卡住的问题

回想你最近一次写 AI 应用被卡住超过 30 分钟的经历，**用本篇 6 步法重新走一遍**，写出每一步的观察和结论。你会发现：**当初如果按这个顺序查，本可以 5 分钟搞定。**

### 任务 B：建立你的个人排查清单

把任务 A 的复盘结果整理成一份 markdown 文档，**永久保存**：

```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](../main.md)