摘要

本文记录一个最小可运行的 Spring AI + DeepSeek Demo，重点覆盖 Maven 依赖、spring.ai.deepseek.api-key、deepseek-v4-flash、ChatClient、流式输出接口和常见启动问题。适合 Spring Boot / Java 后端开发者按步骤复现。

环境说明

• JDK 17+
• Spring Boot 3.5.14
• Spring AI 1.1.7
• DeepSeek 模型：deepseek-v4-flash
• 示例分支：article/001-deepseek-quickstart

---

一、先跑通 Spring AI + DeepSeek 最小 Demo

上一篇我们聊了一个问题：为什么 Java 程序员现在要补上 Spring AI 这一课。

只讲“为什么”还不够。

技术这东西，最怕停留在概念上。

你看完一堆趋势分析，收藏一堆教程，最后项目里还是一行代码没跑起来，那 AI 依然离你很远。

所以这篇直接动手。

我们用 Spring Boot 接 DeepSeek，跑一个最小可用的对话接口。

这篇文章不讲大而全的理论，只做一件事：

用 10 分钟跑通一个可以和 DeepSeek 对话的 Spring Boot Demo。

跑通之后，你会发现，Java 程序员做 AI 应用的第一步，其实没有想象中那么远。

---

一、为什么选 Spring AI + DeepSeek？

对 Java 开发者来说，Spring AI 的最大价值不是“让你少写几行代码”，而是：

用 Spring 熟悉的工程方式，把大模型接进业务系统。

你不用自己封装 HTTP Client，不用手写一堆请求参数，也不用为每个模型供应商维护一套调用逻辑。

Spring AI 把这些能力抽象成统一接口，比如：

• ChatClient：面向应用开发的对话客户端；
• ChatModel：底层模型抽象；
• Prompt：提示词和消息组织；
• Streaming：流式输出；
• Tool Calling、RAG、Chat Memory：后续做企业 AI 应用会用到的能力。

DeepSeek 的优势也很直接：模型效果不错，API 成本友好，而且现在 API 已经支持 deepseek-v4-flash 和 deepseek-v4-pro。

对入门 Demo 来说，建议先用 deepseek-v4-flash。

它响应快、成本低，适合先把 Spring AI 调用链路跑通。

如果你要处理更复杂的推理、代码分析或长上下文任务，再切到 deepseek-v4-pro。

所以这个组合特别适合入门：

Spring AI 负责工程化，DeepSeek 负责模型能力。

---

二、准备工作

你需要准备 4 样东西：

• JDK 17 或以上；
• Maven 或 Gradle；
• 一个 Spring Boot 项目；
• 一个 DeepSeek API Key。

DeepSeek API Key 可以在 DeepSeek Platform 创建：

https://platform.deepseek.com/

真实项目里不要把 Key 写死到代码或配置文件里。

更推荐的方式是用环境变量：

export DEEPSEEK_API_KEY="你的 DeepSeek API Key"

如果只是临时验证，也尽量养成这个习惯：密钥放在环境变量、配置中心或密钥管理工具里，不要提交到代码仓库。

---

三、创建 Spring Boot 项目

最快的方式是用 Spring Initializr：

https://start.spring.io/

可以按下面这样选。

配置项	推荐值
Project	Maven
Language	Java
Spring Boot	3.5.14 或当前稳定版
Group	com.example
Artifact	springai-deepseek-demo
Java	17 或以上

我这里选的是 Maven、Java、Spring Boot 3.5.14、YAML、Java 17，然后在依赖里加了 DeepSeek。

生成后的 pom.xml 大概会长这样：

<properties>
    <java.version>17</java.version>
    <spring-ai.version>1.1.7</spring-ai.version>
</properties>

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

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

<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>

这里有一个小坑：

不建议在单个 starter 上硬写版本号，最好统一交给 spring-ai-bom 管理。

这样后面你接入 RAG、向量数据库、Chat Memory 时，不容易出现 Spring AI 组件版本不一致的问题。

不过，下面我们要写的是一个 HTTP 接口。

