|
此版本仍在开发中，尚未被视为稳定版。如需最新的快照版本，请使用 Spring AI 1.1.3！ |
聊天记忆
大型语言模型（LLM）是无状态的，这意味着它们不会保留关于先前交互的信息。当您希望在多次交互中维持上下文或状态时，这可能成为一个限制。为了解决这个问题，Spring AI 提供了聊天记忆功能，允许您在与 LLM 的多次交互中存储和检索信息。
ChatMemory 抽象允许您实现各种类型的内存，以支持不同的用例。消息的底层存储由 ChatMemoryRepository 处理，其唯一职责是存储和检索消息。ChatMemory 的实现负责决定保留哪些消息以及何时移除它们。策略示例包括：保留最近 N 条消息、在特定时间段内保留消息，或保留消息直至达到特定的Tokens限制。
在选择内存类型之前，必须理解聊天内存和聊天历史之间的区别。
-
聊天记忆。大型语言模型保留并用于在对话过程中维持上下文意识的信息。
-
聊天历史。完整的对话历史，包括用户与模型之间交换的所有消息。
ChatMemory 抽象旨在管理聊天记忆。它允许您存储和检索与当前对话上下文相关的消息。然而，它并不是存储聊天历史的最佳选择。如果您需要维护所有交换消息的完整记录，则应考虑使用其他方法，例如依赖 Spring Data 来高效地存储和检索完整的聊天历史。
快速开始
Spring AI 会自动配置一个 ChatMemory Bean，您可以直接在应用程序中使用。默认情况下，它使用内存存储库来存储消息（InMemoryChatMemoryRepository），并使用 MessageWindowChatMemory 实现来管理会话历史。如果已配置了不同的存储库（例如 Cassandra、JDBC 或 Neo4j），Spring AI 将改用该存储库。
@Autowired
ChatMemory chatMemory;以下部分将进一步介绍 Spring AI 中可用的不同内存类型和存储库。
内存存储
Spring AI 提供了用于存储聊天记忆的 ChatMemoryRepository 抽象。本节介绍了 Spring AI 提供的内置仓库及其使用方法，但您也可以根据需要实现自己的仓库。
内存存储库
InMemoryChatMemoryRepository 使用 ConcurrentHashMap 将消息存储在内存中。
默认情况下，如果尚未配置其他仓库，Spring AI 会自动配置一个类型为 InMemoryChatMemoryRepository 的 ChatMemoryRepository Bean，您可以直接在应用程序中使用它。
@Autowired
ChatMemoryRepository chatMemoryRepository;如果您更愿意手动创建 InMemoryChatMemoryRepository，可以按以下方式操作：
ChatMemoryRepository repository = new InMemoryChatMemoryRepository();JdbcChatMemoryRepository
JdbcChatMemoryRepository 是一个内置实现，使用 JDBC 将消息存储在关系型数据库中。它开箱即用支持多种数据库，适用于需要持久化存储聊天内存的应用程序。
消息按时间戳升序检索（从最旧到最新），这是大语言模型对话历史的预期格式。
首先，将以下依赖项添加到您的项目中：
-
Maven
-
Gradle
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-chat-memory-repository-jdbc</artifactId>
</dependency>dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-chat-memory-repository-jdbc'
}Spring AI 为 JdbcChatMemoryRepository 提供了自动配置，您可以直接在应用程序中使用它。
@Autowired
JdbcChatMemoryRepository chatMemoryRepository;
ChatMemory chatMemory = MessageWindowChatMemory.builder()
.chatMemoryRepository(chatMemoryRepository)
.maxMessages(10)
.build();如果您更愿意手动创建JdbcChatMemoryRepository，可以通过提供一个JdbcTemplate实例和一个JdbcChatMemoryRepositoryDialect来实现：
ChatMemoryRepository chatMemoryRepository = JdbcChatMemoryRepository.builder()
.jdbcTemplate(jdbcTemplate)
.dialect(new PostgresChatMemoryRepositoryDialect())
.build();
ChatMemory chatMemory = MessageWindowChatMemory.builder()
.chatMemoryRepository(chatMemoryRepository)
.maxMessages(10)
.build();支持的数据库和方言抽象
Spring AI 通过方言抽象支持多种关系型数据库。以下数据库可开箱即用：
-
PostgreSQL
-
MySQL / MariaDB
-
SQL Server
-
HSQLDB
-
Oracle 数据库
使用 JdbcChatMemoryRepositoryDialect.from(DataSource) 时，正确的方言可以从 JDBC URL 自动检测。您可以通过实现 JdbcChatMemoryRepositoryDialect 接口来扩展对其他数据库的支持。
配置属性
<property> </property> |
<description> </description> |
默认值 |
|
控制何时初始化模式。取值： |
|
|
用于初始化的架构脚本的位置。支持 |
|
|
如果在初始化脚本中使用了 @@platform@@ 占位符，则指定要使用的平台。 |
auto-detected |
模式初始化
自动配置将在启动时使用针对您数据库的特定提供商 SQL 脚本自动创建 SPRING_AI_CHAT_MEMORY 表。默认情况下，架构初始化仅针对嵌入式数据库（H2、HSQL、Derby 等）运行。
您可以使用 spring.ai.chat.memory.repository.jdbc.initialize-schema 属性控制架构初始化：
spring.ai.chat.memory.repository.jdbc.initialize-schema=embedded # Only for embedded DBs (default)
spring.ai.chat.memory.repository.jdbc.initialize-schema=always # Always initialize
spring.ai.chat.memory.repository.jdbc.initialize-schema=never # Never initialize (useful with Flyway/Liquibase)要覆盖架构脚本位置，请使用：
spring.ai.chat.memory.repository.jdbc.schema=classpath:/custom/path/schema-mysql.sqlCassandraChatMemoryRepository
CassandraChatMemoryRepository 使用 Apache Cassandra 存储消息。它适用于需要持久化存储聊天内存的应用程序，特别是在可用性、耐久性、扩展性以及利用生存时间 (TTL) 功能时。
CassandraChatMemoryRepository 具有时间序列模式，记录所有过去的聊天窗口，对治理和审计非常有价值。建议将生存时间（TTL）设置为某个具体值，例如三年。
消息按时间戳升序检索（从最旧到最新），这是大语言模型对话历史的预期格式。
要首先使用 CassandraChatMemoryRepository，请将依赖项添加到您的项目中：
-
Maven
-
Gradle
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-chat-memory-repository-cassandra</artifactId>
</dependency>dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-chat-memory-repository-cassandra'
}Spring AI 提供了针对 CassandraChatMemoryRepository 的自动配置，您可以直接在应用程序中使用它。
@Autowired
CassandraChatMemoryRepository chatMemoryRepository;
ChatMemory chatMemory = MessageWindowChatMemory.builder()
.chatMemoryRepository(chatMemoryRepository)
.maxMessages(10)
.build();如果您更愿意手动创建 CassandraChatMemoryRepository，可以通过提供一个 CassandraChatMemoryRepositoryConfig 实例来实现：
ChatMemoryRepository chatMemoryRepository = CassandraChatMemoryRepository
.create(CassandraChatMemoryRepositoryConfig.builder().withCqlSession(cqlSession));
ChatMemory chatMemory = MessageWindowChatMemory.builder()
.chatMemoryRepository(chatMemoryRepository)
.maxMessages(10)
.build();配置属性
<property> </property> |
<description> </description> |
默认值 |
|
用于启动集群发现的主机 |
|
|
用于连接的 Cassandra 原生协议端口 |
|
|
要连接的 Cassandra 数据中心 |
|
|
Cassandra 中写入消息的生存时间 (TTL) |
|
|
Cassandra 密钥空间 |
|
|
Cassandra 的消息列名 |
|
|
Cassandra 表 |
|
|
是否在启动时初始化数据库模式。 |
|
Neo4j ChatMemoryRepository
Neo4jChatMemoryRepository 是一个内置实现，使用 Neo4j 将聊天消息作为节点和关系存储在属性图数据库中。它适用于希望利用 Neo4j 的图能力来实现聊天记忆持久化的应用程序。
消息按消息索引升序（从最旧到最新）检索，这是大语言模型对话历史所期望的格式。
首先，将以下依赖项添加到您的项目中：
-
Maven
-
Gradle
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-chat-memory-repository-neo4j</artifactId>
</dependency>dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-chat-memory-repository-neo4j'
}Spring AI 为 Neo4jChatMemoryRepository 提供了自动配置，您可以直接在应用程序中使用它。
@Autowired
Neo4jChatMemoryRepository chatMemoryRepository;
ChatMemory chatMemory = MessageWindowChatMemory.builder()
.chatMemoryRepository(chatMemoryRepository)
.maxMessages(10)
.build();如果您更愿意手动创建Neo4jChatMemoryRepository，可以通过提供一个 Neo4j Driver 实例来实现：
ChatMemoryRepository chatMemoryRepository = Neo4jChatMemoryRepository.builder()
.driver(driver)
.build();
ChatMemory chatMemory = MessageWindowChatMemory.builder()
.chatMemoryRepository(chatMemoryRepository)
.maxMessages(10)
.build();配置属性
<property> </property> |
<description> </description> |
默认值 |
|
存储会话会话的节点标签 |
|
|
存储消息的节点的标签 |
|
|
存储工具调用（例如在助手消息中）的节点的标签 |
|
|
存储消息元数据的节点标签 |
|
|
存储工具响应的节点标签 |
|
|
存储与消息关联的媒体的节点标签 |
|
CosmosDBChatMemoryRepository
CosmosDBChatMemoryRepository 是一个内置实现，使用 Azure Cosmos DB NoSQL API 来存储消息。它适用于需要全球分布、高可扩展文档数据库以持久化聊天内存的应用程序。该仓库使用对话 ID 作为分区键，以确保高效的数据分布和快速检索。
消息按时间戳升序检索（从最旧到最新），这是大语言模型对话历史的预期格式。
首先，将以下依赖项添加到您的项目中：
-
Maven
-
Gradle
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-chat-memory-repository-cosmos-db</artifactId>
</dependency>dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-chat-memory-repository-cosmos-db'
}Spring AI 为 CosmosDBChatMemoryRepository 提供了自动配置，您可以直接在应用程序中使用它。
@Autowired
CosmosDBChatMemoryRepository chatMemoryRepository;
ChatMemory chatMemory = MessageWindowChatMemory.builder()
.chatMemoryRepository(chatMemoryRepository)
.maxMessages(10)
.build();如果您更愿意手动创建 CosmosDBChatMemoryRepository，可以通过提供一个 CosmosDBChatMemoryRepositoryConfig 实例来实现：
ChatMemoryRepository chatMemoryRepository = CosmosDBChatMemoryRepository
.create(CosmosDBChatMemoryRepositoryConfig.builder()
.withCosmosClient(cosmosAsyncClient)
.withDatabaseName("chat-memory-db")
.withContainerName("conversations")
.build());
ChatMemory chatMemory = MessageWindowChatMemory.builder()
.chatMemoryRepository(chatMemoryRepository)
.maxMessages(10)
.build();配置属性
<property> </property> |
<description> </description> |
默认值 |
|
Azure Cosmos DB 终结点 URI。自动配置所必需。 |
|
|
Azure Cosmos DB 的主密钥或辅助密钥。如果未提供，将使用 Azure Identity 进行身份验证。 |
|
|
Cosmos DB 客户端的连接模式（ |
|
|
Cosmos DB 数据库的名称。 |
|
|
Cosmos DB 容器的名称。 |
|
|
容器的分区键路径。 |
|
MongoChatMemoryRepository
MongoChatMemoryRepository 是一个内置实现，使用 MongoDB 存储消息。它适用于需要灵活、面向文档的数据库来实现聊天记忆持久化的应用程序。
消息按时间戳升序检索（从最旧到最新），这是大语言模型对话历史的标准格式。此排序在所有聊天记忆存储库实现中保持一致。
首先，将以下依赖项添加到您的项目中：
-
Maven
-
Gradle
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-chat-memory-repository-mongodb</artifactId>
</dependency>dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-chat-memory-repository-mongodb'
}Spring AI 为 MongoChatMemoryRepository 提供了自动配置，您可以直接在应用程序中使用它。
@Autowired
MongoChatMemoryRepository chatMemoryRepository;
ChatMemory chatMemory = MessageWindowChatMemory.builder()
.chatMemoryRepository(chatMemoryRepository)
.maxMessages(10)
.build();如果您更愿意手动创建 MongoChatMemoryRepository，可以通过提供一个 MongoTemplate 实例来实现：
ChatMemoryRepository chatMemoryRepository = MongoChatMemoryRepository.builder()
.mongoTemplate(mongoTemplate)
.build();
ChatMemory chatMemory = MessageWindowChatMemory.builder()
.chatMemoryRepository(chatMemoryRepository)
.maxMessages(10)
.build();RedisChatMemoryRepository
RedisChatMemoryRepository 是一个内置实现，使用 Redis Stack（包含 Redis Query Engine 和 RedisJSON）来存储聊天消息。
它适用于需要高性能、低延迟的聊天记忆持久化，并支持可选的 TTL（生存时间）以及高级查询功能的应用程序。
该仓库将消息存储为 JSON 文档，并创建搜索索引以实现高效查询。
它还通过 AdvancedRedisChatMemoryRepository 接口提供扩展的查询功能，支持按内容、类型、时间范围和元数据搜索消息。
消息按时间戳升序检索（从最旧到最新），这是大语言模型对话历史的预期格式。
首先，将以下依赖项添加到您的项目中：
-
Maven
-
Gradle
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-chat-memory-repository-redis</artifactId>
</dependency>dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-chat-memory-repository-redis'
}Spring AI 为 RedisChatMemoryRepository 提供了自动配置，您可以直接在应用程序中使用它。
@Autowired
RedisChatMemoryRepository chatMemoryRepository;
ChatMemory chatMemory = MessageWindowChatMemory.builder()
.chatMemoryRepository(chatMemoryRepository)
.maxMessages(10)
.build();如果您更愿意手动创建 RedisChatMemoryRepository，可以通过提供一个 JedisPooled 客户端来实现：
JedisPooled jedisClient = new JedisPooled("localhost", 6379);
ChatMemoryRepository chatMemoryRepository = RedisChatMemoryRepository.builder()
.jedisClient(jedisClient)
.indexName("my-chat-index")
.keyPrefix("my-chat:")
.timeToLive(Duration.ofHours(24))
.build();
ChatMemory chatMemory = MessageWindowChatMemory.builder()
.chatMemoryRepository(chatMemoryRepository)
.maxMessages(10)
.build();配置属性
<property> </property> |
<description> </description> |
默认值 |
|
Redis 服务器主机 |
|
|
Redis 服务器端口 |
|
|
Redis 搜索索引的名称 |
|
|
聊天记忆条目的键前缀 |
|
|
聊天内存条目的生存时间（例如： |
无过期时间 |
|
是否在启动时初始化 Redis 架构 |
|
|
要返回的对话 ID 的最大数量 |
|
|
每次对话返回的最大消息数 |
|
高级查询
RedisChatMemoryRepository 还实现了 AdvancedRedisChatMemoryRepository，后者提供了扩展的查询功能：
// Cast to access advanced features
AdvancedRedisChatMemoryRepository advancedRepo = (AdvancedRedisChatMemoryRepository) chatMemoryRepository;
// Find messages by type across all conversations
List<MessageWithConversation> userMessages = advancedRepo.findByType(MessageType.USER, 100);
// Find messages containing specific content
List<MessageWithConversation> results = advancedRepo.findByContent("Spring AI", 50);
// Find messages within a time range
List<MessageWithConversation> recentMessages = advancedRepo.findByTimeRange(
conversationId,
Instant.now().minus(Duration.ofHours(1)),
Instant.now(),
100
);
// Find messages by metadata
List<MessageWithConversation> priorityMessages = advancedRepo.findByMetadata("priority", "high", 50);
// Execute custom Redis queries
List<MessageWithConversation> customResults = advancedRepo.executeQuery("@type:USER @content:Redis", 100);元数据字段索引
为了在自定义元数据字段上实现高效查询，您可以配置元数据字段定义：
spring.ai.chat.memory.redis.metadata-fields[0].name=priority
spring.ai.chat.memory.redis.metadata-fields[0].type=tag
spring.ai.chat.memory.redis.metadata-fields[1].name=score
spring.ai.chat.memory.redis.metadata-fields[1].type=numeric
spring.ai.chat.memory.redis.metadata-fields[2].name=category
spring.ai.chat.memory.redis.metadata-fields[2].type=tag支持的字段类型包括：tag（用于精确匹配过滤）、text（用于全文搜索）和numeric（用于范围查询）。
聊天客户端中的内存
使用 ChatClient API 时，您可以提供一个 ChatMemory 实现，以在多次交互中保持对话上下文。
Spring AI 提供了一些内置的 Advisor，您可以根据需要配置 ChatClient 的记忆行为。
| 目前，与大型语言模型在执行工具调用时交换的中间消息未存储在内存中。这是当前实现的一个限制，将在未来的版本中解决。如果您需要存储这些消息，请参阅 用户控制的工具执行 的说明。 |
-
MessageChatMemoryAdvisor. 此顾问使用提供的ChatMemory实现来管理对话内存。在每次交互中，它会从内存中检索对话历史，并将其作为消息集合包含在提示中。 -
PromptChatMemoryAdvisor. 此顾问使用提供的ChatMemory实现来管理对话内存。在每次交互中，它会从内存中检索对话历史，并将其作为纯文本附加到系统提示中。 -
VectorStoreChatMemoryAdvisor. 此顾问使用提供的VectorStore实现来管理对话内存。在每次交互时，它会从向量存储中检索对话历史，并将其作为纯文本附加到系统消息中。
例如，如果您想将 MessageWindowChatMemory 与 MessageChatMemoryAdvisor 一起使用，可以按如下方式进行配置：
ChatMemory chatMemory = MessageWindowChatMemory.builder().build();
ChatClient chatClient = ChatClient.builder(chatModel)
.defaultAdvisors(MessageChatMemoryAdvisor.builder(chatMemory).build())
.build();当调用 ChatClient 时，内存将由 MessageChatMemoryAdvisor 自动管理。对话历史将根据指定的对话 ID 从内存中检索：
String conversationId = "007";
chatClient.prompt()
.user("Do I have license to code?")
.advisors(a -> a.param(ChatMemory.CONVERSATION_ID, conversationId))
.call()
.content();提示聊天记忆顾问
自定义模板
PromptChatMemoryAdvisor 使用默认模板来增强系统消息，其中包含检索到的对话记忆。您可以通过 .promptTemplate() 构建器方法提供自己的 PromptTemplate 对象来自定义此行为。
此处提供的 PromptTemplate 用于自定义顾问如何将检索到的记忆与系统消息合并。这不同于在 ChatClient 本身上配置 TemplateRenderer（使用 .templateRenderer()），后者会影响在顾问运行之前初始用户/系统提示内容的渲染。有关客户端级模板渲染的更多详细信息，请参阅 ChatClient 提示模板。 |
自定义的 PromptTemplate 可以使用任何 TemplateRenderer 实现（默认情况下，它使用基于 StringTemplate 引擎的 StPromptTemplate）。重要的要求是模板必须包含以下两个占位符：
-
一个
instructions占位符，用于接收原始系统消息。 -
a
memory占位符，用于接收检索到的对话记忆。
VectorStore 聊天记忆顾问
自定义模板
VectorStoreChatMemoryAdvisor 使用默认模板来增强系统消息，其中包含检索到的对话记忆。您可以通过 .promptTemplate() 构建器方法提供自己的 PromptTemplate 对象来自定义此行为。
此处提供的 PromptTemplate 用于自定义顾问如何将检索到的记忆与系统消息合并。这不同于在 ChatClient 本身上配置 TemplateRenderer（使用 .templateRenderer()），后者会影响在顾问运行之前初始用户/系统提示内容的渲染。有关客户端级模板渲染的更多详细信息，请参阅 ChatClient 提示模板。 |
自定义的 PromptTemplate 可以使用任何 TemplateRenderer 实现（默认情况下，它使用基于 StringTemplate 引擎的 StPromptTemplate）。重要的要求是模板必须包含以下两个占位符：
-
一个
instructions占位符，用于接收原始系统消息。 -
a
long_term_memory占位符，用于接收检索到的对话记忆。
聊天模型中的记忆
如果您直接使用 ChatModel 而不是 ChatClient，则可以显式管理内存：
// Create a memory instance
ChatMemory chatMemory = MessageWindowChatMemory.builder().build();
String conversationId = "007";
// First interaction
UserMessage userMessage1 = new UserMessage("My name is James Bond");
chatMemory.add(conversationId, userMessage1);
ChatResponse response1 = chatModel.call(new Prompt(chatMemory.get(conversationId)));
chatMemory.add(conversationId, response1.getResult().getOutput());
// Second interaction
UserMessage userMessage2 = new UserMessage("What is my name?");
chatMemory.add(conversationId, userMessage2);
ChatResponse response2 = chatModel.call(new Prompt(chatMemory.get(conversationId)));
chatMemory.add(conversationId, response2.getResult().getOutput());
// The response will contain "James Bond"