Skip to content

Commit c5d9ae3

Browse files
tzolovtzolov
committed
Improve Milvus documentation
1 parent 0fdc6aa commit c5d9ae3

File tree

3 files changed

+203
-7
lines changed

3 files changed

+203
-7
lines changed

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

Lines changed: 183 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,190 @@
22

33
link:https://milvus.io/[Milvus] is an open-source vector database that has garnered significant attention in the fields of data science and machine learning. One of its standout features lies in its robust support for vector indexing and querying. Milvus employs state-of-the-art, cutting-edge algorithms to accelerate the search process, making it exceptionally efficient at retrieving similar vectors, even when handling extensive datasets.
44

5-
Milvus's popularity also comes from its ease of integration with popular Python-based frameworks such as PyTorch and TensorFlow, allowing for seamless inclusion in existing machine learning workflows.
5+
== Prerequisites
6+
7+
* A running Milvus instance. The following options are available:
8+
** link:https://milvus.io/docs/install_standalone-docker.md[Milvus Standalone]: Docker, Operator, Helm,DEB/RPM, Docker Compose.
9+
** link:https://milvus.io/docs/install_cluster-milvusoperator.md[Milvus Cluster]: Operator, Helm.
10+
* If required, an API key for the xref:api/embeddings.adoc#available-implementations[EmbeddingClient] to generate the embeddings stored by the `MilvusVectorStore`.
11+
12+
== Dependencies
13+
14+
Then add the Milvus VectorStore boot starter dependency to your project:
15+
16+
[source,xml]
17+
----
18+
<dependency>
19+
<groupId>org.springframework.ai</groupId>
20+
<artifactId>spring-ai-milvus-store-spring-boot-starter</artifactId>
21+
</dependency>
22+
----
23+
24+
or to your Gradle `build.gradle` build file.
25+
26+
[source,groovy]
27+
----
28+
dependencies {
29+
implementation 'org.springframework.ai:spring-ai-milvus-store-spring-boot-starter'
30+
}
31+
----
32+
33+
The Vector Store, also requires an `EmbeddingClient` instance to calculate embeddings for the documents.
34+
You can pick one of the available xref:api/embeddings.adoc#available-implementations[EmbeddingClient Implementations].
35+
36+
TIP: Refer to the xref:getting-started.adoc#dependency-management[Dependency Management] section to add the Spring AI BOM to your build file.
37+
Refer to the xref:getting-started.adoc#repositories[Repositories] section to add Milestone and/or Snapshot Repositories to your build file.
38+
39+
To connect to and configure the `MilvusVectorStore`, you need to provide access details for your instance.
40+
A simple configuration can either be provided via Spring Boot's `application.yml`
41+
42+
[yml]
43+
----
44+
spring:
45+
ai:
46+
vectorstore:
47+
milvus:
48+
client:
49+
host: "localhost"
50+
port: 19530
51+
username: "root"
52+
password: "milvus"
53+
databaseName: "default"
54+
collectionName: "vector_store"
55+
embeddingDimension: 1536
56+
indexType: IVF_FLAT
57+
metricType: COSINE
58+
----
59+
60+
TIP: Check the list of xref:#milvus-properties[configuration parameters] to learn about the default values and configuration options.
61+
62+
Now you can Auto-wire the Milvus Vector Store in your application and use it
63+
64+
[source,java]
65+
----
66+
@Autowired VectorStore vectorStore;
67+
68+
// ...
69+
70+
List <Document> documents = List.of(
71+
new Document("Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!!", Map.of("meta1", "meta1")),
72+
new Document("The World is Big and Salvation Lurks Around the Corner"),
73+
new Document("You walk forward facing the past and you turn back toward the future.", Map.of("meta2", "meta2")));
74+
75+
// Add the documents to PGVector
76+
vectorStore.add(documents);
77+
78+
// Retrieve documents similar to a query
79+
List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(5));
80+
----
81+
82+
=== Manual Configuration
83+
84+
Instead of using the Spring Boot auto-configuration, you can manually configure the `MilvusVectorStore`.
85+
To add the following dependencies to your project:
86+
87+
[source,xml]
88+
----
89+
<dependency>
90+
<groupId>org.springframework.ai</groupId>
91+
<artifactId>spring-ai-milvus-store</artifactId>
92+
</dependency>
93+
----
94+
95+
TIP: Refer to the xref:getting-started.adoc#dependency-management[Dependency Management] section to add the Spring AI BOM to your build file.
96+
97+
To configure MilvusVectorStore in your application, you can use the following setup:
98+
99+
[source,java]
100+
----
101+
@Bean
102+
public VectorStore vectorStore(MilvusServiceClient milvusClient, EmbeddingClient embeddingClient) {
103+
MilvusVectorStoreConfig config = MilvusVectorStoreConfig.builder()
104+
.withCollectionName("test_vector_store")
105+
.withDatabaseName("default")
106+
.withIndexType(IndexType.IVF_FLAT)
107+
.withMetricType(MetricType.COSINE)
108+
.build();
109+
return new MilvusVectorStore(milvusClient, embeddingClient, config);
110+
}
111+
112+
@Bean
113+
public MilvusServiceClient milvusClient() {
114+
return new MilvusServiceClient(ConnectParam.newBuilder()
115+
.withAuthorization("minioadmin", "minioadmin")
116+
.withUri(milvusContainer.getEndpoint())
117+
.build());
118+
}
119+
----
120+
121+
== Metadata filtering
122+
123+
You can leverage the generic, portable link:https://docs.spring.io/spring-ai/reference/api/vectordbs.html#_metadata_filters[metadata filters] with the Milvus store.
124+
125+
For example, you can use either the text expression language:
126+
127+
[source,java]
128+
----
129+
vectorStore.similaritySearch(
130+
SearchRequest.defaults()
131+
.withQuery("The World")
132+
.withTopK(TOP_K)
133+
.withSimilarityThreshold(SIMILARITY_THRESHOLD)
134+
.withFilterExpression("author in ['john', 'jill'] && article_type == 'blog'"));
135+
----
136+
137+
or programmatically using the `Filter.Expression` DSL:
138+
139+
[source,java]
140+
----
141+
FilterExpressionBuilder b = new FilterExpressionBuilder();
142+
143+
vectorStore.similaritySearch(SearchRequest.defaults()
144+
.withQuery("The World")
145+
.withTopK(TOP_K)
146+
.withSimilarityThreshold(SIMILARITY_THRESHOLD)
147+
.withFilterExpression(b.and(
148+
b.in("john", "jill"),
149+
b.eq("article_type", "blog")).build()));
150+
----
151+
152+
NOTE: These filter expressions are converted into the equivalent PgVector filters.
153+
154+
[[milvus-properties]]
155+
== Milvus VectorStore properties
156+
157+
You can use the following properties in your Spring Boot configuration to customize the Milvus vector store.
158+
159+
[cols="4,5,1"]
160+
|===
161+
|Property| Description | Default value
162+
163+
|spring.ai.vectorstore.milvus.database-name | The name of the Milvus database to use. | default
164+
|spring.ai.vectorstore.milvus.collection-name | Milvus collection name to store the vectors | vector_store
165+
|spring.ai.vectorstore.milvus.embedding-dimension | The dimension of the vectors to be stored in the Milvus collection. | 1536
166+
|spring.ai.vectorstore.milvus.index-type | The type of the index to be created for the Milvus collection. | IVF_FLAT
167+
|spring.ai.vectorstore.milvus.metric-type | The metric type to be used for the Milvus collection. | COSINE
168+
|spring.ai.vectorstore.milvus.index-parameters | The index parameters to be used for the Milvus collection. | {"nlist":1024}
169+
|spring.ai.vectorstore.milvus.client.host | The name or address of the host. | localhost
170+
|spring.ai.vectorstore.milvus.client.port | The connection port. | 19530
171+
|spring.ai.vectorstore.milvus.client.uri | The uri of Milvus instance | -
172+
|spring.ai.vectorstore.milvus.client.token | Token serving as the key for identification and authentication purposes. | -
173+
|spring.ai.vectorstore.milvus.client.connect-timeout-ms | Connection timeout value of client channel. The timeout value must be greater than zero . | 10000
174+
|spring.ai.vectorstore.milvus.client.keep-alive-time-ms | Keep-alive time value of client channel. The keep-alive value must be greater than zero. | 55000
175+
|spring.ai.vectorstore.milvus.client.keep-alive-timeout-ms | The keep-alive timeout value of client channel. The timeout value must be greater than zero. | 20000
176+
|spring.ai.vectorstore.milvus.client.rpc-deadline-ms | Deadline for how long you are willing to wait for a reply from the server. With a deadline setting, the client will wait when encounter fast RPC fail caused by network fluctuations. The deadline value must be larger than or equal to zero. | 0
177+
|spring.ai.vectorstore.milvus.client.client-key-path | The client.key path for tls two-way authentication, only takes effect when "secure" is true | -
178+
|spring.ai.vectorstore.milvus.client.client-pem-path | The client.pem path for tls two-way authentication, only takes effect when "secure" is true | -
179+
|spring.ai.vectorstore.milvus.client.ca-pem-path | The ca.pem path for tls two-way authentication, only takes effect when "secure" is true | -
180+
|spring.ai.vectorstore.milvus.client.server-pem-path | server.pem path for tls one-way authentication, only takes effect when "secure" is true. | -
181+
|spring.ai.vectorstore.milvus.client.server-name | Sets the target name override for SSL host name checking, only takes effect when "secure" is True. Note: this value is passed to grpc.ssl_target_name_override | -
182+
|spring.ai.vectorstore.milvus.client.secure | Secure the authorization for this connection, set to True to enable TLS. | false
183+
|spring.ai.vectorstore.milvus.client.idle-timeout-ms | Idle timeout value of client channel. The timeout value must be larger than zero. | 24h
184+
|spring.ai.vectorstore.milvus.client.username | The username and password for this connection. | root
185+
|spring.ai.vectorstore.milvus.client.password | The password for this connection. | milvus
186+
|===
187+
6188

