Spring AI 应用开发

Spring AI 应用开发从入门到智能聊天机器人

生成式 AI 正在进入 Java 企业应用的日常开发流程。对于已经熟悉 Java、Spring Boot 和 Web 开发的开发者来说,Spring AI 的价值在于把大模型能力封装成符合 Spring 生态习惯的组件,让聊天、流式响应、结构化输出、本地模型、云模型、多模态和对话记忆等能力可以通过统一方式接入业务系统。

本文按照从概念到实践、从单次调用到完整聊天机器人的路线,梳理 Spring AI 应用开发的关键知识。

AI 与 Spring AI 的起点

AI 即 Artificial Intelligence,通常指通过计算机系统模拟人类智能,让机器具备学习、推理、决策、识别和生成等能力。它的本质并不是"魔法",而是算法与数据共同作用的结果。医疗影像识别、金融风控、制造业质检、智能驾驶、教育学情分析等场景,都可以看到 AI 技术落地后的实际价值。

从发展历程看,AI 并不是突然出现的新概念。早期的神经元模型和图灵测试奠定了理论基础,达特茅斯会议让"人工智能"成为正式术语,专家系统、国际象棋程序、深度学习、AlphaGo、ChatGPT 以及 DeepSeek-R1 等标志性事件不断推动行业向前。今天开发者面对的重点,已经不只是理解 AI 是什么,而是如何把大模型能力稳定、低成本、可维护地接入应用。

Spring AI 正是在这个背景下出现的。它是 Spring 生态面向 AI 工程的应用框架,目标是把 Spring 一贯强调的可移植性、模块化和 POJO 编程模型带到 AI 应用开发中。开发者可以使用统一的 API 调用不同模型提供商,例如 OpenAI、Anthropic、Microsoft、Amazon、Google、Ollama 以及兼容 OpenAI API 的服务。

Spring AI 支持聊天模型、嵌入模型、图像模型、音频模型和内容审核等能力,并提供同步调用与流式调用。它最大的意义在于降低接入成本:业务代码不用直接处理不同厂商的 HTTP 细节,可以围绕统一抽象构建功能,也更容易在后续切换模型或替换底层服务。

先理解几个核心术语

模型可以理解为经过大量数据训练后得到的一套规则或模式。开发者向模型提供输入,模型根据自身训练得到的能力生成输出。比如点咖啡时,用户的点单就是输入,咖啡师掌握的配方和经验类似模型,最终做出的咖啡就是输出。在 Spring AI 应用中,开发者通常需要选择模型、构造输入、发送请求、接收并处理输出。

LLM 是 Large Language Model 的缩写,也就是大语言模型。它专门处理文本,通常拥有大量参数,能够完成总结、翻译、问答、情感分析、代码生成等任务。常见模型包括 OpenAI 的 GPT 系列、DeepSeek-R1、通义千问 Qwen、Google Gemini 等。不同模型的能力侧重点不同,选择时要结合推理能力、上下文长度、语言支持、成本、响应速度和部署方式。

提示词是提供给模型的指令或文本,用于引导模型生成目标输出。它可以是一个问题、一段描述,也可以是结构化任务说明。从工程角度看,提示词常分为用户提示词和系统提示词。用户提示词用于表达本次请求,例如"总结这段文本";系统提示词用于设定模型角色、行为规范和边界,例如"你是一名严谨的 Java 开发助手,回答要包含关键代码和注意事项"。

词元 Tokens 是大语言模型处理文本时的基本单位。模型的上下文窗口、API 计费、推理耗时和内存占用都与 Tokens 数量有关。输入越冗长,成本越高,响应也可能越慢。因此实际开发中应尽量减少无意义内容,把提示词写得明确、紧凑、结构化。

开发环境与准备工作

使用 Spring AI 前,需要准备合适的 Java 和 Spring Boot 环境。JDK 至少使用 17,因为 Spring Boot 3.x 对 JDK 有明确要求;如果是新项目,JDK 21 也是不错的选择。Spring Boot 推荐使用 3.2 以上版本,新项目可优先选择较新的稳定版本。

