Spring AI

Spring Boot 版本兼容性

Spring AI 2.x.x（main 分支）- Spring Boot 4.x

Spring AI 1.1.x（1.1.x 分支）- Spring Boot 3.5.x

Spring AI 项目提供了一个对 Spring 友好的 API 和抽象层，用于开发 AI 应用程序。

其目标是将 Spring 生态系统的设计原则，如可移植性和模块化设计，应用于 AI 领域，并在 AI 领域推广使用 POJO 作为应用程序的构建块。

在核心层面，Spring AI 解决了 AI 集成的根本挑战：将企业的 数据 和 API 与 AI 模型 连接起来。

该项目受到一些著名的 Python 项目启发，例如 LangChain 和 LlamaIndex，但 Spring AI 并不是这些项目的直接移植。该项目的创立基于这样一种信念：下一代生成式 AI 应用程序不仅会面向 Python 开发人员，还将在多种编程语言中普及。

您可以在博客文章 Why Spring AI 中找到更多相关的动机。

以下是高层次的功能概述。 更多详细信息请参阅 参考文档

• 支持所有主要的 AI 模型提供商，如 Anthropic、OpenAI、Microsoft、Amazon、Google 和 Ollama。支持的模型类型包括：
  • 聊天完成
  • 嵌入
  • 文本转图像
  • 音频转录
  • 文本转语音
  • 内容审核
  • 最新模型：GPT-5 等前沿模型，适用于高级 AI 应用程序。
• 跨 AI 提供商的可移植 API，支持同步和流式传输两种方式。还可以访问 模型特定功能。
• 结构化输出 - 将 AI 模型的输出映射到 POJO。
• 支持所有主要的 向量数据库提供商，如 Apache Cassandra、Azure Vector Search、Chroma、Elasticsearch、Milvus、MongoDB Atlas、MariaDB、Neo4j、Oracle、PostgreSQL/PGVector、Pinecone、Qdrant、Redis 和 Weaviate。
• 跨向量存储提供商的可移植 API，包括一种新颖的类似 SQL 的 元数据过滤 API。
• 工具/函数调用 - 允许模型请求执行客户端工具和函数，从而根据需要访问必要的实时信息。
• 可观测性 - 提供对 AI 相关操作的洞察。
• 数据工程中的文档注入 ETL 框架。
• AI 模型评估 - 提供实用工具来评估生成的内容，并防止出现幻觉式响应。
• ChatClient API - 用于与 AI 聊天模型通信的流畅 API，其语法风格类似于 WebClient 和 RestClient API。
• 顾问 API - 封装了常见的生成式 AI 模式，转换发送给语言模型 (LLM) 和从语言模型返回的数据，并实现跨不同模型和用例的可移植性。
• 支持 聊天对话记忆 和 检索增强生成 (RAG)。
• Spring Boot 自动配置和启动器，适用于所有 AI 模型和向量存储 - 使用 start.spring.io 选择您所需的模型或向量存储。

入门指南

请参阅 入门指南 以了解如何添加依赖项。

项目资源

• 文档
• 问题

• Awesome Spring AI - 一个精选的资源、工具、教程和项目列表，用于使用 Spring AI 构建生成式 AI 应用程序
• Spring AI 示例 包含详细解释特定功能的示例项目。
• Spring AI 社区 - 一个由社区驱动的组织，致力于构建基于 Spring 的 AI 模型、智能体、向量数据库等集成。

重大变更

• 请参阅 升级说明 以了解如何升级到 1.0.0.M1 或更高版本。

克隆仓库

该仓库包含大型模型文件。 要克隆它，您需要：

• 忽略大文件（不会影响 spring-ai 的行为）：GIT_LFS_SKIP_SMUDGE=1 git clone git@github.com:spring-projects/spring-ai.git。
• 或者在克隆仓库之前安装 Git Large File Storage。

构建

该项目的目标和构建产物兼容 Java 17 及以上版本，但需要使用 JDK 21 才能进行构建。这一点由 Maven Enforcer 插件强制执行。

要构建并运行单元测试：

./mvnw clean package

要构建并包含集成测试：

./mvnw clean verify -Pintegration-tests

请注意，在运行测试之前，您应设置 OpenAI 或其他模型提供商的 API 密钥环境变量。如果未为特定的模型提供商设置 API 密钥，则会跳过相应的集成测试。

要运行特定的集成测试，并允许最多两次重试以成功。这在托管服务不可靠或超时时非常有用：

./mvnw -pl vector-stores/spring-ai-pgvector-store -am -Pintegration-tests -Dfailsafe.failIfNoSpecifiedTests=false -Dfailsafe.rerunFailingTestsCount=2 -Dit.test=PgVectorStoreIT verify

集成测试

集成测试数量众多，因此通常不可能一次性全部运行。

可以通过 -Pci-fast-integration-tests 配置文件快速遍历最重要的路径，运行以下集成测试：

• OpenAI 模型
• OpenAI 自动配置
• PGVector
• Chroma

