Spring AI 实战指南：从基础概念到流式输出

Spring AI 提供了作为开发 AI 应用基础的抽象。这些抽象具有多种实现，可以通过最少的代码更改轻松实现组件切换。

Spring AI 提供了一系列强大而实用的功能，使其成为一个功能完备的 AI 应用开发框架：

1. 统一的多模型支持：支持与众多主流的 AI 模型提供商进行交互，包括 OpenAI、Microsoft、Amazon、Google 和 Anthropic 等，无论是云端模型还是本地部署的模型（如通过 Ollama），都能通过一致的接口进行调用。

2. 强大的数据集成能力：这是 Spring AI 的一大亮点。它内置了对向量数据库（如 Chroma、Pinecone、Redis 等）的支持。

3. 与 Spring 生态无缝集成：作为 Spring 大家庭的一员，它能自然地与 Spring Boot、Spring Data 等其他知名项目协同工作。

4. 简化的开发模式：允许 AI 模型根据需要请求执行客户端定义的函数，从而接入实时信息或触发具体动作。

了解了相关概念后，我们就来上手体验一下 Spring AI。

快速入门

环境要求

**JDK 版本：**JDK 17 或以上（推荐 JDK 21），这是强制要求，因为 Spring Boot 3.x 本身就需要 JDK 17+。

**Spring Boot 版本：**Spring Boot 3.2 或以上，具体版本可以是 3.3.3、3.4.3 或 3.5.0，选择一个稳定的 3.x 最新版本即可。

**AI 服务凭证：**有效的 API Key，需要一个来自 AI 服务提供商（如 OpenAI、DeepSeek、阿里百炼等）的账户和 API Key。

在本篇文章中，我们以 DeepSeek 作为示例来进行学习。

申请 API Key

我们访问 DeepSeek 官网：DeepSeek | 深度求索

进入 API 开放平台：

创建 API Key：

点击创建之后输入名称即可完成创建，但需要注意的是 API key 仅在创建时可见可复制。

然后需要进行充值（充值前需要进行实名认证）：

只是学习使用，1 块就够了。

项目创建

Spring AI 专门为 OpenAI 及兼容 API 服务设计了 spring-ai-openai-spring-boot-starter，用于快速集成大模型语言能力到 Spring Boot 应用中：

正常创建 Maven 项目（注意 JDK 和 Spring Boot 版本），并添加 Spring AI 依赖：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
    <version>1.0.0-M6</version>
</dependency>

依赖版本可参考：https://docs.spring.io/spring-ai/reference/getting-started.html

在 application.yml 中配置 API 密钥：

spring:
  ai:
    openai:
      # DeepSeek
      api-key: 申请的 API Key
      base-url: https://api.deepseek.com
      chat:
        options:
          model: deepseek-chat
          temperature: 0.7

其中：

spring.ai.openai.base-url：要连接的 URL。

spring.ai.openai.api-key：申请的 DeepSeek API 密钥。

spring.ai.openai.chat.options.model：要使用的 DeepSeek LLM 模型。

spring.ai.openai.chat.options.temperature：用于控制模型生成文本的随机性和创造性：低温（接近 0.0）→ 保守、确定、可预测；高温（接近 2.0）→ 冒险、多样、富有想象力。也就是说，temperature 值越低，相同的提问得到的结果越类似。此外，不建议在同一个补全请求中同时修改 temperature 和 top_p，因为这两个设置的交互作用难以预测。

配置项可参考：https://docs.spring.io/spring-ai/reference/api/chat/deepseek-chat.html

此时，就已经完成了项目的创建和 DeepSeek 的接入，接下来，我们通过编写接口来调用模型。

接口编写

@RestController
@RequestMapping("/deepseek")
public class DeepSeekChatController {
    @Autowired
    private OpenAiChatModel deepSeekChatModel;

    @GetMapping("/chat")
    public String generate(String message) {
        return deepSeekChatModel.call(message);
    }
}

