1. Spring AI简介

在当今这样一个快速发展的技术时代，人工智能（AI）已经成为各行各业的一种标配。而作为一款主流的Java应用开发框架Spring，肯定会紧跟时代的潮流，所以，推出了Spring AI框架。

1.1 Spring AI是什么

官网 https://spring.io/projects/spring-ai

1.1.1 概述

Spring AI 是一个面向 AI 工程的应用框架。它的目标是把 Spring 生态系统中的设计原则（例如可移植性、模块化设计等）应用到 AI 领域，并推动在 AI 应用中使用 POJO（普通 Java 对象）作为应用的构建模块。

其核心在于解决 AI 集成的基础性挑战：将你的企业数据（Data）和 API 与 AI 模型连接起来。

特性（Features）
Spring AI 提供以下功能：

• 支持所有主要的 AI 模型供应商（Model providers），包括 Anthropic、OpenAI、Microsoft、Amazon、Google，以及 Ollama。支持的模型类型有：

  • 聊天补全（Chat Completion）
  • 嵌入（Embedding）
  • 文本生成图像（Text to Image）
  • 音频转录（Audio Transcription）
  • 文本转语音（Text to Speech）
  • 内容审核 / Moderation（Moderation）

• 对不同 AI 提供商的 API，支持同步（synchronous）和流式（streaming）调用方式，同时也可以访问特定模型（model-specific）的特性。

• 结构化输出（Structured Outputs） —— 将 AI 模型的输出映射为 POJOs（方便在 Java 环境中处理）

• 支持主要的向量数据库（Vector Database）提供商（Providers），例如 Apache Cassandra、Azure Vector Search、 Chroma、Milvus、MongoDB Atlas、Neo4j、Oracle、PostgreSQL/PGVector、PineCone、Qdrant、Redis、Weaviate 等等。

• 在向量存储提供商之间提供可移植 API（Portable API），包括一个类 SQL 的元数据过滤 API（metadata filter API）。

• 支持工具 / 函数调用（Tools / Function Calling）——即模型可以请求执行客户端的工具或函数，以便在必要时访问实时的信息。

• 可观测性（Observability） — 提供 AI 相关操作的可监控、可视化洞见。

• 文档注入（Document injection）以及用于数据工程的 ETL 框架。

• AI 模型评估（AI Model Evaluation） — 包括用于评估生成内容的工具，并帮助防止“幻觉”（hallucinated responses）的问题。

• ChatClient API — 用于与 AI 聊天模型通信的 Fluent API，其风格类似于 Spring 的 WebClient 和 RestClient。

• Advisors API — 封装了常用的生成式 AI 模式，负责变换语言模型（LLM）之间或发送／接收的内容，并为不同模型和用例提供可移植性。

• 支持聊天对话记忆（Chat Conversation Memory）和检索增强生成（Retrieval Augmented Generation, RAG）等功能。

• Spring Boot 的自动配置（Auto Configuration）和 Starter（启动器）支持所有 AI 模型和向量存储 —— 你可以用 Spring Initializr 来选择你想用的模型或向量存储。

这些功能组合起来，使你可以实现诸如 “在你的文档上做问答 (Q&A over your documentation)” 或 “与你的文档进行聊天 (Chat with your documentation)” 这样的常见用例。

1.2 发布版本

写这篇文章的时间是2025年09月20日，可以看到已经有了

• 1.0.1 Current (当前稳定版)
• 1.1.0-SNAPSHOT（开发中的快照版本）
• 1.1.0-M1（预发布版本 Milestone 1）

1.3 Spring AI的主要功能

• 第一、 对主流 AI 大模型供应商提供了支持，比如：OpenAI、DeepSeek、Microsoft、Ollama、Amazon、Google HuggingFace等。
• 第二、 支持AI大模型类型包括：聊天、文本到图像、文本到声音等。
• 第三、 支持主流的Embedding Models（嵌入模型）和向量数据库，比如：Azure Vector Search、Chroma、Milvus、Neo4j、Redis、PineCone、PostgreSQL/PGVector 等。
• 第四、 把 AI 大模型输出映射到简单的 Java 对象（POJOs）上。
• 第五、 支持了函数调用（Function calling）功能。
• 第六、 为数据工程提供 ETL（数据抽取、转换和加载）框架。
• 第七、 支持 Spring Boot 自动配置和快速启动，便于运行 AI 模型和管理向量库。

2. 结合DeepSeek上手使用

2.1 准备工作

DeepSeek 是一款由深度求索所开发的 AI 人工智能大模型，其基于深度学习和多模态数据融合技术，采用先进的 Transformer 架构和跨模态协同算法，可实现对复杂文档和图像的自动化解析与结构化信息提取。