如果选择 DeepSeek 作为模型服务,需要在 DeepSeek 开放平台创建 API Key。API Key 只会在创建时展示,应妥善保存,不能提交到代码仓库,也不要暴露在浏览器端或其他客户端代码中。DeepSeek 兼容 OpenAI API,这意味着 Spring AI 的 OpenAI Starter 可以直接用于接入 DeepSeek,只需要配置 API 地址、密钥和模型名称。

初始化 Spring Boot 项目

项目可以采用 Maven 多模块结构。父工程只保留 pom.xml,打包方式设置为 pom,并继承 Spring Boot Starter Parent:

xml 复制代码
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.5.3</version>
    <relativePath/>
</parent>

<properties>
    <maven.compiler.source>17</maven.compiler.source>
    <maven.compiler.target>17</maven.compiler.target>
</properties>

子模块中添加 Web 和测试依赖,再配置 Spring Boot Maven 插件。为了避免 Spring AI 相关依赖版本冲突,需要引入 Spring AI BOM。BOM 的作用是集中管理一组兼容依赖的版本,项目中具体依赖就不需要逐个写版本号。

xml 复制代码
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-bom</artifactId>
            <version>1.0.0-M6</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

然后创建启动类,并在 application.yml 中配置应用名:

yaml 复制代码
spring:
  application:
    name: spring-ai-demo

接入 DeepSeek

Spring AI 为 OpenAI 以及兼容 OpenAI API 的服务提供了 Starter。接入 DeepSeek 时,可以添加如下依赖:

xml 复制代码
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
</dependency>

配置文件中指定 API Key、基础地址、模型和生成参数:

yaml 复制代码
spring:
  ai:
    openai:
      api-key: sk-your-key
      base-url: https://api.deepseek.com
      chat:
        options:
          model: deepseek-chat
          temperature: 0.7

temperature 用于控制输出随机性。值越高,生成结果越发散;值越低,结果越稳定。实践中不要盲目调高参数,尤其是问答、客服、代码生成等场景,更稳定的输出通常更重要。

配置完成后,业务接口不需要手写 HTTP 请求,只要注入 Spring AI 提供的对象即可完成调用。DeepSeek 接入完成后,切换到 ChatGPT 或其他 OpenAI 兼容服务时,核心业务写法基本保持不变,只需要替换密钥、地址和模型配置。

使用 ChatClient 构建对话

ChatClient 是 Spring AI 中面向业务开发的高阶 API。它封装了与大模型交互的大量细节,提供链式 Fluent API,适合快速实现对话、角色设定、结构化输出、流式响应和拦截增强。

最简单的对话接口可以这样写:

java 复制代码
@GetMapping("/call")
public String chat(String userInput) {
    return chatClient.prompt()
            .user(userInput)
            .call()
            .content();
}

如果希望给智能助手设置固定身份,可以通过默认系统消息完成:

java 复制代码
@Bean
public ChatClient chatClient(ChatClient.Builder builder) {
    return builder
            .defaultSystem("你是一名 Java 学习助手,擅长解释 Spring Boot 和 AI 应用开发问题")
            .build();
}

系统消息会作为对话的基础设定持续影响模型输出。它适合定义角色、语气、回答格式、安全边界和业务范围。

Spring AI 还支持结构化输出。比如让模型生成菜谱,并映射到 Java 对象:

java 复制代码
record Recipe(String dish, List<String> ingredients) {}

@GetMapping("/recipe")
public Recipe recipe(String name) {
    return chatClient.prompt()
            .user("请生成 " + name + " 的菜谱,返回菜名和食材列表")
            .call()
            .entity(Recipe.class);
}

这种写法适合菜单生成、信息抽取、表单填充、分类结果返回等场景。需要注意的是,结构化输出依赖模型按规范生成 JSON,系统提示词和用户提示词应尽量明确字段要求。

流式响应与 SSE

大模型生成长文本时,如果等全部内容完成后再返回,用户会感觉等待时间过长。流式响应的思路是让模型边生成边返回,前端可以逐步渲染结果。ChatClient 使用 stream() 返回响应流:

