Upgrading Notes

Upgrading to 1.0.0.M5

  • Vector Builders have been refactored for consistency.

  • Current VectorStore implementation constructors have been deprecated, use the builder pattern.

  • VectorStore implementation packages have been moved into unique package names, avoiding conflicts across artifact. For example org.springframework.ai.vectorstore to org.springframework.ai.pgvector.vectorstore.

Upgrading to 1.0.0.RC3

  • The type of the portable chat options (frequencyPenalty, presencePenalty, temperature, topP) has been changed from Float to Double.

Upgrading to 1.0.0.M2

  • The configuration prefix for the Chroma Vector Store has been changes from spring.ai.vectorstore.chroma.store to spring.ai.vectorstore.chroma in order to align with the naming conventions of other vector stores.

  • The default value of the initialize-schema property on vector stores capable of initializing a schema is now set to false. This implies that the applications now need to explicitly opt-in for schema initialization on supported vector stores, if the schema is expected to be created at application startup. Not all vector stores support this property. See the corresponding vector store documentation for more details. The following are the vector stores that currently don’t support the initialize-schema property.

    1. Hana

    2. Pinecone

    3. Weaviate

  • In Bedrock Jurassic 2, the chat options countPenalty, frequencyPenalty, and presencePenalty have been renamed to countPenaltyOptions, frequencyPenaltyOptions, and presencePenaltyOptions. Furthermore, the type of the chat option stopSequences have been changed from String[] to List<String>.

  • In Azure OpenAI, the type of the chat options frequencyPenalty and presencePenalty has been changed from Double to Float, consistently with all the other implementations.

Upgrading to 1.0.0.M1

On our march to release 1.0.0 M1 we have made several breaking changes. Apologies, it is for the best!

ChatClient changes

A major change was made that took the 'old' ChatClient and moved the functionality into ChatModel. The 'new' ChatClient now takes an instance of ChatModel. This was done do support a fluent API for creating and executing prompts in a style similar to other client classes in the Spring ecosystem, such as RestClient, WebClient, and JdbcClient. Refer to the [JavaDoc](docs.spring.io/spring-ai/docs/api) for more information on the Fluent API, proper reference documentation is coming shortly.

We renamed the 'old' ModelClient to Model and renamed implementing classes, for example ImageClient was renamed to ImageModel. The Model implementation represent the portability layer that converts between the Spring AI API and the underlying AI Model API.

Adapting to the changes

The ChatClient class is now in the package org.springframework.ai.chat.client

Approach 1

Now, instead of getting an Autoconfigured ChatClient instance, you will get a ChatModel instance. The call method signatures after renaming remain the same. To adapt your code should refactor you code to change use of the type ChatClient to ChatModel Here is an example of existing code before the change

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

Now after the changes this will be

@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));
    }
}
The renaming also applies to the classes * StreamingChatClient → StreamingChatModel * EmbeddingClient → EmbeddingModel * ImageClient → ImageModel * SpeechClient → SpeechModel * and similar for other <XYZ>Client classes

Approach 2

In this approach you will use the new fluent API available on the 'new' ChatClient

Here is an example of existing code before the change

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

Now after the changes this will be

@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()
        );
    }
}
The ChatModel instance is made available to you through autoconfiguration.

Approach 3

There is a tag in the GitHub repository called [v1.0.0-SNAPSHOT-before-chatclient-changes](github.com/spring-projects/spring-ai/tree/v1.0.0-SNAPSHOT-before-chatclient-changes) that you can checkout and do a local build to avoid updating any of your code until you are ready to migrate your code base.

git checkout tags/v1.0.0-SNAPSHOT-before-chatclient-changes

./mvnw clean install -DskipTests

Artifact name changes

Renamed POM artifact names: - 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

Upgrading to 0.8.1

