Spring AI Alibaba Graph 入门实践：理解黑板、节点与边

在智能体或复杂 AI 工作流中，业务步骤往往不是简单的顺序调用，而是需要共享状态、条件分支、并行处理和中断恢复。Spring AI Alibaba Graph 将这些过程组织成可编译、可执行的状态图。下面从一个最小示例出发，逐步理解黑板、节点和边如何配合完成流程编排。

Spring AI Alibaba Graph 快速上手：黑板、节点、边

版本：基于 spring-ai-alibaba 1.0.0.4（配合 Spring AI 1.0.3）

环境准备

    com.alibaba.cloud.ai
    spring-ai-alibaba-graph-core
    1.0.0.4

第 1 层 · 最小骨架

先不谈业务。下面这 40 行是一张完整可运行的图。

输入一段文本，超过 10 个字符就截断，否则原样返回。

import com.alibaba.cloud.ai.graph.*;
import com.alibaba.cloud.ai.graph.action.AsyncEdgeAction;
import com.alibaba.cloud.ai.graph.action.AsyncNodeAction;
import com.alibaba.cloud.ai.graph.state.strategy.ReplaceStrategy;

import java.util.Map;

public class MinimalDemo {

    public static void main(String[] args) throws Exception {

        // ① 黑板：声明有哪些 key，以及多个节点写同一个 key 时怎么合并
        KeyStrategyFactory keys = () -> Map.of(
                "text",   new ReplaceStrategy(),
                "size",   new ReplaceStrategy(),
                "result", new ReplaceStrategy());

        // ② 节点：只读写黑板
        AsyncNodeAction measure = AsyncNodeAction.node_async(state -> {
            String text = state.value("text", "");
            return Map.of("size", text.length() > 10 ? "LONG" : "SHORT");
        });

        AsyncNodeAction keep = AsyncNodeAction.node_async(state -> {
            String text = state.value("text", "");
            return Map.of("result", text);
        });

        AsyncNodeAction cut = AsyncNodeAction.node_async(state -> {
            String text = state.value("text", "");
            return Map.of("result", text.substring(0, 10) + "...");
        });

        // ③ 路由函数：读黑板，返回一个「标签」
        AsyncEdgeAction route = AsyncEdgeAction.edge_async(
                state -> state.value("size", "SHORT"));

        // ④ 组装成图
        CompiledGraph graph = new StateGraph("demo", keys)
                .addNode("measure", measure)
                .addNode("keep",    keep)
                .addNode("cut",     cut)
                .addEdge(StateGraph.START, "measure")
                .addConditionalEdges("measure", route,
                        Map.of("LONG",  "cut",
                               "SHORT", "keep"))
                .addEdge("keep", StateGraph.END)
                .addEdge("cut",  StateGraph.END)
                .compile();

        // ⑤ 跑两次，观察分支
        System.out.println(graph.call(Map.of("text", "hi")).get().data());
        System.out.println(graph.call(Map.of("text", "Hello, Spring AI Alibaba Graph!")).get().data());
    }
}

跑起来会看到两次输出，第二次走了 cut 分支：

{text=hi, size=SHORT, result=hi}
{text=Hello, Spring AI Alibaba Graph!, size=LONG, result=Hello, Spr...}

这张图长什么样

START ──► measure ──┬── "SHORT" ──► keep ──► END
                    └── "LONG"  ──► cut  ──► END

核心概念

第 2 层 · 逐个拆解

2.1 OverAllState：黑板

一个 Map，外加「每个 key 怎么合并」的规则。

节点 A 不直接调用节点 B。A 把结果写到黑板上，B 从黑板上读。节点之间互不认识

声明黑板上有哪些格子

KeyStrategyFactory keys = () -> Map.of(
        "text",   new ReplaceStrategy(),
        "size",   new ReplaceStrategy(),
        "result", new ReplaceStrategy());

KeyStrategyFactory 是个 @FunctionalInterface，返回 Map。写成匿名内部类等价：

KeyStrategyFactory keys = new KeyStrategyFactory() {
    @Override
    public Map apply() {
        return Map.of("text", new ReplaceStrategy());
    }
};

框架内置三种策略：

ReplaceStrategy：发生在每个节点执行完、框架把该节点返回的 Map 合并进黑板的那一刻——apply(旧值, 新值) 的实现就是 return 新值。被换掉的是这个 key 上整个 value 对象。

选型口诀：中间结果用 Replace，对话历史/日志用 Append，多节点共写一个 Map 用 Merge。

没声明的 key 会怎样？ 默认走 ReplaceStrategy

纯覆盖场景理论上可以不声明。但建议写全：显式声明等于给黑板列了一份 schema，哪个节点读哪些 key、写哪些 key，一眼就能看明白。

读：三个重载

String text = state.value("text", "");                       // 带默认值，返回原始类型
Optional