Spring AI Alibaba 快速入门指南

Spring AI Alibaba 简介

Spring AI Alibaba（SAA）是一款以 Spring AI 为基础，深度集成百炼平台，支持 ChatBot、工作流、多智能体应用开发模式的 AI 框架。

Spring AI 和 Spring AI Alibaba 是生态关联但定位、范围、主导方完全不同的两个技术体系，核心区别在于是否为官方生态、覆盖范围、适配场景。

一、核心定位与主导方

维度	Spring AI	Spring AI Alibaba
官方属性	Spring 官方生态项目	阿里云基于 Spring AI 扩展的第三方适配方案
核心定位	通用 AI 应用开发框架	阿里云 AI 服务的 Spring 生态集成方案
主导团队	Spring 社区	阿里云技术团队
生态归属	Spring 官方核心生态	阿里云开源生态

二、覆盖范围与适配能力

1. Spring AI：通用抽象 + 多厂商适配

Spring AI 的核心目标是屏蔽不同 AI 厂商的接口差异，提供一套统一的 Java API，让开发者无需修改代码即可切换不同 AI 服务。

• 适配的 AI 厂商/服务：大模型（OpenAI、Anthropic、Google Gemini 等）、向量存储（Redis、Milvus 等）、其他云厂商 AI 平台。
• 核心能力：通用 LLM 调用、函数调用、向量检索、AI 流式响应、提示词模板、AI 工作流等。
• 适用场景：需要跨 AI 厂商适配、追求技术中立性的通用 AI 应用。

2. Spring AI Alibaba：阿里云专属适配

Spring AI Alibaba 并非独立框架，而是基于 Spring AI 的官方接口，为阿里云 AI 产品提供的专属适配器。

• 适配的 AI 服务：通义千问、通义视觉、通义听悟、阿里云向量数据库等。
• 核心能力：复用 Spring AI 的统一 API，快速接入阿里云 AI 服务，补充阿里云专属特性（如 AK/SK 鉴权、地域路由）。
• 适用场景：已使用阿里云生态且需要接入阿里云 AI 产品的 Spring 应用。

三、技术架构与依赖关系

• 依赖关系：Spring AI Alibaba 必须依赖 Spring AI 的核心包，本质是 Spring AI 的厂商适配模块。
• 独立性：Spring AI 可独立使用；Spring AI Alibaba 不能独立使用，必须搭配 Spring AI 核心依赖。

四、关键差异总结表

对比维度	Spring AI	Spring AI Alibaba
官方属性	Spring 官方项目	阿里云第三方适配方案
覆盖范围	多厂商 AI 服务 + 开源 AI 组件	仅阿里云 AI 服务
核心价值	统一 AI 编程接口，技术中立	简化阿里云 AI 服务接入
依赖关系	可独立使用	必须依赖 Spring AI 核心包
适用场景	跨厂商 AI 适配、开源 AI 项目	阿里云生态用户

对于国内 Java 程序员来说，使用 Spring AI Alibaba 上手比较容易，申请一个阿里云百炼的 Key 就可以进行测试。

申请阿里云百炼 Api Key

访问阿里云百炼平台控制台，使用账号登录后，选择 模型服务 里面的 密钥管理。

创建 API Key，该 Key 将在后续开发中频繁使用。

项目搭建

项目结构

采用 Maven 多模块结构。

父 pom 文件

在父 pom 文件中做项目依赖包的版本管理。

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>org.demo.ai</groupId>
    <artifactId>spring-ai-alibaba</artifactId>
    <version>${revision}</version>
    <packaging>pom</packaging>
    <description>Spring AI Alibaba Examples</description>
    <properties>
        <revision>1.0.0</revision>
        <java.version>17</java.version>
        <spring-ai.version>1.0.0</spring-ai.version>
        <spring-ai-alibaba.version>1.0.0.3</spring-ai-alibaba.version>
        <spring-boot.version>3.5.5</spring-boot.version>
    </properties>
    <modules>
        <module>boot-ai-helloworld</module>
    </modules>
    <dependencyManagement>
        <dependencies>
            <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>
            <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>
        </dependencies>
    </dependencyManagement>
    <repositories>
        <repository>
            <id>aliyunmaven</id>
            <name>aliyun</name>
            <url>https://maven.aliyun.com/repository/public</url>
        </repository>
    </repositories>
