【2026最新】Spring Boot 3.x 集成 DeepSeek 大模型：构建智能REST API助手

一、引言

2026年，大模型技术已全面融入企业级应用开发。本文将手把手教你如何在 Spring Boot 3.x 项目中集成 DeepSeek 大模型 API，构建一个具备智能对话能力的 REST API 助手，实现自然语言交互、智能问答与业务逻辑编排。

---

二、技术栈

| 组件 | 版本 | 说明 | |------|------|------| | Spring Boot | 3.4.x | 企业级微服务框架 | | JDK | 17+ | 长期支持版本 | | DeepSeek API | v2 | 大模型推理接口 | | WebClient | - | 响应式HTTP客户端 | | Lombok | - | 简化代码 | | SpringDoc | 2.8.x | API文档自动生成 |

---

三、核心实现

3.1 项目依赖 (pom.xml)

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
         https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.4.3</version>
        <relativePath/>
    </parent>
    <groupId>com.example</groupId>
    <artifactId>deepseek-spring-boot</artifactId>
    <version>1.0.0</version>
    <name>deepseek-spring-boot</name>
    <description>Spring Boot 3.x 集成 DeepSeek 大模型示例</description>

    <properties>
        <java.version>17</java.version>
    </properties>

    <dependencies>
        <!-- Spring Boot Web -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <!-- WebClient 响应式客户端 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-webflux</artifactId>
        </dependency>
        <!-- Lombok -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
        <!-- SpringDoc OpenAPI -->
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
            <version>2.8.5</version>
        </dependency>
        <!-- 配置处理 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-configuration-processor</artifactId>
            <optional>true</optional>
        </dependency>
        <!-- 测试 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <excludes>
                        <exclude>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                        </exclude>
                    </excludes>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

3.2 配置文件 (application.yml)

server:
  port: 8080

spring:
  application:
    name: deepseek-spring-boot

# DeepSeek API 配置
deepseek:
  api:
    base-url: https://api.deepseek.com/v2
    api-key: ${DEEPSEEK_API_KEY:your-api-key-here}
    model: deepseek-chat
    timeout: 60000
    max-tokens: 2048
    temperature: 0.7

3.3 配置属性类

package com.example.deepseek.config;

import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Configuration;

/**
 * DeepSeek API 配置属性
 */
@Data
@Configuration
@ConfigurationProperties(prefix = "deepseek.api")
public class DeepSeekProperties {

    /** API 基础地址 */
    private String baseUrl = "https://api.deepseek.com/v2";

    /** API 密钥 */
    private String apiKey;

    /** 模型名称 */
    private String model = "deepseek-chat";

    /** 请求超时时间（毫秒） */
    private long timeout = 60000;

    /** 最大输出 Token 数 */
    private int maxTokens = 2048;

    /** 温度参数（0-2），控制生成随机性 */
    private double temperature = 0.7;
}

3.4 数据模型定义

package com.example.deepseek.model;

import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

import java.util.List;

/**
 * 聊天请求体
 */
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class ChatRequest {

    /** 模型名称 */
    private String model;

    /** 消息列表 */
    private List<Message> messages;

    /** 温度参数 */
    private Double temperature;

    /** 最大输出 Token */
    @Builder.Default
    private Integer maxTokens = 2048;

    /** 是否流式输出 */
    private Boolean stream;
}

/**
 * 消息体
 */
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class Message {

    /** 角色：system/user/assistant */
    private String role;

    /** 消息内容 */
    private String content;
}

/**
 * 聊天响应体
 */
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class ChatResponse {

    /** 响应ID */
    private String id;

    /** 模型名称 */
    private String model;

    /** 选择结果列表 */
    private List<Choice> choices;

    /** Token 用量统计 */
    private Usage usage;
}

/**
 * 回答选择
 */
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class Choice {

    /** 索引 */
    private Integer index;

    /** 消息 */
    private Message message;

    /** 结束原因 */
    private String finishReason;
}

/**
 * Token 用量
 */
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class Usage {

    /** 输入 Token 数 */
    private Integer promptTokens;

    /** 输出 Token 数 */
    private Integer completionTokens;

    /** 总 Token 数 */
    private Integer totalTokens;
}

3.5 DeepSeek 客户端服务

package com.example.deepseek.service;