运行，并访问 http://127.0.0.1:8080/deepseek/chat?message=你是谁 进行测试。

上述，我们通过 ChatModel 完成了与模型的交互。

而在 Spring AI 框架中，ChatModel 和 ChatClient 是构建对话式 AI 应用的两大核心接口，接下来，我们分别来看这两个接口。

核心接口

ChatModel

ChatModel 直接与底层 AI 模型（如 GPT-4、Claude 等）通信，处理原始的请求和响应。

因此，ChatModel 更底层，使用更灵活。

@Service
public class ChatService {
    @Autowired
    private ChatModel chatModel; // 例如 OpenAiChatModel

    public String askQuestion(String question) {
        // 1. 构造消息
        UserMessage userMessage = new UserMessage(question);
        // 2. 创建 Prompt
        Prompt prompt = new Prompt(List.of(userMessage));
        // 3. 调用并获得完整响应
        ChatResponse response = chatModel.call(prompt);
        // 4. 从响应中提取内容
        return response.getResult().getOutput().getContent();
    }
}

ChatClient

ChatClient 在 ChatModel 之上提供了一层流畅的 API，简化了常见的使用模式。

即 ChatClient 是对 ChatModel 的一层包装。

因此，ChatClient 更高级，也更简洁。

@Service
public class ChatService {
    @Autowired
    private ChatClient chatClient;

    public String askQuestion(String question) {
        // 一行搞定
        return chatClient.call(question);
    }
}

可以看到，ChatClient 的使用更加简洁直观。

ChatModel 与 ChatClient 对比：

消息类型

在 Spring AI 中，所有消息类型都实现了 org.springframework.ai.chat.messages.Message 接口，系统中的消息被设计用来模拟一个多轮对话中的不同参与者。

其中，最常使用的是 SystemMessage、UserMessage 和 AssistantMessage。

SystemMessage

SystemMessage 通常用于设定 AI 助手的身份、性格、行为准则和对话规则，一般位于对话的开头，为整个对话设定基调。

例如，我们可以为其进行角色预设：

@RequestMapping("/chat")
@RestController
public class ChatClientController {
    private ChatClient chatClient;

    public ChatClientController(ChatClient.Builder chatClientBuilder) {
        this.chatClient = chatClientBuilder
                .defaultSystem("你叫小小鱼，是一款专业的智能答疑 AI 助手，擅长 Java 和 Python，以友好的态度来回答问题")
                .build();
    }

    @GetMapping("/call")
    public String generation(String userInput) {
        return this.chatClient.prompt()
                .user(userInput) // 用户输入
                .call() // 调用 API
                .content(); // 返回响应
    }
}

在 ChatClient 中，通过 defaultSystem 来设置 AI 模型的默认系统消息，通过 ChatClient.Builder 链式调用设置的系统消息会作为对话的'初始指令'，注入到每次对话的上下文中，引导 AI 的回复风格或身份设定。

此时，我们访问接口，再次询问其身份：

UserMessage

UserMessage 表示我们提出的具体问题或指令，上述输入的 "你是谁"，就是 UserMessage。

AssistantMessage

AssistantMessage：是 AI 模型给出的回复。

AssistantMessage 是实现连贯多轮对话的关键。每次 AI 回复后，可以将这个回复作为 AssistantMessage 保存下来，并在下一次请求时将其作为历史上下文的一部分发送给 AI。

输出格式

结构化输出

若想要从 LLM 接收结构化输出，Spring AI 支持将 ChatModel/ChatClient 方法的返回类型从 Spring 更改为其他类型。

通过 entity() 方法将模型输出转化为自定义实体。

例如：

@RequestMapping("/chat")
@RestController
public class ChatClientController {
    private ChatClient chatClient;

    public ChatClientController(ChatClient.Builder chatClientBuilder) {
        this.chatClient = chatClientBuilder
                .build();
    }

