读完你会得到什么
一套能自己复刻的接法:把每轮变成 trace 上的一层,本轮调了什么工具、参数是什么、工具回了什么,都能直接读出来。
配套的验证是两组对照:接了之后看得见,不接就看不见。工程代码不公开,但设置条件都在文里,照着重搭一遍不费事。
一句结论:框架给的 span 是方法调用粒度,调用过模型、调用过工具 它都有,第几轮、为什么选这个工具 它没有。缺的这层得自己补。
一、假设一个改地址的客服助手
假设一个客服助手,接三条工具:查订单地址、改地址、给用户发通知。一次典型任务跑三轮:查到旧地址,改成新地址,发通知。
数据库里的地址改对了,用户收到的通知里却是旧地址。这类事故的量级不小,真实案例里一次约 60 单受影响。(这是一个构造场景,用来复现这类事故的形态。业务量级只有一个数据点,其余都在可复刻的设置里。)
麻烦的地方在这里:服务层代码里没有循环,就是一次 client.prompt().call()。三轮是模型跑出来的,所以「第 3 轮」这个位置断点打不到,日志里也只有一句「已发送」。
二、先看框架给了什么
这套设置跑一遍,trace 里会出现四种 span:
okhttp.requests
gen_ai.client.operation
spring.ai.advisor
spring.ai.chat.client
数量对得上:一次任务四次模型调用,三圈工具调用,每条请求都有对应的 span。
维度对不上。这四条里没有一条能说出第3轮调了 notifyUser,参数里是旧地址。gen_ai.client.operation 只说明模型被调用过;spring.ai.advisor 只说明工具执行器跑过。哪一轮、那轮想干什么,只能拿时间戳去猜。
这段不是推测。对照组用例就是干这个的:注册观测器,跑完任务,把收到的 span 名单输出出来,再断言里面没有任何一条带轮次信息。跑一遍测试就能看到那串名单。
三、轮次能挂在哪
先说两个挂了不行的位置,省得重走:
Advisor 不行。它包住的是 一次 ChatClient 调用,而工具循环在调用内部跑完 ------ 一次调用里可能有三轮,Advisor 只看得见一次。
包装 ChatModel 也不行。循环在更内层,包装层同样只收到一次。
可以的是工具调用管理器(ToolCallingManager 的 executeToolCalls):每一轮执行一次,是唯一的分轮点。装饰它,每轮开一个 span:
java
Observation observation = Observation.start("agent.round", registry)
.lowCardinalityKeyValue("agent.round.index", String.valueOf(round))
.highCardinalityKeyValue("agent.round.tools", requestedTools(response))
.highCardinalityKeyValue("agent.round.args", requestedArgs(response));
四个属性,各自回答一个问题:
| 属性 | 例子 | 定位时回答 |
|---|---|---|
agent.round.index |
3 |
第几轮 |
agent.round.tools |
notifyUser |
这轮要调什么 |
agent.round.args |
{"userId":"u1","message":"...旧地址..."} |
参数从哪来 |
agent.round.result |
已发送 |
工具回了什么 |
四、补上之后
同一个脚本重跑,实测三个 agent.round span,index 依次 1、2、3。第 3 轮的 tools 是 notifyUser,args 里带着旧地址;第 2 轮的 tools 是 updateAddress,参数是新地址。
「哪一轮把旧值发出去了」这个问题,从需要推测变成一眼可见。
能引用的真实数字:一次任务 = 3 轮工具执行 + 4 次模型调用(三轮之后还有一次收尾),用到的工具 3 个,1 读 2 写。这几个数在测试里断言过,脚本改了就会红。
五、两个坑
单参的 ChatClient.builder 会把自己的观测器关掉。
ChatClient.builder(chatModel) 这个重载内部把 ObservationRegistry 写死成 NOOP,顺带用默认的工具调用管理器。表现是:自己注册了 handler,跑完一条 span 都收不到,而且不报错。
反编译能看到那个常量:
scss
DefaultChatClientBuilder(ChatModel);
2: getstatic io/micrometer/observation/ObservationRegistry.NOOP
要显式装配,把 registry 和工具调用管理器一起传进去:
java
ChatClient client = new DefaultChatClientBuilder(
chatModel, registry, null, null,
ToolCallingAdvisor.builder().toolCallingManager(tracedManager))
.defaultAdvisors(toolAdvisor)
.defaultTools(tools)
.build();
假上游的队列空着会阻塞,表现成读超时。
搭脚本化上游时漏了一条响应,请求发出去没人应答,客户端等了两分钟才超时。报错是 Request failed 加 SocketTimeoutException,跟「剧本没排」一点关系都看不出来。
这条是实测踩出来的。判据是看上游收到的请求数:收了两条就没动静,说明第三条在等剧本,不是网络问题 ------ 光看报错只会以为是网络。
六、边界
- 轮次按「工具执行」计数:纯对话任务没有工具调用,一轮 span 都不会有,这套东西对它无效
- 每轮一个 span,轮次多时的量级成本没测,未验证
- 只覆盖同步调用;流式路径的 observation 行为不同,未验证
- 没有接真实 tracing 后端(Zipkin / OTLP),只在内存里断言
- 事故是构造的,业务量级只有 60 单一个数据点
七、怎么接进现有项目
三步,不依赖任何仓库:
- 写一个装饰器实现工具调用管理器,把默认实现包起来,在
executeToolCalls前后起停一个Observation,属性按上面的四个填 - 装配 ChatClient 时显式传
ObservationRegistry和这个装饰器 ------ 走单参重载会静默退回 NOOP - 把 registry 接到现有 tracing 后端(Zipkin / OTLP 都行),轮次就是普通 span,不需要自定义 UI
验证方式建议按对照写:同一个脚本跑两遍,一遍接装饰器、一遍不接。前者的 trace 里应该有 N 个轮次 span,后者的断言是「一条都没有」------ 后者才是这条改动真正的价值证明。