Spring/spring-ai
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

clean up upgrade-notes.adoc

Browse Source
This commit is contained in:
Mark Pollack
2025-04-30 12:09:15 -04:00
parent c347c6feaf
commit b39805af30
1 changed files with 17 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

31
spring-ai-docs/src/main/antora/modules/ROOT/pages/upgrade-notes.adoc
View File

@@ -46,9 +46,13 @@ This approach can save time and reduce the chance of errors when upgrading multi
[[upgrading-to-1-0-0-m8]]
== Upgrading to 1.0.0-M8
You can automate the upgrade process to 1.0.0-M8 using an OpenRewrite recipe.
This recipe helps apply many of the necessary code changes for this version.
Find the recipe and usage instructions at https://github.com/arconia-io/arconia-migrations/blob/main/docs/spring-ai.md[Arconia Spring AI Migrations].
=== Chat Client
* The `ChatClient` has been enhanced to solve some inconsistencies or unwanted behaviour whenever user and system prompts were not rendered before using them in an advisor. The new behavior ensures that the user and system prompts are always rendered before executing the chain of advisors. As part of this enhancement, the `AdvisedRequest` and `AdvisedResponse` APIs have been deprecated, replaced by `ChatClientRequest` and `ChatClientResponse`. Advisors now act on a fully built `Prompt` object included in a `ChatClientRequest` instead of the destructured format used in `AdvisedRequest`, guaranteeing consistency and completeness.
* The `ChatClient` has been enhanced to solve some inconsistencies or unwanted behavior whenever user and system prompts were not rendered before using them in an advisor. The new behavior ensures that the user and system prompts are always rendered before executing the chain of advisors. As part of this enhancement, the `AdvisedRequest` and `AdvisedResponse` APIs have been deprecated, replaced by `ChatClientRequest` and `ChatClientResponse`. Advisors now act on a fully built `Prompt` object included in a `ChatClientRequest` instead of the destructured format used in `AdvisedRequest`, guaranteeing consistency and completeness.
For example, if you had a custom advisor that modified the request prompt in the `before` method, you would refactor it as follows:
@@ -133,7 +137,8 @@ This change addresses potential confusion where the Java compiler might not sele
=== Prompt Templating and Advisors
Several classes and methods related to prompt creation and advisor customization have been deprecated in favor of more flexible approaches using the builder pattern and the `TemplateRenderer` interface.
Several classes and methods related to prompt creation and advisor customization have been deprecated in favor of more flexible approaches using the builder pattern and the `TemplateRenderer` interface.
See xref:api/prompt.adoc#_prompttemplate[PromptTemplate] for details on the new API.
==== PromptTemplate Deprecations
@@ -614,7 +619,6 @@ new DefaultUsage(Long promptTokens, Long generationTokens, Long totalTokens)
new DefaultUsage(Integer promptTokens, Integer completionTokens, Integer totalTokens)
----
NOTE: For more information on handling Usage, refer xref:api/usage-handling.adoc[here]
==== JSON Ser/Deser changes
@@ -666,7 +670,7 @@ NOTE: Refer to xref:api/chat/bedrock-converse.adoc[Bedrock Converse] documentati
=== Changes to use Spring Boot 3.4.2 for dependency management
Spring AI updates to use Spring Boot 3.4.2 for the dependency management. You can refer https://github.com/spring-projects/spring-boot/blob/v3.4.2/spring-boot-project/spring-boot-dependencies/build.gradle[here] for the dependencies which Spring Boot 3.4.2
Spring AI updates to use Spring Boot 3.4.2 for the dependency management. You can refer https://github.com/spring-projects/spring-boot/blob/v3.4.2/spring-boot-project/spring-boot-dependencies/build.gradle[here] for the dependencies managed by Spring Boot 3.4.2
==== Required Actions
@@ -732,9 +736,9 @@ On our march to release 1.0.0 M1 we have made several breaking changes. Apologi
=== 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](https://docs.spring.io/spring-ai/docs/api) for more information on the Fluent API, proper reference documentation is coming shortly.
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 to 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](https://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.
We renamed the 'old' `ModelClient` to `Model` and renamed implementing classes, for example `ImageClient` was renamed to `ImageModel`. The `Model` implementation represents the portability layer that converts between the Spring AI API and the underlying AI Model API.
### Adapting to the changes
@@ -742,8 +746,8 @@ NOTE: The `ChatClient` class is now in the package `org.springframework.ai.chat.
#### 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`
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 your code to change the use of the type `ChatClient` to `ChatModel`
Here is an example of existing code before the change
```java
@@ -837,12 +841,11 @@ class SimpleAiController {
}
```
NOTE: 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](https://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.
There is a tag in the GitHub repository called [v1.0.0-SNAPSHOT-before-chatclient-changes](https://github.com/spring-projects/spring-ai/tree/v1.0.0-SNAPSHOT-before-chatclient-changes) that you can check out and do a local build to avoid updating any of your code until you are ready to migrate your code base.
```bash
git checkout tags/v1.0.0-SNAPSHOT-before-chatclient-changes
@@ -918,14 +921,14 @@ to
=== January 24, 2024 Update
* Moving the `prompt` and `messages` and `metadata` packages to subpackages of `org.sf.ai.chat`
* Moving the `prompt` and `messages` and `metadata` packages to subpackages of `org.springframework.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.
* 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 used in autoconfiguration/configuration properties for the `ImageModel` implementations.
=== January 13, 2024 Update
The following OpenAi Autoconfiguration chat properties has changed
The following OpenAi Autoconfiguration chat properties have 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`.