大模型应用开发 / 系统课时

常见故障排查

常见故障排查

本课提供一套可复用的排查顺序,覆盖检索结果不相关、工具调用失败、模型接口异常和 Agent 循环过长。你将先用最小探针验证各组件,再根据现象定位根因,避免在多个层级同时修改配置。

学习目标

  • 按输入、组件、协议、外部依赖的顺序缩小故障范围
  • 独立检查检索文档与工具函数,区分业务错误和编排错误
  • 使用修复后复测清单确认问题真正消失

先按现象分流

检索效果差时,先看召回文档而不是先改回答 Prompt;工具调用失败时,先直接调用工具,再检查模型生成的工具名和参数;接口报错时,先确认鉴权、模型标识、限流和超时;Agent 重复调用时,检查工具返回是否足以让模型结束任务。

LangChain 常见故障分流与定位流程

排查的核心是把复杂链路拆开。若独立组件已经失败,就不应继续调整 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。缺少这些信息的“偶发错误”很难被后续工程师准确定位。

按自己的节奏,确认真正理解。

目录与阅读设置

记录一个想法

常见故障排查

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通