java 复制代码
@GetMapping(value = "/stream", produces = "text/html;charset=utf-8")
public Flux<String> stream(String userInput) {
    return chatClient.prompt()
            .user(userInput)
            .stream()
            .content();
}

Web 端常用 SSE,也就是 Server-Sent Events。它基于 HTTP,浏览器可通过 EventSource 接收服务端持续推送的数据。SSE 是单向通信,适合模型输出、日志推送、进度反馈等服务端主动返回内容的场景。服务端响应头通常需要声明:

http 复制代码
Content-Type: text/event-stream;charset=utf-8
Connection: keep-alive

SSE 的优点是轻量、兼容性好、部署简单,并且浏览器支持自动重连。对于聊天应用来说,它比一次性响应更接近真实对话体验。

用 Advisor 增强请求与响应

Spring AI 的 Advisor 类似面向 AI 调用链的中间件。它可以在请求发送前和响应返回后插入逻辑,用于日志、敏感词处理、上下文管理、对话记忆、RAG 检索增强等场景。

内置的 SimpleLoggerAdvisor 可以记录请求和响应,方便调试:

java 复制代码
@Bean
public ChatClient chatClient(ChatClient.Builder builder) {
    return builder
            .defaultSystem("你是一名 Java 学习助手")
            .defaultAdvisors(new SimpleLoggerAdvisor())
            .build();
}

也可以只在某次调用中添加 Advisor:

java 复制代码
return chatClient.prompt()
        .user(userInput)
        .advisors(new SimpleLoggerAdvisor())
        .call()
        .content();

如果要看到详细日志,可以在配置中打开对应日志级别:

yaml 复制代码
logging:
  level:
    org.springframework.ai.chat.client.advisor: debug

ChatModel 与 ChatClient 的关系

ChatModel 是更底层的模型交互接口,它接收 Prompt,返回 ChatResponse。开发者可以手动构造用户消息、系统消息和 Prompt,再调用模型:

java 复制代码
Prompt prompt = new Prompt(new UserMessage(message));
ChatResponse response = chatModel.call(prompt);

ChatClient 本质上是对 ChatModel 的封装和增强。ChatModel 更接近原子能力,适合需要精细控制 Prompt 和响应解析的场景;ChatClient 更适合业务开发,链式 API 更简洁,还内置 Advisor、结构化输出、流式响应等扩展能力。

实际项目中,常见选择是优先使用 ChatClient。当业务需要深入控制消息列表、模型参数或响应元数据时,再直接使用 ChatModel。

本地大模型与 Ollama

模型部署有云服务和本地部署两种常见方式。云服务前期成本低、维护简单、扩展方便,但依赖网络,数据需要发送到外部服务;本地部署前期成本和维护复杂度更高,但隐私性更好,长期成本也可能更低。

Ollama 是本地部署大语言模型的常用工具,支持 qwen、deepseek、LLaMA 等模型,并提供本地 API。安装完成后,默认服务地址通常是:

text 复制代码
http://127.0.0.1:11434

拉取模型时可以根据机器配置选择不同参数规模。参数量越大,模型能力通常越强,硬件压力也越高。以 DeepSeek-R1 轻量模型为例:

bash 复制代码
ollama run deepseek-r1:1.5b

Spring AI 接入 Ollama 时,添加 Ollama Starter:

xml 复制代码
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-ollama-spring-boot-starter</artifactId>
</dependency>

配置本地地址和模型:

yaml 复制代码
spring:
  ai:
    ollama:
      base-url: http://localhost:11434
      chat:
        model: deepseek-r1:1.5b

然后可以直接使用 OllamaChatModel 调用,也可以封装成 ChatClient,继续沿用统一的业务写法。

Spring AI Alibaba 与通义模型

对于使用阿里云生态的 Java 开发者,Spring AI Alibaba 提供了面向通义系列模型和百炼平台的适配。它基于 Spring AI 构建,提供 ChatClient、ChatModel、结构化输出、流式响应、向量数据库、函数调用、工具调用、对话记忆和 RAG 等能力。

