跳到主要内容

升级说明

DeepSeek V3 中英对照 Upgrade Notes

升级到 1.0.0.M6​

使用界面和 DefaultUsage 实现的更改​

Usage 接口及其默认实现 DefaultUsage 经历了以下变化：

  1. 方法重命名：

    • getGenerationTokens() 现在改为 getCompletionTokens()

  2. 类型变更：

    • DefaultUsage 中的所有 token 计数字段从 Long 改为 Integer：

      • promptTokens

      • completionTokens（原为 generationTokens）

      • totalTokens

必需操作​

  • 将所有对 getGenerationTokens() 的调用替换为 getCompletionTokens()

  • 更新 DefaultUsage 构造函数的调用：

// Old (M5)
new DefaultUsage(Long promptTokens, Long generationTokens, Long totalTokens)

// New (M6)
new DefaultUsage(Integer promptTokens, Integer completionTokens, Integer totalTokens)
备注

有关处理 Usage 的更多信息，请参考此处

JSON 序列化/反序列化变更​

虽然 M6 在 JSON 反序列化中保持了 generationTokens 字段的向后兼容性，但该字段将在 M7 中被移除。任何使用旧字段名的持久化 JSON 文档都应更新为使用 completionTokens。

新的 JSON 格式示例：

{
  "promptTokens": 100,
  "completionTokens": 50,
  "totalTokens": 150
}
json

对工具调用中 FunctionCallingOptions 使用方式的更改​

每个 ChatModel 实例在构造时，可以接受一个可选的 ChatOptions 或 FunctionCallingOptions 实例，用于配置调用模型时使用的默认工具。

在 1.0.0-M6 版本之前：

  • 通过默认 FunctionCallingOptions 实例的 functions() 方法传递的任何工具都会包含在每次从该 ChatModel 实例调用模型时，可能会被运行时选项覆盖。

  • 通过默认 FunctionCallingOptions 实例的 functionCallbacks() 方法传递的任何工具仅用于运行时动态解析（参见 工具解析），除非明确请求，否则不会包含在任何模型调用中。

从 1.0.0-M6 版本开始：

  • 通过默认 FunctionCallingOptions 实例的 functions() 方法或 functionCallbacks() 传递的任何工具现在都以相同的方式处理：它被包含在该 ChatModel 实例对模型的每次调用中，可能被运行时选项覆盖。这样，工具在模型调用中的包含方式具有一致性，并防止由于 functionCallbacks() 和其他选项之间的行为差异而导致的任何混淆。

如果你想让一个工具在运行时动态解析，并且仅在明确请求时将其包含在发送给模型的聊天请求中，你可以使用 工具解析 中描述的其中一种策略。

备注

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 的 Embedding 模型外，所有 Amazon Bedrock 的聊天模型均被移除。

备注

有关使用聊天模型的信息，请参阅 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 Client 所需的更改。特别是，如果您的 classpath 上没有 HTTP 客户端库，这可能会导致使用 JdkClientHttpRequestFactory，而之前可能会使用 SimpleClientHttpRequestFactory。要切换为使用 SimpleClientHttpRequestFactory，您需要设置 spring.http.client.factory=simple。

  • 如果您使用的是不同版本的 Spring Boot（例如 Spring Boot 3.3.x）并且需要特定版本的依赖项，您可以在构建配置中覆盖它。

Vector Store API 变更​

在 1.0.0-M6 版本中，VectorStore 接口中的 delete 方法已被修改为无返回值（void）操作，而不再返回 Optional<Boolean>。如果你的代码之前检查了删除操作的返回值，你需要移除这一检查。现在，如果删除操作失败，该方法会抛出异常，从而提供了更直接的错误处理机制。

1.0.0-M6 之前:​

Optional<Boolean> result = vectorStore.delete(ids);
if (result.isPresent() && result.get()) {
    // handle successful deletion
}
java

在 1.0.0-M6 及更高版本中：​

vectorStore.delete(ids);
// deletion successful if no exception is thrown
java

升级到 1.0.0.M5​

  • Vector Builders 已进行重构以确保一致性。

  • 当前 VectorStore 实现的构造函数已被弃用，请使用构建器模式。

  • VectorStore 实现的包已被移动到唯一的包名中，以避免跨工件的冲突。例如，从 org.springframework.ai.vectorstore 移动到 org.springframework.ai.pgvector.vectorstore。

升级到 1.0.0.RC3​

  • 便携式聊天选项（frequencyPenalty、presencePenalty、temperature、topP）的类型已从 Float 更改为 Double。