如果你在 Initializr 里只选了 DeepSeek，没有选 Spring Web，需要再补一个 Web 依赖：

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

不然下一步写 @RestController 时，相关注解会找不到。

---

四、配置 DeepSeek

打开 src/main/resources/application.yml，加上配置：

spring:
  ai:
    deepseek:
      api-key: sk-你的-DeepSeek-API-Key
      chat:
        options:
          model: deepseek-v4-flash
          temperature: 0.7

几个关键点：

• spring.ai.deepseek.api-key：DeepSeek API Key，Demo 阶段先直接写在 yml 里；
• model: deepseek-v4-flash：速度快、成本友好，适合 Demo 和常规应用；
• temperature：控制输出随机性，越低越稳定，越高越发散。

如果你写成 ${DEEPSEEK_API_KEY}，但启动时报：

DeepSeek API key must be set

大概率是 IDEA 的运行配置里没有带上这个环境变量。

这个时候先别卡在这里，直接把 Key 写回 application.yml，把 Demo 跑通再说。

如果你想要更强的能力，可以把模型改成：

model: deepseek-v4-pro

不过第一步建议先用 deepseek-v4-flash。

原因很简单：先把链路跑通，再根据任务复杂度选择模型。

---

五、写第一个对话接口

新建一个 Controller：

src/main/java/com/example/springaideepseekdemo/ChatController.java

代码如下：

package com.example.springaideepseekdemo.controller;

import org.springframework.ai.chat.client.ChatClient;
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;

@RestController
@RequestMapping("/chat")
public class ChatController {

    private final ChatClient chatClient;

    public ChatController(ChatClient.Builder chatClientBuilder) {
        this.chatClient = chatClientBuilder
            .defaultSystem("你是一个简洁、准确的 Java 技术助手。")
            .build();
    }

    @GetMapping("/ask")
    public String ask(@RequestParam String question) {
        return chatClient.prompt()
            .user(question)
            .call()
            .content();
    }
}

这段代码的核心只有 3 行：

return chatClient.prompt()
    .user(question)
    .call()
    .content();

含义也很直观：

1. 创建一次提示词请求；
2. 放入用户问题；
3. 调用模型并拿到回答。

这就是 Spring AI 的舒服之处。

你写的是 Spring Boot 代码，但背后已经完成了大模型调用。

---

六、启动并测试

启动项目之前，先确认环境变量已经设置：

echo $DEEPSEEK_API_KEY

然后运行 Spring Boot 主类。

启动成功后，访问：

http://localhost:8080/chat/ask?question=用一句话介绍 Spring AI

如果一切正常，你会看到类似这样的回答：

Spring AI 是一个为 Spring 应用提供 AI 模型（如大型语言模型）集成抽象的框架，旨在简化 AI 功能开发。

到这里，你的第一个 Spring AI + DeepSeek 项目就跑通了。

---

七、加一个流式输出接口

普通接口会等模型完整生成后再返回。

如果你想做出类似 ChatGPT 那种“边生成边显示”的效果，可以加一个流式接口。

import org.springframework.http.MediaType;
import reactor.core.publisher.Flux;

@GetMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<String> stream(@RequestParam String question) {
    return chatClient.prompt()
        .user(question)
        .stream()
        .content();
}

访问：

http://localhost:8080/chat/stream?question=写一首关于程序员的打油诗

流式输出的体验会明显更好。

尤其是回答比较长的时候，用户不需要一直等空白页面。

---

八、加一个系统提示词

真实项目里，AI 不能随便发挥。

你通常要给它一个角色、边界和输出风格。

比如做一个 Java 代码助手：

@GetMapping("/code-helper")
public String codeHelper(@RequestParam String question) {
    return chatClient.prompt()
        .system("""
            你是一个专业的 Java 代码助手。
            你擅长 Spring Boot、Spring AI、微服务和工程化实践。
            回答要简洁、准确，优先给可落地的建议。
            """)
        .user(question)
        .call()
        .content();
}

访问：

http://localhost:8080/chat/code-helper?question=如何优化 Spring Boot 启动速度？

