应用跑起来了,回答却不对劲;agent 明明配了工具,就是不调用;改了提示词反而更差。这类问题最容易一上来就换模型、重装依赖,白折腾一天。这篇给一套分层排查顺序:先定位故障落在哪一层,再决定动不动模型。
应用跑起来了,回答却不对劲;agent 明明配了工具,就是不调用;提示词改了反而更差。这类问题最容易一上来就换模型、重装依赖、换框架,白折腾一天,最后发现是流式拼接少了最后一段。说白了,大模型应用和 agent 的排查,不是先问「哪个模型强」,而是先问「它卡在哪一步没往下走」。
这篇给一套分层顺序:先把故障落到某一层,再决定动不动模型。模型只是四层里的一层,换模型只对那一层有效。其余三层换十次模型也不会好,只会让日志更难读。
先把问题按四层切开,别从模型下手
四层是:输入与提示、模型返回、工具与外部接口、数据与状态。排查时先问一句:这次失败,是哪一层没有把东西交给下一层。是提示里压根没给工具清单,还是模型返回了空内容,还是工具被调了但结果没回灌,还是检索塞了一堆无关文档进去。同一个「答得不对」,落在这四层,处理方式完全不同。
| 层次 | 典型症状 | 先看什么 |
|---|---|---|
| 输入与提示 | 答非所问、格式不对、该调用不调用 | 实际发出的完整请求体,含工具清单和上下文 |
| 模型返回 | 空内容、半截话、报错字段 | 原始响应里的结束原因和用量 |
| 工具与外部接口 | 工具未被触发、调用报错、结果没用上 | 工具注册情况和调用记录 |
| 数据与状态 | 答得流利但事实错、多轮后忘事 | 召回的原文和当前会话状态 |
做法很土但有效:把一次失败请求的输入、原始返回、工具调用记录、最终输出四样全部留档,放在一起看。四样对齐之后,多数情况不用猜,直接能看出断点在哪。少留一样,排查就变成瞎猜。
第一件事不是改代码,是把原始返回打出来
很多「回答不对」根本不是模型的问题,是返回被截断、被前端模板吞掉,或者流式拼接少了最后一段。你看到的是一句话,模型吐出来的是三句话加一个结束标记。所以第一步不是动代码逻辑,是把原始返回完整打出来,越原始越好。
- 结束原因是什么:正常结束、长度截断还是内容过滤,字段不同处理方向就不同
- 用量对不对:输入和输出的量级明显偏小,多半是上下文被裁剪或请求没发全
- 报错字段有没有被吞:有些客户端把错误包成正常响应,业务层根本看不到
- 流式场景单独验一遍:把分块按顺序拼起来,和一次性请求的结果对照
还有一种常见误判:把温度之类的随机参数调来调去,想「试出」稳定输出。参数能影响风格,但改不了断点。先确认返回完整,再谈调参。
agent 不调工具,八成卡在描述和返回格式
- 确认工具是否进了这次请求把实际发出的请求体打出来,看工具清单里有没有这个工具。没进去就查注册和拼装逻辑,别往下走。
- 看工具描述能不能让人看懂把描述单独拿给同事读,问他这个工具什么时候该用。说不清就是描述的问题,模型一样说不清。
- 核对模型返回的函数名模型返回的函数名和注册名对不上,或者参数结构不符,调用自然失败。这一步看原始返回,不看最终输出。
- 确认调用结果回灌了工具执行完,结果有没有塞回下一轮上下文。没回灌,模型就装作没调过,表现为反复调同一个工具。
常见误判是把模型换成更强的,问题依旧,因为它根本没拿到工具列表。先修注册,再谈模型能力。不适用的情形也要说清:工具本身需要真实鉴权、或者外部服务不可达,这时候先修外部接口,调提示词没有意义。
数据和环境问题,症状会伪装成模型变笨
检索类应用先看召回了什么。召回到无关内容,模型答得再流利也是错的,这时候改提示词只是让错误答案更顺口。把召回原文和答案并排放,能对上就是对上了,对不上就别在生成端折腾。
环境层面看三样:接口地址与鉴权、超时与重试、并发下的限流。这三样出问题的症状很像「模型变笨」:时好时坏、高峰期更差、重试之后答案风格突变。同一输入反复跑,结果随机漂移明显,先怀疑超时重试和上下文被裁剪,而不是模型本身。
- 超时
- 请求被掐断,拿到的可能是空内容或半截内容,看原始返回的结束原因。
- 重试
- 失败后自动再发一次,容易导致同一条消息被处理两遍,检查幂等。
- 限流
- 并发一高就报错,表现为高峰期成功率骤降,看错误码分布。
要判断某个接口当前稳不稳、哪家更靠谱,别凭感觉,到站内的测速与检测页面看当时的实测数字,/tools/speed-test 这类页面的结果比拍脑袋强。
下一步把这次失败请求的四样留档对齐之后,多数问题能定位到具体一层。想对照各家接口的可用性和历史表现,去站内页面核对当时的数字,再决定要不要换通道。→常见问题
应用回答不准,第一步应该换模型吗?
不建议。先确认输入和原始返回是否正常、检索内容是否相关、工具是否被调用。这几项都没问题,才是模型能力不足,再考虑换模型或加约束。换模型是最后一步,不是第一步。
agent 能跑但总是多绕几步,算不算 bug?
看它绕的步骤是不是重复调用同一个工具、或者调用参数几乎一样。是的话通常是工具描述不够具体、返回内容没给足线索,或者没设最大步数。加个步数上限和重复调用检测,能省下不少时间和额度。
排查要不要每次都做完整链路记录?
开发阶段建议开,至少记录请求输入、原始返回、工具调用与耗时。上线后再按需采样。没有这份记录,出问题只能靠猜,改一次验证一次,效率很低。