依托于最新推出的“深度思考”模式（R1），这款AI大模型在极低成本下实现了与国际顶尖模型ChatGPT-o1相媲美的性能表现，其中文理解与输出能力更是远超ChatGPT、Claude等顶尖模型。再加上极具竞争力的API定价和全面开源的策略，让这款AI大模型成功在国际上火爆出圈

如果说AI是一个广泛的概念，那么DeepSeek就是是AI领域中的一个具体产品。

DeepSeek的特点‌：

• 成本‌：DeepSeek致力于降低AI应用的成本。通过采用先进的技术和独特的模型架构，DeepSeek在保持高性能的同时，显著降低了推理和训练的成本。
• 性能‌：DeepSeek在性能上表现出色。它使用强化学习技术训练，推理过程中包含大量反思与验证，能够处理更加复杂的数据和任务。在一些benchmark测试中，其性能与OpenAI的模型相当，但推理成本远低于同类产品。
• 功能‌：DeepSeek擅长处理数学、编程和复杂逻辑推理等任务。它的推理能力源于深度思考特性，推理长度与准确率呈正相关。此外，DeepSeek还支持多模态信息处理，能够应对更加多样化的应用场景。
• 应用领域‌：DeepSeek在多个领域展现出巨大的应用潜力。无论是在医疗、教育、交通等传统领域，还是在智能制造、智慧城市等新兴领域，DeepSeek都有望发挥重要作用。

综上所述，AI是一个广泛的概念，涵盖了人工智能领域的所有技术和应用。而DeepSeek则是AI领域中的一个具体产品，它在成本、性能、功能和应用领域等方面都有着独特的特点和优势。两者之间的关系可以理解为：DeepSeek是AI领域中的一个具体实现和优秀代表。

如何使用Java集成DeepSeek：

DeepSeek 作为一款卓越的国产 AI 模型，越来越多的公司考虑在自己的应用中集成。对于 Java 应用来说，我们可以借助 Spring AI 集成 DeepSeek，非常简单方便！

2.2 DeepSeek开放平台创建API KEY

DeepSeek官网 https://www.deepseek.com/
接口文档 https://api-docs.deepseek.com/zh-cn/

在官网上创建api key 注意是需要充值的！

使用curl调用

2.3 实现简单对话

新建一个Maven项目

其中父类的pom依赖

子类springai_hello
application.yml

temperature参数用于控制生成文本的多样性。具体来说：
‌值越高‌，生成的文本越多样化，但也可能包含更多的随机性和不可预测的内容。 ‌值越低‌，生成的文本越接近于确定性的结果，即生成的文本会更加一致和可预测。

子类的pom

配置文件
ChatModelConfig

Controller

方法	作用
prompt()	提示词
user(message)	设置用户消息
call()	发送请求给模型，获取响应
content()	获取模型生成的文本内容

3. Spring AI的聊天模型

3.1 概述

Spring AI的聊天模型API为开发者提供了一条便捷通道，能够将强大的AI驱动的聊天完成功能无缝集成到各类应用中。借助预先训练的语言模型，如广为人知的GPT，它能够依据用户输入生成自然流畅、类人化的回复。这一API不仅工作机制高效，而且设计理念极为先进，旨在实现简单易用与高度可移植性，让开发者能以极少的代码改动在不同AI模型间自由切换，充分契合Spring框架一贯秉持的模块化与可互换性原则。

3.2 ChatClient接口

Spring AI 的 ChatClient 是一个面向开发者的无状态 AI 对话客户端，提供了基于流式/非流式调用的统一 API，用于和不同的 大语言模型（LLM）（如 OpenAI、Ollama、Azure OpenAI、Anthropic 等）交互。

3.2.1 ChatClient接口定位与作用

• ChatClient 是 Spring AI 提供的统一客户端接口，用来调用各种大语言模型（LLM）。

• 目标类似：

  • RestTemplate（同步 HTTP 调用）
  • WebClient（响应式 HTTP 调用）

• 作用是：对接底层模型（OpenAI、Azure、Ollama、Anthropic…）时，开发者不需要关心底层 SDK，直接用统一 API 就能发请求、收响应。

换句话说：ChatClient 是 AI 领域的统一编程入口。

3.2.2 ChatClient接口核心特点

1. 统一 API：不管调用哪个模型，写法都一致。

2. Prompt 构建：支持 system / user / 多消息角色。

3. 调用模式：

   • 同步调用（一次性返回完整答案）
   • 流式调用（逐 Token 实时输出，基于 Reactor Flux）

4. 扩展能力：

   • Advisor：对话增强器（类似拦截器/AOP）
   • Tool / Function Calling：让 AI 调用外部函数或服务
   • Structured Output：LLM 输出直接转为 Java 对象

