智能体跑不起来、答得离谱、调用报错,第一反应往往是卸了重装或者换个更大的模型。可重装一遍环境照样卡在同一个地方。这篇给一条排查顺序:先看现象落在哪一层,再决定要不要动配置,最后才是换模型。
智能体跑不起来、答得离谱、调一次就报错,很多人的第一反应是卸环境重装,或者干脆换个更大的模型试试。折腾半天,环境重装了两遍,问题还卡在原地。这事儿麻烦在,装的那一步往往根本没问题,问题藏在别的地方。真正省时间的做法是先看现象落在哪一层,再决定动不动配置,换模型是最后一步。
下面这套顺序不是理论,是给排查时照着走的。核心就一句:先确认底座通不通,再一层一层往上压,每改一格参数只改一个,改完马上复测。不然改完好了,你也不知道是哪一步起的作用,下次再出问题照样抓瞎。
先看现象长什么样,别急着动环境
排查最容易犯的错,是把三种完全不同的毛病当成一种。连都连不上、能连上但答得不对、答得对但跑不完,这三类背后的原因差得远。能连上说明网络和鉴权这层已经过了,这时候再重装环境就是白费劲,答得不对跟装没装干净没关系。
| 现象 | 大概率卡在哪层 | 要不要重装 |
|---|---|---|
| 完全连不上、鉴权报错 | 调用层:地址、密钥、模型名 | 不用,先核对填的几格 |
| 能连上但答非所问 | 工具层或数据层 | 不用,先看检索和工具返回 |
| 答得对但超时、断流、卡住 | 上下文长度、超时设置 | 不用,先调参数 |
| 单个工具调用失败 | 工具层:参数 schema 变了 | 不用,单独测这个工具 |
动手之前先用最小请求试一次:单条提示词,不带工具,不挂知识库。这一步的目的就是确认底座是通的。底座能正常回话,后面所有问题都往下游找;底座都不通,那才轮到看地址和密钥。别小看这一步,它能帮你砍掉一半的瞎折腾。
把智能体拆成四层,一层一层往下压
智能体不是一块铁板,拆开看是四层:模型层、调用层、工具层、数据层。排查顺序从下往上,先模型,再调用,再工具,最后数据。提示词放到最后再动,一上来就改提示词,等于还不知道哪坏就先给自己加变量。
- 模型层
- 模型本身能不能正常回答,脱离智能体单独测一轮,看纯对话是否通顺合理
- 调用层
- 地址、密钥、模型名、请求格式这几格有没有填错;OpenAI 兼容格式对不上是最常见的一类
- 工具层
- 智能体调的工具能不能单独跑通,参数 schema 有没有悄悄改过
- 数据层
- 知识库检索回来的内容对不对;检索为空会直接表现成模型胡答
实际用下来,调用层出问题的比例比大家想的高。很多人一看到报错就怀疑网络,反复换镜像换代理,结果就是密钥那一格填错了,或者模型名多打了个后缀。这类问题不用猜,看错误原文就能定位,报错里写着鉴权失败、模型不存在,那就直接改配置,跟模型强弱一点关系没有。
几个判断标准:什么情况该换模型,什么情况不该
换模型不是不能换,但得换得明白。同一份提示词,纯对话模型答得对,挂上智能体就答不对,问题在工具或编排,换模型救不了。反过来,换了模型明显变好,也别急着收工,很可能只是新模型更宽容,把原来的配置错误盖住了,哪天换个严格点的又冒出来。
- 同一提示词纯对话对、智能体不对:先去查工具和编排,别动模型
- 报错原文出现鉴权、模型不存在、上下文超长:这三类直接改配置,和模型强弱无关
- 换模型后变好:留一份旧配置,回头确认原来的错误是不是还在
- 任务需要多步工具串联时,模型再强调用也可能不稳,得看编排逻辑本身是否合理
有一种情况不适用这套判断:任务本身要求多步工具串联,中间任何一步返回不符合预期,最终结果都会歪。这种时候别指望换个更聪明的模型一把解决,老老实实把编排拆开,逐步验证每一步的输入输出。
照着做的动作清单
- 测底座用最简单的单条请求测一次,记录返回是成功、报错还是超时。成功就往下走,报错看原文定位,超时先查网络和超时设置
- 逐个测工具把智能体挂的工具单独调用一遍,看哪个返回不符合预期。参数 schema 一处对不上,整个调用就会失败
- 打印检索结果把知识库召回的内容原样打出来,看召回到的是不是你要的。检索为空或召回无关内容,模型只能顺着胡答
- 最后才换模型前三步都确认没问题,再考虑换模型或改提示词。换之前留一份旧配置,方便回滚对比
这套清单的顺序别乱。跳过底座直接查工具,很可能查半天发现是密钥填错;跳过工具直接换模型,换完答得还是不对,白花一次调用。每一步的结论都写成一句话记下来,哪一步开始不对,问题就在那一层。
两个常见的误判
第一个误判是把答非所问当成模型不行。实际上一查,知识库检索没召回,或者工具返回了空结果,模型拿到空上下文只能自己编。第二个是把鉴权失败当成网络问题,反复换镜像换代理,最后发现就是密钥那一格填错了。这俩误判的共同点,都是没看错误原文就凭感觉下结论。
所以排查时养成一个习惯:先把错误原文完整读一遍,再动手。报错信息通常已经把方向指出来了,只是被忽略。模型能力、上下文长度、请求格式这些参数的具体数值,各家会变,去站内资料库核对当时的数字,别拿记忆里的旧值套。
下一步排查完想确认模型和价格资料,去站内资料库和价格追踪页核对当时的数字,再决定要不要换。→常见问题
智能体答得离谱,是模型不够强吗?
多数时候不是。先确认工具调用和知识库检索这两步返回的内容对不对,模型拿到的输入就不对,再强的模型也答不好。只有输入确认没问题、任务又确实复杂时,再考虑换模型。
调用一直报错,重装环境有用吗?
先看错误原文是哪一类。鉴权、模型名不存在、请求格式不对,都跟环境无关,重装白费时间。只有依赖装错、版本冲突这类报错,重装才可能有用。
换模型之后好了,是不是就说明原来的模型不行?
不一定。有可能新模型对格式错误的容忍度更高,把原来的配置问题盖住了,换个更严格的场景还是会犯。换之前最好把配置核对一遍,留个记录。