一、Spring AI 框架概述

Spring AI 是 Spring 生态专为 AI 工程设计的应用框架，旨在简化集成人工智能功能的应用程序开发过程，避免不必要的复杂性。它借鉴了 LangChain、LlamaIndex 等 Python 项目的灵感，但并非直接移植，而是面向 Java 开发者打造的企业级 AI 开发框架。

该框架提供统一的 API 接口，可对接 OpenAI、Anthropic、Google GenAI 等不同 AI 模型，同时内置向量存储、文档处理等核心功能，让开发者能够专注于业务逻辑而非底层集成。截至 2025 年 11 月，Spring AI 已更新至 1.1 GA 版本，引入 Agents 框架和 Bench 评估工具，兼容 Spring Framework 7.x 和 Java 21+，适用于聊天助手、文档 Q&A、智能搜索、图像生成等多种场景。

二、环境搭建与项目初始化

（一）基础环境准备

开发者需提前准备 JDK 17 或更高版本（推荐 Azul Zulu JDK）、IntelliJ IDEA 2023.3+（社区版即可），以及对应 AI 模型的 API 密钥（如 OpenAI 账号密钥，注册时建议使用企业邮箱避免风控）。

（二）项目创建与依赖配置

可通过 Spring Initializr（https://start.spring.io）快速生成 Spring Boot 项目，选择 Spring Web、Spring Boot DevTools、Spring AI 等依赖。也可手动创建 Maven 项目，在 pom.xml 中添加 Spring AI 相关依赖，以 OpenAI 为例：

<dependency>
   <groupId>org.springframework.ai</groupId>
   <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
   <version>0.8.0</version>
</dependency>


若网络环境较差，可配置阿里云镜像加速依赖下载。

（三）API 密钥安全管理

直接将 API Key 写在配置文件中存在安全风险，尤其是代码需上传至公开仓库时。更专业的做法是使用环境变量，在 application.yml 中配置：

spring:
 ai:
   openai:
     api-key: ${OPENAI_API_KEY:}


优先从环境变量 OPENAI_API_KEY 中读取密钥，若读取失败则使用空字符串。随后在系统环境变量或 IDE 运行配置中设置 OPENAI_API_KEY=你的真实密钥，既保证代码安全，又方便在不同环境（开发、测试、生产）切换密钥。

三、核心功能实战

（一）ChatClient API 实现智能对话

ChatClient API 是 Spring AI 与 AI 聊天模型交互的核心接口，支持同步和流式两种调用方式。

同步调用：适用于对响应时间要求不高的场景，可一次性获取完整结果。示例代码如下：

@RestController
@RequiredArgsConstructor
public class ChatController {
   private final ChatClient chatClient;

   @GetMapping("/chat")
   public String simpleChat(@RequestParam String message) {
       String response = chatClient.prompt(message).call().content();
       log.info("AI 回复: {}", response);
       return response;
   }
}


流式调用：类似 ChatGPT 的逐字响应效果，适用于实时性要求较高的应用。需确保 Controller 方法返回类型为 Flux<String>，并设置 @GetMapping 的 produces 属性为 MediaType.TEXT_EVENT_STREAM_VALUE，示例代码：

@GetMapping(value = "/chat-stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<String> chatStream(@RequestParam String message) {
   return chatClient.prompt(message).stream().content();
}


若流式接口调用后无逐字输出效果或报错，需检查返回类型是否为 Flux<String>、是否使用 .stream() 方法，以及 produces 属性配置是否正确。

（二）嵌入模型与向量存储实现 RAG

嵌入模型 API 可将文本转换为向量表示，用于相似度计算等任务，Spring AI 支持 OpenAIEmbeddingModel、AzureOpenAIEmbeddingModel 等多种嵌入模型。向量存储模块则用于高效存储和检索向量数据，提供 PgVector、Redis、MongoDB 等多种实现，满足不同场景需求。

以 MongoDB 向量存储为例，需先在 application.properties 中配置数据库连接信息：

spring.data.mongodb.uri=mongodb+srv://<db_username>:<db_password>@<clusterName>.<hostname>.mongodb.net/?<settings>


随后创建向量搜索索引，确保索引配置的维度与嵌入模型生成的向量维度一致（如 1536 维），否则可能导致查询错误。通过嵌入模型和向量存储的结合，可轻松实现检索增强生成（RAG），提升 AI 回答的准确性和可靠性。

四、生产级实践技巧

（一）配置管理最佳实践

可通过 @ConfigurationProperties 注解统一管理 AI 模型配置，示例代码：

@Configuration
public class AiConfig {
   @Bean
   @ConfigurationProperties(prefix = "spring.ai.openai")
   public OpenAiConnectionProperties openAiConnectionProperties() {
       return new OpenAiConnectionProperties();
   }

   @Bean
   public OpenAiApi openAiApi(OpenAiConnectionProperties properties) {
       return new OpenAiApi(properties);
   }
}


（二）函数调用实现复杂业务逻辑

Spring AI 的函数调用功能允许 AI 模型根据用户请求自动调用预设函数，实现更复杂的业务逻辑。开发者只需定义带有 @Tool 注解的函数，即可被 AI 模型识别和调用，示例代码：

@Slf4j
@Component
public class DateTimeTools {
   @Tool(description = "为给定时间设置用户闹钟，以 ISO-8601 格式提供")
   void setAlarm(String time) {
       log.info("设置闹钟时间: {}", time);
       // 闹钟设置逻辑
   }
}