阅读时长：6分钟 | 适合想把DeepSeek集成到Spring Boot项目的开发者

先说背景

上周接了个活，要把DeepSeek API集成到一个Spring Boot 3.x项目里。我心想这不简单吗，Python那边分分钟搞定，Java这边应该也差不多。

结果打开IDE的那一刻，噩梦开始了。

先是项目死活起不来，报BeanCreationException；改了半天终于起来了，又报401；401搞定了，请求直接超时。一圈折腾下来，天都快亮了。

今天把这几个坑写下来，你照着避，省得跟我一样熬夜。

坑一：依赖地狱——版本不对，项目都起不来

这是第一个拦路虎。按网上的教程加了依赖，一启动直接报错：BeanCreationException: … spring-ai-core 相关类找不到

查了半天发现是版本冲突导致的。

Spring AI还在快速迭代阶段，版本管理非常敏感。很多教程用的是不同的版本号，你抄一个、他抄一个，最后pom.xml里一堆版本不一致的依赖，能起来才怪。

正确的做法是这样：

第一步，用BOM统一管理版本：

<properties>
    <spring-ai.version>1.0.0-M6</spring-ai.version>
</properties>

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

第二步，添加Spring里程碑仓库：

<repositories>
    <repository>
        <id>spring-milestones</id>
        <name>Spring Milestones</name>
        <url>https://repo.spring.io/milestone</url>
    </repository>
</repositories>

第三步，只加一个依赖：

<dependencies>
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
    </dependency>
</dependencies>

注意：DeepSeek API兼容OpenAI格式，所以用spring-ai-openai-starter就行。别乱加别的starter，否则自动配置类会打架。版本建议用1.0.0-M6或更新的里程碑版本。

坑二：API Key硬编码——差点把余额送给陌生人

项目好不容易起来了，结果调用API时疯狂报401：

401 - Authentication fails

检查了三遍Key，确认没复制错。最后发现问题出在配置方式上。
我第一次图省事，直接在application.yml里写了Key：

spring:
  ai:
    openai:
      api-key: sk-xxxxxxxxxxxxx  # 危险！

然后顺手把代码push到了仓库。

还好是私有仓库，要不然这Key现在就被人拿去刷我的余额了。

正确做法是用环境变量：

spring:
  ai:
    openai:
      api-key: ${DEEPSEEK_API_KEY}
      base-url: ${DEEPSEEK_BASE_URL:https://api.deepseek.com}

然后在.env文件或系统环境变量里设置：

DEEPSEEK_API_KEY=你的真实Key

记得把.env和包含真实Key的配置文件加到.gitignore里。

坑三：超时——Spring默认10秒，DeepSeek经常超过

API调通了，Key也安全了。然后迎来了最折磨人的问题——请求动不动就超时。

同步请求时，DeepSeek返回时间经常超过10秒，而Spring的默认超时只有10秒。你看着控制台转圈转了半天，最后抛一个超时异常，心态直接崩了。

解决方案有两个：

方案一：调大超时时间

在配置里自定义RestTemplate的超时参数：

spring:
  ai:
    openai:
      api-key: ${DEEPSEEK_API_KEY}
      base-url: https://api.deepseek.com
      chat:
        options:
          timeout: 60000  # 60秒，单位毫秒

或者在代码里注入自定义的RestTemplate，设置连接超时和读取超时。

方案二：改用流式输出（推荐）

如果你的场景是聊天对话，强烈建议用SSE流式输出。用户能看到AI一个字一个字往外蹦的"打字机效果"，感知延迟大幅降低，不用傻等十几秒。

核心代码：

@PostMapping(value = "/api/chat/stream", 
            produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public SseEmitter streamChat(@RequestBody ChatRequest request) {
    SseEmitter emitter = new SseEmitter(120_000L);  // 120秒超时
    // 异步调用DeepSeek，逐字推送给前端
    return emitter;
}

流式输出的好处是：后端不用等完整响应，边收边推，用户体验好，也不容易超时。

顺便提一嘴：DeepSeek返回的content要判空

这是个细节坑。DeepSeek返回的choices[0].message.content有时候会是null，直接取值会报空指针。
记得判空:

String content = response.getChoices().get(0).getMessage().getContent();
if (content == null) {
    content = "";  // 或者返回默认提示
}

完整配置参考

最后贴一份我调通的完整配置，直接抄作业：
pom.xml关键部分：

<properties>
    <java.version>17</java.version>
    <spring-ai.version>1.0.0-M6</spring-ai.version>
</properties>

<repositories>
    <repository>
        <id>spring-milestones</id>
        <name>Spring Milestones</name>
        <url>https://repo.spring.io/milestone</url>
    </repository>
</repositories>

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

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
    </dependency>
</dependencies>

application.yml：

spring:
  ai:
    openai:
      api-key: ${DEEPSEEK_API_KEY}
      base-url: https://api.deepseek.com
      chat:
        options:
          model: deepseek-chat
          timeout: 60000

说点实在的

这三个坑搞完，我最大的感受是：Spring Boot接大模型，难的不是API本身，而是Spring AI这个框架的版本和配置太敏感了。

如果你也在用Spring Boot接DeepSeek，建议：

1. 版本一定要统一，用BOM管理
2. Key绝对不要硬编码，走环境变量
3. 超时别用默认值，要么调大、要么走流式

这几个问题搞定，剩下的就是调调参数的事了。

有问题评论区见，看到就回。

下一篇写什么？

留言告诉我，选一个：

A. Spring AI + WebFlux 响应式集成的坑

B. 多轮对话 + 会话管理的实践

C. 生产环境部署的注意事项