简介

saa是java的ai agent框架，本系列将深入剖析 Spring AI Alibaba 的源码实现与核心原理，不仅可以指导agent的开发，更可以改造框架，增加新特性

系列内容：

系列(一)架构完成

系列(三)调用

I工具完成

II MCP

1 MCP MCP能力，工具，资源，Prompts，sampling，。。。；springboot自动配置完成

2分布式 MCP

3 MCP security

III skills完成

系列(四) RAG完成

I知识库，文档读取，分块；嵌入，向量store

II检索，增强生成，模块化；混合检索，融合重排

系列(二) I模型 model模型 chat模型，chat client，advisor组件

系列(五) graph

I图结构，节点和边；StateGraph；外部介入完成

推理框架 graph映射: ReAct，relection，CoT，Plan-And-Execute

II图编译 CompiledGraph，扁平化图结构，邻接表结构完成

III图执行，检查点，回溯/回放，中断和恢复，容错

系列(六) agent及组件 ReactAgent，AgentLlmNode，AgentToolNode，钩子和拦截器，记忆，结构化输出完成

系列(七) MAS

I MAS模式 flow模式编排器-子智能体，智能体团队；简单了解 agentic模式消息总线，共享状态；数据交接

II分布式MAS，远程通讯，负载均衡，注册发现，容错

系列(八)观测

I观测组件(micrometer-observation), langfuse

II spring ai观测，观测组件，ChatClient，ChatModel

III 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缩写sa

spring 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，嵌入，audio，image等类型，其中chat模型包括，advisor组件，提示词，记忆等

agent/graphagent和图紧密相关，可以认为agent是一种既定的”图”形，开发人员可以使用graph底层api直接构建graph，使用agent获得既定的图形，简化agent的开发

外部调用(calling)工具，MCP，skills

RAG检索增强生成

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-completion

TracingAwareLoggingObservationHandler作用是在onStop时，传递tracing信息给包装的处理器使用，用于构成日志内容

观测上下文和处理

• ChatClientObservationContext：继承Observation.Context，持有，

ChatClientRequest，ChatClientResponse ，Advisors 3个业务对象，这些都是观测处理器用来计算/获取指标

TracingAwareLoggingObservationHandler上面介绍过，还有2个默认的handler，DefaultTracingObservationHandler和TracingAwareMeterObservationHandler，技术架构介绍过，分别构建span和计算span时长

观测点key和约定

观测点可以与观测值对应

• ChatClientObservationDocumentation：chatclient的ObservationDocumentation实现，定义了观测点的名称（Name）以及低基数（LowCardinality）和高基数（HighCardinality）的键名（Key Names），确保了监控指标命名的标准化

• DefaultChatClientObservationConvention： ObservationConvention 实现，ObservationDocumentation定义观测key，ObservationConvention负责找到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执行结果response

ChatClientCompletionObservationHandler是直接继承ObservationHandler，可归类为日志型handler

meter handler继承TracingObservationHandler，拥有有MeterRegistry属性，构建Counter，Gauge等指标，注册到MeterRegistry

tracing handler继承TracingObservationHandler，拥有Tracer属性，通常onStart创建span，onStop结束span。

spring ai的ChatModelMeterObservationHandler继承ObservationHandler，其实是meter handler，带MeterRegistry属性，负责生成Token Usage指标。

handler结构

本节分析一下观测handler结构，了解handler结构对自定制观测很重要。

agent模块，chatclient，chatmodel，advisor，tool等共用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可以匹配ContextA，Observation事件通知，将选出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 显示具体的模型是通义千问 Plus

Token 指标： 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 工程化落地的开发者来说，这是必不可少的“眼睛”。

NEXT

spring ai alibaba graph 观测，langfuse实例