Skip to content

Commit 154fc1f

Browse files
tzolovtzolov
committed
doc: Improve Redis Vector Store documentation
1 parent abd9e32 commit 154fc1f

File tree

1 file changed

+121
-42
lines changed
  • spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs

1 file changed

+121
-42
lines changed

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

Lines changed: 121 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,8 @@
22

33
This section walks you through setting up `RedisVectorStore` to store document embeddings and perform similarity searches.
44

5-
== What is Redis?
6-
75
link:https://redis.io[Redis] is an open source (BSD licensed), in-memory data structure store used as a database, cache, message broker, and streaming engine. Redis provides data structures such as strings, hashes, lists, sets, sorted sets with range queries, bitmaps, hyperloglogs, geospatial indexes, and streams.
86

9-
== What is Redis Vector Search?
10-
117
link:https://redis.io/docs/interact/search-and-query/[Redis Search and Query] extends the core features of Redis OSS and allows you to use Redis as a vector database:
128

139
* Store vectors and the associated metadata within hashes or JSON documents
@@ -16,53 +12,135 @@ link:https://redis.io/docs/interact/search-and-query/[Redis Search and Query] ex
1612
1713
== Prerequisites
1814

19-
1. `EmbeddingClient` instance to compute the document embeddings. Several options are available:
15+
1. A Redis Stack instance
16+
- https://app.redislabs.com/#/[Redis Cloud] (recommended)
17+
- link:https://hub.docker.com/r/redis/redis-stack[Docker] image _redis/redis-stack:latest_
18+
19+
2. `EmbeddingClient` instance to compute the document embeddings. Several options are available:
20+
- If required, an API key for the xref:api/embeddings.adoc#available-implementations[EmbeddingClient] to generate the embeddings stored by the `RedisVectorStore`.
21+
22+
== Auto-configuration
2023

21-
- `Transformers Embedding` - computes the embedding in your local environment. Follow the ONNX Transformers Embedding instructions.
22-
- `OpenAI Embedding` - uses the OpenAI embedding endpoint. You need to create an account at link:https://platform.openai.com/signup[OpenAI Signup] and generate the api-key token at link:https://platform.openai.com/account/api-keys[API Keys].
23-
- You can also use the `Azure OpenAI Embedding`.
24+
Spring AI provides Spring Boot auto-configuration for the Redis Vector Sore.
25+
To enable it, add the following dependency to your project's Maven `pom.xml` file:
2426

25-
2. A Redis Stack instance
26-
a. https://app.redislabs.com/#/[Redis Cloud] (recommended)
27-
b. link:https://hub.docker.com/r/redis/redis-stack[Docker] image _redis/redis-stack:latest_
27+
[source, xml]
28+
----
29+
<dependency>
30+
<groupId>org.springframework.ai</groupId>
31+
<artifactId>spring-ai-transformers-spring-boot-starter</artifactId>
32+
</dependency>
33+
----
2834

35+
or to your Gradle `build.gradle` build file.
2936

30-
== Dependencies
37+
[source,groovy]
38+
----
39+
dependencies {
40+
implementation 'org.springframework.ai:spring-ai-transformers-spring-boot-starter'
41+
}
42+
----
3143

32-
Add these dependencies to your project:
44+
TIP: Refer to the xref:getting-started.adoc#dependency-management[Dependency Management] section to add the Spring AI BOM to your build file.
3345

34-
* Embedding Client boot starter, required for calculating embeddings.
46+
TIP: Refer to the xref:getting-started.adoc#repositories[Repositories] section to add Milestone and/or Snapshot Repositories to your build file.
3547

36-
* Transformers Embedding (Local) and follow the ONNX Transformers Embedding instructions.
48+
Additionally, you will need a configured `EmbeddingClient` bean. Refer to the xref:api/embeddings.adoc#available-implementations[EmbeddingClient] section for more information.
3749

38-
[source,xml]
50+
Here is an example of the needed bean:
51+
52+
[source,java]
3953
----
40-
<dependency>
41-
<groupId>org.springframework.ai</groupId>
42-
<artifactId>spring-ai-transformers-spring-boot-starter</artifactId>
43-
</dependency>
54+
@Bean
55+
public EmbeddingClient embeddingClient() {
56+
// Can be any other EmbeddingClient implementation.
57+
return new OpenAiEmbeddingClient(new OpenAiApi(System.getenv("SPRING_AI_OPENAI_API_KEY")));
58+
}
4459
----
4560

46-
or use OpenAI (Cloud)
61+
To connect to Redis you need to provide access details for your instance.
62+
A simple configuration can either be provided via Spring Boot's _application.properties_,
4763

48-
[source,xml]
64+
[source,properties]
4965
----
50-
<dependency>
51-
<groupId>org.springframework.ai</groupId>
52-
<artifactId>spring-ai-openai-spring-boot-starter</artifactId>
53-
</dependency>
66+
spring.ai.vectorstore.redis.uri=<host of your redis instance>
67+
spring.ai.vectorstore.redis.index=<your index name>
68+
spring.ai.vectorstore.redis.prefix=<your prefix>
69+
70+
# API key if needed, e.g. OpenAI
71+
spring.ai.openai.api.key=<api-key>
5472
----
5573

