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

在 application.yml 中配置 API 密钥：

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

配置说明：

• base-url：连接地址
• api-key：API 密钥
• model：使用的 LLM 模型
• temperature：控制随机性。低温（接近 0.0）保守确定，高温（接近 2.0）多样富有想象力。不建议同时修改 temperature 和 top_p。

接口编写

完成配置后，编写控制器调用模型：

@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=你是谁 测试。

核心接口

Spring AI 构建对话式 AI 应用主要依赖两个核心接口：ChatModel 和 ChatClient。

ChatModel

ChatModel 直接与底层 AI 模型通信，处理原始请求和响应，更底层且灵活。

@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，简化常见使用模式，更高级简洁。

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

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

对比总结：

消息类型

所有消息类型都实现了 Message 接口，模拟多轮对话中的不同参与者。

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()
            .content();
    }
}

通过 defaultSystem 设置默认系统消息，作为对话的初始指令注入上下文。

UserMessage & AssistantMessage

UserMessage 代表具体问题，AssistantMessage 是 AI 回复。实现连贯多轮对话的关键是将 AI 回复保存为 AssistantMessage，并在下次请求时作为历史上下文发送。

输出格式

结构化输出

Spring AI 支持将模型输出转化为自定义实体。通过 entity() 方法指定返回类型。

@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) {}

流式输出

传统输出等待全部生成完成后一次性返回，流式输出则边生成边返回，类似打电话体验。

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

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

由于 HTTP 协议无状态，无法主动推送，我们通过 SSE（Server-Sent Events）实现服务器向浏览器推送数据流。

SSE 协议介绍

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

核心特点：

1. 单向通信：仅服务器推送到客户端。
2. 基于 HTTP/HTTPS：穿越防火墙无需特殊配置。
3. 长连接：保持连接打开，持续发送数据。
4. 文本数据流：遵循特定格式的文本流。
5. 自动重连：断开后浏览器自动尝试重连。

SSE 数据格式

需设置 HTTP 头：Content-Type: text/event-stream;charset=utf-8。

每条消息由字段名、冒号、空格和值组成，以空行结束。常见字段：

• data：消息主体，承载实际内容。
• event：事件类型，用于分类处理。
• id：唯一 ID，用于断点续传。
• retry：建议重连等待时间（毫秒）。

示例：

data: 这是一条简单的消息


event: foo
data: Hello World

id: msg-123
data: 重要消息

retry: 10000

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++) {
            String s = "event: foo\n";
            s += "data: " + new Date() + "\n\n";
            writer.write(s);
            writer.flush();
            Thread.sleep(1000L);
        }
        writer.write("event: end\ndata: EOF\n\n");
        writer.flush();
    }
}

前端实现：

<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>

在 Spring 中，可通过 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.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 创建
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);
// 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);

过滤操作：

// 3.1 filter - 条件过滤
Flux<Integer> allNumbers = Flux.range(1, 10);
Flux<Integer> evenNumbers = allNumbers.filter(n -> n % 2 == 0);
// 3.2 distinct - 去重
Flux<String> withDuplicates = Flux.just("A", "B", "A", "C");
Flux<String> uniqueItems = withDuplicates.distinct();
// 3.3 take - 取前 N 个
Flux<String> limited = original.take(2);
// 3.4 skip - 跳过前 N 个
Flux<String> skipped = original.skip(1);
// 3.5 takeWhile / skipWhile
Flux<Integer> sequence = Flux.range(1, 100);
Flux<Integer> firstPart = sequence.takeWhile(n -> n < 10);
// 3.6 sample - 采样
Flux<Long> sampled = Flux.interval(Duration.ofMillis(100))
    .sample(Duration.ofSeconds(1))
    .take(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
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.hasElements();
// 4.7 then
Mono<Void> completionSignal = data.then();

Advisors

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

介入时机：

• Before Call：请求发送到模型之前，常用于修改提示词。
• After Call：收到响应后、返回给客户端之前。

执行流程：用户输入 → Advisor1.before() → ... → AI 模型调用 → ... → Advisor1.after() → 最终响应。

Spring AI 内置了 SimpleLoggerAdvisor，用于记录聊天请求和响应。

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

    public ChatClientController(ChatClient.Builder chatClientBuilder) {
        this.chatClient = chatClientBuilder
            .defaultSystem("你叫小小鱼，是一款专业的智能答疑 AI 助手")
            .build();
    }

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

配置日志级别为 debug 观察：

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

即可看到详细的请求和响应日志。