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

Add upgrade notes

Browse Source
This commit is contained in:
Mark Pollack
2025-04-04 12:43:17 -04:00
parent 57f0b592e9
commit 4f63fdc305
3 changed files with 135 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
spring-ai-docs/src/main/antora/modules/ROOT/nav.adoc
View File

@@ -113,5 +113,4 @@
* xref:contribution-guidelines.adoc[Contribution Guidelines]
* Appendices
** xref:upgrade-notes.adoc[]
* xref:upgrade-notes.adoc[]

6
spring-ai-docs/src/main/antora/modules/ROOT/pages/api/retrieval-augmented-generation.adoc
View File

@@ -68,11 +68,9 @@ The `FILTER_EXPRESSION` parameter allows you to dynamically filter the search re
=== RetrievalAugmentationAdvisor (Incubating)
Spring AI includes a xref:api/retrieval-augmented-generation.adoc#modules[library of RAG modules] that you can use to build your own RAG flows.
The `RetrievalAugmentationAdvisor` is an experimental `Advisor` providing an out-of-the-box implementation for the most common RAG flows,
The `RetrievalAugmentationAdvisor` is an `Advisor` providing an out-of-the-box implementation for the most common RAG flows,
based on a modular architecture.
WARNING: The `RetrievalAugmentationAdvisor` is an experimental feature and is subject to change in future releases.
==== Sequential RAG Flows
===== Naive RAG
@@ -165,8 +163,6 @@ String answer = chatClient.prompt()
Spring AI implements a Modular RAG architecture inspired by the concept of modularity detailed in the paper
"https://arxiv.org/abs/2407.21059[Modular RAG: Transforming RAG Systems into LEGO-like Reconfigurable Frameworks]".
WARNING:: Modular RAG is an experimental feature and is subject to change in future releases.
=== Pre-Retrieval
Pre-Retrieval modules are responsible for processing the user query to achieve the best possible retrieval results.

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