56-
TIP: Refer to the xref:getting-started.adoc#dependency-management[Dependency Management] section to add the Spring AI BOM to your build file.
74+
Please have a look at the list of xref:#_configuration_properties[configuration parameters] for the vector store to learn about the default values and configuration options.
75+
76+
Now you can Auto-wire the Redis Vector Store in your application and use it
5777

58-
You'll need to provide your OpenAI API Key. Set it as an environment variable like so:
78+
[source,java]
79+
----
80+
@Autowired VectorStore vectorStore;
81+
82+
// ...
83+
84+
List <Document> documents = List.of(
85+
new Document("Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!!", Map.of("meta1", "meta1")),
86+
new Document("The World is Big and Salvation Lurks Around the Corner"),
87+
new Document("You walk forward facing the past and you turn back toward the future.", Map.of("meta2", "meta2")));
88+
89+
// Add the documents to Redis
90+
vectorStore.add(List.of(document));
91+
92+
// Retrieve documents similar to a query
93+
List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(5));
94+
----
95+
96+
=== Configuration properties
97+
98+
You can use the following properties in your Spring Boot configuration to customize the Redis vector store.
99+
100+
|===
101+
|Property| Description | Default value
102+
103+
|`spring.ai.vectorstore.redis.uri`| Server connection URI | redis://localhost:6379
104+
|`spring.ai.vectorstore.redis.index`| Index name (REQUIRED) | -
105+
|`spring.ai.vectorstore.redis.prefix`| (REQUIRED) | -
106+
107+
|===
108+
109+
== Metadata filtering
110+
111+
You can leverage the generic, portable link:https://docs.spring.io/spring-ai/reference/api/vectordbs.html#_metadata_filters[metadata filters] with the Redis vector store.
59112

60-
[source,bash]
113+
For example, you can use either the text expression language:
114+
115+
[source,java]
116+
----
117+
vectorStore.similaritySearch(
118+
SearchRequest.defaults()
119+
.withQuery("The World")
120+
.withTopK(TOP_K)
121+
.withSimilarityThreshold(SIMILARITY_THRESHOLD)
122+
.withFilterExpression("author in ['john', 'jill'] && article_type == 'blog'"));
123+
----
124+
125+
or programmatically using the `Filter.Expression` DSL:
126+
127+
[source,java]
61128
----
62-
export SPRING_AI_OPENAI_API_KEY='Your_OpenAI_API_Key'
129+
FilterExpressionBuilder b = new FilterExpressionBuilder();
130+
131+
vectorStore.similaritySearch(SearchRequest.defaults()
132+
.withQuery("The World")
133+
.withTopK(TOP_K)
134+
.withSimilarityThreshold(SIMILARITY_THRESHOLD)
135+
.withFilterExpression(b.and(
136+
b.in("author", "john", "jill"),
137+
b.eq("article_type", "blog")).build()));
63138
----
64139

65-
* Add the Redis Vector Store and Jedis dependencies
140+
== Manual configuration
141+
142+
If you prefer not to use the auto-configuration, you can manually configure the Redis Vector Store.
143+
Add the Redis Vector Store and Jedis dependencies
66144

67145
[source,xml]
68146
----
@@ -80,9 +158,7 @@ export SPRING_AI_OPENAI_API_KEY='Your_OpenAI_API_Key'
80158

81159
TIP: Refer to the xref:getting-started.adoc#dependency-management[Dependency Management] section to add the Spring AI BOM to your build file.
82160

83-
== Usage
84-
85-
Create a RedisVectorStore instance connected to your Redis database:
161+
Then, create a `RedisVectorStore` bean in your Spring configuration:
86162

87163
[source,java]
88164
----
@@ -101,14 +177,17 @@ public VectorStore vectorStore(EmbeddingClient embeddingClient) {
101177
}
102178
----
103179

104-
> [NOTE]
105-
> It is more convenient and preferred to create the `RedisVectorStore` as a Bean.
106-
> But if you decide to create it manually, then you must call the `RedisVectorStore#afterPropertiesSet()` after setting the properties and before using the client.
107-
108-
> [NOTE]
109-
> You must list explicitly all metadata field names and types (`TAG`, `TEXT`, or `NUMERIC`) for any metadata field used in filter expression.
110-
> The `withMetadataFields` above registers filterable metadata fields: `country` of type `TAG`, `year` of type `NUMERIC`.
111-
>
180+
[NOTE]
181+
====
182+
It is more convenient and preferred to create the `RedisVectorStore` as a Bean.
183+
But if you decide to create it manually, then you must call the `RedisVectorStore#afterPropertiesSet()` after setting the properties and before using the client.
184+
====
185+
186+
[NOTE]
187+
====
188+
You must list explicitly all metadata field names and types (`TAG`, `TEXT`, or `NUMERIC`) for any metadata field used in filter expression.
189+
The `withMetadataFields` above registers filterable metadata fields: `country` of type `TAG`, `year` of type `NUMERIC`.
190+
====
112191

113192
Then in your main code, create some documents:
114193

0 commit comments

Comments
 (0)