有了系统提示词，模型回答会更稳定，也更贴近你的业务目标。

---

九、最容易踩的 5 个坑

1. starter 名称写错

旧文章里经常会出现类似 spring-ai-deepseek-spring-boot-starter 的写法。

现在更推荐使用：

<artifactId>spring-ai-starter-model-deepseek</artifactId>

再配合 spring-ai-bom 管理版本。

2. API Key 写死

Demo 可以快，但不要把坏习惯带进生产。

推荐这样配置：

spring:
  ai:
    deepseek:
      api-key: ${DEEPSEEK_API_KEY}

3. 模型名填错

DeepSeek 当前 API 常用模型可以先记两个：

• deepseek-v4-flash：更快、更便宜，适合 Demo、普通问答和轻量业务场景；
• deepseek-v4-pro：能力更强，适合复杂推理、代码分析和长上下文任务。

刚入门先用 deepseek-v4-flash，排查问题更简单。

4. temperature 调得太高

如果你做的是代码助手、运维助手、知识库问答，建议把 temperature 调低一些。

比如：

temperature: 0.3

这类场景要的是稳定和准确，不是文采飞扬。

5. 直接拿 Demo 上生产

跑通 Demo 不等于可以上线。

真正上线前，你至少还要补上：

• 超时和重试；
• 日志和调用链追踪；
• Token 成本控制；
• 敏感数据脱敏；
• 异常兜底；
• 权限控制；
• 提示词版本管理。

AI 接口不是普通第三方接口。

它既会花钱，也会产生不可控输出，所以更需要工程治理。

---

十、下一步可以做什么？

这篇先不展开 RAG、Tool Calling 那些大主题。

上一篇已经讲过它们能做什么。

如果你今天只是刚跑通这个 Demo，我更建议你先把它打磨成一个“像样的小项目”。

可以从这几件事开始：

• 把 GET 接口改成 POST，用 JSON 传参；
• 加一个简单的前端页面，不要每次都在浏览器地址栏里改问题；
• 把 temperature、model 做成配置项，方便切换 deepseek-v4-flash 和 deepseek-v4-pro；
• 给接口加上超时、异常提示和调用日志；
• 记录每次提问和回答，方便你观察模型效果。

这些东西听起来不如“智能体”“知识库”酷，但很有用。

因为它们会让你从“我会调一个模型接口”，往“我能做一个可用的 AI 功能”迈一步。

等这个小项目顺手了，再去加 RAG、记忆、多轮对话、Tool Calling。

那时候你不是在追概念，而是在给一个已经跑起来的东西加能力。

---

最后说两句

Spring AI + DeepSeek 的入门门槛不高。

真正难的不是跑通第一个接口，而是把它变成一个可靠、可控、可维护的企业 AI 应用。

但第一步必须先迈出去。

如果你是 Java 后端，建议别只停留在“看看 AI 新闻”的阶段。

今天就建一个 Spring Boot 项目，接上 DeepSeek，跑一次真实调用。

代码在自己电脑上跑起来的那一刻，你对 AI 应用开发的理解会完全不一样。

---

参考资料

• Spring AI DeepSeek Chat 官方文档
• Spring AI Getting Started
• DeepSeek Platform

---

我是 Dilee，11 年 Java 老兵，专注 AI 落地应用。

如果这篇文章帮到你了，欢迎分享给更多需要的人。

常用排查命令

# 确认环境变量
echo $DEEPSEEK_API_KEY

# 启动项目
./mvnw spring-boot:run

# 测试普通接口
curl "http://localhost:8080/chat/ask?question=用一句话介绍SpringAI"

# 测试流式接口
curl -N "http://localhost:8080/chat/stream?question=写一段Java学习建议"

如果启动时报 DeepSeek API key must be set，优先检查 IDEA Run Configuration 里是否带上了 DEEPSEEK_API_KEY。

---

我是 Dilee，11 年 Java 开发者，专注 Spring AI、AI Agent 和大模型应用落地。

后续会继续更新 Spring AI、RAG、Memory、Tool Calling、MCP 等实战内容。