AI 大模型应用开发和 agent 开发怎么排查?先看它在哪一步"不往下走"

模型与算力

按链路分层排查大模型应用与 agent 开发中的问题:先判断是模型、工具调用、数据还是环境出的错,再给出对照顺序和动手动作。

应用跑起来了,回答却不对劲;agent 明明配了工具,就是不调用;改了提示词反而更差。这类问题最容易一上来就换模型、重装依赖,白折腾一天。这篇给一套分层排查顺序:先定位故障落在哪一层,再决定动不动模型。

应用跑起来了,回答却不对劲;agent 明明配了工具,就是不调用;提示词改了反而更差。这类问题最容易一上来就换模型、重装依赖、换框架,白折腾一天,最后发现是流式拼接少了最后一段。说白了,大模型应用和 agent 的排查,不是先问「哪个模型强」,而是先问「它卡在哪一步没往下走」。

这篇给一套分层顺序:先把故障落到某一层,再决定动不动模型。模型只是四层里的一层,换模型只对那一层有效。其余三层换十次模型也不会好,只会让日志更难读。

先把问题按四层切开,别从模型下手

四层是:输入与提示、模型返回、工具与外部接口、数据与状态。排查时先问一句:这次失败,是哪一层没有把东西交给下一层。是提示里压根没给工具清单,还是模型返回了空内容,还是工具被调了但结果没回灌,还是检索塞了一堆无关文档进去。同一个「答得不对」,落在这四层,处理方式完全不同。

层次典型症状先看什么
输入与提示答非所问、格式不对、该调用不调用实际发出的完整请求体,含工具清单和上下文
模型返回空内容、半截话、报错字段原始响应里的结束原因和用量
工具与外部接口工具未被触发、调用报错、结果没用上工具注册情况和调用记录
数据与状态答得流利但事实错、多轮后忘事召回的原文和当前会话状态

做法很土但有效:把一次失败请求的输入、原始返回、工具调用记录、最终输出四样全部留档,放在一起看。四样对齐之后,多数情况不用猜,直接能看出断点在哪。少留一样,排查就变成瞎猜。

第一件事不是改代码,是把原始返回打出来

很多「回答不对」根本不是模型的问题,是返回被截断、被前端模板吞掉,或者流式拼接少了最后一段。你看到的是一句话,模型吐出来的是三句话加一个结束标记。所以第一步不是动代码逻辑,是把原始返回完整打出来,越原始越好。

  • 结束原因是什么:正常结束、长度截断还是内容过滤,字段不同处理方向就不同
  • 用量对不对:输入和输出的量级明显偏小,多半是上下文被裁剪或请求没发全
  • 报错字段有没有被吞:有些客户端把错误包成正常响应,业务层根本看不到
  • 流式场景单独验一遍:把分块按顺序拼起来,和一次性请求的结果对照

还有一种常见误判:把温度之类的随机参数调来调去,想「试出」稳定输出。参数能影响风格,但改不了断点。先确认返回完整,再谈调参。

agent 不调工具,八成卡在描述和返回格式

  1. 确认工具是否进了这次请求把实际发出的请求体打出来,看工具清单里有没有这个工具。没进去就查注册和拼装逻辑,别往下走。
  2. 看工具描述能不能让人看懂把描述单独拿给同事读,问他这个工具什么时候该用。说不清就是描述的问题,模型一样说不清。
  3. 核对模型返回的函数名模型返回的函数名和注册名对不上,或者参数结构不符,调用自然失败。这一步看原始返回,不看最终输出。
  4. 确认调用结果回灌了工具执行完,结果有没有塞回下一轮上下文。没回灌,模型就装作没调过,表现为反复调同一个工具。

常见误判是把模型换成更强的,问题依旧,因为它根本没拿到工具列表。先修注册,再谈模型能力。不适用的情形也要说清:工具本身需要真实鉴权、或者外部服务不可达,这时候先修外部接口,调提示词没有意义。

数据和环境问题,症状会伪装成模型变笨

检索类应用先看召回了什么。召回到无关内容,模型答得再流利也是错的,这时候改提示词只是让错误答案更顺口。把召回原文和答案并排放,能对上就是对上了,对不上就别在生成端折腾。

环境层面看三样:接口地址与鉴权、超时与重试、并发下的限流。这三样出问题的症状很像「模型变笨」:时好时坏、高峰期更差、重试之后答案风格突变。同一输入反复跑,结果随机漂移明显,先怀疑超时重试和上下文被裁剪,而不是模型本身。

超时
请求被掐断,拿到的可能是空内容或半截内容,看原始返回的结束原因。
重试
失败后自动再发一次,容易导致同一条消息被处理两遍,检查幂等。
限流
并发一高就报错,表现为高峰期成功率骤降,看错误码分布。

要判断某个接口当前稳不稳、哪家更靠谱,别凭感觉,到站内的测速与检测页面看当时的实测数字,/tools/speed-test 这类页面的结果比拍脑袋强。

下一步把这次失败请求的四样留档对齐之后,多数问题能定位到具体一层。想对照各家接口的可用性和历史表现,去站内页面核对当时的数字,再决定要不要换通道。

常见问题

应用回答不准,第一步应该换模型吗?

不建议。先确认输入和原始返回是否正常、检索内容是否相关、工具是否被调用。这几项都没问题,才是模型能力不足,再考虑换模型或加约束。换模型是最后一步,不是第一步。

agent 能跑但总是多绕几步,算不算 bug?

看它绕的步骤是不是重复调用同一个工具、或者调用参数几乎一样。是的话通常是工具描述不够具体、返回内容没给足线索,或者没设最大步数。加个步数上限和重复调用检测,能省下不少时间和额度。

排查要不要每次都做完整链路记录?

开发阶段建议开,至少记录请求输入、原始返回、工具调用与耗时。上线后再按需采样。没有这份记录,出问题只能靠猜,改一次验证一次,效率很低。

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