做 agent 应用最难受的不是不会写代码,是现象说不清:回答不对、调不通、跑一半断了,全混在一起叫「有问题」。这篇给一条排查顺序,先判断问题落在模型、链路还是数据提示哪一层,再决定动哪里。顺序错了,改半天都是在好的那层上瞎改。
做 agent 应用最难受的不是不会写代码,是现象说不清。回答不对、调不通、跑一半断了,全混在一起叫「有问题」。你去问,对面也说不出个所以然,只能从头翻代码。翻了两小时发现是模型名写错了一位。这种事儿太常见了。
这篇给一条排查顺序:先判断问题落在模型、链路还是数据提示哪一层,再决定动哪里。顺序错了,改半天都是在好的那层上瞎改。下面按三层拆开讲,每层给判断标准和能直接做的动作。
先分层:模型、链路、数据提示
把现象先归到三层里的一层。模型层指模型本身能力不够,任务超出它的边界;链路层指调用过程出问题,地址、鉴权、超时、流式中断;数据与提示层指喂进去的东西不对,检索召回跑偏、上下文拼接乱、提示没交代清楚。听着像废话,但实际排查时九成返工都是因为三层混着改。
最快的判断方法是拿同一段输入,去网页版或者官方直连跑一遍。结果正常,说明模型不背锅,问题在链路或数据提示。结果一样烂,那大概率是选型或任务本身的问题。这一步花不了几分钟,能省掉后面大量瞎试。
模型这层:输出不对先别改代码
输出不对,第一反应往往是改代码、改提示。先停一下。看任务本身是不是超出了这个模型的定位:要求精确算数、实时事实、超长多跳推理,这类活儿本来就不是所有模型都干得好。你拿一个偏对话的模型去做多步推理,调参数调到天亮也没用。
对照站内的模型库和评测页,看这个模型的任务边界在哪。到 /models 和 /benchmarks 核对当时的数字,别凭印象。然后换一个更合适的模型做同题对比,能出结果,就说明是选型问题,不是代码问题。这一步做完再决定要不要动代码。
还有一类特别容易被误判成「模型变笨」:参数调错了。温度拉太高,输出发散;最大输出长度设太短,回答被硬生生截断。这些参数的含义和推荐范围,到 /ai-dict/category/tips 对一遍,比在网上翻帖子靠谱。
链路这层:能调通和调得好是两件事
链路层的问题分两种:调不通,和调得不好。调不通,先用最小请求跑一次,把地址、鉴权、模型名字这三格逐一对上。实际排查下来,这三处填错占了大多数。别笑,真到赶进度的时候,空格、斜杠、大小写都能坑你半天。
调得不好就麻烦些。延迟高、超时、流式输出断在半路、工具调用结果没回传、多轮对话上下文被截断,这些都算链路层。它们的共同点是:跟提示词没关系,你去改提示词纯属白费。先量一个延迟基线,到 /tools/speed-test 记录一次真实耗时,后面觉得慢或者超时,才有对照。
上线之后的稳定性问题,别靠单次手感判断。用 /tools/quality-monitor 这类监控看趋势,是偶发还是持续劣化,一眼能分清。偶发问题硬当持续问题修,越修越乱。
| 现象 | 先查哪层 | 具体动作 |
|---|---|---|
| 调不通、报鉴权错 | 链路 | 核对地址、鉴权、模型名三格 |
| 回答答非所问 | 数据提示 | 检查检索召回内容是否相关 |
| 简单任务也做不对 | 模型 | 换合适模型做同题对比 |
| 流式输出中途断 | 链路 | 查超时设置和网络稳定性 |
| 同样输入结果飘 | 数据提示 | 检查参数和上下文拼接是否稳定 |
数据与提示这层:agent 多了工具和记忆
agent 和普通问答最大的区别,是多出了工具调用和上下文拼接。所以这一层出错,先看工具返回的内容对不对,而不是先盯着提示词改。工具返回的就是一堆垃圾,你提示词写得再漂亮,模型也只能基于垃圾编。
检索类应用同理。先确认召回来的东西本身相关不相关。召回错了,改提示词没用,得回头修检索的切分、索引和查询。这个顺序别搞反,搞反了就是在一个错的前提上反复打磨。
提示本身,交代清楚「给谁看、要多长、不能出现什么」,比堆一堆形容词有效得多。另外,同一份输入重复跑多次,如果输出飘得厉害,大概率不是模型随机性,而是参数或者上下文拼接不稳定,比如历史消息没按预期顺序拼进去。
一套可以照着走的排查顺序
- 复现固定输入、固定参数、固定模型名,先把问题稳定复现出来。复现不了的问题,先别修。
- 分层用官方直连或网页版做对照,把问题归到三层中的一层,写在纸上。
- 单点改一次只改一处,改完用同一组输入复跑,确认是不是这一处起的作用。
- 留痕每次改动和结果记一行,回退的时候不用猜哪一步有用哪一步没用。
这套顺序有个前提:问题本身是可控的、能复现的。如果是涉及数据合规或私有部署的场景,还得多加一层环境和权限排查,比如网络不通、证书不对、权限没开。那种情况下,前四步走完可能还在原地,别怀疑顺序,是层数本来就不止三层。
说白了,排查不是拼谁改得多,是拼谁先找对地方。先定层,再动手,比闷头改代码快得多。
下一步想对照具体模型的任务边界和当时的评测数据,去站内模型库和评测页看,比凭印象选型靠谱。→常见问题
输出不对,应该先换模型还是先改提示词?
先做一次对照:同一段提示和输入,换到官方直连或网页版跑。结果一样差,说明模型或提示的问题;结果明显好,说明你的调用链路有问题。这一步不做,换模型和改提示都是瞎试。
agent 调工具总是失败,从哪查起?
先看工具本身的返回值,是超时、报错还是返回了空。工具没问题再看参数拼装和模型给的调用格式对不对。多数情况是模型把参数填错或工具描述写得含糊,模型不知道该传什么。
本地部署和调 API 排查思路一样吗?
前半段一样,都要分层。差别在后半段:本地部署多一层环境排查,驱动、显存、服务是否起来、端口是否通,这些在 API 场景里不存在。本地的问题先去 /tools 和 /models/deploy 核对配置。