Skip to content

Commit 5beef21

Browse files
eddumelendeztzolov
eddumelendez
authored and
tzolov
committed
Expose QdrantClient and WeaviateClient as beans
 Currently, `QdrantClient` and `WeaviateClient` are not exposed as beans. Having access to those would benefit to perform operations with an already configured client. - Deprecate QdrantVectorStoreConfig. - Update Qdrant manual config adoc. - Improve Qdrant adoc. - Update Weaviate docs.
1 parent 25f91c3 commit 5beef21

File tree

7 files changed

+231
-273
lines changed

7 files changed

+231
-273
lines changed

‎spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/qdrant.adoc

Lines changed: 59 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ To set up `QdrantVectorStore`, you'll need the following information from your Q
1414
NOTE: It is recommended that the Qdrant collection is link:https://qdrant.tech/documentation/concepts/collections/#create-a-collection[created] in advance with the appropriate dimensions and configurations.
1515
If the collection is not created, the `QdrantVectorStore` will attempt to create one using the `Cosine` similarity and the dimension of the configured `EmbeddingClient`.
1616

17-
== Dependencies
17+
== Auto-configuration
1818

1919
Then add the Qdrant boot starter dependency to your project:
2020

@@ -96,53 +96,21 @@ vectorStore.add(documents);
9696
List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(5));
9797
----
9898

99-
=== Manual Configuration
100-
101-
Instead of using the Spring Boot auto-configuration, you can manually configure the `QdrantVectorStore`. For this you need to add the `spring-ai-qdrant` dependency to your project:
102-
103-
[source,xml]
104-
----
105-
<dependency>
106-
<groupId>org.springframework.ai</groupId>
107-
<artifactId>spring-ai-qdrant</artifactId>
108-
</dependency>
109-
----
110-
111-
or to your Gradle `build.gradle` build file.
112-
113-
[source,groovy]
114-
----
115-
dependencies {
116-
implementation 'org.springframework.ai:spring-ai-qdrant'
117-
}
118-
----
119-
120-
To configure Qdrant in your application, you can use the following setup:
99+
[[qdrant-vectorstore-properties]]
100+
=== Configuration properties
121101

122-
[source,java]
123-
----
124-
@Bean
125-
public QdrantVectorStoreConfig qdrantVectorStoreConfig() {
126-
127-
return QdrantVectorStoreConfig.builder()
128-
.withHost("<QDRANT_HOSTNAME>")
129-
.withPort(<QDRANT_GRPC_PORT>)
130-
.withCollectionName("<QDRANT_COLLECTION_NAME>")
131-
.withApiKey("<QDRANT_API_KEY>")
132-
.build();
133-
}
134-
----
102+
You can use the following properties in your Spring Boot configuration to customize the Qdrant vector store.
135103

136-
Integrate with OpenAI's embeddings by adding the Spring Boot OpenAI starter to your project.
137-
This provides you with an implementation of the Embeddings client:
104+
[cols="3,5,1"]
105+
|===
106+
|Property| Description | Default value
138107

139-
[source,java]
140-
----
141-
@Bean
142-
public VectorStore vectorStore(QdrantVectorStoreConfig config, EmbeddingClient embeddingClient) {
143-
return new QdrantVectorStore(config, embeddingClient);
144-
}
145-
----
108+
|`spring.ai.vectorstore.qdrant.host`| The host of the Qdrant server. | localhost
109+
|`spring.ai.vectorstore.qdrant.port`| The gRPC port of the Qdrant server. | 6334
110+
|`spring.ai.vectorstore.qdrant.api-key`| The API key to use for authentication with the Qdrant server. | -
111+
|`spring.ai.vectorstore.qdrant.collection-name`| The name of the collection to use in Qdrant. | -
112+
|`spring.ai.vectorstore.qdrant.use-tls`| Whether to use TLS(HTTPS). | false
113+
|===
146114

147115
== Metadata filtering
148116

