升级说明
升级到 1.0.0-SNAPSHOT
添加 Snapshot 存储库
要使用 1.0.0-SNAPSHOT 版本,您需要将快照存储库添加到构建文件中。 有关详细说明,请参阅入门指南中的快照版本 - 添加快照存储库部分。
更新依赖项管理
将 Spring AI BOM 版本更新为1.0.0-SNAPSHOT
在您的 build 配置中。
有关配置依赖项管理的详细说明,请参阅入门指南中的 依赖项管理 部分。
使用 AI 自动升级
您可以使用 Claude Code CLI 工具在提供的提示下自动执行到 1.0.0-SNAPSHOT 的升级过程。该提示将指导 AI 执行以下任务:
-
将 Spring AI BOM 版本更新到 1.0.0-SNAPSHOT
-
确保构建配置中存在所有必需的存储库
-
根据新的命名模式更新 Spring AI 工件 ID
要使用此自动化:
-
从 update-to-snapshot.txt 文件中复制提示
-
将提示粘贴到 Claude Code CLI 中
-
AI 将分析您的项目并进行必要的更改
这种方法可以节省时间并减少升级多个项目或复杂代码库时出错的可能性。
升级到 1.0.0-M7
MCP Java SDK 升级到 0.9.0
Spring AI 1.0.0-M7 现在使用 MCP Java SDK 版本 0.9.0,该版本与以前版本相比有重大变化。如果您在应用程序中使用 MCP,则需要更新代码以适应这些更改。
主要更改包括:
接口重命名
-
ClientMcpTransport
→McpClientTransport
-
ServerMcpTransport
→McpServerTransport
-
DefaultMcpSession
→McpClientSession
或McpServerSession
-
都
*Registration
类 →*Specification
类
服务器创建更改
-
用
McpServerTransportProvider
而不是ServerMcpTransport
// Before
ServerMcpTransport transport = new WebFluxSseServerTransport(objectMapper, "/mcp/message");
var server = McpServer.sync(transport)
.serverInfo("my-server", "1.0.0")
.build();
// After
McpServerTransportProvider transportProvider = new WebFluxSseServerTransportProvider(objectMapper, "/mcp/message");
var server = McpServer.sync(transportProvider)
.serverInfo("my-server", "1.0.0")
.build();
处理程序签名更改
现在,所有处理程序都会收到一个exchange
parameter 作为其第一个参数:
// Before
.tool(calculatorTool, args -> new CallToolResult("Result: " + calculate(args)))
// After
.tool(calculatorTool, (exchange, args) -> new CallToolResult("Result: " + calculate(args)))
通过 Exchange 进行客户端交互
以前在服务器上可用的方法现在通过 exchange 对象访问:
// Before
ClientCapabilities capabilities = server.getClientCapabilities();
CreateMessageResult result = server.createMessage(new CreateMessageRequest(...));
// After
ClientCapabilities capabilities = exchange.getClientCapabilities();
CreateMessageResult result = exchange.createMessage(new CreateMessageRequest(...));
根更改处理程序
// Before
.rootsChangeConsumers(List.of(
roots -> System.out.println("Roots changed: " + roots)
))
// After
.rootsChangeHandlers(List.of(
(exchange, roots) -> System.out.println("Roots changed: " + roots)
))
有关迁移 MCP 代码的完整指南,请参阅 MCP 迁移指南。
使用 AI 自动升级
您可以使用 Claude Code CLI 工具在提供的提示下自动升级到 1.0.0-M7:
-
从 update-to-m7.txt 文件中复制提示
-
将提示粘贴到 Claude Code CLI 中
-
AI 将分析您的项目并进行必要的更改
自动升级提示当前处理工件 ID 更改、软件包重定位和模块结构更改,但尚未包括升级到 MCP 0.9.0 的自动更改。如果您使用的是 MCP,则需要按照 MCP Java SDK 升级部分中的指导手动更新代码。 |
跨版本的常见更改
工件 ID 更改
Spring AI Starters工件的命名模式已更改。 您需要根据以下模式更新依赖项:
-
模型Starters:
spring-ai-{model}-spring-boot-starter
→spring-ai-starter-model-{model}
-
Vector Store Starters:
spring-ai-{store}-store-spring-boot-starter
→spring-ai-starter-vector-store-{store}
-
MCP Starters:
spring-ai-mcp-{type}-spring-boot-starter
→spring-ai-starter-mcp-{type}
例子
-
Maven
-
Gradle
<!-- BEFORE -->
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-openai-spring-boot-starter</artifactId>
</dependency>
<!-- AFTER -->
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>
// BEFORE
implementation 'org.springframework.ai:spring-ai-openai-spring-boot-starter'
implementation 'org.springframework.ai:spring-ai-redis-store-spring-boot-starter'
// AFTER
implementation 'org.springframework.ai:spring-ai-starter-model-openai'
implementation 'org.springframework.ai:spring-ai-starter-vector-store-redis'
对 Spring AI 自动配置工件的更改
Spring AI 自动配置已从单个整体工件更改为每个模型、矢量存储和其他组件的单个自动配置工件。 进行此更改是为了最大程度地减少不同版本的依赖库冲突(例如 Google Protocol Buffers、Google RPC 等)的影响。 通过将自动配置分离到特定于组件的构件中,您可以避免引入不必要的依赖项,并降低应用程序中版本冲突的风险。
原始的整体式构件不再可用:
<!-- NO LONGER AVAILABLE -->
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-spring-boot-autoconfigure</artifactId>
<version>${project.version}</version>
</dependency>
相反,每个组件现在都有自己的 autoconfiguration artifact ,遵循以下模式:
-
模型自动配置:
spring-ai-autoconfigure-model-{model}
-
Vector Store 自动配置:
spring-ai-autoconfigure-vector-store-{store}
-
MCP 自动配置:
spring-ai-autoconfigure-mcp-{type}
新的 Autoconfiguration 工件示例
-
Models
-
Vector Stores
-
MCP
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-autoconfigure-model-openai</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-autoconfigure-model-anthropic</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-autoconfigure-model-vertex-ai</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-autoconfigure-vector-store-redis</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-autoconfigure-vector-store-pgvector</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-autoconfigure-vector-store-chroma</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-autoconfigure-mcp-client</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-autoconfigure-mcp-server</artifactId>
</dependency>
在大多数情况下,您不需要显式添加这些自动配置依赖项。 在使用相应的 starter 依赖项时,它们将以传递方式包含。 |
程序包名称更改
您的 IDE 应有助于重构到新的包位置。
-
KeywordMetadataEnricher
和SummaryMetadataEnricher
已从org.springframework.ai.transformer
自org.springframework.ai.chat.transformer
. -
Content
,MediaContent
和Media
已从org.springframework.ai.model
自org.springframework.ai.content
.
模块结构
该项目的模块和工件结构发生了重大变化。以前spring-ai-core
包含所有中央接口,但现在已将其拆分为专门的域模块,以减少应用程序中不必要的依赖关系。

