Spring AI Alibaba 架构设计解析

深入理解 Spring AI Alibaba 的分层架构设计，掌握各层职责边界与核心设计原则。

整体架构哲学

Spring AI Alibaba 遵循 "关注点分离 + 面向接口编程 + 约定优于配置" 的 Spring 核心哲学，将 AI 应用开发中的复杂性封装在框架内部，让开发者专注于业务逻辑。

核心设计原则

1. 可移植性：通过统一抽象，代码不绑定特定 AI 服务商
2. 可扩展性：SPI 机制支持自定义模型、存储、工具
3. 可观测性：内置 Micrometer 指标，生产环境开箱即用
4. 渐进式采用：从简单 ChatClient 到复杂 Graph，按需使用

分层架构详解

┌─────────────────────────────────────────────────────────────────┐
│  Layer 5: 应用与平台层                                           │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
│  │ Admin 平台   │  │ Studio 调试  │  │  JManus / DataAgent  │  │
│  │ 可视化开发   │  │ 嵌入式 UI    │  │  DeepResearch        │  │
│  └──────────────┘  └──────────────┘  └──────────────────────┘  │
├─────────────────────────────────────────────────────────────────┤
│  Layer 4: Agent 框架层                                           │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  Agent Framework                                         │    │
│  │  ReactAgent | SequentialAgent | ParallelAgent           │    │
│  │  RoutingAgent | LoopAgent                               │    │
│  │  Context Engineering | Human-in-the-Loop | A2A          │    │
│  └─────────────────────────────────────────────────────────┘    │
├─────────────────────────────────────────────────────────────────┤
│  Layer 3: Graph 运行时层                                         │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  Spring AI Alibaba Graph                                 │    │
│  │  StateGraph | Node | Edge | Checkpoint                  │    │
│  │  条件路由 | 并行执行 | 嵌套子图 | 流式输出               │    │
│  └─────────────────────────────────────────────────────────┘    │
├─────────────────────────────────────────────────────────────────┤
│  Layer 2: Spring AI 核心抽象层                                   │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐   │
│  │ChatModel │ │Embedding │ │VectorStore│ │  ImageModel      │   │
│  │ChatClient│ │  Model   │ │           │ │  AudioModel      │   │
│  └──────────┘ └──────────┘ └──────────┘ └──────────────────┘   │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐   │
│  │  Tool    │ │   RAG    │ │  Memory  │ │   MCP Client     │   │
│  │ Calling  │ │ Advisor  │ │          │ │                  │   │
│  └──────────┘ └──────────┘ └──────────┘ └──────────────────┘   │
├─────────────────────────────────────────────────────────────────┤
│  Layer 1: 模型与基础设施适配层                                   │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐   │
│  │DashScope │ │  OpenAI  │ │ DeepSeek │ │     Ollama       │   │
│  │(通义千问)│ │          │ │          │ │   (本地模型)     │   │
│  └──────────┘ └──────────┘ └──────────┘ └──────────────────┘   │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐   │
│  │  Nacos   │ │  ARMS    │ │ 向量数据库│ │   Redis/JDBC     │   │
│  │ (注册中心)│ │(可观测性)│ │          │ │   (记忆存储)     │   │
│  └──────────┘ └──────────┘ └──────────┘ └──────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

核心抽象接口体系

模型接口层级

// 最底层：原始模型调用
public interface Model<TReq extends ModelRequest<?>, TRes extends ModelResponse<?>> {
    TRes call(TReq request);
}

// Chat 模型接口
public interface ChatModel extends Model<Prompt, ChatResponse> {
    ChatResponse call(Prompt prompt);
    Flux<ChatResponse> stream(Prompt prompt); // 流式
}

// 高层封装：ChatClient（Fluent API）
ChatClient.create(chatModel)
    .prompt()
    .system("你是一个助手")
    .user("你好")
    .call()
    .content();

请求/响应模型

Prompt
  └── List<Message>
        ├── SystemMessage    // 系统指令
        ├── UserMessage      // 用户输入
        ├── AssistantMessage // 模型回复
        └── ToolResponseMessage // 工具结果

ChatResponse
  └── List<Generation>
        └── AssistantMessage
              └── ChatGenerationMetadata
                    └── FinishReason / TokenUsage

关键设计模式

1. Advisor 拦截器模式

Advisor 是 Spring AI 中最重要的扩展点，类似 Spring AOP，在 ChatClient 调用链上插入横切逻辑：

ChatClient.call()
    │
    ▼
┌─────────────────────────────────────┐
│  Advisor Chain (有序执行)            │
│  ┌─────────────────────────────┐    │
│  │ SimpleLoggerAdvisor         │    │  ← 日志记录
│  ├─────────────────────────────┤    │
│  │ MessageChatMemoryAdvisor    │    │  ← 注入历史对话
│  ├─────────────────────────────┤    │
│  │ QuestionAnswerAdvisor (RAG) │    │  ← 检索增强
│  └─────────────────────────────┘    │
└─────────────────────────────────────┘
    │
    ▼
ChatModel.call(enrichedPrompt)

2. 自动配置模式

Spring Boot AutoConfiguration 驱动，只需引入 Starter 依赖：

<dependency>
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
    <version>1.1.2.1</version>
</dependency>

配置文件：

spring:
  ai:
    dashscope:
      api-key: ${AI_DASHSCOPE_API_KEY}
      chat:
        options:
          model: qwen-max
          temperature: 0.7

3. 策略模式（VectorStore / Memory）

// 开发环境：内存存储
@Bean
VectorStore vectorStore(EmbeddingModel em) {
    return new SimpleVectorStore(em);
}

// 生产环境：Redis 向量存储
@Bean
VectorStore vectorStore(EmbeddingModel em, RedisClient redis) {
    return new RedisVectorStore(em, redis, config);
}
// ChatClient 代码无需修改！

模块依赖关系

spring-ai-alibaba-agent-framework
    └── spring-ai-alibaba-graph
          └── spring-ai-core (Spring AI)
                └── spring-boot-autoconfigure

spring-ai-alibaba-starter-dashscope
    └── spring-ai-alibaba-core
          └── spring-ai-core

spring-ai-alibaba-admin
    └── spring-ai-alibaba-studio
          └── spring-ai-alibaba-agent-framework

与 LangChain / LangGraph 对比

维度	Spring AI Alibaba	LangChain (Python)
语言	Java / JVM	Python
生态	Spring 全家桶	Python AI 生态
类型安全	强类型，编译期检查	动态类型
部署	Spring Boot 标准部署	需要 Python 运行时
企业集成	原生 Spring 集成	需要额外适配
Agent 编排	Graph（类 LangGraph）	LangGraph
学习曲线	Java 开发者友好	Python 开发者友好

下一步

• 快速开始 →
• ChatModel 深度解析 →
• Graph 工作流引擎 →