ai-agent框架spring ai/alibaba源码原理分析(五) graph II 编译图

简介

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 检索，增强生成，模块化；混合检索，融合重排

系列( 二) 模型 model 模型完成

chat 模型，消息，提示词，结构化输出，记忆

chat client ，advisor 组件

系列( 五) graph 图结构，节点和边；StateGraph

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

CompiledGraph ；图执行，状态和存储

系列( 六) agent 组件分析，ReactAgent ，钩子和拦截器，记忆，结构化输出，人工介入

系列( 七) MAS

I flow agent; handoffs 模式，toolcalling 模式；

II 分布式agent ，A2A ，分布式运行

系列( 九) agent 管理平台(admin) agent 发现(a2a) ，agent 列表，提示词管理，会话管理，skill 管理，MCP 管理；chat ；评估；观测

系列( 八) I 观测：观测组件(micrometer-observation) ，观测点：chatClient ，chat 模型，工具(tracing) II 模型评估

本文分析graph，图编译

based spring ai alibaba v1.1.2.2

关键词

agent

graph

缩写

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/graph saa agent，多agent与图紧密相关，可以认为saa agent/多agent是一种既定的"图"形，实现推理框架，开发人员可以使用graph底层api直接构建graph，使用agent获得既定的图形，简化agent的开发

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

RAG 检索增强生成

MAS A2A，FlowAgent，子agnet，agent Tool；agent 集群

studio 简易的agent管理工具，嵌入到agent，带有agent面板，列表agent；提供chat界面，用于调试agent，是开发agent的便利工具

admin 管理台， agent的发布，列表，管理，执行；提示词工程，评估和数据集，观测

graph

saa graph-core是saa的图组件，以图的结构，节点，边构建处理流程，节点执行动作，边决定下一个节点，对应的，agentic是另一种模式，整个流程大模型自主编排，agentic省心省事，但同时agentic容易失控，纯粹看大模型心情，因此，目前比较好的方案，主体使用flowable，需要的时候使用agentic节点。

spring ai alibaba，agent的推理框架映射成graph，多agent角色也映射成graph，以图的节点承载执行逻辑，边决定下一节点，支持检查点保存执行状态，实现执行的暂停和恢复

外部介入

本节介绍saa的中断机制，中断等待外部干预，例如，人工验证，同时生成检查点(CheckPoint)，用于恢复执行

上图是中断机制两种实现方式，

InterruptableAction 实现该接口的NodeAction，执行器识别Action类型，中断，返回提示，等候外部恢复
interruptsBefore /interrupteAfter 设置interruptsBefore/ interrupteAfter，在CompileConfig设置哪个节点的前/后中断，执行时识别，中断处理

编译图

前面分析了状态图，状态图是图的结构，目的是为了方便构建图，编译图扁平化邻接表数据结构，目的是为了高效执行

上图是编译图类图，编译把整个图，包括子图的数据结构转换为扁平化的邻接表结构，遍历不需要递归，还有并行处理，使用并行节点/action，节点内处理并行，执行过程不需处理。

下面分析原理和源码

扁平化邻接表

ProcessedNodesEdgesAndConfig 负责扁平化状态图数据结构，代码比较多，用示例解释代码逻辑，注释版的代码放到附录

首先介绍一下邻接表，

|---------------------------------------|----------------------------------------------------------------------------|
| 'A': $'B'$ , 'B': $'C'$ , 'C': \[\] | |

左：连接点结构，左是head节点，右是数组，head节点连接的节点；右：对应的图

进一步，若B是子图节点，其子图 D->E, D->F,E->G,F->G

ProcessedNodesEdgesAndConfig 处理过后

|--------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|
| 'A': $'B-D'$ , 'B-D': $'B-E', 'B-F'$ , 'B-E': $'B-G'$ , 'B-F': $'B-G'$ , 'B-G': $'C'$ , 'C': \[\] | |

主图子图扁平化，合并到一个**邻接表结构，**主图与子图节点(B)的连接重定向到子图的节点，子图节点名称修改，格式%s-%s

最后，返回子图的Node写入到nodeFactoryes，id为key，action工程为value的map

CompiledGraph.CompiledGraph()

nodeFactoryes是最终的邻接表head节点集

边和并行处理

ProcessedNodesEdgesAndConfig处理后，返回边(edges)是list，图遍历按节点找边需要遍历list，因此边数据需要转为map，以sourceNodeId为key，即，List<Edge>类型转为Map<String, EdgeValue>，另外，图有并行分支，编译使用并行节点替代，并行执行在节点action完成，不需要执行器介入