    @GetMapping("/entity")
    public String entity(String userInput) {
        Recipe entity = this.chatClient.prompt()
                .user(String.format("请帮我生成%s的菜谱", userInput))
                .call()
                .entity(Recipe.class);
        return entity.toString();
    }

    record Recipe(String dis, List<String> ingredients) {}
}

流式输出

首先我们对比来看什么是流式输出：

**传统输出（非流式）：**等待全部生成完成后才一次性返回，用户长时间等待 → 突然显示完整答案。像寄送一封平信，写完所有内容才寄出，对方一次性收到整封信。

**流式输出：**边生成边返回，立即推送部分结果，几乎立即开始显示 → 逐字逐句增长。像打电话一样，对方一边说话，你一边就能听到。

流式输出过程：

用户提问："请写一篇关于春天的短文"

AI 模型生成过程：

"春天"... (立即返回)

"春天来了"... (继续返回)

"春天来了，万物复苏"... (持续返回)

直到生成完整回答

SSE 协议

Spring AI 主要通过响应式编程来实现流式输出，使用 stream() 方法生成 Flux 流。

@RequestMapping("/chat")
@RestController
public class ChatClientController {
    private ChatClient chatClient;

    public ChatClientController(ChatClient.Builder chatClientBuilder) {
        this.chatClient = chatClientBuilder
                .build();
    }

    @GetMapping(value = "/stream", produces = "text/html;charset=utf-8")
    public Flux<String> stream(String userInput) {
        return this.chatClient.prompt()
                .user(userInput)
                .stream()
                .content();
    }

    record Recipe(String dis, List<String> ingredients) {}
}

但是，我们思考这样一个问题：由于 HTTP 协议本身设计为无状态的请求 - 响应模式，也就是严格来说，无法做到服务器主动推送消息到客户端，那么我们要如何实现服务器的流式响应呢？

我们可以通过 SSE（Server-Sent Events，服务器发送事件）来实现流式传输，允许服务器主动向浏览器推送数据流。

SSE 协议介绍

SSE 是一种基于 HTTP 的轻量级实时通信协议，浏览器通过内置的 EventSource API 接收并处理这些实时事件。

服务器向客户端声明：接下来发送的是流消息（streaming），

此时客户端不会关闭连接，会一直等待服务器发送过来新的数据流。

SSE 核心特点：

1. 单向通信：数据流只能从服务器推送到客户端。客户端不能通过这个连接向服务器发送数据（除了最初的建立连接请求）。

2. 基于 HTTP/HTTPS：SSE 使用标准的 HTTP 协议，这意味着它可以轻松地穿越大多数防火墙和代理服务器，无需特殊的配置。

3. 长连接：客户端发起一个普通的 HTTP 请求，但服务器会保持这个连接处于打开状态，而不是在发送一次响应后就关闭它。

4. 文本数据流：服务器通过这个持久的连接，持续地向客户端发送遵循特定格式的文本数据流。

5. 自动重连：SSE 协议内建了重连机制。如果连接意外断开，浏览器会自动尝试重新连接到服务器。

SSE 数据格式

服务器向浏览器发送 SSE 数据，需要设置必须的 HTTP 头信息。

Content-Type: text/event-stream;charset=utf-8
Connection: keep-alive

整个数据流由一系列消息组成，每条消息（message）由一行或多行文本构成，每行文本以一个字段名开头，后跟一个冒号和一个空格，然后是字段的值，每条消息以一个空行（即两个连续的换行符 \n\n）结束。

每一行格式：[field]: value\n

field 的常见取值有：data、event、id、retry。

data

data：消息主体，是最重要的字段，用于承载消息的实际内容，如果一个消息包含多个 data 行，客户端会将它们用换行符 (\n) 连接起来，形成一个完整的数据字符串。可用于传递 JSON 字符串、纯文本、XML 等任何文本数据。

示例：

data: 这是一条简单的消息\n\n

data: Hello\n data: World\n data: !\n\n

event

