[AI应用框架/Java] Spring AI 应用开发指南<1>概述、快速入门

1 概述：Spring AI 应用开发指南

简介

  • 在人工智能技术快速发展的当下，其相关技术已成为各行业企业内部技术栈的标配之一，而作为一款主流的企业级Java应用开发框架Spring，也紧跟时代潮流，推出了—— Spring AI 框架。

image

  • Spring AI 是 Spring 官方推出的 AI 工程化框架，旨在简化 Java 开发者集成 AI 模型（如 OpenAI、Azure OpenAI 等）的过程。

Spring AI 作为主流的AI大模型应用开发框架之一，它的推出标志着—— Spring 框架也正式进入大模型时代。
其提供了开发AI大模型所需的模型API，简化了AI大模型应用的开发工作。

  • Spring AI
  • URL : https://spring.io/projects/spring-ai
  • Slogan : Spring AI 是一个面向人工智能工程的应用框架。它的目标是将 Spring 生态系统的设计原则（例如可移植性和模块化设计）应用于人工智能领域，并推广使用 POJO 作为人工智能领域应用程序的构建模块。
  • License : Apache-2.0

image

主要特性

Spring AI 提供以下功能：

此功能集允许您实现常见的用例，例如“ Q&A over your documentation”或“ Chat with your documentation.”。

版本沿革

image

  • 最新版:
  • v2.0.0-M3 : 2026.3.17

https://github.com/spring-projects/spring-ai/releases/tag/v2.0.0-M3

  • v1.1.3 : 2026.3.17

https://github.com/spring-projects/spring-ai/releases/tag/v1.1.3

根据搜索结果，Spring AI 项目的版本演变历程如下。

请注意，所有信息均基于公开的网络资料整理：

1. 早期探索与孵化阶段 (Legacy)

  • 0.8.1 (2024年3月)：这是早期公开记录的一个旧版本，属于项目孵化期的探索性版本。

2. 里程碑版本阶段 (Milestone Releases)

从2024年中旬开始，Spring AI 进入了快速迭代的里程碑版本发布期，旨在逐步完善核心功能并收集社区反馈。

  • 1.0.0-M1 (2024年5月30日)：首个公开的里程碑版本，初步确立了项目架构。
  • 1.0.0-M2 (2024年7月)：继续完善基础功能。
  • 1.0.0-M3 (2024年10月8日)：增加了对更多模型的支持。
  • 1.0.0-M4 (2024年12月)：功能进一步丰富。
  • 1.0.0-M5 (2025年1月9日)：优化了 API 设计。
  • 1.0.0-M6 (2025年3月)：此版本起，构件开始发布到 Maven Central 仓库，方便了开发者使用。
  • 1.0.0-M7 (2025年4月14日)：接近正式版的功能冻结。
  • 1.0.0-M8 (2025年4月30日)：最后一个里程碑版本，主要进行 Bug 修复和文档完善。

3. 候选版本阶段 (Release Candidate)

  • 1.0.0-RC1 (2025年5月13日)：发布候选版本，标志着功能已基本稳定，邀请社区进行最后的测试。

4. 正式通用版本阶段 (General Availability - GA)

  • 1.0.0 GA (2025年5月20日)：首个正式版本。

    • 意义：标志着 Spring AI 正式进入【生产就绪状态】，API 趋于稳定。
    • 核心特性：提供了统一的 ChatClient 接口，支持 OpenAI、Anthropic、Azure、Google 等【主流模型厂商】；引入了 RAG（检索增强生成）基础支持、【对话记忆管理】以及基础的 Function Calling 能力。
    • 环境要求：主要支持 Spring Boot 3.4.x 及 JDK 17+。

  • 1.0.x 维护版本 (2025年下半年)：

    • 在 1.0.0 之后，陆续发布了 1.0.1, 1.0.2, 1.0.3 等补丁版本，主要用于修复 Bug 和小幅改进（截至2025年10月，1.0.3 是当时的最新稳定分支）。

  • 1.1.0 GA (2025年11月12日)：第二个重大正式版本。

    • 背景：距离 1.0 发布仅半年，包含了超过 850 项变更（354个功能增强、241个Bug修复等）。
    • 核心升级：
      • Agent 框架：引入了更高级的 AI Agent（智能体）构建能力，支持多 Agent 协作。
      • MCP (Model Context Protocol)：深度集成了 MCP 协议，支持更标准的上下文交互。
      • 评估工具：新增了 AI 模型输出的评估（Evaluation）工具。
      • 新模型支持：增加了对更多新兴模型（如 DeepSeek 等）的自动配置支持。
      • 技术栈：更好地兼容 Spring Framework 6/7 和 Java 21+ 的新特性（如 AOT 编译优化）。

