Spring AI Alibaba 架构学习指南

嘿,朋友!👋 欢迎来到 Spring AI Alibaba 的学习之旅。我是你的技术教练,接下来我会像聊天一样,带你一步步揭开这个企业级 AI 应用框架的神秘面纱。相信我,虽然这是个功能强大的企业级框架,但学起来并不可怕,反而会让你对 AI 应用开发有全新的认识!😊

第一部分:项目架构深度解析(像架构师一样俯瞰全景)🔍

本部分目标: 带你站在架构师的视角,理解 Spring AI Alibaba 的设计哲学和架构精髓。不只是知道"是什么",更要理解"为什么这么设计"。

1. 项目架构概览

🎯 用一个类比来理解

想象你要组建一个 AI 助手团队来帮助企业处理各种任务。Spring AI Alibaba 就像是一个智能中央调度系统:

Graph (工作流引擎) 像是项目经理,负责编排任务流程,决定谁先做什么,谁后做什么;
MCP (模型上下文协议) 像是工具库管理员,帮你找到合适的工具和服务;
Core (核心模块) 像是AI 能力中心,提供聊天、图像生成、语音识别等基础能力;
A2A (Agent to Agent) 像是团队协作平台,让不同的 AI 智能体可以互相交流;
Studio (开发平台) 像是可视化调试工具,让你能看到整个系统的运行状态。

🏗️ 核心设计特征

Spring AI Alibaba 采用了模块化 + 分层架构的设计:

模块化设计: 每个模块职责单一,可以独立使用也可以组合使用
Spring Boot Starter 模式: 典型的 Spring 生态风格,开箱即用
企业级集成能力: 深度集成阿里云生态(百炼平台、ARMS、Nacos 等)
可观测性优先: 内置分布式追踪和可观测性支持

🆚 与其他 AI 框架的差异

与 LangChain、LlamaIndex 等 Python 生态的 AI 框架相比,Spring AI Alibaba 的独特优势在于:

✅ Java 生态原生支持: 完美融入 Spring Boot 生态,企业级开发者更熟悉
✅ 企业级生产就绪: 内置可观测性、分布式追踪、服务治理等企业级特性
✅ 阿里云深度集成: 与百炼平台、DashScope 等无缝对接
✅ Graph 多智能体框架: 对标 LangGraph,但更适合 Java 开发者
✅ MCP 企业级实现: 提供基于 Nacos 的分布式 MCP 注册和路由

🛠️ 技术栈分析

从 pom.xml 中可以看到项目的核心技术栈:

技术组件	版本	作用
Java	17	基础运行环境,利用了现代 Java 特性
Spring Boot	3.4.8	应用框架基础
Spring AI	1.0.1	AI 抽象层基础
DashScope SDK	2.15.1	阿里云通义系列模型接入
Nacos	3.1.0	服务注册发现、配置管理
MCP SDK	0.11.2	模型上下文协议支持
OpenTelemetry	1.38.0	分布式追踪

设计考量分析:

Java 17: 不是最新的 LTS 版本(Java 21),但足够现代,平衡了新特性和企业兼容性
Spring Boot 3.x: 拥抱 Jakarta EE 和现代 Spring 生态
Nacos 3.x: 选择了阿里云的服务治理方案,而非 Eureka 或 Consul

🌐 外部系统集成

Spring AI Alibaba 集成了以下外部系统:

graph TB
    A[Spring AI Alibaba] --> B[阿里云百炼平台]
    A --> C[DashScope 模型服务]
    A --> D[Nacos 服务注册]
    A --> E[ARMS 可观测平台]
    A --> F[向量数据库]
    A --> G[Redis/缓存]
    A --> H[关系型数据库]

    B --> |RAG知识库| A
    C --> |通义千问/通义万相| A
    D --> |MCP注册发现| A
    E --> |分布式追踪| A

📊 架构流程描述

让我用一个典型的"智能客服咨询"场景来说明请求流程:

用户提问 
  ↓
[Spring MVC Controller] 接收请求
  ↓
[StateGraph] 工作流引擎启动
  ↓
[QuestionClassifierNode] 问题分类节点(调用 DashScope)
  ↓
[条件边判断] 根据分类结果决定下一步
  ↓                    ↓
[KnowledgeRetrievalNode]   [ToolNode]
(RAG 检索)             (工具调用)
  ↓                    ↓
[LlmNode] 大模型生成答案
  ↓
[ObservationRegistry] 记录可观测数据
  ↓
返回结果给用户

2. 目录结构与核心流程

📁 目录组织逻辑

Spring AI Alibaba 采用典型的 Maven 多模块项目 结构:

spring-ai-alibaba/
├── spring-ai-alibaba-core/              # 核心模块(DashScope、RAG、评估器)
├── spring-ai-alibaba-graph-core/        # Graph 工作流和多智能体框架
├── spring-ai-alibaba-mcp/              # MCP 协议支持
│   ├── spring-ai-alibaba-mcp-common/   # 通用定义
│   ├── spring-ai-alibaba-mcp-registry/ # 服务注册
│   └── spring-ai-alibaba-mcp-router/   # 智能路由
├── spring-ai-alibaba-a2a/              # Agent to Agent 通信
├── spring-ai-alibaba-studio/           # 开发平台
├── spring-ai-alibaba-observation-extension/  # 可观测性扩展
├── auto-configurations/                # 自动配置模块
└── spring-ai-alibaba-spring-boot-starters/   # Starter 依赖

设计意图分析:

✨ 关注点分离: 每个模块职责清晰,core 提供基础能力,graph 提供编排能力
✨ 依赖解耦: mcp、a2a 等可以独立使用
✨ Spring Boot 风格: auto-configurations + starters 的标准模式

🔑 关键文件定位

"第一个应阅读"的文件:

README-zh.md - 项目概览和快速开始(⭐⭐⭐⭐⭐ 必读)
pom.xml - 理解技术栈和依赖版本
spring-ai-alibaba-graph-core/README-zh.md - Graph 核心概念
spring-ai-alibaba-mcp/spring-ai-alibaba-mcp-router/README.md - MCP 路由机制

"核心业务逻辑"所在:

Chat 模型实现: spring-ai-alibaba-core/src/main/java/com/alibaba/cloud/ai/dashscope/chat/DashScopeChatModel.java
Graph 核心: spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/StateGraph.java
预定义节点: spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/node/

🔗 模块依赖关系

graph LR
    A[Starters] --> B[Auto Configurations]
    B --> C[Core Modules]

    D[graph-core] --> E[spring-ai-alibaba-core]
    F[mcp-router] --> E
    G[a2a] --> E

    E --> H[Spring AI]
    E --> I[DashScope SDK]

依赖特点:

✅ 单向依赖: 上层依赖下层,没有循环依赖
✅ 清晰分层: Starter → AutoConfiguration → Core → 第三方 SDK
⚠️ 注意: graph-core、mcp、a2a 都是独立模块,互不依赖

🎬 典型业务流程:工作流客服场景

让我以 Graph 模块中的"客户评价处理系统"为例,详细说明数据流和控制流。

场景: 用户提交产品评价,系统自动分类并处理

涉及的核心文件:

WorkflowAutoconfiguration.java - 定义工作流图
CustomerServiceController.java - REST 控制器
QuestionClassifierNode.java - 问题分类节点
RecordingNode.java - 自定义记录节点

完整流程图:

sequenceDiagram
    participant User as 用户
    participant Controller as CustomerServiceController
    participant Graph as StateGraph
    participant FeedbackNode as feedback_classifier
    participant SpecificNode as specific_question_classifier
    participant RecordNode as recorder
    participant LLM as DashScope 大模型

    User->>Controller: GET /customer/chat?query=产品很好!
    Controller->>Graph: compiledGraph.stream(input)
    Graph->>FeedbackNode: 执行正负面分类
    FeedbackNode->>LLM: 调用大模型分析情感
    LLM-->>FeedbackNode: 返回 "positive feedback"
    FeedbackNode-->>Graph: 更新 classifier_output
    Graph->>RecordNode: 条件边路由到 recorder
    RecordNode->>RecordNode: 生成处理方案
    RecordNode-->>Graph: 返回 "Praise, no action taken."
    Graph-->>Controller: 流式返回结果
    Controller-->>User: 返回处理结果