</project>

子模块 boot-ai-helloworld

子 pom 文件

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.demo.ai</groupId>
        <artifactId>spring-ai-alibaba</artifactId>
        <version>${revision}</version>
        <relativePath>../pom.xml</relativePath>
    </parent>
    <artifactId>boot-ai-helloworld</artifactId>
    <version>${revision}</version>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>com.alibaba.cloud.ai</groupId>
            <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
        </dependency>
    </dependencies>
</project>

配置文件

server:
  port: 18080
spring:
  application:
    name: spring-ai-alibaba-helloworld
  ai:
    dashscope:
      api-key: {替换成阿里云百炼上的 API Key}

启动类

package org.demo.ai.bailian;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class BailianAgentApplication {
    public static void main(String[] args) {
        SpringApplication.run(BailianAgentApplication.class, args);
    }
}

Controller 层

使用 ChatClient 类与大模型交互。

package org.demo.ai.bailian.controller;

import com.alibaba.cloud.ai.dashscope.chat.DashScopeChatOptions;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.client.advisor.MessageChatMemoryAdvisor;
import org.springframework.ai.chat.client.advisor.SimpleLoggerAdvisor;
import org.springframework.ai.chat.memory.ChatMemory;
import org.springframework.ai.chat.memory.MessageWindowChatMemory;
import org.springframework.web.bind.annotation.*;
import reactor.core.publisher.Flux;

@RestController
@RequestMapping("/helloworld")
public class HelloworldController {

    private static final String DEFAULT_PROMPT = "你是一个博学的智能聊天助手，请根据用户提问回答！";
    private final ChatClient dashScopeChatClient;

    public HelloworldController(ChatClient.Builder chatClientBuilder) {
        this.dashScopeChatClient = chatClientBuilder
                .defaultSystem(DEFAULT_PROMPT)
                .defaultAdvisors(MessageChatMemoryAdvisor.builder(MessageWindowChatMemory.builder().build()).build())
                .defaultAdvisors(new SimpleLoggerAdvisor())
                .defaultOptions(DashScopeChatOptions.builder().withTopP(0.7).build())
                .build();
    }

    /**
     * ChatClient 简单调用
     */
    @GetMapping("/simple/chat")
    public String simpleChat(@RequestParam(value = "query", defaultValue = "你好") String query) {
        return dashScopeChatClient.prompt(query).call().content();
    }

    /**
     * ChatClient 流式调用
     */
    @GetMapping("/stream/chat")
    public Flux<String> streamChat(@RequestParam(value = "query", defaultValue = "你好") String query,
                                   HttpServletResponse response) {
        response.setCharacterEncoding("UTF-8");
        return dashScopeChatClient.prompt(query).stream().content();
    }

    /**
     * ChatClient 使用自定义的 Advisor 实现功能增强
     */
    @GetMapping("/advisor/chat/{conversationId}")
    public Flux<String> advisorChat(HttpServletResponse response,
                                    @PathVariable String conversationId,
                                    @RequestParam String query) {
        response.setCharacterEncoding("UTF-8");
        return this.dashScopeChatClient
                .prompt(query)
                .advisors(a -> a.param(ChatMemory.CONVERSATION_ID, conversationId))
                .stream()
                .content();
    }
}

测试

测试一：访问简单 chat

访问链接：/helloworld/simple/chat

测试二：访问流式输出

访问链接：/helloworld/stream/chat

测试三：带有记忆的输出

1. 先访问：/helloworld/advisor/chat/123?query=你好，我叫 jack
2. 再访问：/helloworld/advisor/chat/123?query=我叫什么名字？

通过设置 conversationId 参数，将对话历史记录存储到 ChatMemory 中，后续对话会将之前的历史记录作为上下文。