主题与目标

本文为“基于 Spring AI 的 DeepSeek 集成实战”系列博客的第一版，将重点介绍如何使用 Spring AI 框架对接 DeepSeek 服务，包括依赖配置、核心代码示例以及基础验证步骤。第二版将着重讲解“流式显示”与“Markdown 展示”的实现方式，并在后续发布。本文面向具备 Spring 开发经验的读者，旨在帮助快速搭建、调试并初步理解 DeepSeek 在 Spring 项目中的集成方式。

Spring AI 框架概述

Spring AI 是 Spring 官方推出的人工智能集成框架，旨在简化 AI 功能在 Spring 应用中的整合。自经历多个里程碑版本（M1～M8）后，Spring AI 1.0 版本于 2025 年 5 月 20 日正式发布，标志着 Spring 生态全面拥抱人工智能技术，并提供稳定的 API 支持。Spring AI 提供了一套标准化的接口和工具，可轻松接入 OpenAI、Azure AI、Hugging Face 等主流 AI 服务，同时保持 Spring 生态的简洁性与灵活性。

核心特性

1. 统一 API 设计 通过抽象层屏蔽不同 AI 提供商（如 OpenAI、Gemini、Olama 等）的接口差异，开发者只需使用 Spring AI 的通用接口（如 ChatModel），即可切换底层 AI 服务。

2. 开箱即用的功能支持

   • 对话模型（Chat）：类似 ChatGPT 的交互体验。

   • 嵌入模型（Embedding）：将文本、图像或其他数据转换为数值向量，常用于语义搜索与检索增强（RAG）。

   • 图像生成（Image Generation）：根据文本描述或其他输入创建新图像。

   • 函数调用（Function Calling）：让 AI 模型能够与外部 API 和服务交互，也就是说，开发者编写的函数可以被 AI 调用。

3. 与 Spring 生态无缝集成

   • 支持 Spring Boot 自动配置与依赖注入。

   • 可结合 Spring Actuator 监控、Spring Security、Spring Data 等组件协同工作。

4. Prompt 工程支持 提供 PromptTemplate 等工具，方便动态生成提示词（Prompts），并支持上下文管理，简化复杂对话场景下的提示词编写。

5. 模块化设计 开发者可以根据项目需求选择特定的 AI 服务模块；

   • 若只需 OpenAI 功能，直接引入 spring-ai-openai。

   • 若需 Google Vertex AI，则引入 spring-ai-vertexai。

   • 每个 AI 供应商/服务都有独立的 Spring Starter 模块，按需引入即可。

适用场景

• 快速构建 AI 驱动的应用：如智能客服、内容生成工具等。

• 灵活切换 AI 后端：从本地模型切换到云服务场景下极为方便。

• 结合 Spring 生态实现企业级 AI 功能：如借助 Spring Security 做权限控制、Spring Data 做数据持久化等。

官网与资源

• 官方仓库：

  https://github.com/spring-projects/spring-ai

• 官方文档：

  https://spring.io/projects/spring-ai

AI 提供商与模型类型

在 Spring AI 中，「模型类型」和「AI 提供商」是两个不同维度，但它们之间存在密切联系。下面将分别说明二者的概念，并展示常见厂商与模型类型的对应关系。

模型类型 (Model Type)

指的是 AI 模型的功能类别，即它能够完成什么任务。模型类型与具体厂商无关，属于通用能力分类。常见模型类型如下表所示：

AI 提供商 (Provider)

指提供具体 AI 模型服务的公司或平台。一个厂商通常会提供多种模型类型；同一模型类型也可能由多个厂商提供实现。常见提供商及其示例如下表所示：

两者的关系

• 一个提供商支持多种模型类型 例如：OpenAI 同时提供 Chat（GPT-4）、Embedding（text-embedding-3）、Image（DALL·E）等多种能力。

• 一种模型类型可由多个提供商实现 例如：Chat 模型可使用 OpenAI 的 GPT-4，也可使用 Google 的 PaLM 2 或 Anthropic 的 Claude。

在 Spring AI 中，开发者只需关注「模型类型」，配置对应的厂商标签即可调用所需能力，而无需对接多个不同厂商的底层 API。

Spring AI 支持的厂商与模型

以下列表基于2024 年 6 月 Spring AI 官方及社区支持情况，包含国内外主流厂商与对应的模型类型，以及 Spring AI 对应的 Starter 模块名称（当时版本支持情况可能随后更新，请以官方文档为准）：

说明：

• “是否国内厂商”栏标明该厂商是否来自中国大陆。

• DeepSeek 虽然尚无官方专属 Starter，但其 API 与 OpenAI 保持兼容，因此可直接使用 spring-ai-openai 模块进行接入。

Spring AI 接入 DeepSeek 指南

DeepSeek 官方提供的 API 接口设计与 OpenAI 完全兼容，意味着我们可使用原生的 OpenAI 客户端库直接调用 DeepSeek 服务。下面将详细介绍在 Spring Boot 项目中接入 DeepSeek 的步骤。