关键步骤详解:

初始化状态 (OverAllState):

OverAllState state = new OverAllState();
state.registerKeyAndStrategy("input", new ReplaceStrategy());
state.registerKeyAndStrategy("classifier_output", new ReplaceStrategy());
state.registerKeyAndStrategy("solution", new ReplaceStrategy());

定义节点 (spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/node/QuestionClassifierNode.java):
- 节点使用 ChatClient 调用大模型
- 根据 prompt 进行语义分类
- 将结果写入 classifier_output
条件路由 (FeedbackQuestionDispatcher):
- 读取 classifier_output
- 包含 "positive" → 路由到 recorder
- 否则 → 路由到 specific_question_classifier
状态传递: 整个流程中,OverAllState 对象在各节点间流转,携带所有上下文信息

实现文件索引:

节点定义: spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/node/QuestionClassifierNode.java:108-124
边的调度: 在 Controller 中实现 EdgeAction 接口
图编译: spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/StateGraph.java

3. 代码结构观察

🏛️ 代码组织模式

通过观察代码,我发现 Spring AI Alibaba 遵循了这些模式:

Builder 模式无处不在:

QuestionClassifierNode.builder()
    .chatClient(chatClient)
    .inputTextKey("input")
    .categories(List.of("positive", "negative"))
    .build();

接口与实现分离:
- NodeAction 接口 → 各种具体节点实现
- EdgeAction 接口 → 条件路由实现
- McpServiceDiscovery 接口 → NacosMcpServiceDiscovery 实现

策略模式:

state.registerKeyAndStrategy("messages", new AppenderChannel<>());
state.registerKeyAndStrategy("userId", new ReplaceStrategy());

观察者模式:
- GraphLifecycleListener 监听工作流生命周期
- GraphObservationLifecycleListener 集成 Micrometer 可观测

🎨 设计模式识别

设计模式	应用场景	位置
Builder	复杂对象构建	所有 Node、Options 类
Strategy	状态更新策略	`KeyStrategy` 体系
Factory	创建 StateGraph	`OverAllStateFactory`
Observer	可观测性	`GraphLifecycleListener`
Template Method	执行流程	`AbstractRouterWatcher`
Adapter	协议适配	MCP 相关适配器

📏 代码质量观察

优点:

✅ 命名清晰: 类名和方法名都很直观(QuestionClassifierNode、addConditionalEdges)
✅ 模块化好: 每个类职责单一,没有发现"上帝类"
✅ 注释完善: 核心 API 都有 Javadoc
✅ 测试覆盖: graph-core 和 core 模块都有完整的测试

可以关注的点:

💡 异步编程: 大量使用 CompletableFuture 和 Reactor,需要熟悉异步编程
💡 泛型使用: StateGraph 的泛型设计比较复杂,需要仔细理解
💡 配置复杂度: 多个配置文件(application.yml、spring.factories),需要理解 Spring Boot 自动配置机制

🔍 潜在改进点(学习机会)

通过搜索 TODO 和 FIXME,以及代码观察,我发现一些值得探索的方向:

文档国际化: 部分模块的 README 只有中文版,可以贡献英文文档
示例丰富性: 可以为一些复杂特性(如子图、并行节点)补充更多示例
性能优化: 向量检索部分可以探索缓存策略优化
错误处理: 部分异常信息可以更友好

这里需要说明的是,这些不是"代码问题",而是你可以贡献的"学习机会"。😊 参与这些改进,会让你对框架理解更深刻!

第二部分:技能需求清单(你的学习弹药库)📚

本部分目标: 明确学习 Spring AI Alibaba 需要掌握哪些技能,以及到什么程度。别慌,我会告诉你哪些是必须的,哪些是锦上添花的!

1. 基础技能要求

💻 编程语言和框架

必须掌握的核心技能:

Java 语言基础 (⭐⭐⭐⭐⭐ 核心)
- Java 17 语法特性(Records、Sealed Classes、Text Blocks)
- Lambda 表达式和 Stream API
- 泛型的高级用法
- 异常处理机制
Spring 全家桶 (⭐⭐⭐⭐⭐ 核心)
- Spring IoC 和 DI 原理
- Spring Boot 自动配置机制
- Spring MVC / WebFlux
- Spring Boot Actuator
Maven 构建工具 (⭐⭐⭐⭐ 重要)
- 多模块项目管理
- 依赖管理和版本控制
- Maven 生命周期和插件

📦 具体版本要求

从 pom.xml 中我们可以看到:

<java.version>17</java.version>
<spring-boot.version>3.4.8</spring-boot.version>
<spring-ai.version>1.0.1</spring-ai.version>

版本兼容性重要提示:

⚠️ Java 17 是硬性要求: 代码使用了 Records、Sealed Classes 等新特性
⚠️ Spring Boot 3.x: 基于 Jakarta EE,与 2.x 有较大差异
⚠️ Spring AI 1.0.x: API 可能还在演进,需要关注官方文档

🛠️ 基础工具和概念

工具/概念	重要程度	说明
Git	⭐⭐⭐⭐⭐	版本控制、代码协作
IDE (IntelliJ IDEA)	⭐⭐⭐⭐⭐	推荐使用 IDEA Ultimate
Docker	⭐⭐⭐⭐	运行中间件(Nacos、Redis)
Postman/cURL	⭐⭐⭐⭐	API 测试
基础 SQL	⭐⭐⭐	理解数据持久化
HTTP 协议	⭐⭐⭐⭐	REST API 通信

2. 进阶技能要求

🚀 架构模式和设计原则

学习 Spring AI Alibaba,你会接触到以下架构模式:

状态图模式 (⭐⭐⭐⭐⭐)
- 理解有限状态机(FSM)
- 节点和边的概念
- 条件路由和分支
管道-过滤器模式 (⭐⭐⭐⭐)
- 数据在节点间流转
- 每个节点处理并传递数据
观察者模式 (⭐⭐⭐⭐)
- 生命周期监听
- 可观测性集成
SOLID 原则体现:
- S (单一职责): 每个节点只做一件事
- O (开闭原则): 通过继承 NodeAction 扩展新节点
- D (依赖倒置): 依赖接口而非实现

🧠 领域特定知识

要真正用好 Spring AI Alibaba,你需要了解:

AI/ML 基础概念 (⭐⭐⭐⭐)
- 大语言模型(LLM)的基本原理
- Prompt Engineering(提示词工程)
- RAG(检索增强生成)
- Embedding 和向量检索
- Function Calling(函数调用)
分布式系统 (⭐⭐⭐⭐)
- 服务注册与发现(Nacos)
- 分布式追踪(OpenTelemetry)
- 可观测性三大支柱(日志、指标、追踪)
响应式编程 (⭐⭐⭐)
- Reactor 核心概念(Mono、Flux)
- 背压(Backpressure)
- 异步流处理
协议和标准 (⭐⭐⭐)
- MCP (Model Context Protocol)
- OpenAI API 标准
- SSE (Server-Sent Events)

3. 技能掌握程度建议

根据你的目标和背景,我给出三个层次的学习建议:

🌱 初学者(刚接触 AI 应用开发)

学习侧重点:

✅ 先搞定 Spring Boot 基础,能跑起来一个 Hello World
✅ 理解 ChatModel 的基本用法,知道怎么调用大模型
✅ 学会使用 Starter,不需要深入理解自动配置原理
✅ 跑通 Playground 示例,感受完整功能
⏸️ 暂时跳过 Graph 和 MCP,先专注简单对话

应达到的深度:

能基于 Starter 快速搭建一个 ChatBot
理解 ChatClient、Prompt、ChatResponse 等基本概念
能看懂官方文档和示例代码

🌿 有经验的开发者(熟悉 Spring 生态)

学习侧重点:

✅ 深入理解 Graph 工作流,能设计复杂流程
✅ 掌握 RAG 模式,能集成向量数据库
✅ 学会 Function Calling,让 AI 调用你的业务逻辑
✅ 理解 自动配置原理,知道怎么自定义 Starter
✅ 掌握 可观测性集成,能监控 AI 应用

应达到的深度:

能独立设计和实现多步骤的工作流应用
理解 StateGraph、Node、Edge 的实现原理
能根据业务需求定制节点和策略
能集成企业级中间件(Nacos、ARMS)

