Spring 博客

所有文章
工程
发布
新闻和活动

Spring AI 1.0.0 M8 发布

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

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

以下是此版本中的主要更改。

  • 升级说明
  • 您可以使用 OpenRewrite Recipe 自动化升级到 1.0.0-M8 的过程。此 Recipe 有助于应用此版本的许多必要代码更改。可在 Arconia Spring AI Migrations 查找该 Recipe 和使用说明。

破坏性更改

从 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) 中，当提供的对象上没有找到 @Tool 方法时，tools(Object... toolObjects) 方法现在会抛出异常，而不是静默失败。这有助于开发者立即识别迁移问题。

迁移总结

如果你正在从 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，支持内置函数和自定义验证选项。请在此处查看如何使用它：here。
    • 直接集成到 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. 聊天客户端增强:

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

  2. 提示词模板化和顾问:

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

  3. QuestionAnswerAdvisor 弃用:

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

  4. 聊天记忆配置:

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

  5. 文档处理:

    • DocumentPostProcessor API 替换了诸如 DocumentCompressor、DocumentRanker 和 DocumentSelector 等已弃用的 API。

  6. 聊天记忆弃用:

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

贡献者

各领域的广泛贡献者还进行了其他重构、错误修复和文档增强。如果你的 PR 我们尚未处理，我们会的，请耐心等待。感谢以下贡献者：

订阅 Spring 新闻邮件

通过 Spring 新闻邮件保持联系

订阅

取得领先

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

了解更多

获得支持

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

了解更多

即将到来的活动

查看 Spring 社区所有即将到来的活动。

查看全部