5. 监控集成：支持 Micrometer / Tracing

3.2.3 核心接口与用法

① 创建 ChatClient

---

② 构建 Prompt

支持从文件、模板、参数化：

---

③ 调用方式

• 同步调用

• 流式调用

---

④ Advisor（对话增强器）

Advisor = 对话拦截器，可以在请求前/响应后增强。

例如：追加上下文、敏感词过滤、打日志。

---

⑤ 工具调用（Function Calling）
AI 可以自动触发你的函数：

---

⑥ 结构化输出
让模型返回 JSON → 自动转为对象：

---

⑦ 完整响应对象

3.3 最佳实践

1. 在配置类统一定义 ChatClient Bean，避免重复创建。
2. 同步调用适合短回答，流式调用适合长文本。
3. Advisor 可以做安全过滤/上下文增强。
4. 工具调用要加参数验证/Schema，减少错误调用。
5. 结合 Micrometer 做监控，分析 token 消耗与调用时延。

3.4 流式输出

4. 一个接口使用不同的大模型

4.1 多厂商模型的调用方式

Spring AI 的关键类是 ChatClient，其调用流程大概如下：

这里 chatClient 可以通过配置绑定不同厂商：

• OpenAI
• Azure OpenAI
• Anthropic
• 自定义大模型（DeepSeek、千问等）

Spring AI 的 核心扩展点是 ChatModel 和 ChatClient 的实现：

• chatModels 是你可以注入的所有模型。
• Spring AI 内部会根据模型 id 或 type 决定使用哪个厂商。

配置不同厂商的模型
Spring AI 允许你在配置文件或代码中声明多个模型：

然后在代码里通过 ChatClient 调用时选择模型：

⚡ 关键点：model(“模型名”) 就是多厂商支持的入口。

如果 Spring AI 还没有内置 DeepSeek 或千问模型，你可以自定义实现 ChatModel：
然后 Spring AI 就能像调用内置模型一样调用你的自定义模型。

5. 提示词

• 提示词是引导大模型生成特定输出的输入，提示词的设计和措辞会极大地影响模型的响应结果。

• Prompt 提示词是与模型交互的一种输入数据组织方式，本质上是一种复合结构的输入，在 prompt 我们是可以包含多组不同角色（System、User、Aissistant等）的信息。如何管理好 Prompt 是简化 AI 应用开发的关键环节。

• Spring AI 提供了 Prompt Template 提示词模板管理抽象，开发者可以预先定义好模板，并在运行时替换模板中的关键词。在 Spring AI 与大模型交互的过程中，处理提示词首先要创建包含动态内容占位符 {占位符} 的模板，然后，这些占位符会根据用户请求或应用程序中的其他代码进行替换。在提示词模板中，{占位符} 可以用 Map 中的变量动态替换。

6. Spring AI的函数调用

• Spring AI 的函数调用（Function Calling）功能允许大语言模型在生成回答时触发预定义的外部函数，从而实现动态数据获取或业务逻辑操作（如查询数据库、调用 API 等）。

• SpringAI 帮我们规范了函数定义、注册等过程，并在发起模型请求之前自动将函数注入到 Prompt 中，而当模型决策在合适的时候去调用某个函数时，Spring AI 完成函数调用动作，最终将函数执行结果与原始问题再一并发送给模型，模型根据新的输入决策下一步动作。这其中涉及与大模型的多次交互过程，一次函数调用就是一次完成的交互过程。

• 函数调用的核心流程

• 第一步，定义函数：声明可供模型调用的函数（名称、描述、参数结构）。

• 第二步，模型交互：将函数信息与用户输入一起发送给模型，模型决定是否需要调用函数。

• 第三步，执行函数：解析模型的函数调用请求，执行对应的业务逻辑。

• 第四步，返回结果：将函数执行结果返回给模型，生成最终回答。

6.1 函数调用实现

6.1.1 创建自定义的Function

• 下面CalculatorService类自定义了加法和乘法运算的函数

总结：
Spring AI 使自定义函数这个过程变得简单，只需定义一个返回 java.util.Function 的 @Bean 定义，并在调用 ChatModel 时将 bean 名称作为选项进行注册即可。在底层，Spring 会用适当的适配器代码包装你的函数，以便与 AI 模型进行交互，免去了编写繁琐的代码。

6.1.2 编写Controller

• 为了让模型知道并调用你的自定义函数，您需要在 Prompt 请求中启用它，如上述代码，在functions("addOperation", "mulOperation")中告知ChatClient要使用这两个自定义函数。
• 另外指定了System Prompt：要求AI 模型被设定为一个算术计算器代理，能够执行加法和乘法运算，并且要求用户提供两个数字和运算类型。这个提示词内容很关键，如何让AI按照自己的意图去执行，要不断测试提示词内容。