🌳 意欲贡献代码的进阶者

学习侧重点:

✅ 深入源码,理解 Graph 执行引擎的实现
✅ 掌握 异步编程模型,理解 AsyncGenerator 的设计
✅ 学习 MCP 协议,能扩展新的 MCP Server
✅ 研究 可观测性实现,理解 Micrometer 集成
✅ 熟悉 代码规范和 CI 流程

应达到的深度:

能读懂核心模块的源码
能设计和实现新的预定义节点
能修复 Bug 并提交高质量 PR
能参与架构设计讨论

第三部分:学习路径规划(你的专属教练计划)🎯

本部分目标: 给你一个清晰的、可执行的学习计划,让你知道每个阶段该做什么、怎么做、如何验证学习效果。

1. 项目运行入口定位(快速上手)

好了朋友,理论讲了这么多,现在让我们动手把项目跑起来!💪 我保证,30 分钟内你就能看到第一个 AI 对话效果!

⚡ 快速启动(适合初学者)

前置准备(10 分钟):

# 1. 确认 Java 版本(必须 >= 17)
java -version

# 2. 确认 Maven 安装
mvn -version

# 3. 克隆项目
git clone https://github.com/alibaba/spring-ai-alibaba.git
cd spring-ai-alibaba

最小依赖启动(20 分钟):

不要直接运行整个项目!我们先跑一个最简单的示例:

# 1. 创建一个新的 Spring Boot 项目目录
mkdir my-first-ai-app && cd my-first-ai-app

# 2. 创建 pom.xml
cat > pom.xml << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
         http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.4.8</version>
    </parent>

    <groupId>com.example</groupId>
    <artifactId>my-first-ai-app</artifactId>
    <version>1.0.0</version>

    <properties>
        <java.version>17</java.version>
    </properties>

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>com.alibaba.cloud.ai</groupId>
                <artifactId>spring-ai-alibaba-bom</artifactId>
                <version>1.0.0.2</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>com.alibaba.cloud.ai</groupId>
            <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
        </dependency>
    </dependencies>

    <repositories>
        <repository>
            <id>spring-milestones</id>
            <name>Spring Milestones</name>
            <url>https://repo.spring.io/milestone</url>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
        </repository>
    </repositories>
</project>
EOF

# 3. 创建 application.yml
mkdir -p src/main/resources
cat > src/main/resources/application.yml << 'EOF'
spring:
  ai:
    dashscope:
      api-key: ${DASHSCOPE_API_KEY:your-api-key-here}

server:
  port: 8080
EOF

# 4. 创建主类
mkdir -p src/main/java/com/example/ai
cat > src/main/java/com/example/ai/MyFirstAiApp.java << 'EOF'
package com.example.ai;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@SpringBootApplication
@RestController
public class MyFirstAiApp {

    private final ChatClient chatClient;

    public MyFirstAiApp(ChatClient.Builder chatClientBuilder) {
        this.chatClient = chatClientBuilder.build();
    }

    public static void main(String[] args) {
        SpringApplication.run(MyFirstAiApp.java, args);
    }

    @GetMapping("/chat")
    public String chat(@RequestParam String message) {
        return chatClient.prompt()
                .user(message)
                .call()
                .content();
    }
}
EOF

# 5. 构建项目
mvn clean package

# 6. 运行(记得替换 API Key!)
export DASHSCOPE_API_KEY=sk-your-actual-api-key
mvn spring-boot:run

✅ 验证成功标志

在浏览器访问:

curl "http://localhost:8080/chat?message=你好,介绍一下你自己"

如果看到 AI 的回复,恭喜你!🎉 第一步成功了!

🔧 环境配置清单

配置项	必需性	获取方式
DashScope API Key	✅ 必需	阿里云百炼平台申请
JDK 17+	✅ 必需	Oracle 或 OpenJDK
Maven 3.8+	✅ 必需	Apache Maven
Docker	⭕ 可选	运行 Nacos、Redis 等中间件
IntelliJ IDEA	⭕ 推荐	更好的开发体验

⚠️ 常见配置陷阱及解决方案

Maven 无法下载 Spring AI 依赖

现象: Could not find artifact org.springframework.ai:spring-ai-bom:pom:1.0.1

原因: Spring AI 1.0.x 还在 milestone 仓库

解决:

<repositories>
    <repository>
        <id>spring-milestones</id>
        <url>https://repo.spring.io/milestone</url>
        <snapshots><enabled>false</enabled></snapshots>
    </repository>
</repositories>

API Key 配置不生效

现象: 请求返回 401 Unauthorized

检查清单:
- ✅ application.yml 中的 key 是否正确
- ✅ 环境变量是否生效: echo $DASHSCOPE_API_KEY
- ✅ Key 是否过期或欠费

Java 版本不兼容

现象: class file has wrong version

解决:

# 检查版本
java -version
javac -version
mvn -version

# 如果不一致,设置 JAVA_HOME
export JAVA_HOME=/path/to/jdk-17

2. 循序渐进学习计划(四阶段法)

现在你已经跑通了第一个示例,接下来我们一步步深入!记住,不要着急,每个阶段都要真正理解透彻再往下走。😊

🥉 阶段一:环境搭建和项目启动(1-2 天)

学习目标:

✅ 能够成功运行 Spring AI Alibaba 示例项目
✅ 理解 Spring Boot Starter 的基本用法
✅ 掌握 ChatClient 的基本 API
✅ 能够在代码中打断点调试

具体任务清单:

Day 1 上午:环境准备

# 1. 安装 IntelliJ IDEA(推荐)
# 下载: https://www.jetbrains.com/idea/download/

# 2. 克隆官方示例仓库
git clone https://github.com/springaialibaba/spring-ai-alibaba-examples.git
cd spring-ai-alibaba-examples

# 3. 用 IDEA 打开项目
# File -> Open -> 选择 spring-ai-alibaba-examples 目录

# 4. 配置 API Key
# 编辑 application.yml,添加你的 DashScope API Key

Day 1 下午:运行 Playground

# 进入 playground 目录
cd spring-ai-alibaba-playground

# 配置 application.yml
vim src/main/resources/application.yml
# 修改: spring.ai.dashscope.api-key=sk-你的key

# 启动项目
mvn spring-boot:run

# 浏览器访问
open http://localhost:8080

Day 2:调试和理解
- 在 ChatController 中打断点
- 观察 ChatClient 如何构建请求
- 跟踪 DashScopeChatModel 的调用
- 查看 ChatResponse 的结构

成功标准:

✅ Playground 界面能正常显示
✅ 能够进行多轮对话
✅ 理解请求从 Controller 到 Model 的完整流程
✅ 能够在关键位置打断点并观察数据

推荐练习:

// 练习1:修改系统提示词
@GetMapping("/chat-with-system-prompt")
public String chatWithSystemPrompt(@RequestParam String message) {
   
    return chatClient.prompt()
            .system("你是一个友好的AI助手,喜欢用emoji表情")
            .user(message)
            .call()
            .content();
}

// 练习2:使用流式响应
@GetMapping("/chat-stream")
public Flux<String> chatStream(@RequestParam String message) {
   
    return chatClient.prompt()
            .user(message)
            .stream()
            .content();
}

// 练习3:使用 Function Calling
@GetMapping("/chat-with-function")
public String chatWithFunction(@RequestParam String message) {
   
    return chatClient.prompt()
            .user(message)
            .functions("getCurrentWeather")  // 注册函数
            .call()
            .content();
}

🥈 阶段二:核心流程理解(3-5 天)

学习目标:

✅ 深入理解 Graph 工作流的运行机制
✅ 能够追踪一个完整的业务流程
✅ 理解 StateGraph、Node、Edge 的关系
✅ 能够画出自己的流程图

具体任务清单:

Day 1:理解 Graph 核心概念

# 1. 阅读 Graph 文档
cd spring-ai-alibaba/spring-ai-alibaba-graph-core
cat README-zh.md

# 2. 查看 StateGraph 源码
# 文件: src/main/java/com/alibaba/cloud/ai/graph/StateGraph.java
# 重点理解:
# - addNode() 方法
# - addEdge() 方法
# - addConditionalEdges() 方法
# - compile() 方法