@@ -177,18 +145,52 @@ vectorStore.similaritySearch(SearchRequest.defaults()
177145

178146
NOTE: These filter expressions are converted into the equivalent Qdrant link:https://qdrant.tech/documentation/concepts/filtering/[filters].
179147

180-
[[qdrant-vectorstore-properties]]
181-
== Configuration properties
148+
== Manual Configuration
182149

183-
You can use the following properties in your Spring Boot configuration to customize the Qdrant vector store.
150+
Instead of using the Spring Boot auto-configuration, you can manually configure the `QdrantVectorStore`. For this you need to add the `spring-ai-qdrant` dependency to your project:
184151

185-
[cols="3,5,1"]
186-
|===
187-
|Property| Description | Default value
152+
[source,xml]
153+
----
154+
<dependency>
155+
<groupId>org.springframework.ai</groupId>
156+
<artifactId>spring-ai-qdrant</artifactId>
157+
</dependency>
158+
----
188159

189-
|`spring.ai.vectorstore.qdrant.host`| The host of the Qdrant server. | localhost
190-
|`spring.ai.vectorstore.qdrant.port`| The gRPC port of the Qdrant server. | 6334
191-
|`spring.ai.vectorstore.qdrant.api-key`| The API key to use for authentication with the Qdrant server. | -
192-
|`spring.ai.vectorstore.qdrant.collection-name`| The name of the collection to use in Qdrant. | -
193-
|`spring.ai.vectorstore.qdrant.use-tls`| Whether to use TLS(HTTPS). | false
194-
|===
160+
or to your Gradle `build.gradle` build file.
161+
162+
[source,groovy]
163+
----
164+
dependencies {
165+
implementation 'org.springframework.ai:spring-ai-qdrant'
166+
}
167+
----
168+
169+
To configure Qdrant in your application, you can create a QdrantClient:
170+
171+
[source,java]
172+
----
173+
@Bean
174+
public QdrantClient qdrantClient() {
175+
176+
QdrantGrpcClient.Builder grpcClientBuilder =
177+
QdrantGrpcClient.newBuilder(
178+
"<QDRANT_HOSTNAME>",
179+
<QDRANT_GRPC_PORT>,
180+
<IS_TSL>);
181+
grpcClientBuilder.withApiKey("<QDRANT_API_KEY>");
182+
183+
return new QdrantClient(grpcClientBuilder.build());
184+
}
185+
----
186+
187+
Integrate with OpenAI's embeddings by adding the Spring Boot OpenAI starter to your project.
188+
This provides you with an implementation of the Embeddings client:
189+
190+
[source,java]
191+
----
192+
@Bean
193+
public QdrantVectorStore vectorStore(EmbeddingClient embeddingClient, QdrantClient qdrantClient) {
194+
return new QdrantVectorStore(qdrantClient, "<QDRANT_COLLECTION_NAME>", embeddingClient);
195+
}
196+
----

‎spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/weaviate.adoc

Lines changed: 116 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -19,115 +19,106 @@ It provides tools to store document embeddings, content, and metadata and to sea
1919

2020
On startup, the `WeaviateVectorStore` creates the required `SpringAiWeaviate` object schema if it's not already provisioned.
2121

22-
== Dependencies
22+
== Auto-configuration
2323

24-
Add these dependencies to your project:
25-
26-
* Embedding Client boot starter, required for calculating embeddings.
27-
28-
* Transformers Embedding (Local) and follow the ONNX Transformers Embedding instructions.
24+
Then add the WeaviateVectorStore boot starter dependency to your project:
2925

3026
[source,xml]
3127
----
3228
<dependency>
33-
<groupId>org.springframework.ai</groupId>
34-
<artifactId>spring-ai-transformers-spring-boot-starter</artifactId>
29+
<groupId>org.springframework.ai</groupId>
30+
<artifactId>spring-ai-weaviate-store-spring-boot-starter</artifactId>
3531
</dependency>
3632
----
3733

38-
or use OpenAI (Cloud)
34+
or to your Gradle `build.gradle` build file.
3935

40-
[source,xml]
36+
[source,groovy]
4137
----
42-
<dependency>
43-
<groupId>org.springframework.ai</groupId>
44-
<artifactId>spring-ai-openai-spring-boot-starter</artifactId>
45-
</dependency>
38+
dependencies {
39+
implementation 'org.springframework.ai:spring-ai-weaviate-store-spring-boot-starter'
40+
}
4641
----
4742

48-
You'll need to provide your OpenAI API Key. Set it as an environment variable like so:
43+
The Vector Store, also requires an `EmbeddingClient` instance to calculate embeddings for the documents.
44+
You can pick one of the available xref:api/embeddings.adoc#available-implementations[EmbeddingClient Implementations].
4945

50-
[source,bash]
51-
----
52-
export SPRING_AI_OPENAI_API_KEY='Your_OpenAI_API_Key'
53-
----
54-
55-
* Add the Weaviate VectorStore dependency
46+
For example to use the xref:api/embeddings/openai-embeddings.adoc[OpenAI EmbeddingClient] add the following dependency to your project:
5647

5748
[source,xml]
5849
----
5950
<dependency>
60-
<groupId>org.springframework.ai</groupId>
61-
<artifactId>spring-ai-weaviate-store</artifactId>
51+
<groupId>org.springframework.ai</groupId>
52+
<artifactId>spring-ai-openai-spring-boot-starter</artifactId>
6253
</dependency>
6354
----
6455

65-
TIP: Refer to the xref:getting-started.adoc#dependency-management[Dependency Management] section to add the Spring AI BOM to your build file.
56+
or to your Gradle `build.gradle` build file.
6657

67-
== Usage
68-
69-
Create a WeaviateVectorStore instance connected to the local Weaviate cluster:
70-
71-
[source,java]
58+
[source,groovy]
7259
----
73-
@Bean
74-
public VectorStore vectorStore(EmbeddingClient embeddingClient) {
75-
WeaviateVectorStoreConfig config = WeaviateVectorStoreConfig.builder()
76-
.withScheme("http")
77-
.withHost("localhost:8080")
78-
// Define the metadata fields to be used
79-
// in the similarity search filters.
80-
.withFilterableMetadataFields(List.of(
81-
MetadataField.text("country"),
82-
MetadataField.number("year"),
83-
MetadataField.bool("active")))
84-
// Consistency level can be: ONE, QUORUM, or ALL.
85-
.withConsistencyLevel(ConsistentLevel.ONE)
86-
.build();
87-
88-
return new WeaviateVectorStore(config, embeddingClient);
60+
dependencies {
61+
implementation 'org.springframework.ai:spring-ai-openai-spring-boot-starter'
8962
}
9063
----
9164

92-
> [NOTE]
93-
> You must list explicitly all metadata field names and types (`BOOLEAN`, `TEXT`, or `NUMBER`) for any metadata key used in filter expression.
94-
> The `withFilterableMetadataKeys` above registers filterable metadata fields: `country` of type `TEXT`, `year` of type `NUMBER`, and `active` of type `BOOLEAN`.
95-
>
96-
> If the filterable metadata fields are expanded with new entries, you have to (re)upload/update the documents with this metadata.
97-
>
98-
> You can use the following Weaviate link:https://weaviate.io/developers/weaviate/api/graphql/filters#special-cases[system metadata] fields without explicit definition: `id`, `_creationTimeUnix`, and `_lastUpdateTimeUnix`.
65+
TIP: Refer to the xref:getting-started.adoc#dependency-management[Dependency Management] section to add the Spring AI BOM to your build file.
66+
Refer to the xref:getting-started.adoc#repositories[Repositories] section to add Milestone and/or Snapshot Repositories to your build file.
9967

100-
Then in your main code, create some documents:
68+
To connect to Weaviate and use the `WeaviateVectorStore`, you need to provide access details for your instance.
69+
A simple configuration can either be provided via Spring Boot's _application.properties_,
10170

102-
[source,java]
71+
[source,properties]
10372
----
104-
List<Document> documents = List.of(
105-
new Document("Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!!", Map.of("country", "UK", "active", true, "year", 2020)),
106-
new Document("The World is Big and Salvation Lurks Around the Corner", Map.of()),
107-
new Document("You walk forward facing the past and you turn back toward the future.", Map.of("country", "NL", "active", false, "year", 2023)));
73+
spring.ai.vectorstore.weaviate.host=<host of your Weaviate instance>
74+
spring.ai.vectorstore.weaviate.api-key=<your api key>
75+
spring.ai.vectorstore.weaviate.scheme=http
76+
77+
# API key if needed, e.g. OpenAI
78+
spring.ai.openai.api.key=<api-key>
10879
----
10980

110-
Now add the documents to your vector store:
81+
TIP: Check the list of xref:#weaviate-vectorstore-properties[configuration parameters] to learn about the default values and configuration options.
11182

83+
Now you can Auto-wire the Weaviate Vector Store in your application and use it
11284

11385
[source,java]
11486
----
115-
vectorStore.add(List.of(document));
116-
----
87+
@Autowired VectorStore vectorStore;
11788
118-
And finally, retrieve documents similar to a query:
89+
// ...
11990
120-
[source,java]
121-
----
122-
List<Document> results = vectorStore.similaritySearch(
123-
SearchRequest
124-
.query("Spring")
125-
.withTopK(5));
91+
List <Document> documents = List.of(
92+
new Document("Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!!", Map.of("meta1", "meta1")),
93+
new Document("The World is Big and Salvation Lurks Around the Corner"),
94+
new Document("You walk forward facing the past and you turn back toward the future.", Map.of("meta2", "meta2")));
95+
96+
// Add the documents
97+
vectorStore.add(documents);
98+
99+
// Retrieve documents similar to a query
100+
List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(5));
126101
----
127102

128-
If all goes well, you should retrieve the document containing the text "Spring AI rocks!!".
103+
[[weaviate-vectorstore-properties]]
104+
=== Configuration properties
105+
106+
You can use the following properties in your Spring Boot configuration to customize the weaviate vector store.
129107

130-
=== Metadata filtering
108+
[cols="3,5,1"]
109+
|===
110+
|Property| Description | Default value
111+
112+
|`spring.ai.vectorstore.weaviate.host`| The host of the Weaviate server. | localhost:8080
113+
|`spring.ai.vectorstore.weaviate.scheme`| Connection schema. | http
114+
|`spring.ai.vectorstore.weaviate.api-key`| The API key to use for authentication with the Weaviate server. | -
115+
|`spring.ai.vectorstore.weaviate.object-class`| | "SpringAiWeaviate"
116+
|`spring.ai.vectorstore.weaviate.consistency-level`| Desired tradeoff between consistency and speed | ConsistentLevel.ONE
117+
|`spring.ai.vectorstore.weaviate.filter-field`| spring.ai.vectorstore.weaviate.filter-field.<field-name>=<field-type> | -
118+
|`spring.ai.vectorstore.weaviate.headers`| | -
119+
|===
120+
121+
== Metadata filtering
131122

132123
You can leverage the generic, portable link:https://docs.spring.io/spring-ai/reference/api/vectordbs.html#_metadata_filters[metadata filters] with WeaviateVectorStore as well.
133124

@@ -194,6 +185,61 @@ operator:And
194185
}]
195186
----
196187

