You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This section walks you through setting up the PGvector `VectorStore` to store document embeddings and perform similarity searches.
4
4
5
-
== What is PGvector?
6
-
7
5
link:https://github.com/pgvector/pgvector[PGvector] is an open-source extension for PostgreSQL that enables storing and searching over machine learning-generated embeddings. It provides different capabilities that let users identify both exact and approximate nearest neighbors. It is designed to work seamlessly with other PostgreSQL features, including indexing and querying.
8
6
9
-
=== Prerequisites
7
+
== Prerequisites
10
8
11
-
1. OpenAI Account: Create an account at link:https://platform.openai.com/signup[OpenAI Signup] and generate the token at link:https://platform.openai.com/account/api-keys[API Keys].
9
+
First you need an access to PostgreSQL instance with enabled `vector`, `hstore` and `uuid-ossp` extensions.
12
10
13
-
2. Access to PostgreSQL instance with the following configurations
11
+
TIP: The <<appendix_a,setup local Postgres/PGVector>> appendix shows how to set up a DB locally with a Docker container.
14
12
15
-
The <<appendix_a,setup local Postgres/PGVector>> appendix shows how to set up a DB locally with a Docker container.
13
+
On startup, the `PgVectorStore` will attempt to install the required database extensions and create the required `vector_store` table with an index.
16
14
17
-
On startup, the `PgVectorStore` will attempt to install the required database extensions and create the required `vector_store` table with an index. Optionally, you can do this manually like so:
15
+
Optionally, you can do this manually like so:
18
16
19
17
[sql]
20
18
----
@@ -26,60 +24,41 @@ CREATE TABLE IF NOT EXISTS vector_store (
26
24
id uuid DEFAULT uuid_generate_v4() PRIMARY KEY,
27
25
content text,
28
26
metadata json,
29
-
embedding vector(1536)
27
+
embedding vector(1536) // 1536 is the default embedding dimension
30
28
);
31
29
32
30
CREATE INDEX ON vector_store USING HNSW (embedding vector_cosine_ops);
33
31
----
34
32
35
-
== Configuration
36
-
37
-
To set up `PgVectorStore`, you need to provide (via `application.yaml`) configurations to your PostgreSQL database.
38
-
39
-
Additionally, you'll need to provide your OpenAI API Key. Set it as an environment variable like so:
To acquire Spring AI artifacts, declare the Spring Snapshot repository:
33
+
TIP: replace the `1536` with the actual embedding dimension if you are using a different dimension.
49
34
50
-
[source,xml]
51
-
----
52
-
<repository>
53
-
<id>spring-snapshots</id>
54
-
<name>Spring Snapshots</name>
55
-
<url>https://repo.spring.io/snapshot</url>
56
-
<releases>
57
-
<enabled>false</enabled>
58
-
</releases>
59
-
</repository>
60
-
----
35
+
Next if required, an API key for the xref:api/embeddings.adoc#available-implementations[EmbeddingClient] to generate the embeddings stored by the `PgVectorStore`.
61
36
62
37
== Dependencies
63
38
64
-
Add these dependencies to your project:
65
-
66
-
* PostgreSQL connection and `JdbcTemplate` auto-configuration.
39
+
Then add the PgVectorStore boot starter dependency to your project:
TIP: Refer to the xref:getting-started.adoc#dependency-management[Dependency Management] section to add the Spring AI BOM to your build file.
81
+
Refer to the xref:getting-started.adoc#repositories[Repositories] section to add Milestone and/or Snapshot Repositories to your build file.
103
82
104
-
== Sample Code
105
-
106
-
To configure `PgVectorStore` in your application, you can use the following setup:
107
-
108
-
Add to `application.yml` (using your DB credentials):
83
+
To connect to and configure the `PgVectorStore`, you need to provide access details for your instance.
84
+
A simple configuration can either be provided via Spring Boot's `application.yml`
109
85
110
86
[yml]
111
87
----
@@ -114,9 +90,63 @@ spring:
114
90
url: jdbc:postgresql://localhost:5432/postgres
115
91
username: postgres
116
92
password: postgres
93
+
ai:
94
+
vectorstore:
95
+
pgvector:
96
+
index-type: HNSW
97
+
distance-type: COSINE_DISTANCE
98
+
dimension: 1536
117
99
----
118
100
119
-
Integrate with OpenAI's embeddings by adding the Spring Boot OpenAI Starter to your project. This provides you with an implementation of the Embeddings client:
101
+
TIP: Check the list of xref:#pgvector-properties[configuration parameters] to learn about the default values and configuration options.
102
+
103
+
Now you can Auto-wire the PgVector Store in your application and use it
104
+
105
+
[source,java]
106
+
----
107
+
@Autowired VectorStore vectorStore;
108
+
109
+
// ...
110
+
111
+
List <Document> documents = List.of(
112
+
new Document("Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!!", Map.of("meta1", "meta1")),
113
+
new Document("The World is Big and Salvation Lurks Around the Corner"),
114
+
new Document("You walk forward facing the past and you turn back toward the future.", Map.of("meta2", "meta2")));
Instead of using the Spring Boot auto-configuration, you can manually configure the `PgVectorStore`.
126
+
For this you need to add the PostgreSQL connection and `JdbcTemplate` auto-configuration dependencies to your project:
127
+
128
+
[source,xml]
129
+
----
130
+
<dependency>
131
+
<groupId>org.springframework.boot</groupId>
132
+
<artifactId>spring-boot-starter-jdbc</artifactId>
133
+
</dependency>
134
+
135
+
<dependency>
136
+
<groupId>org.postgresql</groupId>
137
+
<artifactId>postgresql</artifactId>
138
+
<scope>runtime</scope>
139
+
</dependency>
140
+
141
+
<dependency>
142
+
<groupId>org.springframework.ai</groupId>
143
+
<artifactId>spring-ai-pgvector-store</artifactId>
144
+
</dependency>
145
+
----
146
+
147
+
TIP: Refer to the xref:getting-started.adoc#dependency-management[Dependency Management] section to add the Spring AI BOM to your build file.
148
+
149
+
To configure PgVector in your application, you can use the following setup:
120
150
121
151
[source,java]
122
152
----
@@ -126,31 +156,54 @@ public VectorStore vectorStore(JdbcTemplate jdbcTemplate, EmbeddingClient embedd
126
156
}
127
157
----
128
158
129
-
In your main code, create some documents:
159
+
== Metadata filtering
130
160
131
-
[source,java]
132
-
----
133
-
List<Document> documents = List.of(
134
-
new Document("Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!!", Map.of("meta1", "meta1")),
135
-
new Document("The World is Big and Salvation Lurks Around the Corner"),
136
-
new Document("You walk forward facing the past and you turn back toward the future.", Map.of("meta2", "meta2")));
137
-
----
161
+
You can leverage the generic, portable link:https://docs.spring.io/spring-ai/reference/api/vectordbs.html#_metadata_filters[metadata filters] with the PgVector store.
138
162
139
-
Add the documents to your vector store:
163
+
For example, you can use either the text expression language:
140
164
141
165
[source,java]
142
166
----
143
-
vectorStore.add(List.of(document));
167
+
vectorStore.similaritySearch(
168
+
SearchRequest.defaults()
169
+
.withQuery("The World")
170
+
.withTopK(TOP_K)
171
+
.withSimilarityThreshold(SIMILARITY_THRESHOLD)
172
+
.withFilterExpression("author in ['john', 'jill'] && article_type == 'blog'"));
144
173
----
145
174
146
-
And finally, retrieve documents similar to a query:
175
+
or programmatically using the `Filter.Expression` DSL:
If all goes well, you should retrieve the document containing the text "Spring AI rocks!!".
190
+
NOTE: These filter expressions are converted into the equivalent PgVector filters.
191
+
192
+
[[pgvector-properties]]
193
+
== PgVectorStore properties
194
+
195
+
You can use the following properties in your Spring Boot configuration to customize the PGVector vector store.
196
+
197
+
[cols="2,5,1"]
198
+
|===
199
+
|Property| Description | Default value
200
+
201
+
|`spring.ai.vectorstore.pgvector.index-type`| Nearest neighbor search index type. Options are `NONE` - exact nearest neighbor search, `IVFFlat` - index divides vectors into lists, and then searches a subset of those lists that are closest to the query vector. It has faster build times and uses less memory than HNSW, but has lower query performance (in terms of speed-recall tradeoff). `HNSW` - creates a multilayer graph. It has slower build times and uses more memory than IVFFlat, but has better query performance (in terms of speed-recall tradeoff). There’s no training step like IVFFlat, so the index can be created without any data in the table.| HNSW
202
+
|`spring.ai.vectorstore.pgvector.distance-type`| Search distance type. Defaults to `COSINE_DISTANCE`. But if vectors are normalized to length 1, you can use `EUCLIDEAN_DISTANCE` or `NEGATIVE_INNER_PRODUCT` for best performance.| COSINE_DISTANCE
203
+
|`spring.ai.vectorstore.pgvector.dimension`| Embeddings dimension. If not specified explicitly the PgVectorStore will retrieve the dimensions form the provided `EmbeddingClient`. Dimensions are set to the embedding column the on table creation. If you change the dimensions your would have to to re-create the vector_store table as well. | -
204
+
|spring.ai.vectorstore.pgvector.remove-existing-vector-store-table| Deletes the existing `vector_store` table on start up. | false
Copy file name to clipboardExpand all lines: spring-ai-spring-boot-autoconfigure/src/main/java/org/springframework/ai/autoconfigure/vectorstore/pgvector/PgVectorStoreAutoConfiguration.java
0 commit comments