type
Post
status
Published
date
Jun 2, 2025 09:10 AM
slug
summary
Spring AI 常用基本使用方法以及常见 API
tags
开发
Java
category
技术知识
icon
password
快速开始
模型
使用教程
基础框架
ChatClient
ChatClient 提供了与 AI 模型通信的 Fluent API，它支持同步和反应式（Reactive）编程模型。与 ChatModel、Message、ChatMemory 等原子 API 相比，使用 ChatClient 可以将与 LLM 及其他组件交互的复杂性隐藏在背后，因为基于 LLM 的应用程序通常要多个组件协同工作（例如，提示词模板、聊天记忆、LLM Model、输出解析器、RAG 组件：嵌入模型和存储），并且通常涉及多个交互，因此协调它们会让编码变得繁琐。 当然使用 ChatModel 等原子 API 可以为应用程序带来更多的灵活性，成本就是您需要编写大量样板代码。 ChatClient 类似于应用程序开发中的服务层，它为应用程序直接提供 AI 服务，开发者可以使用 ChatClient Fluent API 快速完成一整套 AI 交互流程的组装。 包括一些基础功能，如：定制和组装模型的输入（Prompt） 格式化解析模型的输出（Structured Output） 调整模型交互参数（ChatOptions）聊天记忆（Chat Memory） 工具/函数调用（Function Calling） RAG
ChatClient 创建
使用自动配置的 ChatClient.Builder
定制 ChatClient
开发者可以通过修改 ChatClient.Builder 定制 ChatClient 实例，此后创建 ChatClient 时将指定配置作为与模型交互时的默认参数，避免重复设置。
可以在运行时使用
ChatClient 提供的不带 default 前缀的相应方法覆盖这些默认值。ㅤ | ㅤ |
defaultSystem | 传入 ChatOptions 类中定义的可移植选项或特定于模型实现的如 DashScopeChatOptions 选项。 |
defaultOptions
(ChatOptions chatOptions) | name 用于在用户文本中引用该函数，description解释该函数的用途并帮助 AI 模型选择正确的函数以获得准确的响应，参数 function 是模型将在必要时执行的 Java 函数实例。 |
defaultFunctions(String... functionNames) | 应用程序上下文中定义的 java.util.Function 的 bean 名称。 |
defaultUser(String text)、defaultUser(Resource text)、defaultUser(Consumer<UserSpec> userSpecConsumer) | 允许您定义用户消息输入，Consumer<UserSpec>允许您使用 lambda 指定用户消息输入和任何默认参数。 |
defaultAdvisors(RequestResponseAdvisor... advisor) | dvisors 允许修改用于创建 Prompt 的数据，QuestionAnswerAdvisor 实现通过在 Prompt 中附加与用户文本相关的上下文信息来实现 Retrieval Augmented Generation 模式。 |
defaultAdvisors(Consumer<AdvisorSpec> advisorSpecConsumer) | 允许您定义一个 Consumer 并使用 AdvisorSpec 配置多个 Advisor，Advisor 可以修改用于创建 Prompt 的最终数据，Consumer<AdvisorSpec> 允许您指定 lambda 来添加 Advisor 例如 QuestionAnswerAdvisor。 |
在 Controller 中使用这个 ChatClient
以编程方式创建
可以通过设置属性 spring.ai.chat.client.enabled=false 来禁用 ChatClient.Builder bean 的自动配置，如果需要多个聊天模型一起使用，这会很有用，然后以编程方式创建 ChatClient.Builder，这样可以为每个聊天模型创建一个实例 ChatModel
ChatClient 执行与响应
call()
- String content()：返回响应的字符串内容
- ChatResponse chatResponse() 返回ChatResponse包含多个代以及有关响应的元数据的对象，例如，使用了多少个令牌来创建响应。
- entity 返回 Java 类型
- entity(ParameterizedTypeReference type) 用于返回实体类型的集合。
- entity(Class type): 用于返回特定的实体类型。
- entity(StructuredOutputConverter structuredOutputConverter): 用于指定一个实例 StructuredOutputConverter，将 String 转换为实体类型。
stream
还可以调用该stream方法而call不是，在指定stream方法后ChatClient，响应类型有几个选项：
- Flux<String> content() 返回由AI模型生成的字符串的Flux。
- Flux<ChatResponse> chatResponse() 返回对象的 Flux ChatResponse，其中包含有关响应的附加元数据。
流式响应
stream 方法是一种异步的、持续的获得模型响应的方式：
Advisors
在使用用户输入文本构建 Prompt 调用 AI 模型时，一个常见模式是使用上下文数据附加或扩充 Prompt，最终使用扩充后的 Prompt 与模型交互。
这些用于扩充 Prompt 的上下文数据可以是不同类型的，常见类型包括：
您自己的数据：这是 AI 模型尚未训练过的数据，如特定领域知识、产品文档等，即使模型已经看到过类似的数据，附加的上下文数据也会优先生成响应。
对话历史记录：聊天模型的 API 是无状态的，如果您告诉 AI 模型您的姓名，它不会在后续交互中记住它，每次请求都必须发送对话历史记录，以确保在生成响应时考虑到先前的交互。
检索增强生成 RAG
向量数据库存储的是 AI 模型不知道的数据，当用户问题被发送到 AI 模型时，QuestionAnswerAdvisor 会在向量数据库中查询与用户问题相关的文档。
来自向量数据库的响应被附加到用户消息 Prompt 中，为 AI 模型生成响应提供上下文。
假设您已将数据加载到中 VectorStore，则可以通过向 ChatClient 提供 QuestionAnswerAdvisor 实例来执行检索增强生成 (RAG ) 。
在此示例中，SearchRequest.defaults() 将对 Vector 向量数据库中的所有文档执行相似性搜索。
为了限制要搜索的文档类型，SearchRequest 采用了可移植到任意向量数据库中的类似 SQL 筛选表达式，使用 FILTER_EXPRESSION Advisor 上下文参数在运行时更新过滤表达式.
聊天记忆
ChatMemory 接口表示聊天对话历史记录的存储，它提供向对话添加消息、从对话中检索消息以及清除对话历史记录的方法。当在 Spring AI 中定义 ChatClient 并通过 ChatMemory 和 Advisor 进行配置后，使用该实例进行对话后，对话消息会自动记录到指定的存储中，需要时指定参数可以在存储中检索。
Spring AI Alibaba目前提供两种实现方式
InMemoryChatMemory、CassandraChatMemory，分别为聊天对话历史记录提供内存存储和 time-to-live 类型的持久存储。以下 Advisor 实现使用
ChatMemory 接口来使用对话历史记录来增强（advice）Prompt，这些 advisor 实现在如何将对话历史记录添加到 Prompt 的细节上有所不同。- MessageChatMemoryAdvisor 消息集合，保留每条消息的角色和内容。
- PromptChatMemoryAdvisor 系统文本，保留对话历史的文本。
- VectorStoreChatMemoryAdvisor
当然，开发者也可以自行实现 interface ChatMemory，基于类似于文件、Redis等方式进行上下文内容的存储和记录。
日志记录
SimpleLoggerAdvisor 是一个用于记录 ChatClient 的 request 和 response 数据 Advisor，这对于调试和监控您的 AI 交互非常有用。要启用日志记录，请在创建 ChatClient 时将
SimpleLoggerAdvisor 添加到 Advisor 链中。建议将其添加到链的末尾ChatModel
对话模型（Chat Model）接收一系列消息（Message）作为输入，与模型 LLM 服务进行交互，并接收返回的聊天消息（Chat Message）作为输出。相比于普通的程序输入，模型的输入与输出消息（Message）不止支持纯字符文本，还支持包括语音、图片、视频等作为输入输出。同时，在 Spring AI Alibaba 中，消息中还支持包含不同的角色，帮助底层模型区分来自模型、用户和系统指令等的不同消息。
Spring AI Alibaba 复用了 Spring AI 抽象的 Model API，并与通义系列大模型服务进行适配（如通义千问、通义万相等），目前支持纯文本聊天、文生图、文生语音、语音转文本等。以下是框架定义的几个核心 API：
- ChatModel，文本聊天交互模型，支持纯文本格式作为输入，并将模型的输出以格式化文本形式返回。
- ImageModel，接收用户文本输入，并将模型生成的图片作为输出返回。
- AudioModel，接收用户文本输入，并将模型合成的语音作为输出返回。
Spring AI Alibaba 支持以上 Model 抽象与通义系列模型的适配，并通过
spring-ai-alibaba-starter AutoConfiguration 自动初始化了默认实例，因此我们可以在应用程序中直接注入 ChatModel、ImageModel 等 bean，当然在需要的时候也可以自定义 Model 实例。- 作者:宗海
- 链接:https://nowave.cloud//article/201beb96-1d72-80dd-bb47-edb42e0dcec5
- 声明:本文采用 CC BY-NC-SA 4.0 许可协议，转载请注明出处。