此配置文件用于本项目的主 CI 构建中。

完整的集成测试每天会在 Spring AI 集成测试仓库 中执行两次。

一种仅对部分代码运行集成测试的方法是先快速编译并安装项目：

./mvnw clean install -DskipTests -Dmaven.javadoc.skip=true

然后使用 -pl 选项为特定模块运行集成测试：

./mvnw verify -Pintegration-tests -pl spring-ai-spring-boot-testcontainers

文档

要构建文档：

./mvnw -pl spring-ai-docs antora

生成的文档位于 spring-ai-docs/target/antora/site/index.html 目录下。

源代码格式化

代码在构建过程中会使用 java-format 插件 进行格式化。正确的格式由 CI 强制执行。

更新许可证头

要使用 license-maven-plugin 更新许可证头中的年份：

./mvnw license:update-file-header -Plicense

Javadoc

要使用 javadoc:javadoc 检查 Javadoc：

./mvnw javadoc:javadoc

源代码风格

Spring AI 的源代码 Checkstyle 检查试图遵循 Spring 核心框架项目所使用的 Checkstyle 指南，但也有一些例外。维基页面 代码风格 和 IntelliJ IDEA 编辑器设置 定义了我们使用的源文件编码标准以及我们自定义的一些 IDEA 编辑器设置。

手动运行 Checkstyle：

./mvnw process-sources -P checkstyle-check

贡献

您的贡献始终受到欢迎！请先阅读贡献指南。

Spring AI 快速上手指南

Spring AI 旨在为 Java 开发者提供一套符合 Spring 生态设计原则（如可移植性、模块化）的 API，用于轻松构建生成式 AI 应用。它支持连接企业数据与主流 AI 模型（如 OpenAI、Anthropic、Ollama 等），并兼容多种向量数据库。

1. 环境准备

在开始之前，请确保您的开发环境满足以下要求：

• JDK 版本：
  • 构建要求：必须安装 JDK 21（项目构建强制要求）。
  • 运行要求：生成的制品兼容 Java 17+。
• 构建工具：Maven 或 Gradle（推荐使用项目自带的 Maven Wrapper）。
• Spring Boot 版本兼容性：
  • Spring AI 2.x (main 分支)：需配合 Spring Boot 4.x。
  • Spring AI 1.1.x (1.1.x 分支)：需配合 Spring Boot 3.5.x。
• API Key：若使用云端模型（如 OpenAI），需提前准备好对应的 API Key 并配置为环境变量。

2. 安装步骤

推荐使用 start.spring.io 初始化项目，或通过 Maven/Gradle 手动添加依赖。

方式一：使用 Spring Initializr (推荐)

访问 start.spring.io，在 "Dependencies" 中搜索并添加 Spring AI 相关的 Starter（例如 Spring AI OpenAI 或 Spring AI Ollama），然后生成项目。

方式二：手动添加依赖

在您的 pom.xml 中添加以下依赖（以 OpenAI 为例，请根据实际使用的模型提供商选择对应的 starter）：

<dependencies>
    <!-- Spring Boot Starter Web (基础依赖) -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <!-- Spring AI OpenAI Starter -->
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
        <!-- 版本号通常由 Spring Boot BOM 管理，若需指定请参考 Maven Central 最新版本 -->
    </dependency>
</dependencies>

注意：如果您使用的是快照版本或非正式发布版，可能需要在 pom.xml 中配置 Spring Milestones 或 Snapshots 仓库。

配置 API Key

在 application.properties 或 application.yml 中配置您的模型凭证：

# OpenAI 示例
spring.ai.openai.api-key=${OPENAI_API_KEY}

或者在终端导出环境变量：

export OPENAI_API_KEY="your-api-key-here"

3. 基本使用

Spring AI 提供了流畅的 ChatClient API，风格类似于 WebClient 和 RestClient。以下是一个最简单的聊天交互示例。

创建 ChatClient Bean

首先，在配置类中注入默认的 ChatModel 并构建 ChatClient：

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.model.ChatModel;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class AiConfig {

    @Bean
    public ChatClient chatClient(ChatModel chatModel) {
        return ChatClient.builder(chatModel).build();
    }
}

调用 AI 模型

在服务层或控制器中直接使用 ChatClient 进行对话：

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class AiController {

    private final ChatClient chatClient;

    public AiController(ChatClient chatClient) {
        this.chatClient = chatClient;
    }

    @GetMapping("/ai/chat")
    public String chat(@RequestParam(value = "message", defaultValue = "Hello") String message) {
        // 发送消息并获取响应内容
        return this.chatClient.prompt()
                .user(message)
                .call()
                .content();
    }
}

运行测试

启动 Spring Boot 应用后，访问接口即可看到 AI 返回的结果：

curl "http://localhost:8080/ai/chat?message=请用中文介绍 Spring AI"

---

更多高级功能（如函数调用、RAG、向量数据库集成等）请参阅官方参考文档。