Spring AI 2.0 接 DeepSeek：别从十万字笔记开始，先搭 5 层生产骨架

AI 开箱笔记

309人浏览 · 2026-08-25 17:29:18

AI 开箱笔记 · 2026-08-25 17:29:18 发布

入口契约、ChatClient、DeepSeekChatModel、记忆工具和可观测验收组成 Spring AI 生产骨架

学 Spring AI 很容易掉进一个坑：先收集几万字笔记，从 Ollama、OpenAI、DeepSeek、流式输出一直抄到会话记忆、Function Calling、RAG、Redis 和 MySQL，最后每一段都似乎调通了，却说不清哪层负责安全、状态和故障恢复。

当前 Spring AI 2.0.0 已有原生 DeepSeek starter、统一 Chat API、记忆 repository、工具调用和可观测能力。与其从历史课程的几十个步骤开始，不如先把一条最小对话链路拆成五层，让每层都能回答：

输入从哪里来；
可以修改或调用什么；
敏感数据在哪里；
失败如何表达；
用什么证据验收。

先搭五层骨架，再加 RAG 和业务功能

Spring AI 应用从 Controller 契约、ChatClient、DeepSeekChatModel、ChatMemory 工具到观测和测试的五层架构

第一层：入口契约

Controller 的职责不是把任意字符串原样送给模型。它至少要定义：

谁有权调用；
message、conversationId 和业务字段的长度与格式；
同步、SSE 或其他输出协议；
限流、超时、取消和业务错误格式；
哪些 provider 错误不应直接暴露给用户。

一个最小请求对象可以是：

public record ChatRequest(
        @NotBlank @Size(max = 4_000) String message,
        @NotBlank @Size(max = 128) String conversationId) {
}

这里有意没把 model、temperature 和 API key 暴露成用户可任意修改的请求字段。provider 策略应由服务配置或受控业务规则决定。

第二层：ChatClient 编排

ChatClient 提供类似 Spring WebClient/RestClient 的 fluent API，同时支持 call() 和 stream()。Chat Client API

把公共 system 指令、记忆 Advisor、工具列表和默认行为放在统一配置处，不要散落在每个 Controller：

@Bean
ChatClient chatClient(ChatModel chatModel, ChatMemory chatMemory) {
    return ChatClient.builder(chatModel)
            .defaultAdvisors(
                    MessageChatMemoryAdvisor.builder(chatMemory).build())
            .build();
}

流式接口显式声明 SSE，并传入经身份校验后的会话 ID：

@PostMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
Flux<String> stream(@Valid @RequestBody ChatRequest request) {
    return chatClient.prompt()
            .user(request.message())
            .advisors(a -> a.param(
                    ChatMemory.CONVERSATION_ID,
                    request.conversationId()))
            .stream()
            .content();
}

生产代码中，conversationId 不能只由前端随意提供后直接信任。它必须与当前用户、租户和业务资源关联，否则只需猜到他人 ID 就可能混入他人上下文。

第三层：原生 DeepSeekChatModel

当前 Spring AI 可以直接添加原生 DeepSeek starter：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-deepseek</artifactId>
</dependency>

通过 Spring AI BOM 统一版本，不要给每个 AI 模块单独拼凑版本：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-bom</artifactId>
            <version>2.0.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

密钥从环境或专用 secret manager 读取，不写进可提交 YAML：

spring:
  ai:
    model:
      chat: deepseek
    deepseek:
      api-key: ${DEEPSEEK_API_KEY}
      chat:
        model: ${DEEPSEEK_MODEL}

当前配置项已使用 spring.ai.model.chat=deepseek，历史文章中的 spring.ai.deepseek.chat.enabled 已被删除。原生 DeepSeek 文档

Spring AI Model 和 StreamingModel 与 ChatModel、EmbeddingModel、ImageModel 的类型层级

图：Spring AI 用统一 Model 抽象承载不同模态和 provider；业务层不应绑死某个底层客户端。

记忆与历史必须分开

原笔记已经注意到“会话记忆”和“会话历史”不同，这是很重要的判断。当前官方文档将它们定义为：

Chat Memory：模型为维持当前上下文而保留的相关消息；
Chat History：用户与模型交换的完整记录。

ChatMemory 不适合代替完整历史存储。默认 MessageWindowChatMemory 使用内存 repository 并保留最多 20 条消息，超出窗口后会淘汰旧轮次。Chat Memory

DeepSeek 多轮对话中的问题、思考内容和答案排列方式

生产设计至少要分成三个对象：

会话元数据：用户、租户、标题、时间、状态；
完整历史：用于展示、审计、导出或用户删除；
模型记忆：经窗口、摘要或检索选择后送给模型的部分。

官方已提供 JDBC、Redis、MongoDB、Neo4j 等 memory repository。但需要特别注意：当前 JDBC ChatMemoryRepository 会过滤 tool call 和 tool response 消息。如果应用依赖完整工具轨迹，不能只看“已持久化”就假设消息类型全部保留。