import com.example.deepseek.config.DeepSeekProperties;
import com.example.deepseek.model.*;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;
import org.springframework.web.reactive.function.client.WebClient;
import org.springframework.web.reactive.function.client.WebClientResponseException;
import reactor.core.publisher.Mono;

import java.time.Duration;
import java.util.List;

/**
 * DeepSeek API 客户端服务
 */
@Slf4j
@Service
@RequiredArgsConstructor
public class DeepSeekService {

    private final DeepSeekProperties properties;
    private final WebClient webClient;

    /**
     * 发送聊天请求
     *
     * @param messages 消息列表
     * @return 聊天响应
     */
    public ChatResponse chat(List<Message> messages) {
        ChatRequest request = ChatRequest.builder()
                .model(properties.getModel())
                .messages(messages)
                .temperature(properties.getTemperature())
                .maxTokens(properties.getMaxTokens())
                .stream(false)
                .build();

        log.debug("发送 DeepSeek 请求: model={}, messages={}", 
                  request.getModel(), request.getMessages());

        try {
            ChatResponse response = webClient.post()
                    .uri("/chat/completions")
                    .bodyValue(request)
                    .retrieve()
                    .bodyToMono(ChatResponse.class)
                    .timeout(Duration.ofMillis(properties.getTimeout()))
                    .block();

            log.debug("DeepSeek 响应成功: id={}, usage={}", 
                      response != null ? response.getId() : "null",
                      response != null ? response.getUsage() : "null");
            return response;

        } catch (WebClientResponseException e) {
            log.error("DeepSeek API 请求失败: status={}, body={}", 
                      e.getStatusCode(), e.getResponseBodyAsString());
            throw new RuntimeException("AI 服务调用异常: " + e.getStatusText(), e);
        } catch (Exception e) {
            log.error("DeepSeek API 调用异常", e);
            throw new RuntimeException("AI 服务异常", e);
        }
    }

    /**
     * 简单问答（单轮）
     *
     * @param userMessage 用户消息
     * @return AI 回复内容
     */
    public String ask(String userMessage) {
        Message userMsg = Message.builder()
                .role("user")
                .content(userMessage)
                .build();

        ChatResponse response = chat(List.of(userMsg));

        if (response != null && response.getChoices() != null 
                && !response.getChoices().isEmpty()) {
            return response.getChoices().get(0).getMessage().getContent();
        }
        return "抱歉，我没有理解您的问题。";
    }

    /**
     * 带上下文的对话
     *
     * @param messages 历史消息列表（含system提示）
     * @return AI 回复内容
     */
    public String chatWithContext(List<Message> messages) {
        ChatResponse response = chat(messages);

        if (response != null && response.getChoices() != null 
                && !response.getChoices().isEmpty()) {
            return response.getChoices().get(0).getMessage().getContent();
        }
        return "抱歉，我没有理解您的问题。";
    }
}

3.6 WebClient 配置

package com.example.deepseek.config;

import lombok.RequiredArgsConstructor;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.web.reactive.function.client.WebClient;

/**
 * WebClient 配置
 */
@Configuration
@RequiredArgsConstructor
public class WebClientConfig {

    private final DeepSeekProperties properties;

    @Bean
    public WebClient deepSeekWebClient() {
        return WebClient.builder()
                .baseUrl(properties.getBaseUrl())
                .defaultHeader(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE)
                .defaultHeader(HttpHeaders.AUTHORIZATION, "Bearer " + properties.getApiKey())
                .defaultHeader("Accept", MediaType.APPLICATION_JSON_VALUE)
                .build();
    }
}

3.7 REST 控制器

package com.example.deepseek.controller;

import com.example.deepseek.model.Message;
import com.example.deepseek.service.DeepSeekService;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import lombok.RequiredArgsConstructor;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.util.List;
import java.util.Map;

/**
 * AI 聊天控制器
 */
@Tag(name = "AI 聊天接口", description = "基于 DeepSeek 大模型的智能对话 API")
@RestController
@RequestMapping("/api/ai")
@RequiredArgsConstructor
public class ChatController {

    private final DeepSeekService deepSeekService;

