Spring AI 实战指南：核心接口、消息类型与流式输出详解

其中 temperature 控制生成的随机性，值越低结果越确定。配置完成后即可启动项目。

核心接口

Spring AI 提供了两个构建对话式 AI 应用的核心接口：

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

消息类型

所有消息都实现了 Message 接口，用于模拟多轮对话中的不同角色：

• SystemMessage：设定 AI 的身份、性格和行为准则，通常放在对话开头。
• UserMessage：代表用户的输入，驱动对话前进。
• AssistantMessage：代表 AI 的回复，用于保持上下文连贯性。
• FunctionMessage/ToolMessage：处理工具调用结果。

示例：设置系统预设身份

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

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

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

输出格式

结构化输出

若需获取 JSON 或对象格式的数据，可使用 entity() 方法将输出转换为自定义实体。

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

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

流式输出

传统输出需等待全部生成完成，而流式输出（SSE）能边生成边返回，提升用户体验。Spring AI 基于响应式编程实现，返回 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();
}

SSE 协议基础

SSE（Server-Sent Events）允许服务器主动向浏览器推送数据流。核心特点包括单向通信、基于 HTTP、长连接及自动重连。

数据格式遵循特定规范，例如：

data: 这是一条消息

后端可通过 WebFlux 优雅地实现此协议。

Flux 操作

Flux 是 WebFlux 的核心组件，支持创建、转换、过滤和消费等操作。

// 创建
Flux<String> fixedFlux = Flux.just("Hello", "World");

// 转换
Flux<String> uppercased = fixedFlux.map(String::toUpperCase);

// 过滤
Flux<Integer> evenNumbers = Flux.range(1, 10).filter(n -> n % 2 == 0);

// 消费
fixedFlux.subscribe(System.out::println);

Advisors

Advisors 是一种拦截器机制，允许在 AI 调用链的关键节点注入逻辑，如日志记录或提示词修改。

执行流程为：用户输入 → Advisor.before() → AI 模型 → Advisor.after() → 响应。

内置 SimpleLoggerAdvisor 可自动记录请求和响应：

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

配合日志级别配置，即可清晰追踪交互细节。