7-
In the e-commerce industry, Milvus is used in recommendation systems, which suggest products based on user preferences. In image and video analysis, it excels in tasks like object recognition, image similarity search, and content-based image retrieval. Additionally, it is commonly used in natural language processing for document clustering, semantic search, and question-answering systems.
8189

9190
== Starting Milvus Store
10191

‎spring-ai-spring-boot-autoconfigure/src/main/java/org/springframework/ai/autoconfigure/vectorstore/milvus/MilvusServiceClientProperties.java

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -57,13 +57,13 @@ public class MilvusServiceClientProperties {
5757

5858
/**
5959
* Keep-alive time value of client channel. The keep-alive value must be greater than
60-
* zero. Default is 55000 ms.
60+
* zero.
6161
*/
6262
private long keepAliveTimeMs = 55000;
6363

6464
/**
6565
* The keep-alive timeout value of client channel. The timeout value must be greater
66-
* than zero. Default value is 20000 ms.
66+
* than zero.
6767
*/
6868
private long keepAliveTimeoutMs = 20000;
6969

@@ -121,12 +121,12 @@ public class MilvusServiceClientProperties {
121121
private long idleTimeoutMs = TimeUnit.MILLISECONDS.convert(24, TimeUnit.HOURS);
122122

123123
/**
124-
* The username and password for this connection
124+
* The username and password for this connection.
125125
*/
126126
private String username = "root";
127127

128128
/**
129-
* The password for this connection
129+
* The password for this connection.
130130
*/
131131
private String password = "milvus";
132132

‎spring-ai-spring-boot-autoconfigure/src/main/java/org/springframework/ai/autoconfigure/vectorstore/milvus/MilvusVectorStoreProperties.java

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,18 +28,33 @@ public class MilvusVectorStoreProperties {
2828
public static final String CONFIG_PREFIX = "spring.ai.vectorstore.milvus";
2929

3030
/**
31-
* The database name
31+
* The name of the Milvus database to connect to.
3232
*/
3333
private String databaseName = MilvusVectorStore.DEFAULT_DATABASE_NAME;
3434

35+
/**
36+
* Milvus collection name to store the vectors.
37+
*/
3538
private String collectionName = MilvusVectorStore.DEFAULT_COLLECTION_NAME;
3639

40+
/**
41+
* The dimension of the vectors to be stored in the Milvus collection.
42+
*/
3743
private int embeddingDimension = MilvusVectorStore.OPENAI_EMBEDDING_DIMENSION_SIZE;
3844

45+
/**
46+
* The type of the index to be created for the Milvus collection.
47+
*/
3948
private MilvusIndexType indexType = MilvusIndexType.IVF_FLAT;
4049

50+
/**
51+
* The metric type to be used for the Milvus collection.
52+
*/
4153
private MilvusMetricType metricType = MilvusMetricType.COSINE;
4254

55+
/**
56+
* The index parameters to be used for the Milvus collection.
57+
*/
4358
private String indexParameters = "{\"nlist\":1024}";
4459

4560
public enum MilvusMetricType {

0 commit comments

Comments
 (0)