大模型应用开发 / 系统课时
常见故障排查
常见故障排查
本课提供一套可复用的排查顺序,覆盖检索结果不相关、工具调用失败、模型接口异常和 Agent 循环过长。你将先用最小探针验证各组件,再根据现象定位根因,避免在多个层级同时修改配置。
学习目标
- 按输入、组件、协议、外部依赖的顺序缩小故障范围
- 独立检查检索文档与工具函数,区分业务错误和编排错误
- 使用修复后复测清单确认问题真正消失
先按现象分流
检索效果差时,先看召回文档而不是先改回答 Prompt;工具调用失败时,先直接调用工具,再检查模型生成的工具名和参数;接口报错时,先确认鉴权、模型标识、限流和超时;Agent 重复调用时,检查工具返回是否足以让模型结束任务。

排查的核心是把复杂链路拆开。若独立组件已经失败,就不应继续调整 Agent Prompt;若独立组件正常,再向上检查消息协议、工具绑定和编排状态。
使用最小探针检查检索与工具
下面的可运行示例模拟一条召回文档,并直接调用除法工具。实际项目中,把 documents 替换为 retriever.invoke(query) 的返回值,即可先验证召回内容,再接回完整链路。
python
from langchain.tools import tool
from langchain_core.documents import Document
@tool
def divide(a: float, b: float) -> float:
"""计算 a 除以 b;b 不能为零。"""
if b == 0:
raise ValueError("b must not be zero")
return a / b
def inspect_documents(query: str, documents: list[Document]) -> None:
print(f"query={query}")
print(f"count={len(documents)}")
for index, document in enumerate(documents, start=1):
source = document.metadata.get("source", "<unknown>")
print(f"{index}:{source}:{document.page_content[:20]}")
def main() -> None:
documents = [
Document(
page_content="退款申请需要在支付完成后七天内提交。",
metadata={"source": "refund-policy.md"},
)
]
inspect_documents("退款期限", documents)
print(divide.name)
print(sorted(divide.args))
print(divide.invoke({"a": 12, "b": 3}))
if __name__ == "__main__":
main()预期输出:
text
query=退款期限
count=1
1:refund-policy.md:退款申请需要在支付完成后七天内提交。
divide
['a', 'b']
4.0若直接调用工具失败,修复函数、参数校验或外部依赖;若直接调用成功而 Agent 失败,再检查工具是否注册、模型是否支持工具调用、工具说明是否清晰,以及追踪中生成的参数是否符合 Schema。
对照根因修复
| 现象 | 优先检查 | 常见修复 |
|---|---|---|
| 召回为空 | 查询文本、索引是否写入、过滤条件 | 修正切分与索引流程,移除错误过滤 |
| 召回相关但回答错误 | 文档排序、上下文长度、回答约束 | 提升相关文档位置,要求基于证据回答 |
| 工具名正确但参数错误 | 字段描述、类型、必填项 | 收紧 Schema,拆分含义重叠的字段 |
| 模型返回鉴权或限流错误 | API Key、模型标识、配额、并发 | 更新凭证,校正模型名,增加退避重试 |
| Agent 重复调用 | 工具返回值、停止条件、递归限制 | 返回明确完成状态,设置最大步数 |
不要用无限重试掩盖确定性错误。参数校验失败、模型不存在和权限不足通常不会因立即重试而恢复;网络抖动、限流和临时服务错误才适合带上限的指数退避。
修复后进行回归验证
修复后至少重放一个失败样例、一个正常样例和一个边界样例,并比较追踪中的调用次数、耗时和最终输出。对于检索问题,还要确认文档来源正确;对于工具问题,要确认工具调用参数和返回值可由审计日志复现。
当问题无法稳定复现时,应固定模型、温度、Prompt 版本、数据版本和输入,保留失败 Trace ID。缺少这些信息的“偶发错误”很难被后续工程师准确定位。
按自己的节奏,确认真正理解。