Spring AI 实战系列 | 第 1 篇：Spring AI 概述与快速上手

系列说明：本文是《Spring AI 实战系列》第 1 篇，面向 Java 开发者，从零开始掌握 Spring AI。
前置知识：熟悉 Spring Boot、了解基本 AI 概念即可。

前言

说实话，我第一次听说 Spring AI 的时候，内心是有点抗拒的。

作为一个写了多年 Java 的老码农，AI 这块一直给我一种「Python 专属」的刻板印象。LangChain、LlamaIndex 这些框架确实香，但让我为了做 AI 项目切到 Python 生态？

那是不可能的。

直到 2024 年 Spring AI 正式发布，我才发现：原来 Java 开发者也能这么优雅地玩大模型。

这篇文章，我会把 Spring AI 是什么、为什么要用它、以及怎么快速上手，给你讲清楚。

一、Spring AI 到底是什么

1.1 诞生背景

2023 年 ChatGPT 爆火之后，整个技术圈都在讨论怎么把大模型能力集成到业务系统里。

Python 生态反应最快，LangChain、LlamaIndex 这些框架迅速崛起。Java 这边呢？大多数团队只能手写 HTTP 客户端去调 OpenAI 的 API，代码又臭又长，换个模型提供商就得重写一堆逻辑。

Spring 团队看不下去了。

2024 年，Spring AI 正式诞生。定位很明确：让 Java 开发者用 Spring 的方式做 AI 应用。

1.2 核心定位

Spring AI 不是 LangChain 的 Java 移植版。它是为 Spring 生态量身打造的 AI 框架，核心就三件事。

可移植的抽象层

一套 API 对接 OpenAI、Anthropic、DeepSeek、Ollama 等 N 个模型提供商，切换只需改配置。

Spring 原生体验

自动配置、Starter 依赖、依赖注入，完全遵循 Spring 的设计哲学。

企业级能力

RAG、Tool Calling、对话记忆、可观测性，生产环境需要的它都有。

1.3 与 LangChain/LangChain4j 的对比

很多人问我：Spring AI 和 LangChain4j 有什么区别？我用哪个？

我的建议是：

如果你的项目已经是 Spring Boot 生态，直接上 Spring AI，无缝集成，学习成本最低。

如果你需要更灵活的编排能力，LangChain4j 的 Chain 概念更丰富，可以作为补充。

如果你是从 Python 迁移过来，Spring AI 的 API 设计更贴近 Spring 开发者习惯。

实际项目中，两者甚至可以混用，并不冲突。

二、Spring AI 解决了什么问题

2.1 供应商锁定问题

假设你一开始用的 OpenAI，代码里到处都是OpenAiApi的调用。后来公司要求换国产模型，比如通义千问或者 DeepSeek，你怎么办？

重写所有调用逻辑？

Spring AI 的做法是提供统一抽象：

// 不管是什么模型，都是 ChatClientChatClientchatClient=ChatClient.builder(chatModel).build();Stringresponse=chatClient.prompt().user("讲一个关于程序员的笑话").call().content();

换模型？改个配置就行：

# OpenAIspring:ai:openai:api-key:${OPENAI_API_KEY}# 换成 DeepSeekspring:ai:openai:api-key:${DEEPSEEK_API_KEY}base-url:https://api.deepseek.com

代码一行不用改。

2.2 复杂的 Prompt 管理

直接拼字符串写 Prompt？那是初学者做法。

Spring AI 提供了PromptTemplate，支持占位符和动态填充：

PromptTemplatepromptTemplate=newPromptTemplate(""" 你是一位{role}，请用{style}的风格回答以下问题： {question} """);Promptprompt=promptTemplate.create(Map.of("role","Java 技术专家","style","通俗易懂","question","什么是 Spring AI？"));

配合 Spring 的 ResourceLoader，还能把 Prompt 模板放到外部文件里管理，方便团队协作和版本控制。

2.3 企业级 AI 应用的刚需

做 Demo 很简单，但上生产环境就麻烦了。

怎么让 AI 回答基于企业私有数据？RAG（检索增强生成）。

怎么让 AI 调用业务系统的 API？Tool Calling。

怎么记住用户的对话上下文？ChatMemory。

怎么监控 AI 的调用成本和响应质量？可观测性。

这些 Spring AI 都内置了，不用自己造轮子。

三、核心概念速览

在写代码之前，先搞清楚几个核心概念。

3.1 Model（模型）

AI 模型是处理信息并生成输出的算法。Spring AI 目前支持三类模型：

• Chat Model，比如 GPT-4、Claude、DeepSeek，用于文本对话
• Embedding Model，比如 text-embedding-3-small，用于文本向量化
• Image Model，比如 DALL-E、Stable Diffusion，用于图像生成

3.2 Prompt（提示词）

Prompt 是指导 AI 模型生成特定输出的输入文本。