5. 当前状态 (截至 2026年3月)

  • 主线版本：1.1.x 系列是目前推荐的生产环境使用版本。
  • 开发版本：1.2.0-SNAPSHOT 或更高版本可能正在开发中，用于探索更新的 AI 特性。
  • 生态扩展：基于 Spring AI 的扩展项目（如 Spring AI Alibaba）也紧随其后发布了相应的 1.0 和 1.1 版本，专门针对阿里云百炼及通义千问模型进行了优化。

总结：Spring AI 从 2024 年初的孵化项目，经过约一年的快速迭代（8个里程碑版本），于 2025 年 5 月达到 1.0 成熟度，并在同年 11 月通过 1.1 版本大幅增强了 Agent 和协议支持能力，目前已发展成为 Java 生态中构建企业级 AI 应用的主流框架。

Spring AI: v1.1.3 vs. v2.0.0-M3

基于现有的公开资料和网络搜索结果，关于 Spring AI v1.1.3 与 v2.0.0-M3 的区别，
由于 v2.0.0-M3 的具体发布说明（Release Notes）在当前的公开网络资源中尚未有详尽的独立文档（通常里程碑版本的详细变更集中在 M1 和 GA 前的 RC 阶段，且 M3 是一个非常新的版本或特定内部版本），
为此将基于 v1.1.x 系列的最终状态 与 v2.0.0-M1（及后续 2.0 系列已知的重大架构变更） 的核心差异进行对比。

重要提示：

  • v1.1.3 是 1.1.x 系列的一个稳定补丁版本（Patch Release），主要包含 Bug 修复和小幅优化。
  • v2.0.0-M3 是 2.0 系列的第三个里程碑版本（Milestone），属于非生产就绪的开发版本，其核心特征是破坏性更新（Breaking Changes）和底层架构的重构。

以下是两者的核心区别：

1. 基础运行环境要求（最显著的硬性区别）

这是两个版本之间最大的“分水岭”，直接决定了项目能否启动。

特性 Spring AI v1.1.3 (1.x 系列) Spring AI v2.0.0-M3 (2.x 系列)
最低 JDK 版本 JDK 17 (LTS) JDK 21 (LTS) (强制要求，利用 Java 21 新特性)
Jakarta EE 规范 Jakarta EE 9/10 Jakarta EE 11
Spring Framework Spring Framework 6.2+ Spring Framework 7.0+
Spring Boot 版本 Spring Boot 3.4.x (兼容 3.3+) Spring Boot 4.0.x (GA) (基于 Spring Framework 7)

影响：如果你当前的项目运行在 JDK 17 或 Spring Boot 3.x 上，无法直接升级到 v2.0.0-M3，必须同步升级整个技术栈。

2. 核心架构与 API 变更

v2.0 系列不仅仅是功能增加，更是一次架构重构，旨在解决 1.x 中的设计债务并适应 AI 领域的快速变化。

  • ChatClient API 的重构：

    • v1.1.3: 使用较为初版的 ChatClient 接口，虽然支持流式和非流式，但在复杂上下文管理和拦截器链（Advisors）的配置上相对繁琐。
    • v2.0.0-M3: 对 ChatClient 进行了彻底的重新设计（Reactive-first 或更流畅的构建者模式），简化了多轮对话和复杂 Agent 工作流的代码结构。API 包名或方法签名可能发生变动（Breaking Change）。

  • Model Context Protocol (MCP) 的深度集成：

    • v1.1.3: 引入了 MCP 的初步支持，允许暴露工具和资源，但配置较为手动。
    • v2.0.0-M3: MCP 成为核心一等公民。原生支持 MCP Server/Client 的自动配置，支持更复杂的工具发现机制和动态资源加载，甚至可能内置了对 MCP 标准更新的即时支持（如 SSE 传输层的优化）。

  • 向量存储 (Vector Store) 的增强：

    • v1.1.3: 支持主流向量库（Redis, PGVector, Milvus 等），但部分高级过滤功能（Metadata Filtering）在不同实现间表现不一致。
    • v2.0.0-M3: 统一了向量存储的过滤表达式语言（Filter Expression Language），特别是针对 Redis Vector Store 进行了史诗级增强（支持混合搜索、范围查询优化），并可能引入了对新型向量数据库的原生支持。