依赖引入

在 pom.xml 中添加以下依赖：

<dependencies>
    <!-- Spring Web（Spring MVC） -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <!-- Spring AI OpenAI Starter（兼容 DeepSeek） -->
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
        <version>1.0.0-M6</version>
    </dependency>

    <!-- Lombok，简化代码编写 -->
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
    </dependency>
</dependencies>

<repositories>
    <!-- 指向 Spring 官方快照仓库，以便尝试最新功能（可选） -->
    <repository>
        <id>spring-snapshots</id>
        <name>Spring Snapshots</name>
        <url>https://repo.spring.io/snapshot</url>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
</repositories>

• 使用 spring-ai-openai-spring-boot-starter 来兼容 DeepSeek，因为 DeepSeek 的 API 规范与 OpenAI 保持一致。

• 切勿将 API Key 硬编码到代码仓库，应通过环境变量或密钥管理系统注入。

配置文件编写

在 application.yml 中添加 DeepSeek 的相关配置：

spring:
  ai:
    openai:
      # DeepSeek 的访问密钥，务必不要提交到代码仓库，建议通过环境变量注入
      api-key: ${DEESEEK_API_KEY}
      # 指定 DeepSeek API 的基础地址，格式与 OpenAI 相同
      base-url: https://api.deepseek.com
      chat:
        options:
          # 选择要调用的 DeepSeek 模型名称，需与 DeepSeek 支持的模型列表保持一致
          model: deepseek-chat
          # temperature 值越高，AI 回答越随机和创意；值越低，回答越确定和保守
          # 取值范围一般为 0.0～2.0，此处 1.3 属于较高随机性
          temperature: 1.3

• api-key 使用 ${DEESEEK_API_KEY} 从环境变量中读取，防止明文泄露。

• base-url 指定为 DeepSeek 的接口地址，可与 OpenAI 的基础地址替换使用。

• model 字段填写 DeepSeek 支持的具体模型名称，如 deepseek-chat、deepseek-coder 等。

• temperature 根据业务需求调整，影响模型输出的随机程度。

编写服务层 (Service)

在 com.sangui.demo.service 包下创建 AiService.java，示例代码如下：

package com.sangui.demo.service;
​
import lombok.RequiredArgsConstructor;
import org.springframework.ai.chat.model.ChatModel;
import org.springframework.ai.chat.prompt.Prompt;
import org.springframework.ai.chat.prompt.SystemPromptTemplate;
import org.springframework.stereotype.Service;
​
import java.util.Map;
​
/**
 * @Author: 三桂
 * @CreateTime: 2025-06-06
 * @Description: AI 服务类，调用 DeepSeek Chat 模型进行对话
 * @Version: 1.0
 */
@Service
@RequiredArgsConstructor
public class AiService {
​
    private final ChatModel chatModel;
​
    /**
     * 直接调用 ChatModel，传入用户消息并返回模型输出
     *
     * @param message 用户输入消息
     * @return AI 响应文本
     */
    public String generate(String message) {
        return chatModel.call(message).getResult().getOutput().getText();
    }
​
    /**
     * 使用系统提示模板 (System Prompt) 对生成过程进行控制
     *
     * @param userMessage 用户输入问题
     * @return AI 响应文本
     */
    public String generateWithSystemPrompt(String userMessage) {
        // 定义系统提示模板
        SystemPromptTemplate systemPromptTemplate = new SystemPromptTemplate("""
                你是一个资深{domain}专家，回答需要满足以下要求：
                1. 语言风格：{tone}
                2. 回答长度：{length}
                3. 用户问题：{userMessage}
                """);
​
        // 填充模板参数
        Prompt prompt = new Prompt(
            systemPromptTemplate.createMessage(Map.of(
                "domain", "Java",
                "tone", "幽默",
                "length", "不超过100字",
                "userMessage", userMessage
            ))
        );
​
        // 调用 ChatModel 并返回文本结果
        return chatModel.call(prompt).getResult().getOutput().getText();
    }
}

• 服务类通过注入 Spring AI 提供的 ChatModel 来调用底层 DeepSeek 模型。

• generate 方法直接传入用户消息即可获得模型返回文本。

• generateWithSystemPrompt 方法演示了如何使用系统提示模板 (SystemPromptTemplate)，可为模型调用添加上下文约束，例如指定领域、语气与输出长度。

编写控制层 (Controller)

在 com.sangui.demo.controller 包下创建 AiController.java，示例代码如下：

package com.sangui.demo.controller;
​
import com.sangui.demo.service.AiService;
import lombok.RequiredArgsConstructor;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
​
/**
 * @Author: 三桂
 * @CreateTime: 2025-06-06
 * @Description: AI 控制器，暴露 HTTP 接口供前端调用
 * @Version: 1.0
 */