Day 2-3:运行并调试客服工作流示例

// 找到官方示例中的 WorkflowAutoconfiguration
// 文件位置: examples/workflow-example/src/main/java/.../WorkflowAutoconfiguration.java

// 在以下位置打断点:
// 1. StateGraph.addNode() - 观察节点如何注册
// 2. QuestionClassifierNode.apply() - 观察节点如何执行
// 3. FeedbackQuestionDispatcher.apply() - 观察边如何决策
// 4. CompiledGraph.stream() - 观察流式执行

Day 4:画出流程图

# 使用 PlantUML 或 Mermaid 画出以下流程:
# 1. 客服工作流的完整流程
# 2. 标注每个节点的输入输出
# 3. 标注条件边的判断逻辑
# 4. 标注状态在各节点间的传递

Day 5:实现自己的简单工作流

// 任务:实现一个"博客内容生成"工作流
// 流程: 用户输入主题 -> 生成大纲 -> 扩展每个章节 -> 润色文章

@Configuration
public class BlogGenerationWorkflow {
     

    @Bean
    public StateGraph blogGraph(ChatClient chatClient) {
     
        // 定义状态
        OverAllStateFactory stateFactory = () -> {
     
            OverAllState state = new OverAllState();
            state.registerKeyAndStrategy("topic", new ReplaceStrategy());
            state.registerKeyAndStrategy("outline", new ReplaceStrategy());
            state.registerKeyAndStrategy("content", new AppenderChannel<>());
            return state;
        };

        // 定义节点
        LlmNode outlineNode = LlmNode.builder()
                .chatClient(chatClient)
                .inputKey("topic")
                .outputKey("outline")
                .promptTemplate("为主题 {topic} 生成详细大纲")
                .build();

        LlmNode contentNode = LlmNode.builder()
                .chatClient(chatClient)
                .inputKey("outline")
                .outputKey("content")
                .promptTemplate("根据大纲 {outline} 扩展每个章节")
                .build();

        // 构建图
        return new StateGraph("Blog Generation", stateFactory)
                .addNode("outline_generator", node_async(outlineNode))
                .addNode("content_generator", node_async(contentNode))
                .addEdge(START, "outline_generator")
                .addEdge("outline_generator", "content_generator")
                .addEdge("content_generator", END);
    }
}

成功标准:

✅ 能够用自己的话解释 StateGraph 的工作原理
✅ 能够画出完整的客服工作流流程图
✅ 理解 OverAllState 如何在节点间传递
✅ 能够独立实现一个 3-5 个节点的简单工作流

推荐练习:

练习	难度	描述
练习1	⭐⭐	修改客服工作流,增加一个"优先级评估"节点
练习2	⭐⭐⭐	实现一个"简历筛选"工作流(解析简历 -> 评估技能 -> 打分排序)
练习3	⭐⭐⭐⭐	实现一个并行节点场景(同时调用多个模型,然后汇总结果)

🥇 阶段三:模块深入和定制开发(1-2 周)

学习目标:

✅ 能够自定义节点和边
✅ 理解 RAG 模式并能集成向量数据库
✅ 掌握 Function Calling 的使用
✅ 能够集成 MCP 工具

具体任务清单:

Week 1:深入 Graph 和 RAG

// 任务1:自定义一个数据库查询节点
public class DatabaseQueryNode implements NodeAction<OverAllState> {
   

    private final JdbcTemplate jdbcTemplate;

    @Override
    public OverAllState apply(OverAllState state) {
   
        String query = (String) state.get("query");
        List<Map<String, Object>> results = jdbcTemplate.queryForList(query);
        state.update("results", results);
        return state;
    }
}

// 任务2:实现一个 RAG 应用
@RestController
public class RagController {
   

    private final ChatClient chatClient;
    private final DashScopeDocumentRetriever retriever;

    @GetMapping("/ask")
    public String ask(@RequestParam String question) {
   
        // 1. 从知识库检索相关文档
        List<Document> docs = retriever.retrieve(question);

        // 2. 构建 prompt
        String context = docs.stream()
                .map(Document::getContent)
                .collect(Collectors.joining("\n"));

        // 3. 调用大模型
        return chatClient.prompt()
                .system("根据以下上下文回答问题:\n" + context)
                .user(question)
                .call()
                .content();
    }
}

// 任务3:使用 Function Calling
@Bean
public Function<WeatherRequest, WeatherResponse> getCurrentWeather() {
   
    return request -> {
   
        // 调用天气 API
        return weatherService.getWeather(request.location());
    };
}

@GetMapping("/weather-chat")
public String weatherChat(@RequestParam String message) {
   
    return chatClient.prompt()
            .user(message)
            .functions("getCurrentWeather")
            .call()
            .content();
}

Week 2:集成企业级能力

// 任务4:集成 MCP 工具
@Configuration
public class McpConfiguration {
   

    @Bean
    public StateGraph mcpWorkflow(McpRouterService mcpRouter) {
   
        return new StateGraph("MCP Workflow", stateFactory())
                .addNode("search_tool", node_async(state -> {
   
                    // 搜索合适的 MCP 工具
                    String task = (String) state.get("task");
                    List<McpServer> servers = mcpRouter.searchMcpServer(task);
                    state.update("servers", servers);
                    return state;
                }))
                .addNode("use_tool", node_async(state -> {
   
                    // 调用 MCP 工具
                    McpServer server = (McpServer) state.get("servers").get(0);
                    String result = mcpRouter.useTool(server.getName(), "toolName", params);
                    state.update("result", result);
                    return state;
                }))
                .addEdge(START, "search_tool")
                .addEdge("search_tool", "use_tool")
                .addEdge("use_tool", END);
    }
}

// 任务5:集成可观测性
@Bean
public StateGraph observableWorkflow(ObservationRegistry observationRegistry) {
   
    CompiledGraph graph = stateGraph.compile(
        CompileConfig.builder()
            .withLifecycleListener(
                new GraphObservationLifecycleListener(observationRegistry)
            )
            .build()
    );
    return graph;
}

成功标准:

✅ 能够独立实现自定义节点
✅ 能够搭建一个完整的 RAG 应用
✅ 理解 Function Calling 的原理和应用
✅ 能够集成至少一个 MCP 工具

推荐练习:

练习	难度	描述
练习1	⭐⭐⭐	实现一个 HTTP 调用节点,支持 GET/POST 请求
练习2	⭐⭐⭐⭐	搭建一个企业知识库问答系统(文档上传 + 向量化 + RAG 检索)
练习3	⭐⭐⭐⭐	实现一个多智能体协作场景(研究员 + 作家 + 评审员)
练习4	⭐⭐⭐⭐⭐	集成 Langfuse 实现完整的 AI 应用可观测

🏆 阶段四:架构理解和贡献指南(2 周+)

学习目标:

✅ 理解核心模块的实现原理
✅ 能够阅读并理解源码
✅ 掌握贡献代码的流程
✅ 能够修复简单的 Bug 或添加新特性

具体任务清单:

Week 1:深入源码

# 1. 阅读核心类的源码
# 推荐阅读顺序:
src/main/java/com/alibaba/cloud/ai/graph/
├── StateGraph.java                    # 图的定义和构建
├── CompiledGraph.java                 # 已编译图的执行
├── executor/MainGraphExecutor.java    # 执行引擎
├── action/NodeAction.java             # 节点行为接口
└── state/strategy/                    # 状态更新策略

# 2. 理解关键设计决策
# - 为什么使用 CompletableFuture 而不是 Reactor?
# - StateGraph 的泛型设计有什么优点?
# - 异步节点是如何实现的?

# 3. 研究一个完整特性的实现
# 选择: Human-in-the-loop (人类干预)
# 追踪: 如何暂停、如何恢复、如何修改状态

Week 2:参与贡献

# 1. Fork 仓库
# 访问: https://github.com/alibaba/spring-ai-alibaba
# 点击右上角的 Fork 按钮

# 2. 克隆自己的 Fork
git clone https://github.com/你的用户名/spring-ai-alibaba.git
cd spring-ai-alibaba
git remote add upstream https://github.com/alibaba/spring-ai-alibaba.git

# 3. 寻找合适的 Issue
# 访问: https://github.com/alibaba/spring-ai-alibaba/labels/good%20first%20issue