3. 功能特性的演进

功能领域 v1.1.3 (稳定版特性) v2.0.0-M3 (前沿实验特性)
Agent 框架 提供基础的 React Agent 和工作流支持，需较多样板代码。 原生 Agent 编排。引入更高级的 AgentBuilder，支持多 Agent 协作、更智能的状态管理和内置的“反思”机制。
模型支持 支持 OpenAI, Azure, Anthropic, Google, Ollama 等主流厂商。 新增/更新模型适配。默认集成更新的模型 SDK（如 OpenAI Java SDK 最新版），可能原生支持 Claude 3.5/4, GPT-4o-mini 等新模型的特定功能（如缓存、JSON Mode 优化）。
观察性与评估 基础的 Micrometer 指标和简单的评估接口。 深度可观测性。与 Spring Observability 深度整合，提供针对 LLM Token 消耗、延迟、幻觉率的细粒度追踪；评估框架（Evaluation Harness）更加完善。
RAG 管道 基础的 ETL 和检索流程。 智能 RAG。支持更复杂的预处理管道，自动分块策略优化，以及基于语义的动态检索策略。

4. 稳定性与适用场景

  • v1.1.3:

    • 定位: 生产就绪 (Production Ready)。
    • 适用: 企业级正式项目，需要长期支持（LTS）和稳定 API 的场景。
    • 优点: 社区案例多，坑已踩完，文档完善，兼容性好（JDK 17/SB 3.4）。

  • v2.0.0-M3:

    • 定位: 里程碑测试版 (Milestone)。
    • 适用: 技术预研、尝鲜、新功能验证、非核心业务系统。
    • 风险: API 随时可能变动，不建议用于生产环境。可能存在未发现的 Bug。
    • 优点: 能体验到最新的架构设计、更好的性能（Java 21 虚拟线程支持可能更深入）和未来标准的支持。

总结建议

  • 如果你的项目正在运行或即将上线，请坚守 v1.1.3（或等待 1.1.x 的后续补丁）。不要为了新功能而盲目升级到底层依赖完全不同的 2.0 里程碑版本。
  • 如果你正在启动一个新项目，且团队有能力处理 JDK 21 和 Spring Boot 4 的迁移成本，并希望利用最新的 AI 架构特性（如更强大的 Agent 和 MCP），可以尝试 v2.0.0-M3，但需做好后续跟随版本迭代修改代码的准备（因为 M3 到 GA 期间 API 仍可能调整）。

注意：由于 v2.0.0-M3 是非常新的里程碑版本，具体的 Bug 修复列表和微小的 API 变动，建议直接查阅 Spring AI 官方 GitHub 仓库的 release-notes 或 CHANGELOG 文件以获取最准确的逐行对比。

前置基础知识

  • Java 基础
  • 常用的技术框架： Spring Boot 等
  • 常用的数据库: MySQL 等

2 快速入门

step1 准备工作

  • 在开始编码前，请确保具备以下条件：

或 注册兼容OpenAI的第三方厂商: 硅基流动 / ...

  • Java 环境：JDK 17 或更高版本。例如： OpenJDK 17.0.2
  • 项目构建工具：Maven 或 Gradle。例如： Maven

step2 创建项目

  • Spring Web：用于构建 Web 接口。例如: Spring Web
  • OpenAI：Spring AI 的 OpenAI Starter。

image

image

Maven 核心依赖配置示例：

<dependency>
	<groupId>org.springframework.ai</groupId>
	<artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>

