AI Agent和AI大模型怎么排查:先分清是模型答错还是链路断了

接入与开发

把 Agent 和大模型调用出问题时的排查顺序讲清:先分模型、链路、工具三层,再按现象逐层缩小,别一上来就换模型。

用 Agent 或直接调大模型时,最常见的卡点是同一个现象有好几种成因:答得不对、迟迟没响应、跑到一半停住、报错但看不出是谁拒的。多数人第一反应是换模型或改提示词,结果换完还是那样。这篇给一套从外往里收的排查顺序,帮你先判断问题落在模型、链路还是工具那一层,再去动对应的那格配置。

同一个坏现象,成因往往不止一个。Agent 答得不对,可能是模型选错档、提示词没说清、上下文被截断,也可能是工具返回的数据本身就是错的,或者网关把请求转到了别的模型上。你上来就换模型、改提示词,运气好碰对了,运气不好折腾半天还在原地。我见过有人把温度一路从 0 调到 0.2 又调回去,最后发现是系统提示里塞了一段过期规则。

这篇给一套从外往里收的顺序:先把问题分到模型、链路、工具三层,再按现象对号入座,最后缩成最小可复现。要记住一句话——先证明路是通的,再谈答得好不好。顺序反了,你改的每一处都可能是白改。

先把锅分给三层,别急着改提示词

把一次 Agent 调用想成三层。模型层管生成质量:模型档位、温度、最大输出、上下文长度。链路层管通不通、通多快:Base URL 怎么拼、Key 有没有真的生效、代理和证书。工具层只出现在 Agent 里,管它调外部函数那一段:参数结构、返回格式、步数上限。三层混在一起看,等于同时开三个黑盒。

分层的判断方法很土,但管用:同一段提示词、同样的参数,换成官方直连再跑一次。还能复现,问题大概率在模型或提示词;换直连就好了,问题在链路。这个对照实验花不了几分钟,却能省掉一堆瞎猜。做之前记得把两边的模型名、温度、系统提示都对齐,不然对照本身就不成立。

  • 先关掉工具调用,跑一次纯对话:底层不通,加工具只会让报错更乱
  • 用官方直连做一次对照,模型名和参数保持一致
  • Agent 场景先确认工具定义能不能被正常解析,再谈多轮推理
  • 三层同时可疑时,从链路层开始排,它是另外两层的前提

按现象对号入座,比按报错码找更快

报错码有用,但很多时候你拿到的是「没反应」「跑一半停了」「答得怪」这种模糊现象。与其翻文档找状态码含义,不如先按现象定位到层,再进那一层细查。下面这张表是我自己常用的对照,左边是现象,右边是先去查哪。

现象先查哪层第一个动作
超时、连接被拒、一直转圈链路层核对 Base URL 拼法和环境变量是否真的生效
有响应但内容明显不对模型层确认模型名、温度、上下文有没有被截断
跑到一半停住、反复调同一个工具工具层看参数结构和返回格式,检查步数上限
报错带状态码看是谁在拒区分认证失败、限流和服务端问题,别混为一谈

状态码这块值得单独说一句:401 和 403 不是一回事,前者多半是 Key 没带上或写错,后者是权限或额度问题;429 和 5xx 也不是一回事,一个是你在被限流,一个是对方服务端出状况。站内已有专文把状态码拆开讲过,这里不重复,你按现象定位到层之后再去对号就行。

一个常见的误判

有次排查一个 Agent,现象是「答得不对」,第一反应是换模型。换完还是不对。后来把工具调用关掉跑纯对话,正常;一开工具就错。真正的原因是工具返回的字段名和定义里写的不一致,模型拿到空值只能瞎编。这种错,换十个模型都一样。所以内容不对,先别默认是模型笨。

缩到最小可复现,再往回加东西

定位到层之后,下一步是把现场缩小。最小可复现的意思是:一段十几行的脚本或一条 curl,不经过你的客户端、框架和中间封装,直接打接口。它能通,说明 Key 和端点本身没问题,坏在你加的那层壳上;它不通,问题就在更底下。

  1. 先直打接口用 curl 或短脚本发一次最简请求,只带 Key、模型名和一句提示。返回正常就说明链路层基本干净。
  2. 一次只加一个变量先加工具定义,再加系统提示,最后加多轮历史。每加一样跑一次,哪一步开始坏,问题就在那一步,别一次全加上。
  3. 把入参和结果落日志每次请求记下入参、耗时、返回状态和 token 用量。慢和贵这两件事,事后全靠这几个字段复盘,临时抓是抓不到的。
  4. 固定一个可复现的输入留一条稳定的测试请求当基线,改完配置拿它跑一遍,比凭感觉判断靠谱得多。

这套步骤的用处在于把「偶尔出错」变成「稳定复现」。复现不了的问题,改配置都是碰运气。基线请求不用复杂,一条带工具的短对话就够,关键是每次都跑同一条。

这几种情况换模型没用

有些问题看着像模型不行,其实是别的层在拖后腿。换更贵的模型不但解决不了,还可能让情况更糟。下面几条是我踩过或见人踩过的,遇到先停一下,别急着动模型配置。

  • 并发一上来就 429:这是限流和排队的问题,换更贵的档位只会更早撞墙,该做的是排队、退避和错峰
  • 流式输出首字慢但整体不慢:瓶颈常在网络和网关,跟模型能力关系不大,先看链路层
  • Agent 每轮都重发全部工具描述:账单涨在工具定义那一层,不是模型单价,精简工具集比换模型有效
  • 上下文被悄悄截断导致答非所问:先查历史长度和截断策略,换模型不一定给更长的窗口

判断标准很简单:如果同一个请求换成官方直连、同样的模型名和参数,表现就正常了,那问题不在模型能力,在你这边的链路或封装。反过来,直连也复现,再回头查模型层和提示词。这个对照最好在排查一开始就做,别等改了一圈才想起来。

还有个容易忽略的点:工具层的错误经常伪装成模型错误。模型拿到格式不对的返回值,会顺着编下去,看起来像它在胡说。所以内容不对时,先把工具返回原样打出来看一眼,比换模型快。

下一步想知道你正在用的中转站链路稳不稳、延迟落在哪个区间,可以去测速页跑一轮,把链路层先排掉,再回头调模型和提示词。当时的数字以页面显示为准。

常见问题

Agent 答非所问,是不是该直接换个更强的模型?

先别换。把工具调用关掉、只留纯对话再问一遍,如果这样就正常,问题在工具定义或参数约束,不在模型。纯对话也不对,再看提示词有没有交代清楚给谁看、要多长、不能出现什么。换模型是最后一招,不是第一招。

怎么快速判断是网络问题还是接口问题?

同一台机器上,先用 curl 打一个最简单的请求看返回和耗时。curl 通、客户端不通,多半是客户端的 Base URL 或环境变量没生效;curl 也不通,再往上查代理、DNS 和证书。站内有测速页可以先量一个延迟基线,对比着看。

排查时最该记哪些信息?

至少记四样:请求时间、用的哪个模型和端点、返回状态码、整段耗时。Agent 场景再加一条本轮调了哪些工具、参数长什么样。这几格记下来,慢、贵、错三种问题都能顺着往回找,不用靠回忆复现。

本文依据各平台公开文档与官方公告整理,只做中文归纳;具体做法、参数与限制以官方文档为准。