# 4. 创建功能分支
git checkout -b feature/my-contribution

# 5. 开发和测试
# - 编写代码
# - 添加单元测试
# - 运行 mvn clean test
# - 运行 mvn checkstyle:check

# 6. 提交代码
git add .
git commit -m "feat(graph): 添加新的节点类型"
git push origin feature/my-contribution

# 7. 创建 Pull Request
# 访问你的 Fork 页面,点击 "New Pull Request"

成功标准:

✅ 能够解释 StateGraph 的执行流程
✅ 理解至少一个核心特性的实现原理
✅ 提交了至少一个被合并的 PR
✅ 能够参与社区讨论

推荐贡献方向:

方向	难度	描述
文档改进	⭐⭐	补充英文文档、修复错别字、添加示例
预定义节点	⭐⭐⭐	实现新的预定义节点(如 ElasticsearchNode)
错误提示	⭐⭐⭐	改进异常信息,让错误更容易定位
性能优化	⭐⭐⭐⭐	向量检索缓存、批量处理优化
新特性	⭐⭐⭐⭐⭐	实现新的核心特性(需要先提 Issue 讨论)

3. 学习路径流程图

graph TD
    Start[🎯 开始学习] --> Check{是否熟悉<br/>Spring Boot?}

    Check -->|否| LearnSpring[📚 学习 Spring Boot 基础<br/>1-2周]
    Check -->|是| Phase1

    LearnSpring --> Phase1[🥉 阶段一:环境搭建<br/>1-2天]

    Phase1 --> Verify1{能否成功<br/>运行示例?}
    Verify1 -->|否| Troubleshoot1[🔧 排查问题:<br/>API Key/依赖/版本]
    Troubleshoot1 --> Phase1
    Verify1 -->|是| Phase2

    Phase2[🥈 阶段二:核心流程理解<br/>3-5天] --> Practice2[💪 实践:<br/>自己实现工作流]
    Practice2 --> Verify2{能否画出<br/>完整流程图?}
    Verify2 -->|否| Review2[📖 重新学习<br/>Graph 概念]
    Review2 --> Phase2
    Verify2 -->|是| Choice{学习目标?}

    Choice -->|快速应用| Phase3Easy[🎨 快速应用:<br/>RAG + Function Calling]
    Choice -->|深入研究| Phase3Deep[🔬 深入研究:<br/>源码 + 自定义节点]

    Phase3Easy --> Phase4[🏆 阶段四:贡献代码<br/>可选]
    Phase3Deep --> Phase4

    Phase4 --> Contribute{是否想<br/>参与开源?}
    Contribute -->|是| PR[📝 提交 PR<br/>成为 Contributor]
    Contribute -->|否| BuildApp[🚀 构建企业应用]

    PR --> Community[🌟 持续参与社区]
    BuildApp --> Community

    Community --> Master[🎓 精通 Spring AI Alibaba!]

    style Start fill:#e1f5e1
    style Master fill:#ffe1e1
    style Phase1 fill:#e1e5ff
    style Phase2 fill:#e1e5ff
    style Phase3Easy fill:#fff4e1
    style Phase3Deep fill:#fff4e1
    style Phase4 fill:#ffe1f5

流程说明:

🟢 绿色: 起点和终点
🔵 蓝色: 基础学习阶段
🟡 黄色: 进阶学习阶段
🟣 紫色: 贡献阶段

第四部分:实践建议和进阶指导(从会用到精通)💡

本部分目标: 分享实战经验,帮你避开常见的坑,并提供从初级到高级的练习路径。

1. 调试技巧和常见陷阱

🐛 调试技巧

技巧 1:启用 Debug 日志

# application.yml
logging:
  level:
    com.alibaba.cloud.ai: DEBUG
    org.springframework.ai: DEBUG
    com.alibaba.cloud.ai.graph: TRACE  # 查看图执行细节

技巧 2:使用 GraphLifecycleListener 监听执行

@Component
public class DebugLifecycleListener implements GraphLifecycleListener {
   

    private static final Logger log = LoggerFactory.getLogger(DebugLifecycleListener.class);

    @Override
    public void onNodeStart(String nodeName, OverAllState state) {
   
        log.info("节点 {} 开始执行,当前状态: {}", nodeName, state);
    }

    @Override
    public void onNodeEnd(String nodeName, OverAllState state) {
   
        log.info("节点 {} 执行完成,当前状态: {}", nodeName, state);
    }

    @Override
    public void onError(String nodeName, Throwable error) {
   
        log.error("节点 {} 执行失败", nodeName, error);
    }
}

技巧 3:可视化工作流

// 导出 Mermaid 图
String mermaid = stateGraph.generateMermaid();
System.out.println(mermaid);

// 或者导出 PlantUML
String plantuml = stateGraph.generatePlantUML();
System.out.println(plantuml);

⚠️ 常见陷阱

陷阱 1:状态更新策略理解错误

// ❌ 错误:使用了 ReplaceStrategy,但期望追加
state.registerKeyAndStrategy("messages", new ReplaceStrategy());
// 这会导致每次只保留最后一条消息!

// ✅ 正确:使用 AppenderChannel
state.registerKeyAndStrategy("messages", new AppenderChannel<>());

陷阱 2:忘记处理异步节点的异常

// ❌ 错误:异常被吞掉了
NodeAction asyncNode = node_async(state -> {
   
    // 这里抛出的异常可能不会被正确处理
    throw new RuntimeException("出错了");
});

// ✅ 正确:使用 try-catch 并记录到状态
NodeAction asyncNode = node_async(state -> {
   
    try {
   
        // 业务逻辑
    } catch (Exception e) {
   
        state.update("error", e.getMessage());
        log.error("节点执行失败", e);
    }
    return state;
});

陷阱 3:API Key 配置错误

# ❌ 错误:key 配置到了错误的位置
spring:
  ai:
    openai:
      api-key: sk-xxx  # 这是 DashScope 的 key,但配置到了 openai!

# ✅ 正确
spring:
  ai:
    dashscope:
      api-key: sk-xxx

陷阱 4:Maven 依赖冲突

<!-- ❌ 错误:同时引入了多个版本的 Spring AI -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-openai</artifactId>
    <version>1.0.0</version>
</dependency>
<dependency>
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
    <!-- 这个 starter 已经包含了 Spring AI,会冲突! -->
</dependency>

<!-- ✅ 正确:使用 BOM 管理版本 -->
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.alibaba.cloud.ai</groupId>
            <artifactId>spring-ai-alibaba-bom</artifactId>
            <version>1.0.0.2</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

陷阱 5:忘记配置 Spring Milestones 仓库

现象: Could not find artifact org.springframework.ai:spring-ai-core...

原因: Spring AI 1.0.x 还在 milestone 阶段,需要配置 Spring Milestones 仓库

解决: 参考前面的 pom.xml 配置

2. 扩展练习建议

好了朋友,理论和基础都有了,现在给你一些从易到难的练习题,边做边学效果最好!💪

⭐⭐ 初级练习(1-2天完成)

练习 1:个性化聊天机器人

任务: 实现一个带有记忆功能的聊天机器人
要求:
- 记住用户的名字和偏好
- 能够引用之前的对话内容
- 支持流式响应

提示:
- 使用 MessageChatMemoryAdvisor
- 配置 InMemoryChatMemory

练习 2:多模态应用

任务: 实现图文混合对话
要求:
- 用户可以上传图片并提问
- AI 能够理解图片内容并回答
- 支持多张图片同时上传

提示:
- 使用 DashScope 的 vision 模型
- 构建 UserMessage 时传入 Image

练习 3:简单的 Function Calling

任务: 实现天气查询助手
要求:
- 用户问"今天天气怎么样"
- AI 自动调用天气 API
- 返回格式化的天气信息

提示:
- 定义 @Bean public Function<WeatherRequest, WeatherResponse>
- 使用 chatClient.functions("weatherFunction")

⭐⭐⭐ 中级练习(3-5天完成)

练习 4:文档问答系统

任务: 实现基于 RAG 的文档问答
要求:
- 支持 PDF、Word、TXT 文档上传
- 自动分块、向量化、存储
- 根据用户问题检索相关文档并回答
- 显示引用来源