使用前需要在阿里云百炼平台开通模型服务并创建 API Key。拿到密钥后,可以添加 Spring AI Alibaba 依赖:

xml 复制代码
<dependency>
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>spring-ai-alibaba-starter</artifactId>
    <version>1.0.0-M6.1</version>
</dependency>

配置示例:

yaml 复制代码
server:
  port: 8082
spring:
  ai:
    dashscope:
      api-key: sk-your-key

在 Controller 中注入 ChatClient 后,就可以调用通义模型:

java 复制代码
@RestController
@RequestMapping("/ali")
public class AliController {
    private final ChatClient chatClient;

    public AliController(ChatClient.Builder builder) {
        this.chatClient = builder
                .defaultSystem("你是一个博学的智能聊天助手")
                .defaultAdvisors(new SimpleLoggerAdvisor())
                .build();
    }

    @GetMapping("/chat")
    public String chat(String message) {
        return chatClient.prompt(message).call().content();
    }
}

由于 Spring AI Alibaba 沿用了 Spring AI 的核心抽象,流式响应、结构化输出、默认系统消息、默认用户消息、默认函数、Advisor 等能力都可以继续使用。

多模态能力

多模态指模型同时理解和处理文本、图像、音频、视频等多种信息的能力。人类认识世界并不只依赖文字,还会同时使用视觉、听觉、触觉等多种感知方式。多模态 AI 的目标也是把不同类型的数据融合起来理解。

传统聊天模型只处理文本;多模态模型则可以看图回答、图文结合问答、解析截图、理解设计草图并生成说明。使用阿里云通义视觉模型时,可以开启多模态配置:

yaml 复制代码
spring:
  ai:
    dashscope:
      api-key: sk-your-key
      chat:
        options:
          model: qwen-vl-max-latest
          multi-model: true

业务中可以把图片作为媒体输入,与文本提示词一起发送给模型。典型场景包括图片内容识别、商品图分析、报表截图解读、设计稿转需求说明等。

智能聊天机器人的实现路线

完成基础能力后,可以进一步实现一个智能聊天机器人。目标包括自然对话、流式返回、多轮上下文、历史记录管理,以及在本地模型和云端 API 之间灵活切换。

项目可以使用 Spring Boot Web、Spring AI Ollama Starter、Lombok 和 Spring AI BOM。配置文件中指定本地 Ollama 地址和模型:

yaml 复制代码
spring:
  application:
    name: spring-chat-bot
  ai:
    ollama:
      base-url: http://127.0.0.1:11434
      chat:
        model: deepseek-r1:7b
logging:
  level:
    org.springframework.ai.chat.client.advisor: debug

先定义 ChatClient:

java 复制代码
@Bean
public ChatClient ollamaChatClient(OllamaChatModel model) {
    return ChatClient.builder(model)
            .defaultSystem("你是一款学习助手,用清晰、友好的方式回答问题")
            .defaultAdvisors(new SimpleLoggerAdvisor())
            .build();
}

再实现流式对话接口:

java 复制代码
@RequestMapping(value = "/stream", produces = "text/html;charset=utf-8")
public Flux<String> stream(String prompt) {
    return chatClient.prompt()
            .user(prompt)
            .stream()
            .content();
}

此时机器人已经能回答问题,但还没有记忆。大语言模型本身通常是无状态的,如果希望它理解多轮对话,就要把历史消息与当前输入一起交给模型。Spring AI 提供了 ChatMemory,用于按照会话标识存储和读取消息。

java 复制代码
@Bean
public ChatMemory chatMemory() {
    return new InMemoryChatMemory();
}

把 ChatMemory 注入 ChatClient,并添加记忆 Advisor:

java 复制代码
@Bean
public ChatClient ollamaChatClient(OllamaChatModel model, ChatMemory chatMemory) {
    return ChatClient.builder(model)
            .defaultSystem("你是一款学习助手")
            .defaultAdvisors(
                    new SimpleLoggerAdvisor(),
                    new MessageChatMemoryAdvisor(chatMemory)
            )
            .build();
}

调用时传入 chatId,让不同会话相互隔离:

