Spring AI Alibaba 快速入门与核心功能解析
Spring AI Alibaba 框架的快速入门方法,涵盖 DashScope 模型配置、Ollama 本地部署、ChatModel 与 ChatClient 使用、流式输出、多模型共存、提示词工程、RAG 检索增强生成、工具调用及 MCP 协议等内容。通过代码示例展示了如何在 Java 应用中集成阿里云百炼平台能力,实现文本对话、文生图、语音合成及向量数据库交互,为企业级 AI 应用开发提供实践参考。

Spring AI Alibaba 框架的快速入门方法,涵盖 DashScope 模型配置、Ollama 本地部署、ChatModel 与 ChatClient 使用、流式输出、多模型共存、提示词工程、RAG 检索增强生成、工具调用及 MCP 协议等内容。通过代码示例展示了如何在 Java 应用中集成阿里云百炼平台能力,实现文本对话、文生图、语音合成及向量数据库交互,为企业级 AI 应用开发提供实践参考。

Spring AI Alibaba 开源项目基于 Spring AI 构建,是阿里云通义系列模型及服务在 Java AI 应用开发领域的最佳实践,提供高层次的 AI API 抽象与云原生基础设施集成方案和企业级 AI 应用生态集成。
官网地址:Spring AI Alibaba
阿里云百炼平台:大模型服务平台百炼控制台
Spring AI Alibaba 继承了 Spring AI 的所有原子能力抽象并在此基础上扩充丰富了模型、向量存储、记忆、RAG 等核心组件适配,让其能够接入阿里云的 AI 生态。所有调用均基于 OpenAI 协议标准或者 Spring AI Alibaba 官方推荐模型服务灵积 (DashScope) 整合规则,实现一致的接口设计与规范,确保多模型切换的便利性。
依赖配置 (pom.xml)
<properties>
<spring-ai.version>1.0.0</spring-ai.version>
<spring-ai-alibaba.version>1.0.0.2</spring-ai-alibaba.version>
<spring-boot.version>3.4.5</spring-boot.version>
</properties>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>com.alibaba.cloud.ai</groupId>
<artifactId>spring-ai-alibaba-bom</artifactId>
<version>${spring-ai-alibaba.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-dependencies</artifactId>
<version>${spring-boot.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-bom</artifactId>
<version>${spring-ai.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>com.alibaba.cloud.ai</groupId>
<artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
</dependency>
</dependencies>
配置文件 (application.yml)
server.port: 8001
server.servlet.encoding.enabled: true
server.servlet.encoding.force: true
server.servlet.encoding.charset: UTF-8
spring.application.name: SAA-01HelloWorld
# ====SpringAIAlibaba Config=============
spring.ai.dashscope.api-key: ${ALIYUN_API_KEY}
注意:ApiKey 不应明文配置,建议配置进环境变量。
ChatModel 是底层接口,直接与具体大语言模型交互,提供 call() 和 stream() 方法,适合简单大模型交互场景。
ChatClient 是高级封装,基于 ChatModel 构建,适合快速构建标准化复杂 AI 服务,支持同步和流式交互,集成多种高级功能。
配置示例
@Configuration
public class SaaLLMConfig {
@Value("${spring.ai.dashscope.api-key}")
private String apiKey;
@Bean
public DashScopeApi dashScopeApi() {
return DashScopeApi.builder().apiKey(apiKey).build();
}
@Bean
public ChatClient chatClient(@Qualifier("dashscopeChatModel") ChatModel dashScopeChatModel) {
return ChatClient.builder(dashScopeChatModel).build();
}
}
Controller 调用示例
@RestController
public class ChatHelloController {
@Resource
private ChatModel chatModel;
@GetMapping(value = "/hello/dochat")
public String doChat(@RequestParam(name = "msg", defaultValue = "你是谁") String msg) {
String result = chatModel.call(msg);
return result;
}
@GetMapping(value = "/hello/streamchat")
public Flux<String> stream(@RequestParam(name = "msg", defaultValue = "你是谁") String msg) {
return chatModel.stream(msg);
}
}
为保护企业数据隐私,可使用 Ollama 将大模型拉取到本地进行调用。
安装验证
ollama --version
ollama run qwen:4b
# 退出:/bye
引入依赖
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-ollama</artifactId>
<version>1.0.0</version>
</dependency>
配置
spring.ai.ollama.base-url: http://localhost:11434
spring.ai.ollama.chat.options.model: qwen3:latest
流式输出是一种逐步返回大模型生成结果的技术,允许服务器将响应内容分批次实时传输给客户端。SSE (Server-Sent Events) 是一种让服务器能够主动、持续地向客户端推送数据的技术。
通过修改配置文件和配置类,可以主动指定不同的模型选项,实现一套系统多模型共存。
@Configuration
public class SaaLLMConfig {
private final String DEEPSEEK_MODEL = "deepseek-v3";
private final String QWEN_MODEL = "qwen-max";
@Bean(name = "deepseek")
public ChatModel deepSeek() {
return DashScopeChatModel.builder()
.dashScopeApi(DashScopeApi.builder().apiKey(System.getenv("aliQwen-api")).build())
.defaultOptions(DashScopeChatOptions.builder().withModel(DEEPSEEK_MODEL).build())
.build();
}
@Bean(name = "qwen")
public ChatModel qwen() {
return DashScopeChatModel.builder()
.dashScopeApi(DashScopeApi.builder().apiKey(System.getenv("aliQwen-api")).build())
.defaultOptions(DashScopeChatOptions.builder().withModel(QWEN_MODEL).build())
.build();
}
}
Prompt 是引导 AI 模型生成特定输出的输入格式。Prompt Template 允许引入占位符以动态插入内容。
PromptTemplate 使用示例
@GetMapping("/prompttemplate/chat")
public Flux<String> chat(String topic, String output_format, String wordCount) {
PromptTemplate promptTemplate = new PromptTemplate(
"讲一个关于{topic}的故事并以{output_format}格式输出,字数在{wordCount}左右"
);
Prompt prompt = promptTemplate.create(Map.of(
"topic", topic,
"output_format", output_format,
"wordCount", wordCount
));
return deepseekChatClient.prompt(prompt).stream().content();
}
期望将模型输出转换为 Record 记录类结构体,不再是传统的 String。
@GetMapping("/structuredoutput/chat")
public StudentRecord chat(@RequestParam(name = "sname") String sname, @RequestParam(name = "email") String email) {
return qwenChatClient.prompt().user(new Consumer<ChatClient.PromptUserSpec>() {
@Override
public void accept(ChatClient.PromptUserSpec promptUserSpec) {
promptUserSpec.text("学号 1001,我叫{sname},大学专业计算机科学与技术,邮箱{email}")
.param("sname", sname)
.param("email", email);
}
}).call().entity(StudentRecord.class);
}
Spring AI Alibaba 中的聊天记忆提供了维护 AI 聊天应用程序的对话上下文和历史的机制。需将历史对话信息持久化(如存入 Redis)。
Redis 配置
<dependency>
<groupId>com.alibaba.cloud.ai</groupId>
<artifactId>spring-ai-alibaba-starter-memory-redis</artifactId>
</dependency>
spring.data.redis.host: localhost
spring.data.redis.port: 6379
文生图
public static final String IMAGE_MODEL = "wanx2.1-t2i-turbo";
@Resource
private ImageModel imageModel;
@GetMapping(value = "/t2i/image")
public String image(@RequestParam(name = "prompt", defaultValue = "刺猬") String prompt) {
return imageModel.call(
new ImagePrompt(prompt, DashScopeImageOptions.builder().withModel(IMAGE_MODEL).build())
).getResult().getOutput().getUrl();
}
文生音
@RestController
public class Text2VoiceController {
@Resource
private SpeechSynthesisModel speechSynthesisModel;
public static final String BAILIAN_VOICE_MODEL = "cosyvoice-v2";
public static final String BAILIAN_VOICE_TIMBER = "longyingcui";
@GetMapping("/t2v/voice")
public String voice(@RequestParam(name = "msg", defaultValue = "温馨提醒,支付宝到账 100 元请注意查收") String msg) {
String filePath = "d:\\" + UUID.randomUUID() + ".mp3";
DashScopeSpeechSynthesisOptions options = DashScopeSpeechSynthesisOptions.builder()
.model(BAILIAN_VOICE_MODEL)
.voice(BAILIAN_VOICE_TIMBER)
.build();
SpeechSynthesisResponse response = speechSynthesisModel.call(new SpeechSynthesisPrompt(msg, options));
ByteBuffer byteBuffer = response.getResult().getOutput().getAudio();
try (FileOutputStream fileOutputStream = new FileOutputStream(filePath)) {
fileOutputStream.write(byteBuffer.array());
} (Exception e) {
System.out.println(e.getMessage());
}
filePath;
}
}
向量化是将文本、图像和视频转换为浮点数数组。向量数据库专门用于存储、管理和检索向量数据。
使用 Redis Stack 作为演示
spring.ai.vectorstore.redis.initialize-schema: true
spring.ai.vectorstore.redis.index-name: custom-index
spring.ai.vectorstore.redis.prefix: custom-prefix
引入依赖
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-vector-store-redis</artifactId>
</dependency>
向量化操作
@GetMapping("/embed2vector/add")
public void add() {
List<Document> documents = List.of(
new Document("i study LLM"),
new Document("i love java")
);
vectorStore.add(documents);
}
@GetMapping("/embed2vector/get")
public List getAll(@RequestParam(name = "msg") String msg) {
SearchRequest searchRequest = SearchRequest.builder()
.query(msg)
.topK(2)
.build();
List<Document> list = vectorStore.similaritySearch(searchRequest);
return list;
}
RAG 技术通过引入外部知识源来增强 LLM 的输出能力,解决 LLM 知识非实时、私有领域知识缺失及幻觉问题。
流程:读取文件 -> 分段 -> 向量化(加入向量数据库)-> LLM 检索。
初始化知识库
@Configuration
public class InitVectorDatabaseConfig {
@Autowired
private VectorStore vectorStore;
@Autowired
private RedisTemplate<String, String> redisTemplate;
@Value("classpath:ops.txt")
private Resource opsFile;
@PostConstruct
public void init() {
TextReader textReader = new TextReader(opsFile);
textReader.setCharset(Charset.defaultCharset());
List<Document> list = new TokenTextSplitter().transform(textReader.read());
// 去重逻辑...
vectorStore.add(list);
}
}
RAG 检索
@GetMapping("/rag4aiops")
public Flux<String> rag(String msg) {
String systemInfo = "你是一个运维工程师,按照给出的编码给出对应故障解释,否则回复找不到信息。";
RetrievalAugmentationAdvisor advisor = RetrievalAugmentationAdvisor.builder()
.documentRetriever(VectorStoreDocumentRetriever.builder().vectorStore(vectorStore).build())
.build();
return chatClient.prompt()
.system(systemInfo)
.user(msg)
.advisors(advisor)
.stream()
.content();
}
Tool Calling 允许大模型与一组 API 或工具进行交互,将 LLM 的智能与外部工具无缝连接。
public class DateTimeTools {
@Tool(description = "获取当前时间", returnDirect = false)
public String getCurrentTime() {
return LocalDateTime.now().toString();
}
}
@GetMapping("/toolcall/chat2")
public Flux<String> chat2(@RequestParam(name = "msg", defaultValue = "你是谁现在几点") String msg) {
return chatClient.prompt(msg)
.tools(new DateTimeTools())
.stream()
.content();
}
MCP 提供了一种标准化的方式来连接 LLMs 需要的上下文,类似于 Agent 时代的 Type-C 协议,希望能将不同来源的数据、工具、服务统一起来供大模型调用。
MCP 服务端配置
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-mcp-server-webflux</artifactId>
</dependency>
spring.ai.mcp.server.type: async
spring.ai.mcp.server.name: customer-define-mcp-server
spring.ai.mcp.server.version: 1.0.0
暴露工具
@Configuration
public class McpServerConfig {
@Bean
public ToolCallbackProvider weatherTools(WeatherService weatherService) {
return MethodToolCallbackProvider.builder()
.toolObjects(weatherService)
.build();
}
}
MCP 客户端配置
spring.ai.mcp.client.type: async
spring.ai.mcp.client.request-timeout: 60s
spring.ai.mcp.client.toolcallback.enabled: true
spring.ai.mcp.client.sse.connections.mcp-server1.url: http://localhost:8014
网络调用示例
spring.ai.mcp.client.stdio.servers-configuration: classpath:/mcp-server.json5

微信公众号「极客日志」,在微信中扫描左侧二维码关注。展示文案:极客日志 zeeklog
查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具,Keycode 信息在线工具,online
JavaScript 字符串转义/反转义;Java 风格 \uXXXX(Native2Ascii)编码与解码。 在线工具,Escape 与 Native 编解码在线工具,online
使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具,JavaScript / HTML 格式化在线工具,online
Terser 压缩、变量名混淆,或 javascript-obfuscator 高强度混淆(体积会增大)。 在线工具,JavaScript 压缩与混淆在线工具,online
生成新的随机RSA私钥和公钥pem证书。 在线工具,RSA密钥对生成器在线工具,online
基于 Mermaid.js 实时预览流程图、时序图等图表,支持源码编辑与即时渲染。 在线工具,Mermaid 预览与可视化编辑在线工具,online