【Spring AI 】核心知识体系梳理：从入门到实战

文章目录

- [一、Spring AI 是什么？](#一、Spring AI 是什么？)
- - [1.1 框架定位](#1.1 框架定位)
  - [1.2 核心能力](#1.2 核心能力)
- 二、核心术语
- - [2.1 模型（Model）](#2.1 模型（Model）)
  - [2.2 大语言模型（LLM）](#2.2 大语言模型（LLM）)
  - [2.3 提示词（Prompt）](#2.3 提示词（Prompt）)
  - [2.4 词元（Tokens）](#2.4 词元（Tokens）)
- 三、核心接口
- - [3.1 ChatModel vs ChatClient](#3.1 ChatModel vs ChatClient)
  - [3.2 角色预设（System Message）](#3.2 角色预设（System Message）)
  - [3.3 结构化输出](#3.3 结构化输出)
  - [3.4 流式输出](#3.4 流式输出)
  - [3.5 Advisor 机制](#3.5 Advisor 机制)
- 四、多模型接入实战
- - [4.1 接入 DeepSeek](#4.1 接入 DeepSeek)
  - [4.2 本地部署 Ollama](#4.2 本地部署 Ollama)
  - [4.3 接入阿里云百炼](#4.3 接入阿里云百炼)
- 五、对话记忆实现
- - [5.1 核心原理](#5.1 核心原理)
  - [5.2 ChatMemory 接口](#5.2 ChatMemory 接口)
  - [5.3 实战配置](#5.3 实战配置)
- 六、多模态能力
- 七、最佳实践速查
- - [7.1 环境要求](#7.1 环境要求)
  - [7.2 BOM 依赖管理](#7.2 BOM 依赖管理)
  - [7.3 关键设计决策](#7.3 关键设计决策)
- 八、总结

一、Spring AI 是什么？

1.1 框架定位

Spring AI 是 Spring 官方推出的 AI 工程领域应用框架，2025年5月20日发布 1.0 GA 版本。其核心目标是：

将 Spring 生态的设计原则（可移植性、模块化设计）应用于 AI 领域
帮助 Java/Spring 开发者便捷地在企业级应用中集成 AI 能力
提供标准化的 AI 开发工具链

1.2 核心能力

能力	说明
多模型提供商支持	OpenAI、DeepSeek、Ollama、Google、Amazon、Anthropic 等
跨提供商可移植 API	统一的 Chat、Image、Embedding 接口
同步/流式 API	支持 call() 和 stream() 两种调用方式
结构化输出	将 AI 响应自动映射为 POJO
Advisor 机制	AOP 风格拦截器，支持日志、记忆、RAG 等增强功能

二、核心术语

2.1 模型（Model）

模型是经过大规模数据训练后形成的"规则集合"，能够根据输入产生相应输出。

类比：咖啡师根据点单（输入）运用技能（模型）制作咖啡（输出）
Spring AI 的作用：让我们在 Java 应用中方便地选择模型、构造输入、处理输出

2.2 大语言模型（LLM）

专门处理文本的 AI 模型，参数规模庞大（数十亿级），在大量文本数据上训练。

主流 LLM 对比：

模型	特点
GPT-5 (OpenAI)	128K 长上下文，创意写作突出
DeepSeek-R1	开源，专注逻辑推理与数学求解
Qwen2.5-72B	擅长代码生成、结构化数据处理
Gemini 2.5 Pro	多模态融合，支持图文混合输入

2.3 提示词（Prompt）

用户或系统提供给 LLM 的指令文本，用于引导模型生成特定输出。

两类提示词：

类型	定义	示例
用户提示词	终端用户直接输入	"总结这篇论文的核心观点"
系统提示词	开发者预设，定义角色和行为规范	"你是一名严谨的学术助手"

2.4 词元（Tokens）

LLM 处理文本的最小语义单位，通过分词器拆分文本而来。

关键认知：

上下文窗口大小 = Token 数量限制（如 128K）
API 计费通常按 Token 数计算
开发时应避免冗余词汇，降低成本

三、核心接口

3.1 ChatModel vs ChatClient

Spring AI 提供两个核心接口用于与大模型交互：

维度	ChatModel	ChatClient
定位	底层接口，直接与模型交互	高阶封装，简化开发流程
使用方式	手动构建 Prompt、解析响应	链式 API，自动封装
结构化输出	手动解析文本	`.entity(Class)` 自动映射
扩展能力	依赖外部组件	内置 Advisor 机制
适用场景	精细控制模型参数、实验调优	快速构建 AI 服务

ChatModel 基础用法：

java 复制代码

@Autowired
private OpenAiChatModel openAiChatModel;

public String generate(String message) {
    return openAiChatModel.call(message);
}

ChatClient 基础用法：

java 复制代码

private final ChatClient chatClient;

public ChatController(ChatClient.Builder builder) {
    this.chatClient = builder.build();
}

public String generation(String userInput) {
    return this.chatClient.prompt()
            .user(userInput)
            .call()
            .content();
}

3.2 角色预设（System Message）

通过系统消息定义 AI 的角色和行为规范：

java 复制代码

@Bean
public ChatClient chatClient(ChatClient.Builder builder) {
    return builder
            .defaultSystem("你叫小特，是比特科技的智能助手，精通Java和C++")
            .build();
}

3.3 结构化输出

将 AI 响应自动映射为 Java 对象：

java 复制代码

record Recipe(String dish, List<String> ingredients) {}

@GetMapping("/entity")
public Recipe entity(String userInput) {
    return chatClient.prompt()
            .user(String.format("请帮我生成%s的食谱", userInput))
            .call()
            .entity(Recipe.class);
}

3.4 流式输出

实现类似 ChatGPT 的逐字输出效果：

java 复制代码

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

技术背景：流式输出基于 SSE（Server-Sent Events）协议，服务器保持连接开放，持续推送数据流。

3.5 Advisor 机制

Advisor 是介于用户请求与 AI 模型之间的中间件，基于 AOP 思想实现，支持请求拦截和增强。

内置 SimpleLoggerAdvisor：

java 复制代码

@Bean
public ChatClient chatClient(ChatClient.Builder builder) {
    return builder
            .defaultSystem("...")
            .defaultAdvisors(new SimpleLoggerAdvisor())
            .build();
}

应用场景：

日志记录
敏感词过滤
对话记忆管理
RAG 上下文增强

四、多模型接入实战

4.1 接入 DeepSeek

依赖：

xml 复制代码

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

配置：

yaml 复制代码

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

4.2 本地部署 Ollama

Ollama 是简化大模型本地部署的开源工具。

安装与拉取模型：

bash 复制代码

# 验证安装
ollama --version

# 拉取模型（根据机器配置选择版本）
ollama pull deepseek-r1:1.5b

# 运行模型
ollama run deepseek-r1:1.5b

Spring AI 接入配置：

yaml 复制代码

spring:
  ai:
    ollama:
      base-url: http://localhost:11434
      chat:
        model: deepseek-r1:1.5b

4.3 接入阿里云百炼

依赖：

xml 复制代码

<dependency>
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>spring-ai-alibaba-starter</artifactId>
    <version>1.0.0-M6.1</version>
</dependency>

配置：

yaml 复制代码

spring:
  ai:
    dashscope:
      api-key: sk-XXXXXX

五、对话记忆实现

5.1 核心原理

LLM 本身是无状态的，要实现多轮对话记忆，需要将历史对话与新的提示词一起发送给模型。

5.2 ChatMemory 接口

Spring AI 提供 ChatMemory 接口管理对话历史：

java 复制代码

public interface ChatMemory {
    void add(String conversationId, List<Message> messages);
    List<Message> get(String conversationId, int lastN);
    void clear(String conversationId);
}

5.3 实战配置

java 复制代码

@Bean
public ChatMemory chatMemory() {
    return new InMemoryChatMemory();
}

@Bean
public ChatClient chatClient(ChatModel model, ChatMemory chatMemory) {
    return ChatClient.builder(model)
            .defaultSystem("你是智能助手小特")
            .defaultAdvisors(new MessageChatMemoryAdvisor(chatMemory))
            .build();
}

@GetMapping("/stream")
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();
}

六、多模态能力

多模态指模型同时理解和处理文本、图像、音频等多种信息的能力。

视觉理解示例（基于阿里云通义千问 VL）：

yaml 复制代码

spring:
  ai:
    dashscope:
      api-key: sk-XXX
      chat:
        options:
          model: qwen-vl-max-latest
          multi-model: true

java 复制代码

@GetMapping("/image")
public String image(String prompt) throws Exception {
    String url = "https://example.com/image.jpg";
    List<Media> mediaList = List.of(
        new Media(MimeTypeUtils.IMAGE_PNG, new URI(url).toURL())
    );
    
    UserMessage message = UserMessage.builder()
            .text(prompt)
            .media(mediaList)
            .build();
    
    ChatResponse response = chatClient.prompt(new Prompt(message))
            .call()
            .chatResponse();
    
    return response.getResult().getOutput().getText();
}

七、最佳实践速查

7.1 环境要求

组件	最低版本	推荐版本
JDK	17+	21（支持虚拟线程）
Spring Boot	3.2+	3.4.x

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

7.3 关键设计决策

场景	推荐方案
快速原型开发	ChatClient + DeepSeek API
数据安全要求高	Ollama 本地部署
阿里云生态整合	Spring AI Alibaba
需要多轮对话	ChatMemory + MessageChatMemoryAdvisor
长文本生成	流式输出（SSE）
需要结构化数据	`.entity(Class)` 自动映射

八、总结

ChatClient 是主要入口：链式 API 简化开发，优先使用
Advisor 是扩展核心：日志、记忆、RAG 都基于此机制
模型切换成本极低：统一 API 抽象，改配置即可切换提供商