Spring AI 的 Prompt 不是简单的字符串，它包含多个 Message，每个 Message 都有角色：

• System Message，设定 AI 的行为和背景
• User Message，用户的输入
• Assistant Message，AI 的回复（用于多轮对话）

Promptprompt=newPrompt(List.of(newSystemMessage("你是一位幽默的 Java 技术专家"),newUserMessage("什么是 Spring AI？")));

3.3 Embedding（嵌入）

Embedding 是把文本转换成向量的技术。这些向量可以表示文本的语义信息，用于语义搜索、文本相似度计算、RAG 中的文档检索。

List<Double>embedding=embeddingModel.embed("Spring AI 很强大");// 返回一个 1536 维的向量（取决于模型）

3.4 Token

Token 是模型处理文本的基本单位。理解 Token 很重要，因为它直接关系到调用成本（按 Token 数量计费）、上下文窗口（模型一次能处理的最大 Token 数）、性能（Token 越多，响应越慢）。

Spring AI 提供了 Token 计数工具，方便你做成本控制和性能优化。

四、快速上手，第一个 Spring AI 项目

4.1 环境准备

• JDK 17+（Spring AI 1.0+ 要求）
• Maven 或 Gradle
• IDEA（推荐）
• AI 模型的 API Key（OpenAI、DeepSeek、智谱等均可）

4.2 创建项目

用 Spring Initializr（https://start.spring.io）创建项目：

1. Project：Maven
2. Language：Java
3. Spring Boot：3.2.x 或更高
4. Dependencies：添加Spring AI（如果可选列表里没有，手动加依赖）

4.3 添加依赖

<dependencyManagement><dependencies><dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-bom</artifactId><version>1.0.0-M5</version><type>pom</type><scope>import</scope></dependency></dependencies></dependencyManagement><dependencies><!-- Spring Boot Starter --><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></dependency></dependencies>

如果你用 DeepSeek，也是spring-ai-openai-spring-boot-starter，因为 DeepSeek 兼容 OpenAI 的 API 格式。

4.4 配置 API Key

spring:ai:openai:api-key:${OPENAI_API_KEY}# 如果用 DeepSeek，加上 base-url# base-url: https://api.deepseek.comchat:options:model:gpt-4otemperature:0.7

4.5 编写第一个 Controller

@RestController@RequestMapping("/ai")publicclassChatController{privatefinalChatClientchatClient;publicChatController(ChatClient.BuilderchatClientBuilder){this.chatClient=chatClientBuilder.build();}@GetMapping("/chat")publicStringchat(@RequestParamStringmessage){returnchatClient.prompt().user(message).call().content();}}

启动项目，访问：

GET http://localhost:8080/ai/chat?message=你好，Spring AI

如果看到 AI 的回复，恭喜你，第一个 Spring AI 项目跑通了！

4.6 流式输出

上面的例子是同步调用，等 AI 全部生成完才返回。如果回复很长，用户体验会很差。

Spring AI 支持流式输出：

@GetMapping(value="/chat/stream",produces=MediaType.TEXT_EVENT_STREAM_VALUE)publicFlux<String>chatStream(@RequestParamStringmessage){returnchatClient.prompt().user(message).stream().content();}

前端用 EventSource 接收，就能实现打字机效果了。

五、版本说明与选型建议

5.1 当前版本状态

截至 2025 年，Spring AI 的版本情况：

• 1.0.0-M5，Milestone 版本，功能基本稳定，API 可能微调
• 1.1.x，GA 正式发布，新增 Agent 框架、MCP 支持

生产环境建议用1.1.x GA版本。

5.2 本系列使用的版本

本系列文章基于Spring AI 1.0.0+，部分高级特性（如 Agent、MCP）需要1.1.x。

我会在涉及新特性的地方特别标注版本要求。

写在最后

这篇文章是系列的开篇，主要是让你对 Spring AI 有个整体认知，并跑通第一个项目。

下一篇，我会深入讲解ChatClient 的完整用法，包括多模型切换、Prompt 模板、以及各种配置选项的实战技巧。

如果你已经迫不及待想继续深入，可以先去 Spring AI 官方文档 逛逛，但相信我，跟着这个系列走，你会少走很多弯路。

系列目录：

• 第 1 篇：Spring AI 概述与快速上手 ✅（本文）
• 第 2 篇：ChatClient 详解与多模型集成
• 第 3 篇：结构化输出与多模态
• 第 4 篇：Embedding 与向量数据库
• 第 5 篇：RAG 检索增强生成
• 第 6 篇：Tool Calling 工具调用
• 第 7 篇：Advisor 机制与对话管理
• 第 8 篇：MCP 模型上下文协议
• 第 9 篇：AI Agent 开发实战
• 第 10 篇：企业级应用与最佳实践

如果这篇文章对你有帮助，欢迎点赞收藏关注，系列持续更新中！