升级到 1.0.0.M2​

  • Chroma Vector Store 的配置前缀已从 spring.ai.vectorstore.chroma.store 更改为 spring.ai.vectorstore.chroma，以便与其他向量存储的命名约定保持一致。

  • 支持初始化模式的向量存储的 initialize-schema 属性的默认值现在设置为 false。这意味着如果希望在应用程序启动时创建模式，应用程序现在需要明确选择在支持的向量存储上进行模式初始化。并非所有向量存储都支持此属性。有关更多详细信息，请参阅相应的向量存储文档。以下是目前不支持 initialize-schema 属性的向量存储。

    1. Hana

    2. Pinecone

    3. 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 的实例。这样做的目的是为了支持一种流畅的 API，用于以类似于 Spring 生态系统中其他客户端类（如 RestClient、WebClient 和 JdbcClient）的风格创建和执行提示。有关 Fluent API 的更多信息，请参考 JavaDoc，正式的参考文档即将发布。

我们将旧的 ModelClient 重命名为 Model，并将实现类进行了重命名，例如 ImageClient 被重命名为 ImageModel。Model 实现代表了在 Spring AI API 和底层 AI Model API 之间进行转换的可移植层。

适应变化​

备注

ChatClient 类现在位于 org.springframework.ai.chat.client 包中

方法 1​

现在，你将获得一个 ChatModel 实例，而不是自动配置的 ChatClient 实例。重命名后的 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));
    }
}
java

现在，经过这些更改，这将变为

@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));
    }
}
java
备注

重命名也适用于以下类：* StreamingChatClient → StreamingChatModel * EmbeddingClient → EmbeddingModel * ImageClient → ImageModel * SpeechClient → SpeechModel * 以及其他类似的 <XYZ>Client 类

方法 2​

在这种方法中，你将使用新的 ChatClient 上提供的流式 API。

以下是更改前的现有代码示例

@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)
        );
	}
}
java

现在经过这些更改后，将会是

@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()
        );
    }
}
java
备注

ChatModel 实例通过自动配置提供给您使用。

方法 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
bash

制品名称变更​

重命名的 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-redis-store-spring-boot-starter

升级到 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>
xml

To

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-vertex-ai-palm2</artifactId>
</dependency>
xml

并且，Palm2 模型相关的 Boot starter 已经从

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-vertex-ai-spring-boot-starter</artifactId>
</dependency>
xml

到

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-vertex-ai-palm2-spring-boot-starter</artifactId>
</dependency>
xml

  • 重命名的类 (2024年1月3日)

    • VertexAiApi → VertexAiPalm2Api

    • VertexAiClientChat → VertexAiPalm2ChatClient

    • VertexAiEmbeddingClient → VertexAiPalm2EmbeddingClient

    • VertexAiChatOptions → VertexAiPalm2ChatOptions

升级到 0.8.0​

2024 年 1 月 24 日更新​

  • 将 prompt、messages 和 metadata 包移动到 org.sf.ai.chat 的子包中。

  • 新增功能是 文本生成图像 客户端。相关类为 OpenAiImageModel 和 StabilityAiImageModel。使用示例请参见集成测试，文档即将发布。

  • 新增 model 包，其中包含接口和基类，用于支持为任何输入/输出数据类型组合创建 AI 模型客户端。目前，聊天和图像模型包已实现此功能。我们很快将更新嵌入包以适配此新模型。

  • 新的“便携式选项”设计模式。我们希望尽可能在 ModelCall 中提供跨不同基于聊天的 AI 模型的可移植性。有一组通用的生成选项，以及特定于模型提供商的选项。采用了一种类似“鸭子类型”的方法。model 包中的 ModelOptions 是一个标记接口，表示该类的实现将提供模型的选项。参见 ImageOptions，这是一个子接口，定义了所有文本→图像 ImageModel 实现的便携式选项。然后 StabilityAiImageOptions 和 OpenAiImageOptions 提供了特定于每个模型提供商的选项。所有选项类都是通过流畅的 API 构建器创建的，并且都可以传递到便携式 ImageModel API 中。这些选项数据类型用于 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 * 使用 SimpleVectorStore 替换 InMemoryVectorStore

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.autoconfigure.ollama.OllamaChatProperties，并将后缀更改为：spring.ai.ollama.chat。部分属性也有所更改。

2023 年 12 月 19 日更新​

重命名 AiClient 及相关类和包名

  • 将 AiClient 重命名为 ChatClient

  • 将 AiResponse 重命名为 ChatResponse

  • 将 AiStreamClient 重命名为 StreamingChatClient

  • 将包 org.sf.ai.client 重命名为 org.sf.ai.chat

重命名 artifact ID

  • transformers-embedding 转换为 spring-ai-transformers

将 Maven 模块从顶级目录和 embedding-clients 子目录移动到一个统一的 models 目录下。

2023 年 12 月 1 日​

我们正在迁移项目的 Group ID：

  • FROM: org.springframework.experimental.ai

  • TO: org.springframework.ai

Artifacts 仍将托管在快照仓库中，如下所示。

主分支将迁移到 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>
    xml

  • OpenAI

    <dependency>
        <groupId>org.springframework.experimental.ai</groupId>
        <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
        <version>0.7.1-SNAPSHOT</version>
    </dependency>
    xml

升级到 1.0.0.M4​

  • 移除 PaLM API 支持

继宣布弃用 PaLM API 之后，PaLM API 的支持已被移除。