step3 配置属性(application.yaml)

  • 在 application.yaml 或 application.properties 中配置你的 API Key。如果在中国国内使用，通常需要配置代理地址
spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      # base-url: https://api.openai-proxy.com # 如需使用代理，请在此配置

image

step4 编写代码实现对话

  • 注入 ChatModel（或旧版本中的 ChatClient）来调用 OpenAI 接口。
@RestController
public class ChatController {
    private final ChatModel chatModel;

    @Autowired
    public ChatController(ChatModel chatModel) {
        this.chatModel = chatModel;
    }

    @GetMapping("/ai/generate")
    public String generate(@RequestParam(value = "message") String message) {
        return chatModel.call(message);
    }
}

image

step5 启动运行、调用接口

  • com.johnnyzen.spring_ai_examples.SpringAiExamplesApplication

image

  • 调用接口
curl -X GET http://127.0.0.1:8080/spring-ai/what-is-the-meaning-of-life

curl -X GET http://127.0.0.1:8080/spring-ai/what-is-the-meaning-of-life?language=en

image

//message="总结最近一周的AI Agent前沿进展"
curl -X GET http://127.0.0.1:8080/spring-ai/ai/generate?message=%e6%80%bb%e7%bb%93%e6%9c%80%e8%bf%91%e4%b8%80%e5%91%a8%e7%9a%84AI+Agent%e5%89%8d%e6%b2%bf%e8%bf%9b%e5%b1%95

3 核心组件、原理与架构

FAQ for Spring AI

Q: Spring AI 与 Spring AI Alibaba 的联系与区别?

  • Spring AI 与 Spring AI Alibaba：联系、区别与版本兼容性

在 Java 生态中，Spring AI 和 Spring AI Alibaba 是两个紧密相关但定位不同的框架。简单来说，它们是 “通用基础标准”与“企业级增强实现” 的关系。

1. 核心联系与区别

维度 Spring AI (官方) Spring AI Alibaba (SAA)
维护者 Spring Team (VMware/Broadcom) 阿里云 (Alibaba Cloud)
定位 基础抽象层。提供统一的 AI 编程模型（ChatClient, ToolContext 等），屏蔽底层模型差异。 企业级增强版。基于 Spring AI 构建，专注于解决国内企业落地痛点（模型接入、Agent 编排、RAG 增强）。
核心依赖 无厂商绑定，需自行集成具体模型 SDK。 强依赖 Spring AI，是其超集（Super-set）。代码完全兼容 Spring AI 标准 API。
模型支持 支持 OpenAI, Azure, Anthropic, HuggingFace 等国际主流模型。 原生支持阿里系模型 (通义千问/Qwen, 百炼平台)，同时兼容 Spring AI 支持的所有模型。
特色功能 基础 Chat, Embedding, VectorStore, Function Calling。 Agent Framework (多智能体编排), Graph (工作流引擎), RAG 增强 (40+ 数据源插件), MCP 客户端。
适用场景 通用 AI 应用，跨国项目，或使用非阿里系模型的场景。 国内企业级应用，需要复杂 Agent 编排、快速接入通义大模型、使用阿里云服务的场景。

形象比喻

  • Spring AI 就像是 Android 开源项目 (AOSP)，定义了标准和基础能力。
  • Spring AI Alibaba 就像是 小米澎湃OS 或 华为鸿蒙 (兼容安卓层)，在标准基础上增加了针对特定生态（阿里/国内）的深度优化、预装应用（Agent 框架）和本地化服务。

2. 版本兼容性矩阵 (2026 年最新版)

由于 Spring AI Alibaba 是建立在 Spring AI 之上的，版本严格对应至关重要。根据最新官方文档（截至 2026 年初），兼容性如下：

Spring AI Alibaba (SAA) 版本 依赖的 Spring AI 版本 依赖的 Spring Boot 版本 关键特性说明
1.1.2.0 (当前推荐) 1.1.2 3.5.x 支持最新的 Agent Skills (Supervisor, Routing)，优化多智能体协作。
1.1.0.0 1.1.0 3.4.x 引入完整的 Agent Framework 和 Graph 工作流，支持 MCP 协议。
1.0.0.x 1.0.x 3.3.x 初始版本，提供基础的 Qwen 模型接入和 RAG 支持。

