跳到主要内容
Spring AI 快速上手与实战指南 | 极客日志
Java AI java 算法
Spring AI 快速上手与实战指南 Spring AI 是 Spring 官方推出的 AI 工程框架,旨在简化 Java 开发者构建大模型应用的流程。本文涵盖 DeepSeek、Ollama 及阿里云通义模型的集成方法,详解 ChatClient 与 ChatModel 接口使用、函数调用 Function Calling、图像与语音生成 API,以及基于 RAG(检索增强生成)的知识库构建实战。通过具体代码示例,展示如何配置依赖、处理流式响应、实现本地模型部署及综合案例开发,帮助开发者快速掌握 Spring AI 核心能力并落地实际项目。
SqlMaster 发布于 2026/3/27 0 浏览Spring AI 快速上手与实战指南
1. Spring AI 简介
在人工智能飞速发展的今天,AI 已成为行业标配。作为主流 Java 开发框架,Spring 社区顺势推出了 Spring AI 框架,旨在将 Spring 的设计原则应用于 AI 领域。
1.1 什么是 Spring AI
官网将其定义为 AI 工程领域的应用程序框架。其核心目标是将 Spring 生态系统的可移植性和模块化设计原则引入 AI 领域,促进使用 POJO 作为构建块。简单来说,它提供了开发大模型应用所需的基本抽象模型,拥有多种实现方式,让开发者能用很少的代码改动实现组件的轻松替换。
目前版本分为预览版 (PRE)、快照版 (SNAPSHOT) 和正式版 (GA)。推荐使用 GA 版本以保证稳定性,SNAPSHOT 版本则持续更新。
1.2 主要功能
支持主流 AI 大模型供应商(OpenAI、DeepSeek、Ollama 等)
涵盖聊天、文本到图像、文本到声音等多种模型类型
集成主流 Embedding Models 和向量数据库(如 Chroma、Milvus、Redis 等)
支持函数调用 (Function Calling)
提供 ETL 数据工程框架
支持 Spring Boot 自动配置
2. 快速入门
2.1 准备工作
我们以 DeepSeek 为例进行集成。DeepSeek 是一款基于深度学习和多模态数据融合技术的大模型,具有成本低、性能强的特点。集成前需要获取 API Key。
进入 DeepSeek 开放平台注册账号并创建 API Key,后续配置中需填入该密钥。
2.2 创建 SpringBoot 工程
创建一个 SpringBoot 项目,注意 JDK 版本建议 17+,Spring AI 版本建议使用较新的稳定版。
2.2.1 引入依赖
在父模块 pom.xml 中添加公共依赖:
<properties >
<maven.compiler.source > 17</maven.compiler.source >
<maven.compiler.target > 17</maven.compiler.target >
<spring-ai.version > 1.0.0-M5</spring-ai.version >
</properties >
<dependencies >
<dependency >
<groupId > org.springframework.boot</groupId >
<artifactId > spring-boot-starter-web</ >
org.springframework.ai
spring-ai-openai-spring-boot-starter
org.projectlombok
lombok
1.18.30
org.springframework.ai
spring-ai-bom
${spring-ai.version}
pom
import
artifactId
</dependency >
<dependency >
<groupId >
</groupId >
<artifactId >
</artifactId >
</dependency >
<dependency >
<groupId >
</groupId >
<artifactId >
</artifactId >
<version >
</version >
</dependency >
</dependencies >
<dependencyManagement >
<dependencies >
<dependency >
<groupId >
</groupId >
<artifactId >
</artifactId >
<version >
</version >
<type >
</type >
<scope >
</scope >
</dependency >
</dependencies >
</dependencyManagement >
2.2.2 配置文件 在子模块的 application.properties 中配置服务端口及 API Key:
server.port=8899
spring.application.name=spring-ai-deepseek-demo
# DeepSeek 的 Api key
spring.ai.openai.api-key=sk-****************
spring.ai.openai.base-url=https://api.deepseek.com
spring.ai.openai.chat.options.model=deepseek-chat
spring.ai.openai.chat.options.temperature=0.7
其中 temperature 控制生成文本的多样性,值越高越随机,值越低越确定。
2.2.3 启动类与 Controller 创建启动类后,编写一个简单的 Controller 来测试调用:
package com.example.ai.controller;
import jakarta.annotation.Resource;
import org.springframework.ai.openai.OpenAiChatModel;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class ChatDeepSeekController {
@Resource
private OpenAiChatModel chatModel;
@GetMapping("/ai/generate")
public String generate (@RequestParam(value = "message", defaultValue = "hello") String message) {
String response = this .chatModel.call(message);
System.out.println("response: " + response);
return response;
}
}
访问接口 localhost:8899/ai/generate?message=你好 即可看到返回结果。
3. 聊天模型详解 Spring AI 提供了便捷的聊天模型 API,支持无缝集成大语言模型。
3.1 ChatClient 接口 ChatClient 是定义与聊天服务交互的核心接口,用于创建客户端对象、设置请求规范及发起请求。
3.1.1 简单对话 通过 ChatClient.Builder 注入客户端,使用链式调用发送用户消息:
@GetMapping("/chat")
public String chat (@RequestParam(value = "message", defaultValue = "你是谁") String message) {
return this .chatClient.prompt()
.user(message)
.call()
.content();
}
3.1.2 角色预设 可以通过配置 Bean 为所有请求设置默认的系统提示词(System Prompt),例如设定 AI 的身份:
@Bean
public ChatClient chatClient (ChatClient.Builder builder) {
return builder.defaultSystem("你是 Java 开发专家,名字叫 AI 助手。" ).build();
}
3.1.3 流式响应 为了提升用户体验,特别是在模型推理较慢时,可以使用流式输出:
@GetMapping(value = "/chat/stream", produces = "text/html;charset=UTF-8")
public Flux<String> chatStream (@RequestParam(value = "message") String message) {
return chatClient.prompt().user(message).stream().content();
}
3.2 ChatModel 接口 ChatModel 定义了与 AI 模型交互的基本方法,ChatClient 底层即基于此接口。
3.2.1 基础用法 @GetMapping("/chatModel02")
public String chatModel02 (@RequestParam("message") String message) {
ChatResponse call = chatModel.call(new Prompt (
message,
OpenAiChatOptions.builder()
.model("deepseek-chat" )
.temperature(0.8 )
.build()
));
return call.getResult().getOutput().getContent();
}
3.2.2 提示词模板 Spring AI 提供了 Prompt Template 管理抽象,允许在运行时动态替换占位符:
String systemText = "你是一个美食咨询助手,你的名字是{name},你应该用{name}和{voice}的饮食习惯回复。" ;
SystemPromptTemplate systemPromptTemplate = new SystemPromptTemplate (systemText);
Message systemMessage = systemPromptTemplate.createMessage(Map.of("name" , "张三" , "voice" , "北京" ));
Prompt prompt = new Prompt (List.of(userMessage, systemMessage));
4. 函数调用 (Function Calling) 函数调用允许大模型在生成回答时触发预定义的外部函数,实现动态数据获取或业务逻辑操作。
4.1 核心流程
定义函数 :声明名称、描述及参数结构。
模型交互 :将函数信息发送给模型,模型决定是否需要调用。
执行函数 :解析请求并执行业务逻辑。
返回结果 :将执行结果反馈给模型生成最终回答。
4.2 实现示例 @Bean
@Description("加法运算")
public Function<AddOperation, Integer> addOperation () {
return request -> request.a + request.b;
}
@GetMapping("/function")
public String ragJsonText (@RequestParam(value = "message") String message) {
return ChatClient.builder(chatModel).build()
.prompt()
.system("您是算术计算器的代理..." )
.user(message)
.functions("addOperation" , "mulOperation" )
.call()
.content();
}
5. 本地模型部署 (Ollama) 对于隐私要求高或离线场景,可使用 Ollama 本地部署模型。
5.1 安装与配置 下载并安装 Ollama,设置环境变量 OLLAMA_MODELS 指定模型存储路径。拉取模型(如 deepseek-r1:1.5b)并启动服务。
5.2 代码集成 添加 spring-ai-ollama-spring-boot-starter 依赖,配置 base-url 指向本地服务:
spring.ai.ollama.base-url=http://localhost:11434
spring.ai.ollama.chat.options.model=deepseek-r1:1.5b
注入 OllamaChatModel 即可像使用云端模型一样调用。
6. Spring AI Alibaba 阿里云推出的 Spring AI 扩展,针对国内环境优化,支持通义千问等模型。
6.1 快速开始 申请阿里云百炼 API Key,引入 spring-ai-alibaba-starter 依赖。
<dependency >
<groupId > com.alibaba.cloud.ai</groupId >
<artifactId > spring-ai-alibaba-starter</artifactId >
<version > 1.0.0-M5.1</version >
</dependency >
配置中排除默认的 OpenAI 自动配置以避免冲突,并设置 DashScope API Key。
7. 其他模型能力 除了文本对话,Spring AI 还支持图像和语音生成。
7.1 图像模型 利用 ImageModel 接口实现文生图。通过 ImagePrompt 封装输入,ImageResponse 处理输出。可以指定模型、尺寸及生成数量。
7.2 语音模型 通过 SpeechSynthesisModel 实现文本转语音 (TTS),支持语速、音调、音量等参数配置,可将文字内容转化为音频文件。
8. RAG (检索增强生成) RAG 结合检索系统与生成模型,解决大模型知识局限性和幻觉问题。
8.1 工作原理
向量化 :将文档转换为向量存入向量数据库。
检索 :根据用户问题向量检索相似片段。
上下文构建 :将检索到的片段与系统提示词组合。
生成 :LLM 基于上下文生成准确回答。
8.2 实现步骤 创建 VectorStore Bean,加载文档并初始化嵌入模型。在 Controller 中使用 QuestionAnswerAdvisor 关联向量库:
@GetMapping("/rag/chat")
public String generation (@RequestParam("userInput") String userInput) {
return dashScopeChatClient.prompt()
.user(userInput)
.advisors(new QuestionAnswerAdvisor (vectorStore))
.call()
.content();
}
9. 综合案例:智能简历筛选
知识库构建 :将候选人简历文本切分并向量化存储。
工具定义 :创建查询岗位匹配度的 Function。
人设设定 :在 System Prompt 中明确助手角色、指导原则及限制。
应用串联 :在 Controller 中检索简历信息,结合工具返回结果生成专业建议。
通过上述步骤,即可完成一个具备上下文理解能力的智能应用原型。
相关免费在线工具 Keycode 信息 查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具,Keycode 信息在线工具,online
Escape 与 Native 编解码 JavaScript 字符串转义/反转义;Java 风格 \uXXXX(Native2Ascii)编码与解码。 在线工具,Escape 与 Native 编解码在线工具,online
JavaScript / HTML 格式化 使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具,JavaScript / HTML 格式化在线工具,online
JavaScript 压缩与混淆 Terser 压缩、变量名混淆,或 javascript-obfuscator 高强度混淆(体积会增大)。 在线工具,JavaScript 压缩与混淆在线工具,online
加密/解密文本 使用加密算法(如AES、TripleDES、Rabbit或RC4)加密和解密文本明文。 在线工具,加密/解密文本在线工具,online
RSA密钥对生成器 生成新的随机RSA私钥和公钥pem证书。 在线工具,RSA密钥对生成器在线工具,online