-
Notifications
You must be signed in to change notification settings - Fork 603
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Adds spring boot auto-configuration support for GemFireVectorStore - Adds integration test GemFireVectorStoreAutoConfigurationIT - Includes gemfire-testcontainers in integration tests - Adds unit test GemFireVectorStorePropertiesTests - Refactors GemFireVectorStore.java extracting GemFireVectorStoreConfig.java - Renames spring-ai-gemfire to spring-ai-gemfire-store - Adds GemFireConnectionDetails - Adds GemFireVectorStoreProperties with default values - Remove gemfire-release-repo maven repository Co-authored-by: Louis Jacome <louis.jacome@broadcom.com> Co-authored-by: Jason Huyn <jason.huynh@broadcom.com>
- Loading branch information
1 parent
58a30f7
commit 067a33d
Showing
15 changed files
with
979 additions
and
251 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
149 changes: 81 additions & 68 deletions
149
spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/gemfire.adoc
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,122 +1,135 @@ | ||
= GemFire Vector Store | ||
|
||
This section walks you through setting up the GemFire VectorStore to store document embeddings and perform similarity searches. | ||
This section walks you through setting up the `GemFireVectorStore` to store document embeddings and perform similarity searches. | ||
|
||
link:https://tanzu.vmware.com/gemfire[GemFire] is an ultra high speed in-memory data and compute grid, with vector extensions to store and search vectors efficiently. | ||
link:https://tanzu.vmware.com/gemfire[GemFire] is a distributed, in-memory, key-value store performing read and write operations at blazingly fast speeds. It offers highly available parallel message queues, continuous availability, and an event-driven architecture you can scale dynamically without downtime. As your data size requirements increase to support high-performance, real-time apps, GemFire can easily scale linearly. | ||
|
||
link:https://docs.vmware.com/en/VMware-GemFire-VectorDB/1.0/gemfire-vectordb/overview.html[GemFire VectorDB] extends GemFire's capabilities, serving as a versatile vector database that efficiently stores, retrieves, and performs vector searches through a distributed and resilient infrastructure: | ||
|
||
Capabilities: | ||
- Create Indexes | ||
- Store vectors and the associated metadata | ||
- Perform vector searches based on similarity | ||
link:https://docs.vmware.com/en/VMware-GemFire-VectorDB/1.0/gemfire-vectordb/overview.html[GemFire VectorDB] extends GemFire's capabilities, serving as a versatile vector database that efficiently stores, retrieves, and performs vector similarity searches. | ||
|
||
== Prerequisites | ||
|
||
Access to a GemFire cluster with the link:https://docs.vmware.com/en/VMware-GemFire-VectorDB/1.0/gemfire-vectordb/install.html[GemFire Vector Database] extension installed. | ||
You can download the GemFire VectorDB extension from the link:https://network.pivotal.io/products/gemfire-vectordb/[VMware Tanzu Network] after signing in. | ||
1. A GemFire cluster with the GemFire VectorDB extension enabled | ||
- link:https://docs.vmware.com/en/VMware-GemFire-VectorDB/1.0/gemfire-vectordb/install.html[Install GemFire VectorDB extension] | ||
|
||
== Dependencies | ||
2. An `EmbeddingModel` bean to compute the document embeddings. Refer to the xref:api/embeddings.adoc#available-implementations[EmbeddingModel] section for more information. | ||
An option that runs locally on your machine is xref:api/embeddings/onnx.adoc[ONNX] and the all-MiniLM-L6-v2 Sentence Transformers. | ||
|
||
Add these dependencies to your project: | ||
== Auto-configuration | ||
|
||
- Embedding Model boot starter, required for calculating embeddings. | ||
- Transformers Embedding (Local) and follow the ONNX Transformers Embedding instructions. | ||
Add the GemFire VectorStore Spring Boot starter to you project's Maven build file `pom.xml`: | ||
|
||
[source,xml] | ||
[source, xml] | ||
---- | ||
<dependency> | ||
<groupId>org.springframework.ai</groupId> | ||
<artifactId>spring-ai-transformers</artifactId> | ||
<groupId>org.springframework.ai</groupId> | ||
<artifactId>spring-ai-gemfire-store-spring-boot-starter</artifactId> | ||
</dependency> | ||
---- | ||
|
||
- Add the GemFire VectorDB dependencies | ||
or to your Gradle `build.gradle` file | ||
|
||
[source, xml] | ||
---- | ||
dependencies { | ||
implementation 'org.springframework.ai:spring-ai-gemfire-store-spring-boot-starter' | ||
} | ||
---- | ||
|
||
=== Configuration properties | ||
|
||
You can use the following properties in your Spring Boot configuration to further configure the `GemFireVectorStore`. | ||
|
||
|=== | ||
|Property|Default value | ||
|
||
|`spring.ai.vectorstore.gemfire.host`|localhost | ||
|`spring.ai.vectorstore.gemfire.port`|8080 | ||
|`spring.ai.vectorstore.gemfire.index-name`|spring-ai-gemfire-store | ||
|`spring.ai.vectorstore.gemfire.beam-width`|100 | ||
|`spring.ai.vectorstore.gemfire.max-connections`|16 | ||
|`spring.ai.vectorstore.gemfire.vector-similarity-function`|COSINE | ||
|`spring.ai.vectorstore.gemfire.fields`|[] | ||
|`spring.ai.vectorstore.gemfire.buckets`|0 | ||
|=== | ||
|
||
|
||
== Manual Configuration | ||
|
||
[source,xml] | ||
To use just the `GemFireVectorStore`, without Spring Boot's Auto-configuration add the following dependency to your project’s Maven `pom.xml`: | ||
|
||
[source, xml] | ||
---- | ||
<dependency> | ||
<groupId>org.springframework.ai</groupId> | ||
<artifactId>spring-ai-gemfire-store</artifactId> | ||
</dependency> | ||
---- | ||
|
||
For Gradle users, add the following to your `build.gradle` file under the dependencies block to use just the `GemFireVectorStore`: | ||
|
||
TIP: Refer to the xref:getting-started.adoc#dependency-management[Dependency Management] section to add the Spring AI BOM to your build file. | ||
|
||
[souce, xml] | ||
---- | ||
dependencies { | ||
implementation 'org.springframework.ai:spring-ai-gemfire-store' | ||
} | ||
---- | ||
|
||
== Sample Code | ||
== Usage | ||
|
||
- To configure GemFire in your application, use the following setup: | ||
Here is a sample that creates an instance of the `GemfireVectorStore` instead of using AutoConfiguration | ||
|
||
[source,java] | ||
---- | ||
@Bean | ||
public GemFireVectorStoreConfig gemFireVectorStoreConfig() { | ||
return GemFireVectorStoreConfig.builder() | ||
.withUrl("http://localhost:8080") | ||
.withIndexName("spring-ai-test-index") | ||
.build(); | ||
public VectorStore vectorStore(EmbeddingModel embeddingModel) { | ||
return new GemFireVectorStore(new GemFireVectorStoreConfig() | ||
.setIndexName("my-vector-index") | ||
.setPort(7071), embeddingClient); | ||
} | ||
---- | ||
|
||
- Create a GemFireVectorStore instance connected to your GemFire VectorDB: | ||
[NOTE] | ||
==== | ||
The GemFire VectorStore does not yet support xref:api/vectordbs.adoc#metadata-filters[metadata filters]. | ||
==== | ||
|
||
[NOTE] | ||
==== | ||
The default configuration connects to a GemFire cluster at `localhost:8080` | ||
==== | ||
|
||
- In your application, create a few documents: | ||
|
||
[source,java] | ||
---- | ||
@Bean | ||
public VectorStore vectorStore(GemFireVectorStoreConfig config, EmbeddingModel embeddingModel) { | ||
return new GemFireVectorStore(config, embeddingModel); | ||
} | ||
List<Document> documents = List.of( | ||
new Document("Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!!", Map.of("country", "UK", "year", 2020)), | ||
new Document("The World is Big and Salvation Lurks Around the Corner", Map.of()), | ||
new Document("You walk forward facing the past and you turn back toward the future.", Map.of("country", "NL", "year", 2023))); | ||
---- | ||
- Create a Vector Index which will configure GemFire region. | ||
|
||
[source,java] | ||
---- | ||
public void createIndex() { | ||
try { | ||
CreateRequest createRequest = new CreateRequest(); | ||
createRequest.setName(INDEX_NAME); | ||
createRequest.setBeamWidth(20); | ||
createRequest.setMaxConnections(16); | ||
ObjectMapper objectMapper = new ObjectMapper(); | ||
String index = objectMapper.writeValueAsString(createRequest); | ||
client.post() | ||
.contentType(MediaType.APPLICATION_JSON) | ||
.bodyValue(index) | ||
.retrieve() | ||
.bodyToMono(Void.class) | ||
.block(); | ||
} | ||
catch (Exception e) { | ||
logger.warn("An unexpected error occurred while creating the index"); | ||
} | ||
} | ||
---- | ||
|
||
- Create some documents: | ||
- Add the documents to the vector store: | ||
|
||
[source,java] | ||
---- | ||
List<Document> documents = List.of( | ||
new Document("1", getText("classpath:/test/data/spring.ai.txt"), Map.of("meta1", "meta1")), | ||
new Document("2", getText("classpath:/test/data/time.shelter.txt"), Map.of()), | ||
new Document("3", getText("classpath:/test/data/great.depression.txt"), Map.of("meta2", "meta2"))); | ||
vectorStore.add(documents); | ||
---- | ||
|
||
- Add the documents to GemFire VectorDB: | ||
- And to retrieve documents using similarity search: | ||
|
||
[source,java] | ||
---- | ||
vectorStore.add(List.of(document)); | ||
List<Document> results = vectorStore.similaritySearch( | ||
SearchRequest.query("Spring").withTopK(5)); | ||
---- | ||
|
||
- And finally, retrieve documents similar to a query: | ||
You should retrieve the document containing the text "Spring AI rocks!!". | ||
|
||
You can also limit the number of results using a similarity threshold: | ||
[source,java] | ||
---- | ||
List<Document> results = vectorStore.similaritySearch("Spring", 5); | ||
List<Document> results = vectorStore.similaritySearch( | ||
SearchRequest.query("Spring").withTopK(5) | ||
.withSimilarityThreshold(0.5d)); | ||
---- | ||
|
||
If all goes well, you should retrieve the document containing the text "Spring AI rocks!!". | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
29 changes: 29 additions & 0 deletions
29
...va/org/springframework/ai/autoconfigure/vectorstore/gemfire/GemFireConnectionDetails.java
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,29 @@ | ||
/* | ||
* Copyright 2024 - 2024 the original author or authors. | ||
* | ||
* Licensed under the Apache License, Version 2.0 (the "License"); | ||
* you may not use this file except in compliance with the License. | ||
* You may obtain a copy of the License at | ||
* | ||
* https://www.apache.org/licenses/LICENSE-2.0 | ||
* | ||
* Unless required by applicable law or agreed to in writing, software | ||
* distributed under the License is distributed on an "AS IS" BASIS, | ||
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
* See the License for the specific language governing permissions and | ||
* limitations under the License. | ||
*/ | ||
package org.springframework.ai.autoconfigure.vectorstore.gemfire; | ||
|
||
import org.springframework.boot.autoconfigure.service.connection.ConnectionDetails; | ||
|
||
/** | ||
* @author Geet Rawat | ||
*/ | ||
public interface GemFireConnectionDetails extends ConnectionDetails { | ||
|
||
String getHost(); | ||
|
||
int getPort(); | ||
|
||
} |
83 changes: 83 additions & 0 deletions
83
...ngframework/ai/autoconfigure/vectorstore/gemfire/GemFireVectorStoreAutoConfiguration.java
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,83 @@ | ||
/* | ||
* Copyright 2023-2024 the original author or authors. | ||
* | ||
* Licensed under the Apache License, Version 2.0 (the "License"); | ||
* you may not use this file except in compliance with the License. | ||
* You may obtain a copy of the License at | ||
* | ||
* https://www.apache.org/licenses/LICENSE-2.0 | ||
* | ||
* Unless required by applicable law or agreed to in writing, software | ||
* distributed under the License is distributed on an "AS IS" BASIS, | ||
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
* See the License for the specific language governing permissions and | ||
* limitations under the License. | ||
*/ | ||
|
||
package org.springframework.ai.autoconfigure.vectorstore.gemfire; | ||
|
||
import org.springframework.ai.embedding.EmbeddingModel; | ||
import org.springframework.ai.vectorstore.GemFireVectorStore; | ||
import org.springframework.ai.vectorstore.GemFireVectorStoreConfig; | ||
import org.springframework.boot.autoconfigure.AutoConfiguration; | ||
import org.springframework.boot.autoconfigure.condition.ConditionalOnClass; | ||
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean; | ||
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; | ||
import org.springframework.boot.context.properties.EnableConfigurationProperties; | ||
import org.springframework.context.annotation.Bean; | ||
|
||
/** | ||
* @author Geet Rawat | ||
*/ | ||
@AutoConfiguration | ||
@ConditionalOnClass({ GemFireVectorStore.class, EmbeddingModel.class }) | ||
@EnableConfigurationProperties(GemFireVectorStoreProperties.class) | ||
@ConditionalOnProperty(prefix = "spring.ai.vectorstore.gemfire", value = { "index-name" }) | ||
public class GemFireVectorStoreAutoConfiguration { | ||
|
||
@Bean | ||
@ConditionalOnMissingBean(GemFireConnectionDetails.class) | ||
GemFireVectorStoreAutoConfiguration.PropertiesGemFireConnectionDetails gemfireConnectionDetails( | ||
GemFireVectorStoreProperties properties) { | ||
return new GemFireVectorStoreAutoConfiguration.PropertiesGemFireConnectionDetails(properties); | ||
} | ||
|
||
@Bean | ||
@ConditionalOnMissingBean | ||
public GemFireVectorStore gemfireVectorStore(EmbeddingModel embeddingModel, GemFireVectorStoreProperties properties, | ||
GemFireConnectionDetails gemFireConnectionDetails) { | ||
var config = new GemFireVectorStoreConfig(); | ||
|
||
config.setHost(gemFireConnectionDetails.getHost()) | ||
.setPort(gemFireConnectionDetails.getPort()) | ||
.setIndexName(properties.getIndexName()) | ||
.setBeamWidth(properties.getBeamWidth()) | ||
.setMaxConnections(properties.getMaxConnections()) | ||
.setBuckets(properties.getBuckets()) | ||
.setVectorSimilarityFunction(properties.getVectorSimilarityFunction()) | ||
.setFields(properties.getFields()) | ||
.setSslEnabled(properties.isSslEnabled()); | ||
return new GemFireVectorStore(config, embeddingModel); | ||
} | ||
|
||
private static class PropertiesGemFireConnectionDetails implements GemFireConnectionDetails { | ||
|
||
private final GemFireVectorStoreProperties properties; | ||
|
||
PropertiesGemFireConnectionDetails(GemFireVectorStoreProperties properties) { | ||
this.properties = properties; | ||
} | ||
|
||
@Override | ||
public String getHost() { | ||
return this.properties.getHost(); | ||
} | ||
|
||
@Override | ||
public int getPort() { | ||
return this.properties.getPort(); | ||
} | ||
|
||
} | ||
|
||
} |
Oops, something went wrong.