它是如何工作的拆解Spring AI Alibaba DataAgent的StateGraph工作流引擎从意图识别到报告生成的全链路【免费下载链接】DataAgentSpring AI Alibaba DataAgent项目地址: https://gitcode.com/gh_mirrors/da/DataAgentSpring AI Alibaba DataAgent 是一款基于 Spring AI Alibaba 构建的NL2SQL 数据分析智能体你用一句自然语言提问比如帮我查询订单数据它就能自动识别意图、检索数据库 Schema、生成并执行 SQL、用 Python 做进一步分析最终输出一份完整的分析报告。而这一切的大脑就是项目里那张由StateGraph 工作流引擎驱动的有向图。这篇文章带你完整拆解这个工作流引擎16 个工作节点如何串联、条件边Dispatcher如何分岔、状态如何在节点之间流动以及人工审核如何在工作流中途暂停-恢复。读完你会对多智能体工作流的工程设计有一个清晰的认知。一、StateGraph 工作流引擎是什么在图数据库和工作流编排的语境里StateGraph可以理解为三个要素的组合节点Node每个节点干一件具体的事——调 LLM、查向量库、执行 SQL……边Edge节点之间的连线。分两种固定边addEdge无条件A 执行完必定到 B条件边addConditionalEdges由一个Dispatcher分发器根据当前状态动态决定下一站甚至可以绕回自己重试。共享状态OverAllState一块所有节点都能读写的黑板节点之间不直接传参而是把结果写进状态下游节点从状态里取。整张图的定义集中在一个 Spring 配置类里打开它就能看懂全局图的构建入口DataAgentConfiguration.java#L148-L294启动时它还会把整张工作流渲染成 PlantUML 日志打印出来方便开发者看图说话。图被compile()编译后由 GraphServiceImpl.java 负责驱动以stream()方式流式执行把每个节点的输出通过 SSE 实时推送到前端页面。二、全链路拆解一句话如何变成一份报告整条链路共5 个阶段、16 个节点源码全部位于 workflow/node/ 目录。下面按执行顺序逐个介绍。阶段 1听懂你在问什么意图识别 → 证据召回 → 查询改写① 意图识别节点IntentRecognitionNode是入口。它调 LLM 判断用户输入属于哪类如果是闲聊或无关指令直接给出回答并结束流程直达 END不浪费算力如果是有意义的数据分析请求则进入后续链路。实现见 IntentRecognitionNode.java#L54-L87——这里有个巧妙设计节点输出一个流式生成器所以识别过程能逐字打字机式地推送到前端。② 证据召回节点EvidenceRecallNode负责两件事从问题中提取关键词再到业务知识库向量检索中寻找相关证据比如指标口径、业务术语解释。③ 查询增强节点QueryEnhanceNode基于召回的证据对问题进行改写与扩展把口语化的提问翻译成结构化、信息量更大的分析查询。前端页面上你能实时看到这三个节点依次展开的过程 小提示任一节点若判定此路不通其 Dispatcher 都会把流程导向 END 并给出原因而不是硬闯到下一步。阶段 2找到数据在哪Schema 召回 → 表关系推理 → 可行性评估④ Schema 召回节点SchemaRecallNode根据关键词和意图从数据库表结构向量库中召回相关的表、列及其注释避免把几十张表全部塞给大模型。⑤ 表关系推理节点TableRelationNode自动补齐 JOIN 关系与外键结构让大模型知道订单表和用户表该怎么连。这个节点带自环重试推理失败时 Dispatcher 会把它指回自己再试一次。⑥ 可行性评估节点FeasibilityAssessmentNode在动手前先审题根据已召回的表结构判断这个问题能否用现有数据回答。如果答案明显不在数据库里流程到此终止并礼貌地回复用户——这是省钱又省时的守门员。阶段 3制定计划Planner → PlanExecutor⑦ 规划节点PlannerNode综合前面的所有信息让 LLM 输出一份多步执行计划Plan比如第一步用 SQL 提取订单数据第二步用 Python 做趋势分析第三步汇总成报告。⑧ 计划执行器PlanExecutorNode是整张图最像调度塔的节点它负责两件事校验计划格式不对退回 Planner 修复自环按计划分发当前步骤是 SQL 类任务去 SQL 生成节点是 Python 类任务去 Python 代码生成节点所有步骤做完去报告生成节点如果开启了人工审核则先去人工反馈节点等人拍板。阶段 4两条执行路线SQL 路线与 Python 路线 SQL 路线三步走带双重校验⑨ SQL 生成节点SqlGenerateNode结合 Schema、表关系与业务知识生成 SQL支持多轮优化与自我再生成⑩ 语义一致性节点SemanticConsistencyNode校验生成的 SQL 语义与用户原始问题是否一致不一致则打回重新生成⑪ SQL 执行节点SqlExecuteNode对真实数据库执行 SQL执行报错则回到 ⑨ 重新生成成功后把结果写回状态并回到 PlanExecutor 执行计划的下一步。 Python 路线三步走带重试⑫ Python 代码生成节点PythonGenerateNode基于 SQL 查询结果生成 Python 分析代码统计、绘图、建模等⑬ Python 执行节点PythonExecuteNode在沙箱Docker / 本地 / AI 模拟三种执行器中运行代码失败则退回 ⑫ 重试超过次数上限则降级处理⑭ Python 分析节点PythonAnalyzeNode对代码运行结果做总结然后回到 PlanExecutor 继续推进计划。纯 SQL 模式下用户也可以跳过整个分析链路直接走nl2sql()接口只拿 SQL 语句阶段 5生成报告收尾⑮ 报告生成节点ReportGeneratorNode汇总全部执行结果——SQL 数据、Python 分析结论、图表——生成一份结构化的 Markdown 分析报告随后流程走向 END。最终你在页面上看到的就是这样一份包含执行摘要、关键发现和完整分析过程的报告三、两个核心机制条件边分发器与检查点暂停1. Dispatcher工作流的交通警察你会发现每个节点后面跟的不是固定边而是一个Dispatcher共 11 个位于 workflow/dispatcher/ 目录。以意图识别为例IntentRecognitionDispatcher读取状态里的识别结果——闲聊 → END数据分析 → 证据召回节点。这种节点产出状态 分发器读取状态决定去向的模式让工作流的路由逻辑与业务逻辑彻底解耦也为每个节点保留了独立的回退路径重试、修复、降级这是 DataAgent 工作流健壮性的关键来源。2. 人工审核如何在工作流中途暂停-恢复开启人工反馈模式后PlanExecutor 分发到的不是执行节点而是⑯ 人工反馈节点HumanFeedbackNode。此时编译配置里声明了interruptBefore(HUMAN_FEEDBACK_NODE)见 DataAgentConfiguration.java#L318-L322图运行到该节点之前自动中断当前工作流状态由检查点保存器持久化默认MysqlSaver存入 MySQL也可切换为内存MemorySaver用户在页面上批准或驳回计划后GraphServiceImpl.java#L190-L234 会先把反馈写入状态updateState再以stream(null, resumeConfig)从断点原地恢复执行批准则继续驳回则回退给 Planner 重新规划。这就是 LangGraph 风格的人在回路Human-in-the-loop能力在 Spring AI Alibaba 上的落地四、状态如何流动OverAllState 共享黑板所有节点之间不直接传话而是读写一块共享状态。每个状态键在图上声明了策略DataAgent 中统一为REPLACE见 Constant.java#L97-L128 定义的节点名与状态键典型的流转链路是阶段写入状态举例谁消费意图识别INTENT_RECOGNITION_NODE_OUTPUT证据召回节点证据召回EVIDENCE查询增强节点Schema 召回表/列文档表关系、SQL 生成节点计划与执行PLANNER_NODE_OUTPUT、SQL_EXECUTE_NODE_OUTPUTPlanExecutor、报告生成节点最终产出FINAL_ANSWER流式推送给前端多轮对话场景下MultiTurnContextManager还会把历史轮次的对话上下文注入MULTI_TURN_CONTEXT让每一轮工作流都记得上一轮问过了什么。五、想深入源码从这里开始图的构建DataAgentConfiguration.java —— 节点注册与条件边连接的全貌图运行与 SSE 推送GraphServiceImpl.java16 个节点实现workflow/node/11 个条件边分发器workflow/dispatcher/架构总览文档docs/ARCHITECTURE.md节点依赖关系分析docs/superpowers/nodes-dependency-analysis.md进阶功能说明docs/ADVANCED_FEATURES.md。一句话总结DataAgent 的 StateGraph 工作流引擎 一条主干流水线意图 → 检索 → 规划 一个智能调度塔PlanExecutor 两条可重试的执行路线SQL / Python 一套检查点机制支持人工介入。理解了这个结构你也就掌握了用 Spring AI Alibaba 搭建多节点 LLM 工作流的核心范式 【免费下载链接】DataAgentSpring AI Alibaba DataAgent项目地址: https://gitcode.com/gh_mirrors/da/DataAgent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/2 16:43:06 · 阅读 1.2k 它是如何工作的？拆解Spring AI Alibaba DataAgent的StateGraph工作流引擎：从意图识别到报告生成的全链路
它是如何工作的拆解Spring AI Alibaba DataAgent的StateGraph工作流引擎从意图识别到报告生成的全链路【免费下载链接】DataAgentSpring AI Alibaba DataAgent项目地址: https://gitcode.com/gh_mirrors/da/DataAgentSpring AI Alibaba DataAgent 是一款基于 Spring AI Alibaba 构建的NL2SQL 数据分析智能体你用一句自然语言提问比如帮我查询订单数据它就能自动识别意图、检索数据库 Schema、生成并执行 SQL、用 Python 做进一步分析最终输出一份完整的分析报告。而这一切的大脑就是项目里那张由StateGraph 工作流引擎驱动的有向图。这篇文章带你完整拆解这个工作流引擎16 个工作节点如何串联、条件边Dispatcher如何分岔、状态如何在节点之间流动以及人工审核如何在工作流中途暂停-恢复。读完你会对多智能体工作流的工程设计有一个清晰的认知。一、StateGraph 工作流引擎是什么在图数据库和工作流编排的语境里StateGraph可以理解为三个要素的组合节点Node每个节点干一件具体的事——调 LLM、查向量库、执行 SQL……边Edge节点之间的连线。分两种固定边addEdge无条件A 执行完必定到 B条件边addConditionalEdges由一个Dispatcher分发器根据当前状态动态决定下一站甚至可以绕回自己重试。共享状态OverAllState一块所有节点都能读写的黑板节点之间不直接传参而是把结果写进状态下游节点从状态里取。整张图的定义集中在一个 Spring 配置类里打开它就能看懂全局图的构建入口DataAgentConfiguration.java#L148-L294启动时它还会把整张工作流渲染成 PlantUML 日志打印出来方便开发者看图说话。图被compile()编译后由 GraphServiceImpl.java 负责驱动以stream()方式流式执行把每个节点的输出通过 SSE 实时推送到前端页面。二、全链路拆解一句话如何变成一份报告整条链路共5 个阶段、16 个节点源码全部位于 workflow/node/ 目录。下面按执行顺序逐个介绍。阶段 1听懂你在问什么意图识别 → 证据召回 → 查询改写① 意图识别节点IntentRecognitionNode是入口。它调 LLM 判断用户输入属于哪类如果是闲聊或无关指令直接给出回答并结束流程直达 END不浪费算力如果是有意义的数据分析请求则进入后续链路。实现见 IntentRecognitionNode.java#L54-L87——这里有个巧妙设计节点输出一个流式生成器所以识别过程能逐字打字机式地推送到前端。② 证据召回节点EvidenceRecallNode负责两件事从问题中提取关键词再到业务知识库向量检索中寻找相关证据比如指标口径、业务术语解释。③ 查询增强节点QueryEnhanceNode基于召回的证据对问题进行改写与扩展把口语化的提问翻译成结构化、信息量更大的分析查询。前端页面上你能实时看到这三个节点依次展开的过程 小提示任一节点若判定此路不通其 Dispatcher 都会把流程导向 END 并给出原因而不是硬闯到下一步。阶段 2找到数据在哪Schema 召回 → 表关系推理 → 可行性评估④ Schema 召回节点SchemaRecallNode根据关键词和意图从数据库表结构向量库中召回相关的表、列及其注释避免把几十张表全部塞给大模型。⑤ 表关系推理节点TableRelationNode自动补齐 JOIN 关系与外键结构让大模型知道订单表和用户表该怎么连。这个节点带自环重试推理失败时 Dispatcher 会把它指回自己再试一次。⑥ 可行性评估节点FeasibilityAssessmentNode在动手前先审题根据已召回的表结构判断这个问题能否用现有数据回答。如果答案明显不在数据库里流程到此终止并礼貌地回复用户——这是省钱又省时的守门员。阶段 3制定计划Planner → PlanExecutor⑦ 规划节点PlannerNode综合前面的所有信息让 LLM 输出一份多步执行计划Plan比如第一步用 SQL 提取订单数据第二步用 Python 做趋势分析第三步汇总成报告。⑧ 计划执行器PlanExecutorNode是整张图最像调度塔的节点它负责两件事校验计划格式不对退回 Planner 修复自环按计划分发当前步骤是 SQL 类任务去 SQL 生成节点是 Python 类任务去 Python 代码生成节点所有步骤做完去报告生成节点如果开启了人工审核则先去人工反馈节点等人拍板。阶段 4两条执行路线SQL 路线与 Python 路线 SQL 路线三步走带双重校验⑨ SQL 生成节点SqlGenerateNode结合 Schema、表关系与业务知识生成 SQL支持多轮优化与自我再生成⑩ 语义一致性节点SemanticConsistencyNode校验生成的 SQL 语义与用户原始问题是否一致不一致则打回重新生成⑪ SQL 执行节点SqlExecuteNode对真实数据库执行 SQL执行报错则回到 ⑨ 重新生成成功后把结果写回状态并回到 PlanExecutor 执行计划的下一步。 Python 路线三步走带重试⑫ Python 代码生成节点PythonGenerateNode基于 SQL 查询结果生成 Python 分析代码统计、绘图、建模等⑬ Python 执行节点PythonExecuteNode在沙箱Docker / 本地 / AI 模拟三种执行器中运行代码失败则退回 ⑫ 重试超过次数上限则降级处理⑭ Python 分析节点PythonAnalyzeNode对代码运行结果做总结然后回到 PlanExecutor 继续推进计划。纯 SQL 模式下用户也可以跳过整个分析链路直接走nl2sql()接口只拿 SQL 语句阶段 5生成报告收尾⑮ 报告生成节点ReportGeneratorNode汇总全部执行结果——SQL 数据、Python 分析结论、图表——生成一份结构化的 Markdown 分析报告随后流程走向 END。最终你在页面上看到的就是这样一份包含执行摘要、关键发现和完整分析过程的报告三、两个核心机制条件边分发器与检查点暂停1. Dispatcher工作流的交通警察你会发现每个节点后面跟的不是固定边而是一个Dispatcher共 11 个位于 workflow/dispatcher/ 目录。以意图识别为例IntentRecognitionDispatcher读取状态里的识别结果——闲聊 → END数据分析 → 证据召回节点。这种节点产出状态 分发器读取状态决定去向的模式让工作流的路由逻辑与业务逻辑彻底解耦也为每个节点保留了独立的回退路径重试、修复、降级这是 DataAgent 工作流健壮性的关键来源。2. 人工审核如何在工作流中途暂停-恢复开启人工反馈模式后PlanExecutor 分发到的不是执行节点而是⑯ 人工反馈节点HumanFeedbackNode。此时编译配置里声明了interruptBefore(HUMAN_FEEDBACK_NODE)见 DataAgentConfiguration.java#L318-L322图运行到该节点之前自动中断当前工作流状态由检查点保存器持久化默认MysqlSaver存入 MySQL也可切换为内存MemorySaver用户在页面上批准或驳回计划后GraphServiceImpl.java#L190-L234 会先把反馈写入状态updateState再以stream(null, resumeConfig)从断点原地恢复执行批准则继续驳回则回退给 Planner 重新规划。这就是 LangGraph 风格的人在回路Human-in-the-loop能力在 Spring AI Alibaba 上的落地四、状态如何流动OverAllState 共享黑板所有节点之间不直接传话而是读写一块共享状态。每个状态键在图上声明了策略DataAgent 中统一为REPLACE见 Constant.java#L97-L128 定义的节点名与状态键典型的流转链路是阶段写入状态举例谁消费意图识别INTENT_RECOGNITION_NODE_OUTPUT证据召回节点证据召回EVIDENCE查询增强节点Schema 召回表/列文档表关系、SQL 生成节点计划与执行PLANNER_NODE_OUTPUT、SQL_EXECUTE_NODE_OUTPUTPlanExecutor、报告生成节点最终产出FINAL_ANSWER流式推送给前端多轮对话场景下MultiTurnContextManager还会把历史轮次的对话上下文注入MULTI_TURN_CONTEXT让每一轮工作流都记得上一轮问过了什么。五、想深入源码从这里开始图的构建DataAgentConfiguration.java —— 节点注册与条件边连接的全貌图运行与 SSE 推送GraphServiceImpl.java16 个节点实现workflow/node/11 个条件边分发器workflow/dispatcher/架构总览文档docs/ARCHITECTURE.md节点依赖关系分析docs/superpowers/nodes-dependency-analysis.md进阶功能说明docs/ADVANCED_FEATURES.md。一句话总结DataAgent 的 StateGraph 工作流引擎 一条主干流水线意图 → 检索 → 规划 一个智能调度塔PlanExecutor 两条可重试的执行路线SQL / Python 一套检查点机制支持人工介入。理解了这个结构你也就掌握了用 Spring AI Alibaba 搭建多节点 LLM 工作流的核心范式 【免费下载链接】DataAgentSpring AI Alibaba DataAgent项目地址: https://gitcode.com/gh_mirrors/da/DataAgent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考