> For the complete documentation index, see [llms.txt](https://yeasy.gitbook.io/context_engineering_guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](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).

# 12.5 故障排查与问题诊断

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

## 12.5.1 问题分类

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

```mermaid
graph TB
    A["常见问题"] --> B["检索问题"]
    A --> C["生成问题"]
    A --> D["性能问题"]
    A --> E["成本问题"]
    A --> F["稳定性问题"]
```

图 12-8：常见问题分类

## 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. 关键指令冗余：在多个位置重复核心约束

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