Former spring-ai-vertex-ai has been renamed to spring-ai-vertex-ai-palm2 and spring-ai-vertex-ai-spring-boot-starter has been renamed to spring-ai-vertex-ai-palm2-spring-boot-starter.

So, you need to change the dependency from

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

To

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

and the related Boot starter for the Palm2 model has changed from

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

to

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

  • Renamed Classes (01.03.2024)

    • VertexAiApi → VertexAiPalm2Api

    • VertexAiClientChat → VertexAiPalm2ChatClient

    • VertexAiEmbeddingClient → VertexAiPalm2EmbeddingClient

    • VertexAiChatOptions → VertexAiPalm2ChatOptions

Upgrading to 0.8.0

January 24, 2024 Update

  • Moving the prompt and messages and metadata packages to subpackages of org.sf.ai.chat

  • New functionality is text to image clients. Classes are OpenAiImageModel and StabilityAiImageModel. See the integration tests for usage, docs are coming soon.

  • A new package model that contains interfaces and base classes to support creating AI Model Clients for any input/output data type combination. At the moment the chat and image model packages implement this. We will be updating the embedding package to this new model soon.

  • A new "portable options" design pattern. We wanted to provide as much portability in the ModelCall as possible across different chat based AI Models. There is a common set of generation options and then those that are specific to a model provider. A sort of "duck typing" approach is used. ModelOptions in the model package is a marker interface indicating implementations of this class will provide the options for a model. See ImageOptions, a subinterface that defines portable options across all text→image ImageModel implementations. Then StabilityAiImageOptions and OpenAiImageOptions provide the options specific to each model provider. All options classes are created via a fluent API builder all can be passed into the portable ImageModel API. These option data types are using in autoconfiguration/configuration properties for the ImageModel implementations.

January 13, 2024 Update

The following OpenAi Autoconfiguration chat properties has changed

  • from spring.ai.openai.model to spring.ai.openai.chat.options.model.

  • from spring.ai.openai.temperature to spring.ai.openai.chat.options.temperature.

Find updated documentation about the OpenAi properties: docs.spring.io/spring-ai/reference/api/chat/openai-chat.html

December 27, 2023 Update

Merge SimplePersistentVectorStore and InMemoryVectorStore into SimpleVectorStore * Replace InMemoryVectorStore with SimpleVectorStore

December 20, 2023 Update

Refactor the Ollama client and related classes and package names

  • Replace the org.springframework.ai.ollama.client.OllamaClient by org.springframework.ai.ollama.OllamaModelCall.

  • The OllamaChatClient method signatures have changed.

  • Rename the org.springframework.ai.autoconfigure.ollama.OllamaProperties into org.springframework.ai.autoconfigure.ollama.OllamaChatProperties and change the suffix to: spring.ai.ollama.chat. Some of the properties have changed as well.

December 19, 2023 Update

Renaming of AiClient and related classes and package names

  • Rename AiClient to ChatClient

  • Rename AiResponse to ChatResponse

  • Rename AiStreamClient to StreamingChatClient

  • Rename package org.sf.ai.client to org.sf.ai.chat

Rename artifact ID of

  • transformers-embedding to spring-ai-transformers

Moved Maven modules from top-level directory and embedding-clients subdirectory to all be under a single models directory.

December 1, 2023

We are transitioning the project’s Group ID:

  • FROM: org.springframework.experimental.ai

  • TO: org.springframework.ai

Artifacts will still be hosted in the snapshot repository as shown below.

The main branch will move to the version 0.8.0-SNAPSHOT. It will be unstable for a week or two. Please use the 0.7.1-SNAPSHOT if you don’t want to be on the bleeding edge.

You can access 0.7.1-SNAPSHOT artifacts as before and still access 0.7.1-SNAPSHOT Documentation.

0.7.1-SNAPSHOT Dependencies

  • 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>

Upgrading to 1.0.0.M4

  • PaLM API support removal

As a follow up to the announcement to deprecate PaLM API, the PaLM API support is removed.