提示:
- 使用 DashScopeDocumentTransformer 分块
- 使用 DashScopeEmbeddingModel 向量化
- 使用 SimpleVectorStore 或阿里云向量检索
- 使用 DocumentRetrievalAdvisor

练习 5:工作流博客生成器

任务: 实现多步骤博客内容生成
流程:
1. 用户输入主题和关键词
2. 生成文章大纲
3. 为每个章节生成详细内容
4. 润色和优化文章
5. 生成 SEO 元数据

要求:
- 使用 StateGraph 编排流程
- 每个步骤可以人工干预
- 支持流式显示生成进度

提示:
- 定义多个 LlmNode
- 使用 HumanNode 实现人工干预
- 使用 CompileConfig 配置 checkpoint

练习 6:智能客服路由系统

任务: 实现多场景客服路由
流程:
1. 识别用户意图(咨询/投诉/建议)
2. 根据意图路由到不同处理流程
3. 调用相应的工具或知识库
4. 生成回复并记录日志

要求:
- 使用 QuestionClassifierNode 分类
- 使用 addConditionalEdges 路由
- 集成至少2个不同的处理节点

提示:
- 参考官方的客服示例
- 自定义 EdgeAction 实现复杂路由逻辑

⭐⭐⭐⭐ 高级练习(1-2周完成)

练习 7:多智能体协作系统

任务: 实现研究团队协作
角色:
- Researcher(研究员): 负责搜索和整理资料
- Writer(作家): 负责撰写内容
- Reviewer(评审员): 负责审核和提出修改意见

流程:
1. Researcher 搜索资料
2. Writer 根据资料撰写初稿
3. Reviewer 提出修改意见
4. Writer 根据意见修订
5. 循环 2-4 直到 Reviewer 满意

要求:
- 使用多个 AgentNode
- 实现循环流程
- 支持异步执行

提示:
- 研究 ReactAgent 的实现
- 使用 addConditionalEdges 实现循环
- 定义明确的停止条件

练习 8:企业级 RAG 系统

任务: 实现生产级知识库问答
要求:
- 支持多种文档格式(PDF/Word/Excel/PPT)
- 支持增量更新(新文档自动索引)
- 支持混合检索(关键词+向量)
- 集成 Rerank 提升召回精度
- 集成可观测性(Langfuse/ARMS)
- 支持多租户隔离

提示:
- 使用 DashScopeDocumentCloudReader
- 使用 DashScopeRerankModel
- 使用 DashScopeCloudStore 作为知识库
- 配置 ObservationRegistry

练习 9:MCP 工具生态系统

任务: 构建 MCP 工具管理平台
要求:
- 实现 MCP Server 注册到 Nacos
- 实现基于语义的工具搜索
- 实现工具调用的智能路由
- 实现工具调用的监控和统计
- 实现工具调用的权限控制

提示:
- 使用 spring-ai-alibaba-mcp-registry
- 使用 spring-ai-alibaba-mcp-router
- 集成 Nacos 服务发现
- 实现自定义的 McpServiceDiscovery

⭐⭐⭐⭐⭐ 大师级挑战(3-4周完成)

练习 10:DeepResearch 克隆

任务: 实现类似 DeepResearch 的深度研究系统
流程:
1. 用户输入研究主题
2. 自动拆解为子问题
3. 并行搜索资料
4. 整合和分析信息
5. 生成结构化报告
6. 引用来源和数据验证

要求:
- 使用 Graph 编排复杂流程
- 集成网络搜索工具
- 集成爬虫和内容提取
- 支持长文本生成
- 支持导出多种格式(Markdown/PDF)
- 完整的可观测性

提示:
- 研究官方 DeepResearch 的实现
- 使用子图(SubGraph)拆分复杂流程
- 使用并行节点加速搜索
- 集成多个工具(搜索/爬虫/PDF生成)

3. 参与贡献的途径

想成为 Spring AI Alibaba 的 Contributor 吗?🌟 让我告诉你具体怎么做!

🎯 Step 1:找到合适的 Issue

访问 GitHub Issues 页面:

🟢 good first issue - 适合新手的简单任务
🟡 help wanted - 需要社区帮助的任务
🔴 bug - Bug 修复

如何选择 Issue:

先看 good first issue,选择你感兴趣的
在 Issue 下留言表示你想认领:I'd like to work on this issue
等待 Maintainer 回复分配给你

📝 Step 2:Fork 并配置仓库

# 1. Fork 仓库(点击 GitHub 页面右上角的 Fork 按钮)

# 2. 克隆你的 Fork
git clone https://github.com/你的用户名/spring-ai-alibaba.git
cd spring-ai-alibaba

# 3. 添加上游仓库
git remote add upstream https://github.com/alibaba/spring-ai-alibaba.git

# 4. 配置 Git 用户信息(如果还没配置)
git config user.name "Your Name"
git config user.email "your.email@example.com"

# 5. 拉取最新代码
git fetch upstream
git checkout main
git rebase upstream/main

🔧 Step 3:开发和测试

# 1. 创建功能分支(遵循命名规范)
git checkout -b feat/add-elasticsearch-node
# 或
git checkout -b fix/graph-execution-error

# 2. 开发你的功能
# ...

# 3. 运行测试
mvn clean test

# 4. 运行 Checkstyle
mvn checkstyle:check

# 5. 自动删除未使用的导入
mvn spotless:apply

# 6. 本地 CI 检查(推荐)
cd tools/make
make check  # 运行所有检查

✅ Step 4:代码规范

Spring AI Alibaba 遵循 Spring Code Style:

// ✅ 好的代码风格
public class MyNode implements NodeAction<OverAllState> {
   

    private final ChatClient chatClient;
    private final String inputKey;

    public MyNode(ChatClient chatClient, String inputKey) {
   
        this.chatClient = chatClient;
        this.inputKey = inputKey;
    }

    @Override
    public OverAllState apply(OverAllState state) {
   
        String input = (String) state.get(this.inputKey);
        String result = this.chatClient.prompt()
                .user(input)
                .call()
                .content();
        state.update("result", result);
        return state;
    }

}

// ❌ 不好的代码风格
public class MyNode implements NodeAction<OverAllState>{
     // 缺少空格
    private ChatClient chatClient;  // 缺少 final
    private String inputKey;

    public MyNode(ChatClient chatClient,String inputKey){
     // 参数间缺少空格
        this.chatClient=chatClient;  // 赋值符号缺少空格
        this.inputKey=inputKey;
    }

    @Override
    public OverAllState apply(OverAllState state){
   
        String input=(String)state.get(inputKey);  // 类型转换缺少空格
        String result=chatClient.prompt().user(input).call().content();  // 链式调用应该换行
        state.update("result",result);
        return state;
    }
}

关键规范:

✅ 使用 Tab 缩进(4个空格)
✅ 类名使用 大驼峰 MyCustomNode
✅ 方法名使用 小驼峰 applyTransformation
✅ 常量使用 全大写+下划线 MAX_RETRY_COUNT
✅ 所有公共 API 必须有 Javadoc
✅ 链式调用适当换行提高可读性

📤 Step 5:提交 PR

# 1. 提交代码(遵循 Commit 规范)
git add .
git commit -m "feat(graph): add ElasticsearchNode for full-text search"

# Commit 规范:
# feat(模块): 新功能
# fix(模块): Bug 修复
# docs(模块): 文档更新
# refactor(模块): 代码重构
# test(模块): 测试相关
# chore(模块): 构建/工具相关

# 2. 推送到你的 Fork
git push origin feat/add-elasticsearch-node

# 3. 在 GitHub 上创建 Pull Request
# 访问: https://github.com/alibaba/spring-ai-alibaba/compare
# 选择: base: main ← compare: 你的分支

# 4. 填写 PR 描述(遵循模板)

PR 描述模板:

## 功能描述
<!-- 简要描述你的修改 -->
添加了 ElasticsearchNode,支持全文检索功能。

## 修改内容
<!-- 列出主要修改点 -->
- 实现了 ElasticsearchNode 类
- 添加了配置类 ElasticsearchProperties
- 补充了单元测试
- 更新了文档

## 相关 Issue
<!-- 关联相关 Issue -->
Closes #123

