ai-agent框架spring ai/alibaba原理源码分析(八)观测II spring ai观测 ChatClient

简介saa是java的ai agent框架本系列将深入剖析 Spring AI Alibaba 的源码实现与核心原理不仅可以指导agent的开发更可以改造框架增加新特性系列内容系列(一)架构完成系列(三)调用I工具完成II MCP1 MCP MCP能力工具资源Promptssampling。。。springboot自动配置完成2分布式 MCP3 MCP securityIII skills完成系列(四) RAG完成I知识库文档读取分块嵌入向量storeII检索增强生成模块化混合检索融合重排系列(二) I模型 model模型 chat模型chat clientadvisor组件系列(五) graphI图结构节点和边StateGraph外部介入完成推理框架 graph映射: ReActrelectionCoTPlan-And-ExecuteII图编译 CompiledGraph扁平化图结构邻接表结构完成III图执行检查点回溯/回放中断和恢复容错系列(六) agent及组件 ReactAgentAgentLlmNodeAgentToolNode钩子和拦截器记忆结构化输出完成系列(七) MASI MAS模式 flow模式编排器-子智能体智能体团队简单了解 agentic模式消息总线共享状态数据交接II分布式MAS远程通讯负载均衡注册发现容错系列(八)观测I观测组件(micrometer-observation), langfuseII spring ai观测观测组件ChatClientChatModelIII spring ai alibaba观测图观测系列(九)评估 langfuse本文分析spring ai观测以chatclient观测为例langfuse观测平台based spring ai v1.1.1.2关键词低基数Low-Cardinality标签值组合有限且数量可控的指标数据如HTTP方法(GET/POST/DELETE)、状态码(200/404)等。高基数High-Cardinality标签值可能无限多的数据比如请求ID (requestId)、用户ID (userId)等缩写spring ai缩写saspring ai alibaba本文缩写saa参考资料概览 | Spring AI Alibaba spring ai alibaba官网文档https://docs.spring.io/spring-ai/reference/index.html spring ai官方文档SAA概览上图是saa原理源码分析场景视图每个包对应着saa/sa组件或特性是本文分析的目录model大模型的封装模型包括Chat嵌入audioimage等类型其中chat模型包括advisor组件提示词记忆等agent/graphagent和图紧密相关可以认为agent是一种既定的”图”形开发人员可以使用graph底层api直接构建graph使用agent获得既定的图形简化agent的开发外部调用(calling)工具MCPskillsRAG检索增强生成MASMAS模式 flow模式 编排器-子智能体智能体团队数据交接studio简易的agent管理工具嵌入到agent带有agent面板列表agent提供chat界面用于调试agent是开发agent的便利工具admin管理台 agent的发布列表管理执行提示词工程评估和数据集观测观测微服务监控常用Prometheus Zipkin/SkyWalking微服务与AI Agent的可观测性相同的核心3要素, 日志指标和链路跟踪但ai agent的监控有其特性langfuse 在监控维度、数据结构和工程闭环上对agent有着深度的定制与扩展微服务监控优化的是性能与可用性系统跑得更快、更稳。langfuse优化效率与智能不仅要看Agent“慢不慢”更关心它“好不好”质量和“贵不贵”成本最终目的是让这个AI系统变得越来越“聪明” 关注agent的思考过程决策逻辑和token消耗观测点-ChatClient上文分析的观测组件opentelemetry组件组合一起的技术架构打通观测链本文结合源码分析使用观测组件实现chatclient观测上图是chatclient的观测类图基于上面micrometer-observation组件和观测技术架构设计启动和自动配置ChatClientAutoConfiguration spirng ai的自动配置这个类在系列-模型分析过负责构建ChatClient本文分析构建ChatClient的观测组件部分创建TracingAwareLoggingObservationHandler依赖ObservationAutoConfiguration构建的Tracer,该类有2个实例分别包装ChatClientCompletionObservationHandler和 ChatClientPromptContentObservationHandler用于记录大模型返回文本和提示词日志大模型返回文本和提示词日志内容很多需手动设置激活spring.ai.chat.client.observations.log-prompt和spring.ai.chat.client.observations.log-completionTracingAwareLoggingObservationHandler作用是在onStop时传递tracing信息给包装的处理器使用用于构成日志内容观测上下文和处理ChatClientObservationContext继承Observation.Context持有ChatClientRequestChatClientResponse Advisors 3个业务对象这些都是观测处理器用来计算/获取指标TracingAwareLoggingObservationHandler上面介绍过还有2个默认的handlerDefaultTracingObservationHandler和TracingAwareMeterObservationHandler技术架构介绍过分别构建span和计算span时长观测点key和约定观测点可以与观测值对应ChatClientObservationDocumentationchatclient的ObservationDocumentation实现定义了观测点的名称Name以及低基数LowCardinality和高基数HighCardinality的键名Key Names确保了监控指标命名的标准化DefaultChatClientObservationConvention ObservationConvention 实现ObservationDocumentation定义观测keyObservationConvention负责找到key的值形成KeyValues。源码分析观测点key和约定上图是ChatClientObservationDocumentation实现为enum是一种单例实现方式上图红框展示低基/高基的key上面两个典型的观测keyValues上方chatclient advisors列表名称通过上下文的advisors属性获取下方是spring ai类型值是枚举获取keyValues的两种来源。观测handler下面以ChatClientCompletionObservationHandler为例子分析handler的处理原理上图ChatClientCompletionObservationHandler在onStop生成completion日志接收ChatClientObservationContext参数使用其属性ChatResponse计算大模型返回文本ChatResponse怎么来DefaultCallResponseSpec doGetObservableChatClientResponse调用大模型的方法Observation的observe调用大模型的代码往ChatClientObservationContext set执行结果responseChatClientCompletionObservationHandler是直接继承ObservationHandler可归类为日志型handlermeter handler继承TracingObservationHandler拥有有MeterRegistry属性构建CounterGauge等指标注册到MeterRegistrytracing handler继承TracingObservationHandler拥有Tracer属性通常onStart创建spanonStop结束span。spring ai的ChatModelMeterObservationHandler继承ObservationHandler其实是meter handler带MeterRegistry属性负责生成Token Usage指标。handler结构本节分析一下观测handler结构了解handler结构对自定制观测很重要。agent模块chatclientchatmodeladvisortool等共用ObservationAutoConfiguration的ObservationRegistryPostProcessor和ObservationRegistry观测handlers注册到ObservationRegistry的ObservationConfig也就是agent全局一套观测handlers。ObservationRegistryPostProcessor用PostProcessor为ObservationRegistry注入handler其内部的ObservationHandlerGrouping将meter和tracing类型的观测handlers分组其他直接继承ObservationHandler不参与分组各自独立。meter组和tracing组各使用FirstMatchingCompositeObservationHandler(实现CompositeObservationHandler接口)*包装起来作为一个handler使用内部getFirstApplicableHandler方法选择使用那个handler选择的依据是第一个匹配Observation.Context结构如下图如上图所示meter handler1和meter handler4可以匹配ContextAObservation事件通知将选出meter handler1处理上图只有一个ObservationHandlerGrouping的情况ObservationHandlerGrouping有多个情况更复杂自定义观测需要耐心规划。*还有一个CompositeObservationHandler实现AllMatchingCompositeObservationHandler选择所有匹配的Observation.Context的handlers观测示例spring ai langfuse本节演示spring ai 的langfuse观测用debug”观测”观测组件示例使用saa的observability-langfuse-example下图展示handler的结构tracing分组meter分组其他3个继承ObservationHandler是日志相关tracing分组两个Propagating*用于远程服务间调用观测的衔接chatclient调用上图chatclient的观测的tracing图节点简要描述Web 入口层 (http get /observability/chat)用户发起的原始 HTTP GET 请求Spring MVCFlux过滤器链产生的异步的观测点Spring AI chatclient (spring_ai chat_client)上图是chatclient观测LLM 交互层 (call - chat qwen-plus)call 节点代表通用的模型调用动作 chat qwen-plus 显示具体的模型是通义千问 PlusToken 指标 Token 消耗数据 14 - 792 (Σ 806)这意味着本次对话输入了 14 个 Token模型输出了 792 个 Token总计消耗 806 个 Token这对于成本核算和性能分析至关重要网络传输层 (http post - POST)chatclient调用-带工具上图是chatclient带工具调用的观测tracing图使用魔搭的bing 搜索mcp工具上图是搜索工具观测观测选项设置include-content: true搜索的内容返回示例改为同步看起来层次比较明显原代码是用stream方式层次不明显总结langfuse 结合 Spring AI 的观测机制解决 AI Agent 开发中的主要痛点隐秘、不可控的模型思考过程、工具执行细节、Token开销转化为了可视化、结构化、可调试的业务指标。对于AI Agent 工程化落地的开发者来说这是必不可少的“眼睛”。NEXTspring ai alibaba graph 观测langfuse实例