java 复制代码
@RequestMapping(value = "/stream", produces = "text/html;charset=utf-8")
public Flux<String> stream(String prompt, String chatId) {
    return chatClient.prompt()
            .user(prompt)
            .advisors(spec -> spec.param(
                    AbstractChatMemoryAdvisor.CHAT_MEMORY_CONVERSATION_ID_KEY,
                    chatId
            ))
            .stream()
            .content();
}

有了对话记忆后,还需要管理历史会话列表。可以定义 ChatInfo 保存标题和会话标识,再通过内存 Map 保存会话索引:

java 复制代码
@Data
public class ChatInfo {
    private String title;
    private String chatId;
}

历史记录接口通常包含这些能力:保存会话、获取会话列表、根据 chatId 读取最近若干条消息、删除指定会话。读取消息时,可以把 Spring AI 的 Message 转成前端更容易使用的 VO,例如包含 role 和 content 字段。

如果后续要从本地 Ollama 切换到 DeepSeek 开放 API,只需要添加 OpenAI Starter,改为 OpenAI 兼容配置,并把 ChatClient 构建时注入的模型从 OllamaChatModel 换成 OpenAiChatModel:

yaml 复制代码
spring:
  ai:
    openai:
      api-key: sk-your-key
      base-url: https://api.deepseek.com
      chat:
        options:
          model: deepseek-chat
          temperature: 0.7
java 复制代码
@Bean
public ChatClient deepSeekChatClient(OpenAiChatModel model, ChatMemory chatMemory) {
    return ChatClient.builder(model)
            .defaultSystem("你是一款学习助手")
            .defaultAdvisors(
                    new SimpleLoggerAdvisor(),
                    new MessageChatMemoryAdvisor(chatMemory)
            )
            .build();
}

这正是 Spring AI 抽象带来的好处:上层接口、流式返回、记忆和历史管理逻辑基本不需要重写,底层模型服务可以根据成本、效果和部署要求进行替换。

总结

Spring AI 让 Java 开发者可以用熟悉的 Spring Boot 方式构建 AI 应用。入门时先理解模型、提示词、Tokens、ChatClient 和 ChatModel,再接入 DeepSeek 或 OpenAI 兼容服务;随后加入流式响应、日志 Advisor、结构化输出和 SSE;当需要私有化能力时,可以使用 Ollama 部署本地模型;当使用阿里云生态时,可以通过 Spring AI Alibaba 接入通义模型和多模态能力。

最终落到业务应用,智能聊天机器人并不只是一个调用大模型的接口。它需要角色设定、流式体验、对话记忆、历史记录、会话隔离,以及灵活切换模型服务的能力。把这些能力组合起来,才是一个可扩展、可维护、接近真实业务需求的 Spring AI 应用。

相关推荐
英辰朗迪AI获客1 小时前
英辰朗迪GEO知识库第188期:动态渲染站点在AI搜索里成了隐形人
人工智能
硅谷秋水2 小时前
MorphMimic 方法分析
人工智能·机器学习·计算机视觉·机器人
MobotStone2 小时前
AI 能不能越用越会用?从“改答案”到“改进自己”,读懂 RSI
人工智能·算法
下一站春风里2 小时前
Spring IoC 控制反转 完整技术笔记
java·spring boot·笔记·spring
挖掘狂人2 小时前
用户连点两次「确认支付」,你的后端凭什么只扣一次钱?
java·后端·面试
jay神2 小时前
基于 YOLOv8 的传送带异物检测系统(Web 版)
前端·人工智能·深度学习·yolo·计算机视觉·计算机毕业设计
codigger2 小时前
用户连点两次「确认支付」,你的后端凭什么只扣一次钱?
java·程序员·支付·java后端
Resean02232 小时前
SpringMVC 6+源码分析(十)数据绑定与类型转换
java·spring·springmvc
lw_zhang11012 小时前
爆肝一个月,Java 从入门到精通39 - 使用Log4j
java·单元测试·log4j
复杂网络与机器学习3 小时前
Meta 重写 K-Means:25 轮压成 2 轮,GPU 快 45 倍
人工智能·算法·数据挖掘