@@ -4,6 +4,7 @@
[[upgrading-to-1-0-0-snapshot]]
== Upgrading to 1.0.0-SNAPSHOT
== Part 1
You can upgrade to 1.0.0-SNAPSHOT either by following the manual steps outlined below or by using an automated approach with the Claude Code CLI tool and a provided prompt.
The automated approach can save time and reduce errors when upgrading multiple projects or complex codebases.
@@ -171,7 +172,138 @@ To use this automation:
This approach can save time and reduce the chance of errors when upgrading multiple projects or complex codebases.
== Upgrading to 1.0.0.M7
== Part 2
As of April 4, the main branch now has changes to module/artifact structure of the project.
Since the start of the Spring AI project, there has been one central artifact where the main interfaces are defined, the `spring-ai-core` module.
Over time, this has grown to contain multiple specialized domains and we wanted to separate these domain out into their own modules.
For example, to use the `ChatClient` functionality, there does not need to be any classes related to Vector Stores in your application.
The `spring-ai-core` module had a clean Dependency Structure Matrix, so most of the work to break up this module was simply cut and pasting code.
However, there were a few cases where the package names of classes have been changed.
=== Changes to package names
Your IDE should assist with refactoring to the new package locations.
`ContentFormatTransformer` and `KeywordMetadataEnricher` have moved from `org.springframework.ai.transformer` to `org.springframework.ai.chat.transformer`.
`Content`, `MediaContent`, and `Media` have moved from `org.springframework.ai.model` to `org.springframework.ai.content`.
=== New Modules Overview
==== `spring-ai-commons`
This is a base module with no dependencies on other Spring AI modules.
It defines core domain models (`Document`, `TextSplitter`, etc.), JSON utilities, resource handling, and structured logging.
Supports document processing, tokenization, embedding optimization, and observability via operation metadata and metrics.
==== `spring-ai-model`
Provides abstractions for AI capabilities via interfaces like `ChatModel`, `EmbeddingModel`, and `ImageModel`.
Includes message types, prompt templates, response structures, and a full function-calling framework (`ToolDefinition`, `ToolCallback`, annotations).
Supports observation, content filtering, and consistent builder/strategy patterns across AI providers.
==== `spring-ai-vector-store`
Defines a unified abstraction (`VectorStore`) for vector databases and similarity search.
Includes advanced filtering via SQL-like expressions, `SearchRequest`, and `Filter.Expression.`
Offers `SimpleVectorStore` (in-memory) and observability integration.
Emphasizes type safety, extensibility, and batching support for embeddings.
==== `spring-ai-client-chat`
This module provides high-level APIs for conversational AI via the `ChatClient` interface.
Includes conversation persistence (`ChatMemory`), response conversion (`OutputConverter`), and advisor-based interception.
Supports synchronous and streaming (Project Reactor) interactions with observability via Micrometer.
This client layer abstracts away the complexities of different AI model implementations, providing application developers with a uniform way to incorporate conversational AI capabilities while handling common concerns like conversation state management, response transformation, and instrumentation in a consistent manner.
==== `spring-ai-advisors-vector-store`
Bridges chat with vector stores for RAG and persistent memory.
`QuestionAnswerAdvisor`: injects context into prompts using similarity search.
`VectorStoreChatMemoryAdvisor`: stores/retrieves conversation history in vector stores, with filtering and session continuity.
This component is essential for implementing sophisticated conversational applications that require both context retrieval and memory persistence within the Spring AI ecosystem.
==== `spring-ai-model-chat-memory-cassandra`
This module adds Apache Cassandra persistence for `ChatMemory` (via `CassandraChatMemory`).
Extracted from the Cassandra vector store module to provide a standalone, production-ready solution.
Uses immutable config records and Cassandra's QueryBuilder for type-safe CQL.
==== `spring-ai-model-chat-memory-neo4j`
This module provides Neo4j graph database persistence for chat conversations.
This functionality was previously located in the Neo4j vector store implementation module, but has been extracted to create a dedicated chat memory solution.
==== `spring-ai-rag`
This module provides a comprehensive framework for implementing Retrieval Augmented Generation (RAG)
pipelines based on a modular architecture inspired by academic research. It offers a structured approach to the entire RAG workflow through well-defined interfaces for each stage of the process.
The central `RetrievalAugmentationAdvisor` serves as the main entry point, orchestrating the entire RAG workflow.
The design follows functional programming principles with composable components, enabling customization of each pipeline stage while maintaining a consistent programming model aligned with Spring's conventions.
=== Dependency Structure
The dependency hierarchy can be summarized as:
* `spring-ai-commons` (foundation)
* `spring-ai-model` (depends on commons)
* `spring-ai-vector-store` and `spring-ai-client-chat` (both depend on model)
* `spring-ai-advisors-vector-store` and `spring-ai-rag` (depend on both client-chat and vector-store)
* `spring-ai-model-chat-memory-*` modules (depend on client-chat)
The details are:
=== Module Dependencies
[cols="1,3,3", options="header"]
|===
| Module
| Depends On
| Description
| `spring-ai-commons`
| _None_
| Base module with no dependencies on other Spring AI modules. Used by many other modules.
| `spring-ai-model`
| `spring-ai-commons`
| Provides core model interfaces and abstractions.
| `spring-ai-vector-store`
| `spring-ai-model` → `spring-ai-commons`
| Provides vector database abstractions.
| `spring-ai-client-chat`
| `spring-ai-model` → `spring-ai-commons`
| High-level client API for chat interactions.
| `spring-ai-advisors-vector-store`
| `spring-ai-client-chat`, `spring-ai-vector-store`
| Bridges chat capabilities with vector stores.
| `spring-ai-model-chat-memory-cassandra`
| `spring-ai-client-chat`
| Provides Cassandra implementation for chat memory.
| `spring-ai-model-chat-memory-neo4j`
| `spring-ai-client-chat`
| Provides Neo4j implementation for chat memory.
| `spring-ai-rag`
| `spring-ai-client-chat`, `spring-ai-vector-store`
| Provides RAG framework implementation.
|===
=== ToolContext changes
* The `ToolContext` class has now been marked as final and cannot be extended anymore. It was never supposed to be subclassed. You can add all the contextual data you need when instantiating a `ToolContext`, in the form of a `Map<String, Object>`. For more information, check the [documentation](https://docs.spring.io/spring-ai/reference/api/tools.html#_tool_context).