## 测试
<!-- 说明如何测试 -->
- [x] 单元测试通过
- [x] 集成测试通过
- [x] 手动测试通过

## Checklist
- [x] 代码遵循项目规范
- [x] 添加了必要的测试
- [x] 更新了相关文档
- [x] 通过了 CI 检查

🔄 Step 6:响应 Code Review

Maintainer 可能会提出修改意见:

# 1. 根据意见修改代码

# 2. 提交修改
git add .
git commit -m "refactor(graph): optimize ElasticsearchNode performance"

# 3. 推送更新(会自动更新 PR)
git push origin feat/add-elasticsearch-node

# 4. 在 PR 评论中回复
"感谢审查!已根据建议优化了性能。"

🎉 Step 7:合并成功!

恭喜你!PR 被合并后:

✅ 你的名字会出现在贡献者列表中
✅ 你会收到 GitHub 通知
✅ 你可以在简历中加上"开源贡献者"的标签了!😊

保持同步:

# 定期同步上游代码
git fetch upstream
git checkout main
git rebase upstream/main
git push origin main

第五部分:技术栈学习指引(你的知识地图)🌐

本部分目标: 为你识别出的关键技能提供精准的学习路径,构建完整的学习支持体系。不只是列个清单,而是告诉你在哪学、怎么学、学到什么程度。

1. 官方文档定位(学习的基石)

📘 核心技术栈文档

技术	官方文档	重点章节	难度
Spring AI Alibaba	java2ai.com	快速开始、Graph 工作流、MCP 集成	⭐⭐⭐
Spring AI	docs.spring.io/spring-ai	Chat Clients、Advisors、Vector Stores	⭐⭐⭐⭐
Spring Boot 3	docs.spring.io/spring-boot	自动配置、Actuator、测试	⭐⭐⭐
阿里云百炼	help.aliyun.com/bailian	模型调用、RAG、知识库	⭐⭐⭐
DashScope	dashscope.aliyun.com	API 文档、模型能力	⭐⭐
Nacos 3.x	nacos.io/docs	服务发现、配置管理	⭐⭐⭐
OpenTelemetry	opentelemetry.io/docs	Java SDK、分布式追踪	⭐⭐⭐⭐

学习优先级建议:

🥇 先学: Spring AI Alibaba 官方文档(必读!所有特性都在这里)
🥈 再学: Spring AI 基础概念(理解底层抽象)
🥉 按需学: 其他技术(用到什么学什么)

📗 项目自身文档

必读文档:

文档	位置	优先级	说明
README-zh.md	项目根目录	⭐⭐⭐⭐⭐	项目概览和快速开始
Graph 工作流	spring-ai-alibaba-graph-core/README-zh.md	⭐⭐⭐⭐⭐	核心特性详解
MCP Router	spring-ai-alibaba-mcp/spring-ai-alibaba-mcp-router/README.md	⭐⭐⭐⭐	MCP 路由机制
贡献指南	CONTRIBUTING-zh.md	⭐⭐⭐⭐	参与开源必读
Studio 文档	spring-ai-alibaba-studio/spring-ai-alibaba-studio-server/docs/	⭐⭐⭐	开发平台使用

官方示例仓库:

# 克隆示例仓库(强烈推荐!)
git clone https://github.com/springaialibaba/spring-ai-alibaba-examples.git

# 包含的示例:
├── spring-ai-alibaba-playground/        # 完整的 Playground 示例
├── chatbot-example/                     # 聊天机器人
├── workflow-example/                    # 工作流示例
├── rag-example/                         # RAG 应用
├── function-calling-example/            # 函数调用
└── mcp-example/                         # MCP 集成

📕 权威技术书籍

书籍	作者	适合阶段	说明
Spring Boot 实战	Craig Walls	初级	Spring Boot 基础入门
Spring 源码深度解析	郝佳	中级	理解自动配置原理
深入理解 Java 虚拟机	周志明	中级	Java 17 新特性和性能优化
大语言模型应用开发实战	吴恩达等	初级	AI 应用基础概念
Designing Data-Intensive Applications	Martin Kleppmann	高级	分布式系统设计(英文)

2. 学习路径建议(社区智慧)

🎯 技能学习顺序

根据依赖关系,我建议的学习顺序:

graph LR
    A[Java 17 基础] --> B[Spring Boot 3]
    B --> C[Spring AI 基础]
    C --> D{选择方向}
    D -->|应用开发| E[ChatClient + Advisor]
    D -->|工作流| F[Graph 框架]
    D -->|企业集成| G[MCP + Nacos]
    E --> H[实战项目]
    F --> H
    G --> H
    H --> I[深入源码]
    I --> J[贡献代码]

详细说明:

阶段 1:Java 和 Spring 基础(2-3周)

如果你对 Spring Boot 还不熟悉,先补补课:

// 必须掌握的 Java 17 特性
// 1. Records
public record User(String name, int age) {
   }

// 2. Text Blocks
String json = """
    {
   
        "name": "John",
        "age": 30
    }
    """;

// 3. Pattern Matching for instanceof
if (obj instanceof String s) {
   
    System.out.println(s.length());
}

// 4. Sealed Classes
public sealed interface Shape permits Circle, Rectangle {
   }

推荐资源:

阶段 2:Spring AI 核心概念(1周)

重点理解这些核心抽象:

概念	说明	重要程度
ChatModel	大模型调用的统一接口	⭐⭐⭐⭐⭐
ChatClient	构建器模式的对话客户端	⭐⭐⭐⭐⭐
Prompt	提示词封装	⭐⭐⭐⭐
Advisor	增强 ChatClient 的拦截器	⭐⭐⭐⭐
VectorStore	向量存储抽象	⭐⭐⭐⭐
EmbeddingModel	向量化模型	⭐⭐⭐⭐
Document	文档对象	⭐⭐⭐
FunctionCallback	函数调用	⭐⭐⭐⭐

推荐学习路径:

# 1. 阅读 Spring AI 官方文档
https://docs.spring.io/spring-ai/reference/

# 重点章节:
- Getting Started
- Chat Clients
- Advisors (重点!)
- Function Calling
- Vector Stores and Embeddings

# 2. 动手实践
# 跑通官方的 Quick Start
# 实现一个简单的 ChatBot
# 尝试使用不同的 Advisor

阶段 3:Spring AI Alibaba 特有特性(2-3周)

这是核心!按这个顺序学:

Week 1:DashScope 集成
- ChatModel 使用
- 多模态(图像、语音)
- Function Calling
Week 2:Graph 工作流
- StateGraph 核心概念
- 预定义节点使用
- 自定义节点开发
Week 3:企业级特性
- RAG 和知识库
- MCP 集成
- 可观测性

🎨 核心概念优先级

概念	初学者	中级	高级
ChatClient 基础用法	✅ 必学	✅ 必学	✅ 必学
Advisor 模式	⭕ 了解	✅ 必学	✅ 必学
StateGraph 基础	⭕ 了解	✅ 必学	✅ 必学
自定义 Node	❌ 跳过	✅ 必学	✅ 必学
RAG 模式	⭕ 了解	✅ 必学	✅ 必学
Function Calling	⭕ 了解	✅ 必学	✅ 必学
MCP 协议	❌ 跳过	⭕ 了解	✅ 必学
A2A 通信	❌ 跳过	❌ 跳过	⭕ 了解
源码实现	❌ 跳过	⭕ 了解	✅ 必学

💡 实践项目推荐

学习最好的方式就是动手做!这里推荐一些参考项目:

项目类型	推荐项目	技术栈	难度
ChatBot	LangChain ChatBot	RAG + 多轮对话	⭐⭐
工作流	LangGraph Examples	工作流编排	⭐⭐⭐
多智能体	AutoGPT	Agent 协作	⭐⭐⭐⭐
深度研究	DeepResearch	信息整合	⭐⭐⭐⭐⭐

如何参考这些项目:

✅ 学习它们的架构设计和流程编排
✅ 理解它们如何拆解复杂任务
✅ 借鉴它们的Prompt 设计
❌ 不要直接抄代码(Python → Java 需要重新设计)

3. 工具与环境配置指南

🛠️ 开发环境搭建

推荐开发工具链:

# 1. JDK 17 (必须)
# 下载: https://adoptium.net/
# 验证:
java -version
# 输出: openjdk version "17.0.x"