event：事件类型，用于指定消息的自定义类型，若提供了此字段，客户端将触发对该特定事件名的监听器；否则，将触发通用的 onmessage 事件，可用于对不同类型的消息进行分类处理。

示例：

event: userJoined data: Alice

id

id：事件 id，用于为消息设置一个唯一的 ID（字符串），如果连接中断，当客户端重新连接时，会在 HTTP 请求头 Last-Event-ID 中自动发送最后一个接收到的 ID。可以用于实现消息的幂等性和断点续传。

示例：

id: msg-123 data: 这是一条重要消息

retry

retry：重连时间，表示建议浏览器在连接断开后再次尝试连接之前应等待的毫秒数，由于这不是一个强制命令，浏览器可能会忽略它。用于避免在服务器出现故障时，客户端过于频繁地重试。

示例：告诉浏览器，如果连接失败，请等待 10 秒后再尝试重连。

retry: 10000

我们通过一个简单的示例来看 SSE 协议的使用。

SSE 使用示例

后端接口：

@Slf4j
@RequestMapping("/sse")
@RestController
public class SseController {
    @RequestMapping("/end")
    public void end(HttpServletResponse response) throws IOException, InterruptedException {
        log.info("发起请求：event");
        response.setContentType("text/event-stream;charset=utf-8");
        PrintWriter writer = response.getWriter();
        for (int i = 0; i < 10; i++) {
            // 事件 foo 事件
            String s = "event: foo\n";
            s += "data: " + new Date() + "\n\n";
            writer.write(s);
            writer.flush();
            Thread.sleep(1000L);
        }
        //定义 end 事件，表示当前流传输结束
        writer.write("event: end\ndata: EOF\n\n");
        writer.flush();
    }
}

前端实现：

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>SSE</title>
</head>
<body>
    <div></div>
    <script>
        let eventSource = new EventSource("/sse/end");
        eventSource.addEventListener("foo", function(event) {
            console.log(event);
            document.getElementById("sse").innerHTML = event.data;
        });
        eventSource.addEventListener("end", function(event) {
            console.log("连接关闭");
            eventSource.close();
        });
    </script>
</body>
</html>

运行，观察控制台打印的日志：

可以看到成功传输消息，并在消息传输完毕后关闭连接。

而在 Spring 中，可以通过 WebFlux 优雅地实现 SSE 协议，也就是我们之前使用的 Flux，它是 WebFlux 中的核心组件，我们来看 Flux 的使用和常见操作。

Flux

Flux 的使用流程：创建 → 转换 → 过滤 → 消费。

创建 Flux：

import reactor.core.publisher.Flux;
// 1.1 从固定值创建
Flux<String> fixedFlux = Flux.just("Hello", "World", "!");
// 1.2 从集合创建
List<String> list = Arrays.asList("A", "B", "C");
Flux<String> fromCollection = Flux.fromIterable(list);
// 1.3 数值范围
Flux<Integer> rangeFlux = Flux.range(1, 5); // 1,2,3,4,5
// 1.4 动态生成
Flux<Long> intervalFlux = Flux.interval(Duration.ofSeconds(1)).take(5);
// 1.5 从数组创建
Flux<String> arrayFlux = Flux.fromArray(new String[]{"X", "Y", "Z"});
// 1.6 空流
Flux<String> emptyFlux = Flux.empty();
// 1.7 从 Future 创建（适配传统异步 API）
CompletableFuture<String> future = CompletableFuture.supplyAsync(() -> "Result");
Flux<String> futureFlux = Flux.fromFuture(future);

转化操作：

// 2.1 map - 一对一转换
Flux<String> original = Flux.just("apple", "banana", "cherry");
Flux<String> uppercased = original.map(String::toUpperCase); // APPLE, BANANA, CHERRY
// 2.2 flatMap - 一对多转换（异步展平）
Flux<String> words = Flux.just("hello world", "spring ai");
Flux<String> splitWords = words.flatMap(word -> Flux.fromArray(word.split(" ")));
// 2.3 cast - 类型转换
Flux<Object> objects = Flux.just("text1", "text2");
Flux<String> strings = objects.cast(String.class);
// 2.4 scan - 累积计算
Flux<Integer> numbers = Flux.range(1, 4);
Flux<Integer> cumulativeSum = numbers.scan((acc, current) -> acc + current); // 1,3,6,10

