Spring 博客

所有帖子
工程
发布
新闻和事件

Spring AI 1.0.0 M8 发布

发布 | Mark Pollack | 2025年4月30日 | ...

在审查了 M7 之后的 API 设计和弃用信息后，我们确定了几项重大更改将在 RC1 版本中成为破坏性更改。因此，我们引入了这个额外的里程碑，为开发者提供一个过渡版本，其中弃用的 API 与其替换项共存，从而在 RC1 发布之前实现更平滑的升级体验。

以下是本次发布的主要变更。

  • 升级说明
  • 您可以使用 OpenRewrite 脚本自动升级到 1.0.0-M8。该脚本有助于应用许多此版本所需的代码更改。请访问 Arconia Spring AI Migrations 来查找脚本和使用说明。

破坏性变更

在从 Spring AI 1.0 M7 升级到 1.0 M8 时，先前注册了工具回调的用户会遇到破坏性更改，导致工具调用功能无声地失败。这尤其影响了使用已弃用的 tools() 方法的代码。

示例

以下是一个在 M7 中有效但在 M8 中不再按预期工作的代码示例

// Old code in M7 - no longer works correctly in M8
chatClient.prompt("What day is tomorrow?")
    .tools(toolCallback)
    .call()
    .content();

如何修改您的代码

要修复升级到 M8 时出现此问题，您需要更新代码以使用新的 toolCallbacks() 方法

// Updated code for M8
chatClient.prompt("What day is tomorrow?")
    .toolCallbacks(toolCallback)
    .call()
    .content();

此更改的原因

Spring AI 团队重命名了重载的 tools() 方法，以提高清晰度并避免方法分派时的歧义。之前的 API 设计在 Java 编译器需要根据参数类型在多个重载方法之间进行选择时，会导致混淆。

M7 到 M8 的方法映射

旧方法如何映射到新方法

  1. tools(String... toolNames) → toolNames(String... toolNames)

    • 用于引用在其他地方注册的工具（例如，通过带有 @Description 的 @Bean）

  2. tools(ToolCallback... toolCallbacks) → toolCallbacks(ToolCallback... toolCallbacks)

    • 用于内联工具回调注册

  3. tools(List<ToolCallback> toolCallbacks) → toolCallbacks(List<ToolCallback> toolCallbacks)

    • 当您有一个工具回调集合时使用

  4. tools(ToolCallbackProvider... toolCallbackProviders) → toolCallbacks(ToolCallbackProvider... toolCallbackProviders)

    • 用于实现 ToolCallbackProvider 接口的对象

  5. tools(Object... toolObjects) 保持不变

    • 仅用于带有 @Tool 注解的方法的对象

改进的错误处理

在 最新的 PR (spring-projects/spring-ai#2964) 中，tools(Object... toolObjects) 方法现在会在提供的对象上找不到 @Tool 方法时抛出异常，而不是无声地失败。这有助于开发者立即识别迁移问题。

迁移总结

如果您正在从 M7 升级到 M8

  1. 将所有对 .tools(toolCallback) 的调用替换为 .toolCallbacks(toolCallback)
  2. 将所有对 .tools(toolCallbackProvider) 的调用替换为 .toolCallbacks(toolCallbackProvider)
  3. 将所有对 .tools("toolName") 的调用替换为 .toolNames("toolName")

这些更改将确保您的工具调用功能在升级到 Spring AI 1.0 M8 后继续正常工作。

新功能

  1. 聊天内存增强
  • 增强的聊天内存架构
    • 改进的 ChatMemory API，用于更灵活的对话历史管理
    • 新的 ChatMemoryRepository 接口允许不同的存储策略
    • 添加了 MessageWindowChatMemory，用于维护消息窗口
    • 改进了属性命名，以在实现之间保持一致
    • 支持各种存储后端
      • InMemoryChatMemoryRepository（默认）
      • JdbcChatMemoryRepository，用于关系型数据库
    • 有关聊天内存配置的更多详细信息，请参阅 内存类型 和 内存存储。
  1. 模板渲染*
  • 引入 TemplateRenderer 用于提示模板化
    • 用于模板渲染的灵活新 API，可在不同的模板引擎之间提供一致的接口
    • 包括新的 StTemplateRenderer，支持内置函数和自定义验证选项。在此 处 查看如何使用它。
    • 直接集成到 ChatClient 中，以简化提示模板化
    • 添加了 NoOpTemplateRenderer，用于不需要模板化的场景
    • 相关： "在 ChatClient 中配置 TemplateRenderer"、"更新文档以提及 NoOpTemplateRenderer"
  1. MCP 改进
  • 增强的 MCP 工具回调配置
    • 将工具回调配置添加到 MCP 客户端属性
    • 支持 MCP 服务器中的完成规范
    • 为 MCP 服务器添加了说明支持
    • 为 WebFlux 和 WebMvc 传输提供商添加了 SSE 端点参数
  1. 提示工程模式
  • 添加提示工程模式文档
    • 关于高级提示工程技术的全新综合文档
    • 为开发者提供有效提示设计的最佳实践
    • 包括各种用例的示例和模式
  1. 向量存储增强
  • Cosmos DB Entra ID 支持和修复
    • 为 Cosmos DB 添加了 Azure Entra ID（前身为 Azure AD）身份验证
    • 改进了 Azure 部署的安全和身份验证选项
  • Cassandra 向量存储改进
    • 修复了 Cassandra 聊天内存中的消息顺序
    • 添加了更好的错误消息并修复了各种问题

弃用

需要注意的重要弃用信息包括

  1. Chat Client 增强:

    • ChatClient 已更新，以确保用户和系统提示始终在顾问执行之前进行渲染。此更改用 ChatClientRequest 和 ChatClientResponse 替换了 AdvisedRequest 和 AdvisedResponse API。

  2. 提示模板化和顾问:

    • 与提示创建和顾问自定义相关的类和方法已被弃用，取而代之的是构建器模式和 TemplateRenderer 接口。

  3. QuestionAnswerAdvisor 弃用:

    • 弃用了依赖于简单 userTextAdvise 字符串的构造函数和构建器方法。

  4. 聊天内存配置:

    • spring.ai.chat.memory.jdbc.initialize-schema 属性已被弃用，取而代之的是 spring.ai.chat.memory.repository.jdbc.initialize-schema。

  5. 文档处理:

    • DocumentPostProcessor API 取代了 DocumentCompressor、DocumentRanker 和 DocumentSelector 等已弃用的 API。

  6. 聊天内存弃用:

    • ChatMemory 中的 @Deprecated List<Message> get(String conversationId, int lastN); 已被弃用。

贡献者

还有许多其他重构、错误修复、文档增强等工作由众多贡献者完成。如果您的 PR 尚未被处理，我们会尽快处理，请耐心等待。感谢

获取 Spring 新闻通讯

通过 Spring 新闻通讯保持联系

订阅

领先一步

VMware 提供培训和认证，助您加速进步。

了解更多

获得支持

Tanzu Spring 提供 OpenJDK™、Spring 和 Apache Tomcat® 的支持和二进制文件，只需一份简单的订阅。

了解更多

即将举行的活动

查看 Spring 社区所有即将举行的活动。

查看所有