# 2. Maven 3.8+ (必须)
# 下载: https://maven.apache.org/download.cgi
# 验证:
mvn -version

# 3. IntelliJ IDEA Ultimate (强烈推荐)
# 下载: https://www.jetbrains.com/idea/download/
# 激活: 学生免费 或 购买正版

# 4. Docker Desktop (推荐)
# 下载: https://www.docker.com/products/docker-desktop/
# 用途: 运行 Nacos、Redis 等中间件

# 5. Git (必须)
# 下载: https://git-scm.com/downloads

IDEA 插件推荐:

插件	作用	必需性
Spring Assistant	Spring 开发增强	✅ 必装
Rainbow Brackets	括号高亮	⭕ 推荐
GitToolBox	Git 增强	⭕ 推荐
Maven Helper	Maven 依赖分析	✅ 必装
SequenceDiagram	生成时序图	⭕ 推荐
Key Promoter X	快捷键提示	⭕ 推荐

Maven 配置优化:

<!-- ~/.m2/settings.xml -->
<settings>
    <mirrors>
        <mirror>
            <id>aliyun-maven</id>
            <mirrorOf>central</mirrorOf>
            <name>Aliyun Maven</name>
            <url>https://maven.aliyun.com/repository/central</url>
        </mirror>
    </mirrors>

    <profiles>
        <profile>
            <id>spring-milestones</id>
            <repositories>
                <repository>
                    <id>spring-milestones</id>
                    <url>https://repo.spring.io/milestone</url>
                    <snapshots><enabled>false</enabled></snapshots>
                </repository>
            </repositories>
        </profile>
    </profiles>

    <activeProfiles>
        <activeProfile>spring-milestones</activeProfile>
    </activeProfiles>
</settings>

🐳 Docker 环境搭建

快速启动开发环境:

# 创建 docker-compose.yml
version: '3.8'

services:
  # Nacos 服务注册中心
  nacos:
    image: nacos/nacos-server:v3.1.0
    container_name: nacos
    environment:
      - MODE=standalone
    ports:
      - "8848:8848"
      - "9848:9848"

  # Redis 缓存
  redis:
    image: redis:7-alpine
    container_name: redis
    ports:
      - "6379:6379"
    command: redis-server --appendonly yes

  # MySQL 数据库(可选)
  mysql:
    image: mysql:8.0
    container_name: mysql
    environment:
      - MYSQL_ROOT_PASSWORD=root123
      - MYSQL_DATABASE=ai_alibaba
    ports:
      - "3306:3306"

# 启动所有服务
docker-compose up -d

# 验证服务
curl http://localhost:8848/nacos  # Nacos 管理界面
redis-cli ping                     # 应该返回 PONG

4. 进阶拓展方向

学完基础后,你可以根据兴趣选择不同的进阶方向!🚀

🎓 方向 1:AI 应用架构师

学习重点:

✅ 复杂工作流设计
✅ 多智能体协作模式
✅ 企业级 RAG 系统
✅ 性能优化和成本控制

推荐资源:

资源类型	名称	说明
课程	Andrew Ng - AI Agents	deeplearning.ai
博客	LangChain Blog	blog.langchain.dev
论文	ReAct: Synergizing Reasoning and Acting	arxiv.org/abs/2210.03629
社区	AI 工程师社区	reddit.com/r/LangChain

🔬 方向 2:框架核心开发者

学习重点:

✅ Spring AI 源码深度解析
✅ 响应式编程(Reactor)
✅ 分布式系统设计
✅ 性能优化和监控

推荐资源:

资源类型	名称	说明
源码阅读	Spring AI GitHub	github.com/spring-projects/spring-ai
技术博客	Spring 官方博客	spring.io/blog
书籍	Reactive Spring	Josh Long
会议	SpringOne	每年的 Spring 技术大会

总结与寄语 🎓

恭喜你读到这里!🎉 如果你跟着这份指南一步步学习,相信你已经:

✅ 理解了 Spring AI Alibaba 的整体架构和设计哲学
✅ 掌握了 从简单 ChatBot 到复杂工作流的开发技能
✅ 学会了 如何参与开源贡献,成为社区的一员
✅ 规划了 自己的进阶学习路径

最后的建议 💡

不要着急 😊
- AI 应用开发是个新领域,大家都在探索
- 慢慢学,扎实掌握每个概念比囫囵吞枣强
多动手 💪
- 看十遍文档不如写一遍代码
- 遇到问题就调试,调试是最好的老师
参与社区 🌟
- 加入钉钉群或微信群,和其他开发者交流
- 在 GitHub 上提 Issue 和 PR,贡献自己的力量
- 分享你的学习心得和实战经验
保持好奇 🔍
- AI 技术日新月异,持续学习很重要
- 关注 Spring AI Alibaba 的更新和新特性
- 探索其他 AI 框架和技术,拓宽视野

社区资源 📮

官方网站: java2ai.com
GitHub: github.com/alibaba/spring-ai-alibaba
示例仓库: github.com/springaialibaba/spring-ai-alibaba-examples
钉钉群: 124010006813
问题反馈: GitHub Issues

Spring AI Alibaba 架构学习指南

Spring AI Alibaba 架构学习指南

第一部分:项目架构深度解析(像架构师一样俯瞰全景)🔍

1. 项目架构概览

🎯 用一个类比来理解

🏗️ 核心设计特征

🆚 与其他 AI 框架的差异

🛠️ 技术栈分析

🌐 外部系统集成

📊 架构流程描述

2. 目录结构与核心流程

📁 目录组织逻辑

🔑 关键文件定位

🔗 模块依赖关系

🎬 典型业务流程:工作流客服场景

3. 代码结构观察

🏛️ 代码组织模式

🎨 设计模式识别

📏 代码质量观察

🔍 潜在改进点(学习机会)

第二部分:技能需求清单(你的学习弹药库)📚

1. 基础技能要求

💻 编程语言和框架

📦 具体版本要求

🛠️ 基础工具和概念

2. 进阶技能要求

🚀 架构模式和设计原则

🧠 领域特定知识

3. 技能掌握程度建议

🌱 初学者(刚接触 AI 应用开发)

🌿 有经验的开发者(熟悉 Spring 生态)

🌳 意欲贡献代码的进阶者

第三部分:学习路径规划(你的专属教练计划)🎯

1. 项目运行入口定位(快速上手)

⚡ 快速启动(适合初学者)

✅ 验证成功标志

🔧 环境配置清单

⚠️ 常见配置陷阱及解决方案

2. 循序渐进学习计划(四阶段法)

🥉 阶段一:环境搭建和项目启动(1-2 天)

🥈 阶段二:核心流程理解(3-5 天)

🥇 阶段三:模块深入和定制开发(1-2 周)

🏆 阶段四:架构理解和贡献指南(2 周+)

3. 学习路径流程图

第四部分:实践建议和进阶指导(从会用到精通)💡

1. 调试技巧和常见陷阱

🐛 调试技巧

⚠️ 常见陷阱

2. 扩展练习建议

⭐⭐ 初级练习(1-2天完成)

⭐⭐⭐ 中级练习(3-5天完成)

⭐⭐⭐⭐ 高级练习(1-2周完成)

⭐⭐⭐⭐⭐ 大师级挑战(3-4周完成)

3. 参与贡献的途径

🎯 Step 1:找到合适的 Issue

📝 Step 2:Fork 并配置仓库

🔧 Step 3:开发和测试

✅ Step 4:代码规范

📤 Step 5:提交 PR

🔄 Step 6:响应 Code Review

🎉 Step 7:合并成功!

第五部分:技术栈学习指引(你的知识地图)🌐

1. 官方文档定位(学习的基石)

📘 核心技术栈文档

📗 项目自身文档

📕 权威技术书籍

2. 学习路径建议(社区智慧)

🎯 技能学习顺序

🎨 核心概念优先级

💡 实践项目推荐

3. 工具与环境配置指南

🛠️ 开发环境搭建

🐳 Docker 环境搭建

4. 进阶拓展方向

🎓 方向 1:AI 应用架构师

🔬 方向 2:框架核心开发者

总结与寄语 🎓

最后的建议 💡

社区资源 📮

通义大模型