    /**
     * 简单问答
     */
    @Operation(summary = "简单问答", description = "发送单条消息并获取 AI 回复")
    @PostMapping("/ask")
    public ResponseEntity<Map<String, String>> ask(
            @Parameter(description = "用户问题") @RequestParam String question) {
        String answer = deepSeekService.ask(question);
        return ResponseEntity.ok(Map.of(
                "question", question,
                "answer", answer,
                "timestamp", String.valueOf(System.currentTimeMillis())
        ));
    }

    /**
     * 多轮对话
     */
    @Operation(summary = "多轮对话", description = "发送包含上下文的对话消息列表")
    @PostMapping("/chat")
    public ResponseEntity<Map<String, Object>> chat(
            @Parameter(description = "消息列表（含历史上下文）") 
            @RequestBody List<Message> messages) {

        String answer = deepSeekService.chatWithContext(messages);
        return ResponseEntity.ok(Map.of(
                "reply", answer,
                "timestamp", System.currentTimeMillis()
        ));
    }

    /**
     * 健康检查
     */
    @Operation(summary = "健康检查", description = "检查 AI 服务是否正常")
    @GetMapping("/health")
    public ResponseEntity<Map<String, String>> health() {
        return ResponseEntity.ok(Map.of(
                "status", "UP",
                "service", "DeepSeek AI",
                "version", "2.0"
        ));
    }
}

3.8 启动类

package com.example.deepseek;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.properties.EnableConfigurationProperties;

@SpringBootApplication
@EnableConfigurationProperties
public class DeepSeekApplication {

    public static void main(String[] args) {
        SpringApplication.run(DeepSeekApplication.class, args);
    }
}

---

四、API 测试

4.1 简单问答

curl -X POST "http://localhost:8080/api/ai/ask?question=请介绍一下Spring Boot 3.x的新特性"

响应示例：

{
  "question": "请介绍一下Spring Boot 3.x的新特性",
  "answer": "Spring Boot 3.x 带来了多项重要更新：...（AI生成内容）",
  "timestamp": "1747622400000"
}

4.2 多轮对话

curl -X POST "http://localhost:8080/api/ai/chat" \
  -H "Content-Type: application/json" \
  -d '[
    {"role": "system", "content": "你是一位资深的Java技术专家"},
    {"role": "user", "content": "请用Java实现一个单例模式"}
  ]'

---

五、架构设计总结

┌──────────────┐     ┌─────────────────┐     ┌──────────────┐
│  客户端/前端   │ ──▶ │  Spring Boot 3.x │ ──▶ │  DeepSeek    │
│  REST调用     │ ◀── │  AI REST API    │ ◀── │  大模型API   │
└──────────────┘     └─────────────────┘     └──────────────┘
                           │
                    ┌──────┴──────┐
                    │   WebClient  │
                    │  (HTTP客户端) │
                    └─────────────┘

核心设计要点：

1. 分层解耦：Controller → Service → WebClient → 外部API
2. 配置外置：所有API参数通过 application.yml 管理
3. 响应式支持：基于 WebClient 实现非阻塞调用
4. 错误处理：统一异常捕获与日志记录
5. 文档自动生成：集成 SpringDoc，自动生成 Swagger 文档

---

六、最佳实践与扩展

6.1 生产环境注意事项

• API Key 安全管理：使用环境变量或配置中心，避免硬编码
• 限流与降级：集成 Resilience4j 实现熔断降级
• 缓存策略：对高频相似请求进行缓存
• 日志追踪：使用 MDC 实现请求链路跟踪

6.2 扩展方向

• 支持流式输出（SSE），实现打字机效果
• 集成函数调用（Function Calling），实现工具调用
• 支持多模型切换（DeepSeek/ChatGPT/通义千问）
• 添加 LangChain4j 框架支持，构建复杂 AI 工作流

---

七、总结

本文从零开始，完整演示了 Spring Boot 3.x 集成 DeepSeek 大模型 的全过程。通过 WebClient 构建 HTTP 客户端、配置属性管理 API 参数、REST 控制器暴露智能接口，最终实现了一个功能完备的 AI REST API 助手。

这套架构可轻松扩展支持任意大模型 API，是企业级 AI 应用集成的最佳实践模板。

---

项目源码：关注公众号回复 "deepseek-spring-boot" 获取完整源码

作者：CSDN文章发布专家

日期：2026-05-19