188+
== Manual Configuration
189+
190+
Instead of using the Spring Boot auto-configuration, you can manually configure the `WeaviateVectorStore`.
191+
For this you need to add the `spring-ai-weaviate-store` dependency to your project:
192+
193+
[source,xml]
194+
----
195+
<dependency>
196+
<groupId>org.springframework.ai</groupId>
197+
<artifactId>spring-ai-weaviate-store</artifactId>
198+
</dependency>
199+
----
200+
201+
or to your Gradle `build.gradle` build file.
202+
203+
[source,groovy]
204+
----
205+
dependencies {
206+
implementation 'org.springframework.ai:spring-ai-weaviate-store'
207+
}
208+
----
209+
210+
To configure Weaviate in your application, you can create a WeaviateClient:
211+
212+
[source,java]
213+
----
214+
@Bean
215+
public WeaviateClient weaviateClient() {
216+
try {
217+
return WeaviateAuthClient.apiKey(
218+
new Config(<YOUR SCHEME>, <YOUR HOST>, <YOUR HEADERS>),
219+
<YOUR API KEY>);
220+
}
221+
catch (AuthException e) {
222+
throw new IllegalArgumentException("WeaviateClient could not be created.", e);
223+
}
224+
}
225+
----
226+
227+
Integrate with OpenAI's embeddings by adding the Spring Boot OpenAI starter to your project.
228+
This provides you with an implementation of the Embeddings client:
229+
230+
[source,java]
231+
----
232+
@Bean
233+
public WeaviateVectorStore vectorStore(EmbeddingClient embeddingClient, WeaviateClient weaviateClient) {
234+
235+
WeaviateVectorStoreConfig.Builder configBuilder = WeaviateVectorStore.WeaviateVectorStoreConfig.builder()
236+
.withObjectClass(<YOUR OBJECT CLASS>)
237+
.withConsistencyLevel(<YOUR CONSISTENCY LEVEL>);
238+
239+
return new WeaviateVectorStore(configBuilder.build(), embeddingClient, weaviateClient);
240+
}
241+
----
242+
197243
== Run Weaviate cluster in docker container
198244

199245
Start Weaviate in a docker container:

0 commit comments

Comments
 (0)