spring-ai-commons
Base 模块,不依赖于其他 Spring AI 模块。包含:
- 核心域模型 (Document
,TextSplitter
)
- JSON 实用程序和资源处理
- 结构化日志记录和可观测性支持
spring-ai-模型
提供 AI 能力抽象:
- 接口,如ChatModel
,EmbeddingModel
和ImageModel
- 消息类型和提示模板
- 函数调用框架 (ToolDefinition
,ToolCallback
)
- 内容过滤和观察支持
spring-ai-vector-store
统一向量数据库抽象:
-VectorStore
相似性搜索界面
- 使用类似 SQL 的表达式进行高级筛选
-SimpleVectorStore
用于内存中使用
- 对嵌入的批处理支持
spring-ai-client-chat
高级对话式 AI API:
-ChatClient
接口
- 对话持久性ChatMemory
- 响应转换OutputConverter
- 基于 advisor 的拦截
- 同步和反应式流式处理支持
spring-ai-advisors-vector-store
Bridges 与 RAG 的载体商店聊天:
-QuestionAnswerAdvisor
:将上下文注入提示
-VectorStoreChatMemoryAdvisor
:存储/检索对话历史记录
依赖关系结构
依赖项层次结构可以概括为:
-
spring-ai-commons
(基金会) -
spring-ai-model
(取决于共享资源) -
spring-ai-vector-store
和spring-ai-client-chat
(两者都取决于型号) -
spring-ai-advisors-vector-store
和spring-ai-rag
(取决于 client-chat 和 vector-store) -
spring-ai-model-chat-memory-*
modules (取决于 client-chat)
ToolContext 更改
这ToolContext
类已得到增强,可同时支持显式和隐式工具解析。工具现在可以是:
-
Explicitly Included:在提示中明确请求并包含在对模型的调用中的工具。
-
Implicitly Available:可用于运行时动态解析的工具,但除非明确请求,否则从不包含在对模型的任何调用中。
从 1.0.0-M7 开始,仅当在提示中明确请求或显式包含在调用中时,工具才会包含在对模型的调用中。
此外,ToolContext
类现在已标记为 final,无法再扩展。它从来都不应该被子类化。您可以在实例化ToolContext
,以Map<String, Object>
.有关更多信息,请查看 [文档](docs.spring.io/spring-ai/reference/api/tools.html#_tool_context)。
升级到 1.0.0-M6
对使用接口和 DefaultUsage 实现的更改
这Usage
interface 及其默认实现DefaultUsage
进行了以下更改:
-
方法重命名:
-
getGenerationTokens()
现在是getCompletionTokens()
-
-
类型更改:
-
中的所有令牌计数字段
DefaultUsage
从Long
自Integer
:-
promptTokens
-
completionTokens
(以前generationTokens
) -
totalTokens
-
-
所需作
-
将所有调用 替换为
getGenerationTokens()
跟getCompletionTokens()
-
更新
DefaultUsage
constructor 调用:
// Old (M5) new DefaultUsage(Long promptTokens, Long generationTokens, Long totalTokens) // New (M6) new DefaultUsage(Integer promptTokens, Integer completionTokens, Integer totalTokens)
有关处理 Usage 的更多信息,请参阅此处 |
更改了 FunctionCallingOptions 在工具调用中的用法
每ChatModel
实例在构造时接受可选的ChatOptions
或FunctionCallingOptions
实例
可用于配置用于调用模型的默认工具。
1.0.0-M6 之前:
-
通过
functions()
method 的默认值FunctionCallingOptions
实例包含在 从该ChatModel
实例,可能会被运行时选项覆盖。 -
通过
functionCallbacks()
method 的默认值FunctionCallingOptions
实例仅 可用于运行时动态解析(请参阅工具解析),但从不可用于运行时动态解析 包含在对模型的任何调用中,除非明确请求。
从 1.0.0-M6 开始:
-
通过
functions()
方法或functionCallbacks()
的默认值FunctionCallingOptions
实例现在以相同的方式处理:它包含在从该ChatModel
实例 可能被运行时选项覆盖。因此,调用中包含工具的方式是一致的 添加到模型,并防止由于functionCallbacks()
以及所有其他选项。
如果要使工具可用于运行时动态解析,并将其仅包含在对模型的聊天请求中 当明确请求时,您可以使用 Tool Resolution 中描述的策略之一。
1.0.0-M6 引入了用于处理工具调用的新 API。保持旧 API 的向后兼容性 所有场景,除了上面描述的场景。旧 API 仍然可用,但它们已被弃用 并将在 1.0.0-M7 中删除。 |
删除已弃用的 Amazon Bedrock 聊天模型
从 1.0.0-M6 开始,Spring AI 过渡到使用 Amazon Bedrock 的 Converse API 来实现 Spring AI 中的所有聊天对话。 除 Cohere 和 Titan 的嵌入模型外,所有 Amazon Bedrock Chat 模型都将被删除。
请参阅 Bedrock Converse 文档以使用聊天模型。 |
使用 Spring Boot 3.4.2 进行依赖项管理的更改
Spring AI 更新以使用 Spring Boot 3.4.2 进行依赖项管理。Spring Boot 3.4.2 的依赖可以参考这里
所需作
-
如果要升级到 Spring Boot 3.4.2,请务必参考此文档,了解配置 REST 客户端所需的更改。值得注意的是,如果你在 Classpath 上没有 HTTP 客户端库,这可能会导致使用
JdkClientHttpRequestFactory
哪里SimpleClientHttpRequestFactory
之前会使用。切换到使用SimpleClientHttpRequestFactory
,您需要设置spring.http.client.factory=simple
. -
如果您使用的是不同版本的 Spring Boot(例如 Spring Boot 3.3.x)并且需要特定版本的依赖项,则可以在构建配置中覆盖它。
Vector Store API 更改
在版本 1.0.0-M6 中,delete
方法中的VectorStore
interface 已修改为 void作,而不是返回Optional<Boolean>
.
如果您的代码之前检查了 delete作的返回值,则需要删除此检查。
现在,如果删除失败,该作将引发异常,从而提供更直接的错误处理。
升级到 1.0.0.M5
-
为了保持一致性,对 Vector Builder 进行了重构。
-
当前的 VectorStore 实现构造函数已被弃用,请使用 builder 模式。
-
VectorStore 实现包已移至唯一的包名称中,从而避免了跨构件的冲突。例如
org.springframework.ai.vectorstore
自org.springframework.ai.pgvector.vectorstore
.
升级到 1.0.0.M2
-
Chroma Vector Store 的配置前缀已从
spring.ai.vectorstore.chroma.store
自spring.ai.vectorstore.chroma
为了与其他 Vector Store 的命名约定保持一致。 -
的
initialize-schema
能够初始化 Schema 的 vector store 上的属性现在设置为false
. 这意味着,如果需要在应用程序启动时创建架构,则应用程序现在需要在支持的向量存储上显式选择加入架构初始化。 并非所有 vector store 都支持此属性。 有关更多详细信息,请参阅相应的 vector store 文档。 以下是目前不支持initialize-schema
财产。-
汉娜
-
Pinecone
-
Weaviate
-
-
在 Bedrock Jurassic 2 中,聊天选项
countPenalty
,frequencyPenalty
和presencePenalty
已重命名为countPenaltyOptions
,frequencyPenaltyOptions
和presencePenaltyOptions
. 此外,聊天选项的类型stopSequences
已从String[]
自List<String>
. -
在 Azure OpenAI 中,聊天选项的类型
frequencyPenalty
和presencePenalty
已从Double
自Float
,与所有其他实现一致。
升级到 1.0.0.M1
在发布 1.0.0 M1 的过程中,我们进行了几项重大更改。抱歉,这是最好的!
ChatClient 更改
进行了一次重大更改,将“旧的”ChatClient
并将功能移至ChatModel
.“新”ChatClient
现在采用ChatModel
.这样做是为了支持一个 Fluent API,用于以类似于 Spring 生态系统中其他客户端类的样式创建和执行提示,例如RestClient
,WebClient
和JdbcClient
.有关 Fluent API 的更多信息,请参阅 [JavaDoc](docs.spring.io/spring-ai/docs/api),适当的参考文档即将发布。
我们将 'old' 重命名为ModelClient
自Model
并重命名了实现类,例如ImageClient
已重命名为ImageModel
.这Model
implementation 表示在 Spring AI API 和底层 AI 模型 API 之间进行转换的可移植性层。
适应变化
这ChatClient class 现在位于软件包中org.springframework.ai.chat.client
|
方法 1
现在,无需获取 AutoconfiguredChatClient
实例,您将获得一个ChatModel
实例。这call
重命名后的方法签名保持不变。
要适应您的代码,您应该重构您的代码以更改ChatClient
自ChatModel
以下是更改前的现有代码示例
@RestController
public class OldSimpleAiController {
private final ChatClient chatClient;
public OldSimpleAiController(ChatClient chatClient) {
this.chatClient = chatClient;
}
@GetMapping("/ai/simple")
Map<String, String> completion(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
return Map.of("generation", this.chatClient.call(message));
}
}
现在,在更改之后,这将是
@RestController
public class SimpleAiController {
private final ChatModel chatModel;
public SimpleAiController(ChatModel chatModel) {
this.chatModel = chatModel;
}
@GetMapping("/ai/simple")
Map<String, String> completion(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
return Map.of("generation", this.chatModel.call(message));
}
}
重命名也适用于类
*StreamingChatClient →StreamingChatModel
* EmbeddingClient →EmbeddingModel
* ImageClient →ImageModel
* SpeechClient →SpeechModel * 和其他类似<XYZ>Client 类 |
方法 2
在此方法中,您将使用“new”上提供的新 Fluent APIChatClient
以下是更改前的现有代码示例
@RestController
class OldSimpleAiController {
ChatClient chatClient;
OldSimpleAiController(ChatClient chatClient) {
this.chatClient = chatClient;
}
@GetMapping("/ai/simple")
Map<String, String> completion(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
return Map.of(
"generation",
this.chatClient.call(message)
);
}
}
现在,在更改之后,这将是
@RestController
class SimpleAiController {
private final ChatClient chatClient;
SimpleAiController(ChatClient.Builder builder) {
this.chatClient = builder.build();
}
@GetMapping("/ai/simple")
Map<String, String> completion(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
return Map.of(
"generation",
this.chatClient.prompt().user(message).call().content()
);
}
}
这ChatModel 实例 通过 Autoconfiguration 提供给您。 |
方法 3
GitHub 存储库中有一个名为 [v1.0.0-SNAPSHOT-before-chatclient-changes](github.com/spring-projects/spring-ai/tree/v1.0.0-SNAPSHOT-before-chatclient-changes) 的标记,您可以签出该标记并执行本地构建,以避免在准备好迁移代码库之前更新任何代码。
git checkout tags/v1.0.0-SNAPSHOT-before-chatclient-changes
./mvnw clean install -DskipTests
构件名称更改
重命名了 POM 构件名称: - spring-ai-qdrant → spring-ai-qdrant-store - spring-ai-cassandra → spring-ai-cassandra-store - spring-ai-pinecone → spring-ai-pinecone-store - spring-ai-redis → spring-ai-redis-store - spring-ai-qdrant → spring-ai-qdrant-store - spring-ai-gemfire → spring-ai-gemfire-store - spring-ai-azure-vector-store-spring-boot-starter → spring-ai-azure-store-spring-boot-starter - spring-ai-redis-spring-boot-starter → spring-ai-starter-vector-store-redis
升级到 0.8.1
前spring-ai-vertex-ai
已重命名为spring-ai-vertex-ai-palm2
和spring-ai-vertex-ai-spring-boot-starter
已重命名为spring-ai-vertex-ai-palm2-spring-boot-starter
.
因此,您需要将依赖项从
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-vertex-ai</artifactId>
</dependency>
自
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-vertex-ai-palm2</artifactId>
</dependency>
并且 Palm2 型号的相关 Boot starter 已从
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-vertex-ai-spring-boot-starter</artifactId>
</dependency>
自
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-vertex-ai-palm2-spring-boot-starter</artifactId>
</dependency>
-
重命名的类 (01.03.2024)
-
VertexAiApi → VertexAiPalm2Api
-
VertexAiClientChat → VertexAiPalm2ChatClient
-
VertexAiEmbeddingClient → VertexAiPalm2EmbeddingClient
-
VertexAiChatOptions → VertexAiPalm2ChatOptions
-
升级到 0.8.0
2024 年 1 月 24 日更新
-
将
prompt
和messages
和metadata
packages 的子软件包org.sf.ai.chat
-
新功能是文本生成图像客户端。类是
OpenAiImageModel
和StabilityAiImageModel
.有关用法,请参阅集成测试,文档即将推出。 -
新软件包
model
其中包含接口和基类,以支持为任何输入/输出数据类型组合创建 AI 模型客户端。目前,chat 和 image model 包实现了这一点。我们很快就会将 embedding 包更新到这个新模型。 -
新的 “portable options” 设计模式。我们希望在
ModelCall
尽可能跨不同的基于聊天的 AI 模型。有一组通用的生成选项,然后是特定于模型提供程序的选项。使用了一种 “duck typing” 方法。ModelOptions
在 model 包中是一个 marker 接口,指示此类的实现将为模型提供选项。看ImageOptions
,一个定义所有 text→image 的可移植选项的子接口ImageModel
实现。然后StabilityAiImageOptions
和OpenAiImageOptions
提供特定于每个模型提供程序的选项。所有选项类都是通过 Fluent API 构建器创建的,都可以传递到可移植的ImageModel
应用程序接口。这些选项数据类型在 autoconfiguration/configuration 属性中使用ImageModel
实现。
2024 年 1 月 13 日更新
以下 OpenAi 自动配置聊天属性已更改
-
从
spring.ai.openai.model
自spring.ai.openai.chat.options.model
. -
从
spring.ai.openai.temperature
自spring.ai.openai.chat.options.temperature
.
查找有关 OpenAi 属性的更新文档:docs.spring.io/spring-ai/reference/api/chat/openai-chat.html
2023 年 12 月 27 日更新
将 SimplePersistentVectorStore 和 InMemoryVectorStore 合并到 SimpleVectorStore 中 * 将 InMemoryVectorStore 替换为 SimpleVectorStore
2023 年 12 月 20 日更新
重构 Ollama 客户端和相关类和包名称
-
将org.springframework.ai.ollama.client.OllamaClient替换为org.springframework.ai.ollama.OllamaModelCall。
-
OllamaChatClient 方法签名已更改。
-
将org.springframework.ai.autoconfigure.ollama.OllamaProperties重命名为org.springframework.ai.model.ollama.autoconfigure.OllamaChatProperties,并将后缀更改为:
spring.ai.ollama.chat
.一些属性也发生了变化。
2023 年 12 月 19 日更新
重命名 AiClient 和相关类和包名
-
将 AiClient 重命名为 ChatClient
-
将 AiResponse 重命名为 ChatResponse
-
将 AiStreamClient 重命名为 StreamingChatClient
-
将包 org.sf.ai.client 重命名为 org.sf.ai.chat
重命名 的工件 ID
-
transformers-embedding
自spring-ai-transformers
将 Maven 模块从顶级目录和embedding-clients
子目录下的所有models
目录。
12月 1, 2023
我们正在转换项目的组 ID:
-
出发地:
org.springframework.experimental.ai
-
收件人:
org.springframework.ai
构件仍将托管在快照存储库中,如下所示。
main 分支将移动到版本0.8.0-SNAPSHOT
.
它会不稳定一两周。
如果您不想处于最前沿,请使用 0.7.1-SNAPSHOT。
您可以访问0.7.1-SNAPSHOT
工件,并且仍然可以访问 0.7.1-SNAPSHOT 文档。
0.7.1-SNAPSHOT 依赖项
-
Azure OpenAI
<dependency> <groupId>org.springframework.experimental.ai</groupId> <artifactId>spring-ai-azure-openai-spring-boot-starter</artifactId> <version>0.7.1-SNAPSHOT</version> </dependency>
-
OpenAI
<dependency> <groupId>org.springframework.experimental.ai</groupId> <artifactId>spring-ai-openai-spring-boot-starter</artifactId> <version>0.7.1-SNAPSHOT</version> </dependency>
升级到 1.0.0.M4
-
删除 PaLM API 支持
作为弃用 PaLM API 的公告的后续行动,已删除 PaLM API 支持。