# 12.5 故障排查与问题诊断

在上下文工程的实践中，会遇到各种问题。本节汇总常见问题的诊断方法和解决方案，帮助快速定位和解决问题。

## 12.5.1 问题分类

上下文工程中的问题可以分为以下几类：

{% @mermaid/diagram content="graph TB
A\["常见问题"] --> B\["检索问题"]
A --> C\["生成问题"]
A --> D\["性能问题"]
A --> E\["成本问题"]
A --> F\["稳定性问题"]" %}

图 12-7：常见问题分类

## 12.5.2 检索问题

检索是 [RAG](/context_engineering_guide/di-er-bu-fen-he-xin-ji-shu-yu-ce-le/05_select/5.1_rag_principles.md) 系统的核心环节，检索问题直接影响最终效果。

### 问题：检索不到相关内容

**症状**：用户提问后，系统返回“未找到相关信息”或答案明显缺乏依据。

**可能原因**：

* 知识库未包含相关信息
* 嵌入模型与查询类型不匹配
* 分块策略导致信息碎片化
* 检索阈值设置过高

**诊断步骤**：

1. 检查知识库是否包含相关文档
2. 手动测试查询的嵌入相似度
3. 查看检索返回的原始结果（含得分）
4. 对比不同分块大小的检索效果

**解决方案**：

1. 补充知识库覆盖度：添加缺失的文档
2. 测试嵌入模型效果：尝试不同的嵌入模型
3. 调整分块参数：增大块大小或添加重叠
4. 引入混合检索：结合关键词和语义检索
5. 降低检索阈值：获取更多候选结果

### 问题：检索结果不相关

**症状**：检索返回了内容，但与用户问题不相关。

**可能原因**：

* 语义相似但实际不相关（如同一领域的不同话题）
* 关键词权重不足
* 缺少重排序步骤

**诊断步骤**：

1. 查看检索返回的具体内容
2. 分析查询与结果的语义关系
3. 检查是否存在关键词匹配

**解决方案**：

1. 添加重排序步骤：使用交叉编码器二次排序
2. 结合关键词检索：对专有名词等使用精确匹配
3. 优化查询改写：使用 HyDE 等技术增强查询
4. 添加元数据过滤：按类别、时间等过滤

## 12.5.3 生成问题

即使检索正确，生成阶段仍可能出现问题。

**症状**：模型的回答与事实不符，或与检索内容矛盾。

**可能原因**：

* 上下文信息不足
* 模型产生幻觉
* 指令不够明确
* 检索内容质量差

**诊断步骤**：

1. 检查上下文是否包含正确答案
2. 对比模型输出与上下文内容
3. 分析系统提示词的约束是否清晰

**解决方案**：

1. 补充更多相关信息：增加检索数量
2. 强化约束指令：明确要求“仅基于上下文回答”
3. 加入事实核查步骤：让模型自查答案依据
4. 使用引用格式：要求模型标注信息来源

```python
# 在系统提示词中加入约束
system_prompt = """
基于提供的上下文回答问题。
如果上下文中没有相关信息，请明确说明"根据现有信息无法回答"。
每个关键论点都需要引用上下文中的具体内容。
"""
```

### 问题：不遵循指令

**症状**：模型不遵守输出格式要求，或忽略重要约束。

**可能原因**：

* 指令被淹没在大量上下文中
* 格式要求不清晰
* 上下文存在冲突信息

**诊断步骤**：

1. 检查指令在上下文中的位置
2. 验证指令表述是否明确
3. 检查是否有相互矛盾的内容

**解决方案**：

1. 使用 XML 标签隔离：`<instructions>...</instructions>`
2. 重要指令放在开头/结尾：利用位置优势
3. 简化和明确指令：避免模糊表述
4. 移除冲突内容：确保上下文一致

### 问题：输出不一致

**症状**：相同问题多次询问得到明显不同的答案。

**可能原因**：

* 温度（temperature）设置过高
* 上下文每次略有变化
* 检索结果不稳定

**解决方案**：

1. 降低温度参数：设为 0 或很低的值（如 0.1）
2. 固定上下文模板：确保每次构建一致
3. 使用更明确的格式约束：减少输出变异
4. 固定随机种子：部分模型支持

## 12.5.4 性能问题

### 问题：响应延迟高

**症状**：用户等待时间过长，影响体验。

**可能原因**：

* 上下文过长
* 检索慢
* 网络延迟
* 模型响应慢

**诊断步骤**：

1. 分解各阶段耗时（检索、构建、生成）
2. 检查上下文 Token 数量
3. 监控网络延迟

**解决方案**：

1. 压缩上下文：减少 Token 数量
2. 优化索引：使用更高效的向量索引
3. 使用缓存：缓存常见查询结果
4. 流式输出：改善用户感知延迟
5. 模型降级：延迟敏感时使用更快模型

### 问题：吞吐量不足

**症状**：高并发时请求堆积，响应变慢。

**解决方案**：

1. 并行处理：充分利用异步能力
2. 批量请求：合并处理相似请求
3. 横向扩展：增加服务实例
4. 队列缓冲：使用消息队列削峰

## 12.5.5 成本问题：成本超出预算

**症状**：API 费用快速增长，超出预期。

**诊断步骤**：

1. 分析 Token 使用分布
2. 识别高成本的请求类型
3. 检查是否有异常请求

**解决方案**：

1. 压缩上下文减少 Token
2. 使用更小的模型处理简单任务
3. 增加缓存命中率
4. 设置成本限制和告警
5. 清理滥用或无效请求

## 12.5.6 稳定性问题：服务不稳定

**症状**：偶发性失败、超时或异常。

**解决方案**：

1. 实现重试机制：指数退避重试
2. 设置超时控制：防止无限等待
3. 添加熔断器：故障时快速失败
4. 准备降级方案：核心功能保证可用

```python
@retry(max_attempts=3, backoff=exponential)
@timeout(30)
@circuit_breaker(failure_threshold=5)
async def call_llm(prompt):
    return await model.generate(prompt)
```

## 12.5.7 问题诊断清单

遇到问题时，按此清单逐项检查：

* [ ] 上下文内容是否正确构建？
* [ ] Token 数量是否在限制内？
* [ ] 检索是否返回相关结果？
* [ ] 重排序是否正常工作？
* [ ] 指令是否清晰且被遵循？
* [ ] 是否有错误日志？
* [ ] 性能指标是否正常？
* [ ] 最近是否有配置变更？

## 12.5.8 问题上报模板

团队协作时，使用标准化的问题报告格式：

```markdown
## 问题描述
[具体症状]

## 复现步骤
1. [步骤1]
2. [步骤2]

## 相关日志
[关键日志片段]

## 已尝试的解决方案
- [方案1]: [效果]

## 环境信息
- 模型版本：
- 配置版本：
- 发生时间：
```

通过系统化的问题诊断和解决流程，可以快速定位问题根因，减少排查时间，提高系统可靠性。

以下是三个真实场景的故障排查过程，展示完整的诊断思路。

***

### 案例一：检索增强生成系统召回率骤降（示意）

**故障现象**：运行稳定的客服 RAG 系统，出现大比例的问题无法找到相关答案。

**排查过程**：

```
第 1 步：检查知识库
→ 知识库未变化，文档数量正常

第 2 步：检查嵌入服务
→ 嵌入 API 正常响应，延迟无变化

第 3 步：对比历史查询
→ 发现失败的查询集中在"退货政策"相关问题

第 4 步：深挖嵌入向量
→ 用相同查询获取嵌入，与历史嵌入对比
→ 发现：嵌入服务提供商升级了模型版本（或变更了默认版本）

第 5 步：验证假设
→ 新模型的嵌入与旧模型不兼容
→ 知识库中的文档仍是旧嵌入，查询使用新嵌入
```

**根因**：嵌入服务提供商静默升级了模型版本，新旧嵌入不在同一向量空间。

**解决方案**：

1. 回滚嵌入 API 版本（临时）
2. 用新模型重新嵌入全部知识库文档
3. 添加嵌入版本监控告警

**教训**：嵌入模型版本必须与知识库一致，变更需要重建索引。

***

### 案例二：智能体陷入死循环（示意）

**故障现象**：代码生成 Agent 在某些任务上不停循环调用工具，Token 消耗暴涨。

**排查过程**：

```
第 1 步：查看 Agent 执行日志
→ Thought-Action-Observation 循环正常开始
→ 在第 15 轮后开始重复相同的 Action

第 2 步：分析循环点
→ Agent 反复尝试：Action: run_tests()
→ Observation: "3 tests failed"
→ Thought: "需要修复测试"
→ 但修复后测试仍失败

第 3 步：检查工具返回
→ run_tests() 返回的错误信息过于简略
→ 只说"failed"，没有具体原因

第 4 步：手动复现
→ 测试失败是因为缺少环境变量，与代码无关
```

**根因**：工具返回的错误信息不完整，Agent 无法判断是代码问题还是环境问题，陷入“修代码”的循环。

**解决方案**：

1. 丰富工具返回信息：包含错误类型、堆栈、环境状态
2. 添加循环检测：连续 3 次相同 Action 时强制退出
3. 加入 `diagnose_failure()` 工具帮助 Agent 分析失败原因

**教训**：工具返回必须提供足够的上下文让 Agent 做出正确判断。

***

### 案例三：Token 超限导致关键信息被截断（示意）

**故障现象**：法律咨询系统偶发性给出错误建议，复现困难。

**排查过程**：

```
第 1 步：收集失败案例
→ 共 12 个用户投诉，涉及不同问题

第 2 步：分析共同点
→ 都是长对话（20+ 轮）
→ 都涉及多个法条的综合分析

第 3 步：检查上下文构建
→ 打印实际发送的上下文
→ 发现：部分案例的系统提示词被截断了！

第 4 步：分析 Token 分配
→ 模型限制：上下文窗口存在上限
→ 长对话 + 多法条检索 → 超过限制
→ 截断策略从尾部截断
→ 系统提示词放在末尾 → 被截断

第 5 步：验证
→ 被截断的内容包含"必须引用法条原文"等关键指令
→ 导致模型根据记忆生成，产生幻觉
```

**根因**：上下文超限后的截断策略不当，重要指令被截断。

**解决方案**：

1. 调整上下文结构：系统提示词置顶，永不截断
2. 添加 Token 预算检查：超限时主动压缩历史而非被动截断
3. 关键指令冗余：在多个位置重复核心约束

**教训**：截断是“隐形杀手”，必须明确控制各部分优先级。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://yeasy.gitbook.io/context_engineering_guide/di-si-bu-fen-gong-cheng-shi-zhan-yu-wei-lai-yan-jin/12_production/12.5_troubleshooting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.