Spring AI 入门与实战：构建生成式 AI 应用

在 application.yml 中配置密钥：

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

其中 temperature 控制生成的随机性：低温更保守，高温更多样。

接口编写

创建一个简单的 Controller 来调用模型：

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

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

访问接口即可测试。接下来深入核心接口。

核心接口

ChatModel

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

@Service
public class ChatService {
    @Autowired
    private ChatModel chatModel;

    public String askQuestion(String question) {
        UserMessage userMessage = new UserMessage(question);
        Prompt prompt = new Prompt(List.of(userMessage));
        ChatResponse response = chatModel.call(prompt);
        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);
    }
}

消息类型

Spring AI 中的消息实现了 Message 接口，模拟多轮对话中的不同角色。

SystemMessage

用于设定 AI 的身份和行为准则，通常放在对话开头。

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

通过 defaultSystem 设置默认系统消息，引导 AI 的回复风格。

AssistantMessage

这是实现连贯多轮对话的关键。每次 AI 回复后，将其作为历史上下文的一部分发送，保持对话连续性。

输出格式

结构化输出

Spring AI 支持将 LLM 输出转化为自定义实体。使用 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 的轻量级实时通信协议。客户端发起请求后，服务器保持长连接，持续推送文本数据流。

核心特点：

• 单向通信：服务器推送到客户端。
• 基于 HTTP：易于穿越防火墙。
• 长连接：连接不关闭，持续传输。
• 自动重连：断线后浏览器会自动尝试重连。

SSE 数据格式

服务器需设置 Content-Type: text/event-stream。每条消息由字段名、冒号、值和换行符组成，以空行结束。

常用字段：

• data：消息主体。
• event：事件类型。
• id：唯一 ID，用于断点续传。
• retry：建议重连时间。

示例：

data: 这是一条消息

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

前端通过 EventSource 接收：

<script>
let eventSource = new EventSource("/sse/end");
eventSource.addEventListener("foo", function(event) {
    console.log(event.data);
});
eventSource.addEventListener("end", function(event) {
    eventSource.close();
});
</script>

在 Spring 中，结合 WebFlux 的 Flux 可以更优雅地处理流式数据。

Flux

Flux 是响应式编程的核心组件，流程包括创建、转换、过滤、消费。

创建：

import reactor.core.publisher.Flux;
// 从固定值创建
Flux<String> fixedFlux = Flux.just("Hello", "World");
// 从集合创建
Flux<String> fromCollection = Flux.fromIterable(Arrays.asList("A", "B"));
// 数值范围
Flux<Integer> rangeFlux = Flux.range(1, 5);

转化操作：

// map - 一对一转换
Flux<String> uppercased = original.map(String::toUpperCase);
// flatMap - 一对多转换
Flux<String> splitWords = words.flatMap(word -> Flux.fromArray(word.split(" ")));

过滤操作：

// filter - 条件过滤
Flux<Integer> evenNumbers = allNumbers.filter(n -> n % 2 == 0);
// take - 取前 N 个
Flux<String> limited = original.take(2);

消费操作：

// subscribe - 订阅消费
data.subscribe(
    item -> System.out.println(item),
    error -> System.err.println(error),
    () -> System.out.println("Completed!")
);

Advisors

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

执行时机：

• Before Call：请求发送前，常用于修改提示词。
• After Call：收到响应后，常用于记录日志或处理结果。

内置了 SimpleLoggerAdvisor，只需添加到链中即可自动记录请求和响应。

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

配置日志级别为 debug 即可观察打印内容。