过滤操作：

// 3.1 filter - 条件过滤
Flux<Integer> allNumbers = Flux.range(1, 10);
Flux<Integer> evenNumbers = allNumbers.filter(n -> n % 2 == 0); // 2,4,6,8,10
// 3.2 distinct - 去重
Flux<String> withDuplicates = Flux.just("A", "B", "A", "C");
Flux<String> uniqueItems = withDuplicates.distinct(); // A,B,C
// 3.3 take - 取前 N 个
Flux<String> limited = original.take(2); // apple, banana
// 3.4 skip - 跳过前 N 个
Flux<String> skipped = original.skip(1); // banana, cherry
// 3.5 takeWhile / skipWhile - 条件取/跳
Flux<Integer> sequence = Flux.range(1, 100);
Flux<Integer> firstPart = sequence.takeWhile(n -> n < 10); // 1,2,3,...,9
// 3.6 sample - 采样（定期取最新元素）
Flux<Long> sampled = Flux.interval(Duration.ofMillis(100))
        .sample(Duration.ofSeconds(1))
        .take(3); // 每隔 1 秒取样，共取 3 次

消费操作：

// 4.1 subscribe - 最基本的消费方式
Flux<String> data = Flux.just("one", "two", "three");
data.subscribe(
    item -> System.out.println("Received: " + item),
    error -> System.err.println("Error: " + error),
    () -> System.out.println("Completed!")
);
// 4.2 collectList - 收集所有元素到 List
Mono<List<String>> listMono = data.collectList();
// 4.3 blockFirst / blockLast - 阻塞获取（仅用于测试）
// String first = data.blockFirst();
// 4.4 reduce - 归约操作
Mono<Integer> sum = numbers.reduce(0, Integer::sum);
// 4.5 count - 计数
Mono<Long> count = data.count();
// 4.6 hasElement - 检查是否有元素
Mono<Boolean> hasData = data.hasElement();
// 4.7 then - 忽略元素，只在完成后触发
Mono<Void> completionSignal = data.then();

Advisors

Advisors 是 Spring AI 中的一种拦截器机制，允许我们在 AI 调用链的特定节点注入自定义逻辑。

Advisors 在两个关键的时机点介入：

**Before Call（调用前）：**在请求发送到 AI 模型之前执行，主要用于修改提示词。

**After Call（调用后）：**在收到 AI 响应后、返回给客户端之前执行。

其执行流程为：

用户输入 → Advisor1.before() → Advisor2.before() → AI 模型调用 → Advisor2.after() → Advisor1.after() → 最终响应

在 Spring AI 中内置了一些 Advisors，如 SimpleLoggerAdvisor，其主要功能是进行日志记录，只需要将其添加到 Advisor 链中，就可以自动记录 Advisor 的聊天请求和响应：

@RequestMapping("/chat")
@RestController
public class ChatClientController {
    private ChatClient chatClient;

    public ChatClientController(ChatClient.Builder chatClientBuilder) {
        this.chatClient = chatClientBuilder
                .defaultSystem("你叫小小鱼，是一款专业的智能答疑 AI 助手，擅长 Java 和 Python，以友好的态度来回答问题")
                .build();
    }

    @GetMapping("/advisor")
    public String advisor(String userInput) {
        return this.chatClient.prompt()
                .advisors(new SimpleLoggerAdvisor())
                .user(userInput)
                .call()
                .content();
    }

    record Recipe(String dis, List<String> ingredients) {}
}

我们将日志级别配置为 debug 来观察：

logging:
  level:
    org.springframework.ai.chat.client.advisor: debug

观察打印的日志内容：

成功打印了对应的请求和响应日志。