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

其中 temperature 控制生成的随机性：低温更保守确定，高温更多样富有想象力。

接口编写

完成配置后，可以通过 Controller 调用模型：

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

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

核心接口

Spring AI 中构建对话式 AI 应用主要有两大核心接口：ChatModel 和 ChatClient。

ChatModel

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

@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 助手的身份和规则，位于对话开头。

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

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

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

AssistantMessage

它是实现连贯多轮对话的关键。每次 AI 回复后，可将此回复作为历史上下文的一部分发送给 AI。

输出格式

结构化输出

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

SSE 协议介绍

由于 HTTP 是无状态的，要实现服务器主动推送，通常使用 SSE（Server-Sent Events）。这是一种基于 HTTP 的轻量级实时通信协议，浏览器通过内置的 EventSource API 接收数据。

核心特点：

• 单向通信：仅从服务器推送到客户端。
• 基于 HTTP：易于穿越防火墙。
• 长连接：保持连接打开持续发送数据。
• 自动重连：连接断开后浏览器会自动尝试重连。

SSE 数据格式

服务器需设置 Content-Type: text/event-stream。数据流由一系列消息组成，每条消息以空行结束。

常用字段：

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

Flux 使用示例

在 Spring WebFlux 中，Flux 是核心组件。使用流程通常为：创建 → 转换 → 过滤 → 消费。

创建 Flux：

// 从固定值创建
Flux<String> fixedFlux = Flux.just("Hello", "World");
// 从集合创建
List<String> list = Arrays.asList("A", "B");
Flux<String> fromCollection = Flux.fromIterable(list);

转化操作：

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

Advisors

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

介入时机：

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

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

内置了 SimpleLoggerAdvisor 用于日志记录：

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

配置日志级别为 debug 即可观察详细的请求和响应日志。