From db1f3ea5d2999414f79d065a6ea43444fec9bd75 Mon Sep 17 00:00:00 2001 From: Mark Pollack Date: Mon, 27 May 2024 23:35:44 -0400 Subject: [PATCH] doc fixes --- README.md | 137 +----------------- .../modules/ROOT/pages/api/chatclient.adoc | 2 +- .../modules/ROOT/pages/upgrade-notes.adoc | 137 ++++++++++++++++++ 3 files changed, 140 insertions(+), 136 deletions(-) diff --git a/README.md b/README.md index e3e9c33785c..fe4aa92acdb 100644 --- a/README.md +++ b/README.md @@ -10,147 +10,14 @@ For further information go to our [Spring AI reference documentation](https://do ## Breaking changes -On our march to release 1.0.0 M1 we have made several breaking changes. Apologies, it is for the best! - -**(22.05.2024)** - -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/1.0.0-SNAPSHOT/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 - -NOTE: 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 - -```java -@RestController -public class OldSimpleAiController { - - private final ChatClient chatClient; - - public OldSimpleAiController(ChatClient chatClient) { - this.chatClient = chatClient; - } - - @GetMapping("/ai/simple") - Map completion(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) { - return Map.of("generation", chatClient.call(message)); - } -} -``` - -Now after the changes this will be - -```java -@RestController -public class SimpleAiController { - - private final ChatModel chatModel; - - public SimpleAiController(ChatModel chatModel) { - this.chatModel = chatModel; - } - - @GetMapping("/ai/simple") - Map completion(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) { - return Map.of("generation", chatModel.call(message)); - } -} -``` - -NOTE: The renaming also applies to the classes -* `StreamingChatClient` -> `StreamingChatModel` -* `EmbeddingClient` -> `EmbeddingModel` -* `ImageClient` -> `ImageModel` -* `SpeechClient` -> `SpeechModel` -* and similar for other `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 - -```java -@RestController -class OldSimpleAiController { - - ChatClient chatClient; - - OldSimpleAiController(ChatClient chatClient) { - this.chatClient = chatClient; - } - - @GetMapping("/ai/simple") - Map completion(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) { - return Map.of( - "generation", - chatClient.call(message) - ); - } -} -``` - -Now after the changes this will be - -```java -@RestController -class SimpleAiController { - - private final ChatClient chatClient; - - SimpleAiController(ChatClient.Builder builder) { - this.builder = builder.build(); - } - - @GetMapping("/ai/simple") - Map completion(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) { - return Map.of( - "generation", - chatClient.prompt().user(message).call().content() - ); - } -} -``` - - -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. - -```bash -git checkout tags/v1.0.0-SNAPSHOT-before-chatclient-changes - -./mvnw clean install -DskipTests -``` - - -**(15.05.2024)** - -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 +* Refer to the [upgrade notes](https://docs.spring.io/spring-ai/reference/upgrade-notes.html) to see how to upgrade to 1.0.0.M1 or higher. ## Project Links * [Documentation](https://docs.spring.io/spring-ai/reference/) * [Issues](https://github.com/spring-projects/spring-ai/issues) * [Discussions](https://github.com/spring-projects/spring-ai/discussions) - Go here if you have a question, suggestion, or feedback! -* [Upgrade from 0.7.1-SNAPSHOT](https://docs.spring.io/spring-ai/reference/upgrade-notes.html) + ## Educational Resources diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chatclient.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chatclient.adoc index 66522264c0c..70922b36c8c 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chatclient.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chatclient.adoc @@ -181,7 +181,7 @@ After specifying the `stream` method on `ChatClient`, there are a few options fo == Using Defaults Creating a ChatClient with default system text in an `@Configuration` class simplifies runtime code. -By setting defaults, you only need to specify user text when calling `ChatClient, eliminating the need to set system text for each request in your runtime codeala path. +By setting defaults, you only need to specify user text when calling `ChatClient`, eliminating the need to set system text for each request in your runtime code path. diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/upgrade-notes.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/upgrade-notes.adoc index 7195e6209ce..eae7f4f55f6 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/upgrade-notes.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/upgrade-notes.adoc @@ -1,6 +1,143 @@ [[upgrade-notes]] = Upgrading Notes +== 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](https://docs.spring.io/spring-ai/docs/1.0.0-SNAPSHOT/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 + +NOTE: 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 + +```java +@RestController +public class OldSimpleAiController { + + private final ChatClient chatClient; + + public OldSimpleAiController(ChatClient chatClient) { + this.chatClient = chatClient; + } + + @GetMapping("/ai/simple") + Map completion(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) { + return Map.of("generation", chatClient.call(message)); + } +} +``` + +Now after the changes this will be + +```java +@RestController +public class SimpleAiController { + + private final ChatModel chatModel; + + public SimpleAiController(ChatModel chatModel) { + this.chatModel = chatModel; + } + + @GetMapping("/ai/simple") + Map completion(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) { + return Map.of("generation", chatModel.call(message)); + } +} +``` + +NOTE: The renaming also applies to the classes +* `StreamingChatClient` -> `StreamingChatModel` +* `EmbeddingClient` -> `EmbeddingModel` +* `ImageClient` -> `ImageModel` +* `SpeechClient` -> `SpeechModel` +* and similar for other `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 + +```java +@RestController +class OldSimpleAiController { + + ChatClient chatClient; + + OldSimpleAiController(ChatClient chatClient) { + this.chatClient = chatClient; + } + + @GetMapping("/ai/simple") + Map completion(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) { + return Map.of( + "generation", + chatClient.call(message) + ); + } +} +``` + +Now after the changes this will be + +```java +@RestController +class SimpleAiController { + + private final ChatClient chatClient; + + SimpleAiController(ChatClient.Builder builder) { + this.builder = builder.build(); + } + + @GetMapping("/ai/simple") + Map completion(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) { + return Map.of( + "generation", + chatClient.prompt().user(message).call().content() + ); + } +} +``` + + +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. + +```bash +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`.