@RestController
@RequestMapping("/api/ai")
@RequiredArgsConstructor
public class AiController {
​
    private final AiService aiService;
​
    /**
     * 直接对话接口
     * 示例：GET /api/ai/chat?message=你好
     *
     * @param message 用户消息
     * @return AI 响应文本
     */
    @GetMapping("/chat")
    public String chat(@RequestParam String message) {
        return aiService.generate(message);
    }
​
    /**
     * 使用系统提示模板的对话接口
     * 示例：GET /api/ai/chat-with-prompt?message=请给我讲一个笑话
     *
     * @param message 用户消息
     * @return AI 响应文本
     */
    @GetMapping("/chat-with-prompt")
    public String chatWithPrompt(@RequestParam String message) {
        return aiService.generateWithSystemPrompt(message);
    }
}

• 将 AiService 注入到控制器层，分别暴露两个 GET 接口：

  1. /api/ai/chat：直接对话

  2. /api/ai/chat-with-prompt：带系统提示模板的对话

• 接口调用示例：

  http://localhost:8080/api/ai/chat?message=你做个自我介绍

  或

  http://localhost:8080/api/ai/chat-with-prompt?message=请解释一下 Spring Boot 的原理

运行与验证

1. 启动项目 在 IDE 或命令行中运行 Spring Boot 启动类（通常是 DemoApplication.java），确保服务正常启动，控制台无报错。

2. 浏览器/Postman 调试 打开浏览器，访问以下 URL：

   http://localhost:8080/api/ai/chat?message=你做个自我介绍

   如果一切配置正确，应能看到 DeepSeek 返回的自我介绍文本。

3. 示例结果展示 结果输出如下：

   
   

到此，Spring AI 集成 DeepSeek 的基本流程就完成了。您可以根据业务需求继续完善，例如：

• 对接更多 DeepSeek 模型（如 deepseek-coder 用于代码生成）。

• 使用嵌入模型做检索增强（RAG）。

• 配合 Spring Security 控制 AI 接口访问权限。

• 在前端页面集成 WebSocket 或 SSE，实现实时对话。

第四章与第五章预览

4. 流式显示（待第二版完善）

本部分将在第二版中详细讲解如何利用 Spring AI 的流式调用能力（如 ChatModel.stream() 方法）实现文本实时输出，包括如何在前端页面中通过 WebSocket 将 AI 的响应逐步渲染，提升用户体验。

5. Markdown 展示（待第二版完善）

本部分将在第二版中介绍如何将 AI 返回的多行 Markdwon 内容原样展示在前端，例如使用

、支持语法高亮的组件或专门的 Markdown 渲染器，确保 AI 生成的代码片段、表格或列表格式正确且易于阅读。

补充说明与注意事项

1. API Key 管理

   • 切勿将密钥硬编码或提交到公共仓库，推荐使用环境变量或加密凭据管理。

   • 可在服务器环境变量中设置 DEESEEK_API_KEY，在项目启动时由 Spring Boot 自动加载。

2. 模型名称与计费

   • DeepSeek 不同模型（如 deepseek-chat、deepseek-coder、deepseek-math）能力和计费标准可能不同。应根据实际需求选择合适模型。

   • 推荐在测试阶段使用小模型（或本地测试环境），避免大模型高额费用。

3. 异常处理与超时配置

   • 生产环境中建议对 AI 接口做异常捕获与重试策略，例如网络超时、API 返回错误等。

   • 可在 application.yml 中配置 HTTP 客户端超时参数，或在 ChatModel 调用时传入自定义的 Request Options。

4. 本地与云端模型切换

   • 如果后续需要使用本地部署的开源模型（如 Ollama 本地 Llama），只需替换 Starter 模块为 spring-ai-ollama，并修改配置中的 base-url 与模型名称。

   • 这种弹性切换能力使得开发者无需改动业务代码，即可轻松切换多种后端实现。

5. Prompt 工程与上下文管理

   • 对话场景中，若需多轮交互，建议在业务层维护对话上下文，将历史对话传递给 ChatModel，以保证 AI 能够理解上下文。

   • Spring AI 提供了 Conversation 等 API，可帮助管理多轮对话上下文。

6. 日志与监控

   • 可结合 Spring Actuator 监控 AI 接口调用情况，如请求次数、错误率等。

   • 对关键事件（如高耗时请求、异常响应）可通过日志或告警系统进行跟踪，以便及时优化。

7. 后续扩展

   • 可基于 Spring MVC、Spring WebFlux 等技术栈，多种方式暴露 AI 服务接口。

   • 将 DeepSeek 与数据库、消息队列等系统打通，实现企业级应用场景，如：

     • 智能客服系统：用户提问后，结合知识库和搜索引擎做检索增强。

     • 内容生产平台：自动生成文章摘要、图片、代码示例等。

     • 数据分析助手：让 AI 调用自定义函数，查询数据库并返回结果。