⚠️ 重要警告：

  • 不要混用版本：例如，不要在 Spring Boot 3.3 下强行使用 SAA 1.1.2，这会报 NoSuchMethodError 或类找不到错误（正如你之前遇到的 HttpClientSettings.defaults() 问题，通常就是 Boot 版本过低导致的）。
  • Spring Boot 3.5：SAA 1.1.2+ 开始依赖 Spring Boot 3.5（2025 年底发布），如果你的项目还在 3.2 或 3.3，建议升级 Boot 或降级 SAA 到 1.0.x。

3. 如何选择？

选择 Spring AI Alibaba 如果：

  1. 主要使用阿里云模型：你需要使用通义千问（Qwen）、百炼平台，希望配置最简单（通常只需一个 Starter 依赖）。
  2. 需要复杂的 Agent 编排：你需要构建多智能体（Multi-Agent）、工作流（Workflow）或图状任务流程（Graph），SAA 提供的 Agent Framework 和 Graph 组件能节省大量开发时间。
  3. 国内数据源集成：你需要快速对接钉钉、飞书、语雀、GitHub/Gitee 等作为 RAG 知识库，SAA 内置了 40+ 现成插件。
  4. 企业级落地：你需要更完善的中文文档、国内社区支持和阿里云原生集成。

选择 Spring AI (官方) 如果：

  1. 多云/多模型策略：你的应用需要灵活切换 OpenAI, Google Gemini, AWS Bedrock 等多种非阿里系模型，且不希望引入阿里特定的依赖。
  2. 轻量级应用：只需要简单的对话接口（ChatClient），不需要复杂的 Agent 编排功能。
  3. 国际化项目：目标用户主要在海外，且基础设施不依赖阿里云。

4. 能否混合使用？

理论上可以，但不推荐。

  • 兼容性：因为 SAA 实现了 Spring AI 的标准接口（如 ChatClient, ChatModel），你可以在代码中通过 Spring AI 的标准 API 调用 SAA 提供的功能。
  • 风险：
    • 依赖冲突：如果手动引入了不同版本的 spring-ai 和 spring-ai-alibaba，极易出现类加载冲突。
    • 配置混乱：两者的自动配置类（AutoConfiguration）可能会争夺 Bean 的定义权。
  • 最佳实践：
    • 二选一作为主框架。
    • 如果你选了 Spring AI Alibaba，直接用它提供的 Starter (spring-ai-alibaba-starter)，它会自动传递依赖正确的 Spring AI 版本。你依然可以使用 Spring AI 的标准注解和接口写代码。

5. Maven 依赖示例 (推荐配置)

如果你想使用最新的 Agent 功能 (2026 年标准)：

<properties>
    <spring-boot.version>3.5.0</spring-boot.version> <!-- 必须匹配 -->
</properties>

<dependencyManagement>
    <dependencies>
        <!-- 引入 Spring AI Alibaba 的 BOM 以管理所有版本 -->
        <dependency>
            <groupId>com.alibaba.cloud.ai</groupId>
            <artifactId>spring-ai-alibaba-dependencies</artifactId>
            <version>1.1.2.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <!-- 只需引入这个 Starter，它会自动包含 spring-ai 和 spring-boot 的正确版本 -->
    <dependency>
        <groupId>com.alibaba.cloud.ai</groupId>
        <artifactId>spring-ai-alibaba-starter</artifactId>
    </dependency>
    
    <!-- 可选：如果需要 Web 支持 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
</dependencies>

总结

  • 对于大多数中国开发者而言，Spring AI Alibaba 是更优的选择。它不仅包含了 Spring AI 的所有能力，还解决了“最后一公里”的问题（模型接入、Agent 编排、中文文档），且完全兼容 Spring AI 的编程模型，未来迁移成本极低。唯一需要注意的是严格保持 Spring Boot 和 SAA 的版本对应。

Y 推荐文献

  • Spring AI
  • 学习资源

X 参考文献

posted @ 2026-03-20 15:08  数据知音  阅读(498)  评论(0)    收藏  举报