> 本文由 苏州市天智教育培训中心 技术团队整理，基于真实生产故障复盘，面向一线运维与开发同学，可直接用于排障参考。
一、问题现象
知识库里明明有答案，但 Agent 就是答不出来，或者答得像模像样却是错的。这类问题看起来像"模型不行"，其实 80% 出在检索环节。
二、排查思路速览
先按下面的路径走，每一步都有明确的判断分支，避免"上来就重启"这种无效操作。
三、先看清链路：AI Agent 的典型架构
动手之前先明确"请求经过了哪些环节"，把问题定位到具体一层，排查效率会成倍提升。
四、根因分析
结合现场日志、监控与配置，逐条核对，绝大多数情况都能收敛到下面这几类原因：
- 分块过大或过小，答案被切断或引入大量噪声
- 只用向量检索，专有名词 / 编号类查询召回差
- 缺少 Rerank，TopK 里正确片段排在第 8 位
- Prompt 里没有强约束"仅依据资料回答"，模型自由发挥
五、处置过程
处置原则：先止血、再根治。先让业务恢复，再回头解决根因，不要在故障中做长期改造。
- 必须先看"检索到的片段"，把问题定位在检索还是生成
- 分块要按语义边界（标题 / 段落）而不是固定字符数
- 混合检索 + Rerank 是提升准确率最有效的一招
- 建立评估集（问题 → 期望答案），否则优化靠感觉
六、关键命令与配置
下面这些命令/配置可以直接在生产上核对（执行前请确认环境与权限）：
# RAG 调试：先看检索，再看生成
docs = retriever.search(query, top_k=8)
for i, d in enumerate(docs):
print(f"[{i}] score={d.score:.3f} src={d.metadata.get('source')}")
print(d.page_content[:120].replace("\n", " "))
# 判读：
# 正确片段不在列表里 → 检索问题（分块 / Embedding / 召回策略）
# 正确片段在列表但排名靠后 → 加 Rerank
# 检索没问题但答案错 → Prompt / 上下文窗口 / 模型指令问题七、复盘
故障恢复后必须做复盘，重点不是"谁的责任"，而是"哪个机制缺位"：
- 根因是固定 500 字切分，把表格和定义切成了两半
- 复盘发现团队一直在调 Prompt，没人看检索片段
- 没有评估集，改了半天说不清到底有没有变好
八、预防建议
- 先建评估集，再谈优化
- 分块按语义 + 重叠窗口，保留上下文
- 上混合检索与 Rerank，专有名词场景收益最大
- Prompt 明确"资料不足时如实说明"，降低幻觉
九、官方版本动态（自动同步）
以下内容由官方发布渠道自动同步（最近同步 2026-10-11），用于提醒你：同一个问题在不同版本上的表现与处置方式可能不同，动手前先确认线上实际版本。
- OpenAI Python SDK Release v3.28.0（2026-10-09 发布） 官方说明
- OpenAI Python SDK Release v3.27.0（2026-10-09 发布） 官方说明
- LangChain Release 1.4.4（2026-10-08 发布）：langchain==1.4.4 官方说明
> 版本升级前务必先在测试环境验证，特别是标注了「破坏性变更」或「停止维护」的版本。
十、写在最后
上面这套排查方法，是 AI Agent 在生产环境中最常见的一类问题，也是AI Agent方向岗位面试里经常被追问的场景题。很多人搜「苏州aiagent培训」或者关心「AI Agent 培训」，真正想确认的其实是：课程讲不讲真实的线上故障。我们在AI Agent 开发工程师课程里，会把这类故障做成实战演练——从监控曲线、日志、命令输出一路推到根因，再动手恢复，而不是背命令。苏州校区面授 + 线上同步，主打苏州aiagent培训方向的实战教学，就业推荐覆盖江浙沪。如果你正在做AI Agent方向、或者想转行进入AI Agent领域，可以了解一下我们的课程（苏州aiagent培训、AI Agent 培训、智能体开发培训），也可以直接联系我们做一次免费的职业与技术评估。