6.1.3 测试

7. SpringAI调用Ollama

7.1 什么是Ollama

Ollama官方地址 https://ollama.com/

Ollama 是一个 在本地运行大模型（LLM） 的工具和平台。

它的核心目标是：
👉 让你在 自己的电脑上（Mac、Linux、Windows）非常方便地下载、运行和管理大语言模型（类似 OpenAI 的 GPT、Meta 的 LLaMA、Mistral 等）。

换句话说：

• 如果 Hugging Face 更像是“模型超市”，
• 那么 Ollama 就是“本地模型的运行时 + 包管理器”。

🚀 Ollama 的主要特点

1. 开箱即用

安装 Ollama 后，只需要一条命令就能启动一个大模型：
ollama run llama2
它会自动下载模型文件并运行，无需自己折腾复杂的依赖。

2. 支持多种模型

• 内置支持：LLaMA 2、Mistral、Phi-3、CodeLLaMA、Gemma 等

• 也可以加载自定义模型（通过 Modelfile 配置）。

3. 轻量化 & 本地推理

• 针对消费级电脑优化，能在 MacBook 或普通 PC 上跑小规模 LLM。
• 底层用的是 GGUF 格式的量化模型文件，显存/内存占用更低。

4. 简单的 API 调用

提供一个类似 OpenAI API 的接口：

这让它可以无缝接入到各种应用里（比如 LangChain、Spring AI）。

5. 跨平台

最初只支持 macOS，现在已经支持 Linux 和 Windows。

6. 隐私和安全

所有数据和模型都在本地运行，不会上传到云端 → 适合对数据安全要求高的场景。

7.2 使用Docker安装

-v ollama:/root/.ollama
数据卷映射，把宿主机的 ollama 数据卷挂载到容器内的 /root/.ollama 目录。
/root/.ollama 是 Ollama 存储模型文件、配置文件 的地方。
好处：即使容器删除，模型文件也会保留，不需要每次重新下载。

进入容器跑大模型

启动大模型

7.3 SpringAI结合Ollama

8. 图像模型

8.1 Image Model API概述

• 在Spring AI框架中，Image Model API旨在为与专注于图像生成的各种AI模型进行交互提供一个简单且可移植的接口，使开发者能够以最小的代码改动切换不同的图像相关模型。这一设计符合Spring模块化和互换性的理念，确保开发者可以快速调整其应用程序以适应不同的图像处理相关的AI能力。

• 此外，通过支持像ImagePrompt这样的辅助类来进行输入封装以及使用ImageResponse来处理输出，图像模型API统一了与致力于图像生成的AI模型之间的通信。它管理请求准备和响应解析的复杂性，为图像生成功能提供直接而简化的API交互。

• Image Model API建立在Spring AI通用模型API之上，提供了特定于图像的抽象和实现。

8.2 Image Model API接口及相关类

8.2.1 ImageModel（图像模型）

这里展示的是ImageModel接口定义：

8.2.2 ImagePrompt（图像提示）

ImagePrompt是一个封装了ImageMessage对象列表及可选模型请求选项的ModelRequest。下面显示的是ImagePrompt类的一个简化版本，省略了构造函数和其他工具方法：

8.2.3 ImageMessage（图像消息）

ImageMessage类封装了用于影响生成图像的文本及其权重。对于支持权重的模型，它们可以是正数或负数。

8.2.4 ImageOptions（图像选项）

表示可以传递给图像生成模型的选项。ImageOptions接口扩展了ModelOptions接口，并用于定义可以传递给AI模型的一些可移植选项。

8.2.5 ImageResponse（图像响应）

持有AI模型的输出，每个ImageGeneration实例包含来自单一提示的可能多个输出结果之一。

8.2.6 ImageGeneration（图像生成）

最终，ImageGeneration类扩展自ModelResult，代表输出响应及有关此结果的元数据。

P13 TODO

附录

1.炸裂！Spring AI 1.0 正式发布 https://zhuanlan.zhihu.com/p/1909928795659567609
2.【尚硅谷SpringAI实战教程，springai轻松上手大模型应用开发】 https://www.bilibili.com/video/BV1Cxj7zjEng/?p=9&share_source=copy_web&vd_source=6888e998072955ff0cd273996df291f5
3.【2025吃透Spring AI 1.0全套教程（入门+实战+原理&源码；大模型+tools+mcp+Agent全流程落地），7天学完，让你少走99%弯路！！】https://www.bilibili.com/video/BV1z7h3zbEd2/?share_source=copy_web&vd_source=6888e998072955ff0cd273996df291f5