Spring AI落地Java企业应用:不换语言也能接大模型
本文不讲虚的,直接拆解 Spring AI 的核心架构与代码实现。从 ChatClient 统一调用、RAG 知识库搭建,到函数调用和 Docker 部署,展示 Java 生态下集成大模型的具体路径。适合希望在不引入 Python 技术栈的前提下,为现有 Spring Boot 项目增加 AI 能力的后端工程师参考。
为什么Java开发者需要Spring AI
过去两年,大语言模型(LLM)持续升温,不少后端团队因此感到压力。Python看上去成了AI的专属语言,Java开发者则常被放到“只管调API”或者“等Python团队把服务封装好”的位置上。
情况正在起变化。Spring AI要做的并不是抢Python在数据科学领域的地盘,它瞄准的是一个很具体的工程问题:在现有的Java/Spring生态里,如何安全、规范地把大模型能力接进来。
对多数企业应用而言,AI只是业务逻辑中的一块。可能是一个智能客服入口,也可能是一个基于内部文档的问答助手。为这些功能单独养一套Python微服务,代价是额外的运维成本、跨语言通信的延迟,以及团队技能栈被拆散。Spring AI的核心价值就是“就地解决”——依赖注入、配置管理、安全机制,Java开发者用熟悉的那一套就能处理AI交互。
这篇文章不谈宏大的行业趋势,直接看代码和架构,看Spring AI究竟怎样把复杂的LLM交互收拢成几个Bean。
核心设计:抽象是为了不被厂商绑定
Spring AI的设计哲学很明确:抽象即自由。这和当年Spring JDBC或JPA的思路一脉相承。
如果直接调用OpenAI的HTTP API,代码里会塞满Authorization: Bearer sk-...这类头信息,以及OpenAI特有的请求体结构。哪天老板说“我们要换成阿里云通义千问以降低成本”,大量代码就得重写。
Spring AI用两层核心抽象把这个问题解决掉:
- Model层(ChatModel/EmbeddingModel):最底层的接口,负责与具体的LLM提供商通信,各家厂商API的差异在这里被屏蔽。
- Client层(ChatClient):更高一级的抽象,类似RestTemplate或WebClient。链式调用、提示词模板管理、消息历史记忆等功能都由它提供。
分层架构解析
Spring AI的应用结构可以分成四层:
- 应用层:你的Controller或Service,处理业务逻辑,比如“用户提问”、“生成报表”。
- 增强层:PromptTemplate(提示词模板)、Function Calling(函数调用)、Structured Output(结构化输出)和RAG流程都在这一层。让LLM变得“有用”的关键组件就是这些。
- 抽象层:
ChatClient和ChatModel。用哪个模型在这里决定,具体的HTTP请求细节则不必关心。 - 基础设施层:VectorStore(向量数据库)、DocumentReader(文档解析器)。RAG应用靠它们打底。
这样分层的好处是,底层模型提供商随时可以换(比如从OpenAI切到Ollama本地模型),上层业务逻辑几乎不用动。只需修改application.yml中的配置,Spring AI会自动加载对应的Starter。
快速上手:从依赖配置开始
建一个Spring AI项目,最省事的办法是用Spring Initializr。需要添加spring-ai-starter以及具体模型的starter,比如spring-ai-openai-spring-boot-starter 或 spring-ai-ollama-spring-boot-starter。
在Maven里,版本管理建议走BOM,避免依赖冲突:
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-bom</artifactId>
<version>1.0.0-M3</version> <!-- 请检查最新稳定版 -->
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>配置文件 application.yml用法很直接。拿本地 Ollama 来说:
spring:
ai:
ollama:
base-url: http://localhost:11434
chat:
model: llama3.2
options:
temperature: 0.7换成 OpenAI 的话,把这段替换成openai节点,再填上 API Key 就行。敏感信息可以通过环境变量注入,Spring AI 支持这种做法,生产环境里这一步跑不掉。
核心功能实战
1. 基础对话:ChatClient vs ChatModel
简单的问答场景,最推荐用它的 API 很顺,消息列表的管理交给它自动完成。ChatClient
@RestController
public class SimpleChatController {
private final ChatClient chatClient;
public SimpleChatController(ChatClient.Builder chatClientBuilder) {
this.chatClient = chatClientBuilder.build();
}
@GetMapping("/chat")
public String chat(@RequestParam String message) {
return chatClient.prompt()
.user(message)
.call()
.content();
}
}乍看之下,这段代码跟普通的服务调用没差别。实际上它在背后会把自动拼好,发给配置好的模型,再把返回的内容取出来。ChatClientmessage 封装为 UserMessage
想要更细的控制,比如设系统提示词(System Message)、调温度参数,那就用底层的ChatModel:
Prompt prompt = new Prompt(
List.of(
new SystemMessage("你是一个严谨的技术专家,回答要简洁。"),
new UserMessage(message)
)
);
ChatResponse response = chatModel.call(prompt);2. 流式响应(SSE)
聊天界面里,没人愿意盯着屏幕干等几秒,等整句生成完才见字。这个问题的标准解法就是 Server-Sent Events (SSE)。
Spring AI 对 Reactor 的支持,让流式响应的实现变得很简单:
@GetMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<String> streamChat(@RequestParam String message) {
return chatClient.prompt()
.user(message)
.stream()
.content();
}前端订阅这个 SSE 端点,就能实时收到生成的文本片段。要留意,这里返回的是Spring WebFlux 会把它转成 SSE 格式。Flux<String>
3. 结构化输出:告别 JSON 解析噩梦
LLM 一般吐的是纯文本,可业务系统要的往往是结构化数据,比如 JSON 对象。过去开发者得写一堆复杂的正则或提示词,逼着模型输出 JSON,解析失败的情况还得另外兜着。
Spring AI 带来了BeanOutputConverter只要模型本身支持结构化输出,比如 GPT-4o 或者版本较新的 Ollama 模型,也可以走这条路。
做法是先写一个 POJO:
public class WeatherInfo {
private String city;
private double temperature;
private String condition;
// getters and setters
}调用的时候再把输出类型指定好:
WeatherInfo info = chatClient.prompt()
.user("查询北京今天的天气")
.call()
.entity(WeatherInfo.class);剩下的交给 Spring AI:提示词怎么拼(相当于告诉模型“请返回符合以下 JSON Schema 的数据”)、结果怎么反序列化,它都在后台完成。代码的健壮性因此提升不少。
4. 函数调用(Function Calling)
LLM 从“聊天机器人”走向“Agent”,函数调用是绕不开的一环。有了它,模型能自己判断什么时候该去调外部工具,比如查数据库、请求天气 API。
在 Spring AI 里,先定义一个方法,加上@Tool注解就行:
@Service
public class WeatherService {
@Tool(description = "获取指定城市的当前天气状况")
public String getWeather(String city) {
// 模拟调用外部 API
return "{\"temperature\": 22, \"condition\": \"Sunny\"}";
}
}当你在 ChatClient这个 Tool 注册进去之后,用户问“北京今天天气怎么样?”这类问题,模型会自动认出该调getWeather函数,再把返回结果揉进最终回答。对开发者来说,这整套流程基本是透明的。
5. RAG:检索增强生成
幻觉和知识滞后是 LLM 的两个老毛病,RAG 就是对付它们的标准方案。Spring AI 把整条 RAG 流水线都备齐了:
- Document Reader:负责读 PDF、Word、Markdown 等文件。
- Text Splitter:把长文档切成小块(Chunks)。
- Embedding Model:把文本块转成向量。
- Vector Store:存向量,Milvus、Redis、Pinecone 等都能用。
- Retrieval:按用户提问去检索相关的文档块。
- Generation:检索到的内容作为上下文,和问题一起送给 LLM。
代码示例:
@Service
public class RagService {
private final VectorStore vectorStore;
private final ChatClient chatClient;
// 注入依赖...
public void ingestDocuments(Path filePath) {
// 1. 读取和分割
Document document = new Document(Files.readString(filePath));
List<Document> chunks = new TokenTextSplitter().split(List.of(document));
// 2. 嵌入并存储
vectorStore.add(chunks);
}
public String askQuestion(String question) {
// 1. 检索相关文档
List<Document> relevantDocs = vectorStore.similaritySearch(question);
String context = relevantDocs.stream()
.map(Document::getContent)
.collect(Collectors.joining("\n"));
// 2. 构建提示词
String promptText = "基于以下上下文回答问题:\n{context}\n问题:{question}";
return chatClient.prompt()
.system(promptText)
.user(u -> u.param("context", context).param("question", question))
.call()
.content();
}
}上面这段代码就是 RAG 的核心逻辑。至于向量库的切换,Spring AI 的VectorStore接口把不同向量数据库的操作统一了起来,换底层存储不再费劲。
部署与运维:Docker 化实践
落到企业环境,大家一般都想少依赖点外部 SaaS 服务,实在不行也至少留个本地 fallback。Ollama 就是眼下常用的本地 LLM 运行工具。
用 Docker Compose 可以把 Ollama 和 Spring Boot 应用一起拉起来:
version: '3.8'
services:
ollama:
image: ollama/ollama
ports:
- "11434:11434"
volumes:
- ollama-data:/root/.ollama
app:
build: .
ports:
- "8080:8080"
environment:
- SPRING_AI_OLLAMA_BASE_URL=http://ollama:11434
depends_on:
- ollama
volumes:
ollama-data:在 Dockerfile应用这边,按标准 Java 镜像打包即可。这样部署出来的 AI 应用能在内网独立跑,数据隐私和安全合规的要求也就照顾到了。
可观测性:盯住 AI 服务的运行状态
跟传统 CRUD 比,AI 服务的不确定性高出不少。下面这几件事得心里有数:
- 每调一次用掉多少 Token?
- 响应要等多久?
- 出错的请求是不是很多?
Spring AI 已经自带 Micrometer 集成。只要把spring-boot-starter-actuator 和 micrometer-registry-prometheus引进来,就能通过/actuator/prometheus这个端点把指标暴露出来。
主要看这几个指标:
spring.ai.chat.client.call.duration调用花了多长时间。spring.ai.chat.client.tokens.usageToken 消耗了多少。
再配上 Grafana,就能搭一个实时监控面板,随时看 AI 服务健不健康、成本烧了多少。想把 LLM 的使用成本管住,这一步很关键。
最佳实践与避坑指南
- 版本选择:Spring AI 眼下迭代挺快。上生产最好等 GA 版本,或者把 M 版本的兼容性测扎实了再用。依赖管理一定要走 BOM。
- 超时设置LLM 的响应时间起伏很大。所以
RestTemplate或WebClient这一层要设好合理的超时,别让线程卡死。 - 缓存策略:同一个问题,LLM 给出的答案通常差不多。把常见问答对放进 Redis 缓存,Token 成本和延迟都能明显降下来。
- 安全过滤:用户输入不能直接信。发给 LLM 之前,先做基本的敏感词过滤或者长度限制。LLM 的输出同样要校验,防住注入攻击和不当内容。
- 本地测试:开发阶段最好用 Ollama 或 LocalAI 在本地跑。API 费用能省一大笔,调试起来也顺手。
结语
Spring AI 并没有造出什么新的 AI 算法,它干的是工程化的活。原来那些零散、各说各话的 LLM 接口,被它收拢进了 Java 开发者最熟的 Spring 编程模型里。
对 Java 团队而言,这意味着不用专门招 Python AI 工程师,也不用把现有的微服务架构推倒重来,就能动手做智能应用。从简单的聊天机器人到复杂的 RAG 知识库,Spring AI 给了一条清楚、好维护的路。
当然,AI 应用开发照样有不少难题,尤其是提示词工程和效果评估。但至少在代码这一层,Spring AI 能让你把心思放在业务逻辑上,而不是底层 API 那些琐碎细节。框架的意义也就在这里。