Add OpenSearch vector store integration
- implement OpensSearchVectorStore - add opensearch auto-configuration and boot starter - add documentation for OpenSearch VectorStore - add bom dependecies - align with to new Spirng AI API
This commit is contained in:
Jemin Huh
committed by
Christian Tzolov
Christian Tzolov
parent
80a5f2f5b7
commit
46e47849ce
@@ -62,6 +62,7 @@
|
||||
*** xref:api/vectordbs/milvus.adoc[]
|
||||
*** xref:api/vectordbs/mongodb.adoc[]
|
||||
*** xref:api/vectordbs/neo4j.adoc[]
|
||||
*** xref:api/vectordbs/opensearch.adoc[]
|
||||
*** xref:api/vectordbs/oracle.adoc[Oracle DB AI Vector Search]
|
||||
*** xref:api/vectordbs/pgvector.adoc[]
|
||||
*** xref:api/vectordbs/pinecone.adoc[]
|
||||
|
||||
@@ -103,6 +103,7 @@ These are the available implementations of the `VectorStore` interface:
|
||||
* xref:api/vectordbs/milvus.adoc[Milvus Vector Store] - The https://milvus.io/[Milvus] vector store.
|
||||
* xref:api/vectordbs/mongodb.adoc[MongoDB Atlas Vector Store] - The https://www.mongodb.com/atlas/database[MongoDB Atlas] vector store.
|
||||
* xref:api/vectordbs/neo4j.adoc[Neo4j Vector Store] - The https://neo4j.com/[Neo4j] vector store.
|
||||
* xref:api/vectordbs/opensearch.adoc[OpenSearch Vector Store] - The https://opensearch.org/platform/search/vector-database.html[OpenSearch] vector store.
|
||||
* xref:api/vectordbs/oracle.adoc[Oracle Vector Store] - The https://docs.oracle.com/en/database/oracle/oracle-database/23/vecse/overview-ai-vector-search.html[Oracle Database] vector store.
|
||||
* xref:api/vectordbs/pgvector.adoc[PgVector Store] - The https://github.com/pgvector/pgvector[PostgreSQL/PGVector] vector store.
|
||||
* xref:api/vectordbs/pinecone.adoc[Pinecone Vector Store] - https://www.pinecone.io/[PineCone] vector store.
|
||||
|
||||
@@ -0,0 +1,227 @@
|
||||
= OpenSearch
|
||||
|
||||
This section guides you through setting up the OpenSearch `VectorStore` to store document embeddings and perform similarity searches.
|
||||
|
||||
link:https://opensearch.org[OpenSearch] is an open-source search and analytics engine originally forked from Elasticsearch, distributed under the Apache License 2.0. It enhances AI application development by simplifying the integration and management of AI-generated assets. OpenSearch supports vector, lexical, and hybrid search capabilities, leveraging advanced vector database functionalities to facilitate low-latency queries and similarity searches as detailed on the link:https://opensearch.org/platform/search/vector-database.html[vector database page]. This platform is ideal for building scalable AI-driven applications and offers robust tools for data management, fault tolerance, and resource access controls.
|
||||
|
||||
== Prerequisites
|
||||
|
||||
* A running OpenSearch instance. The following options are available:
|
||||
** link:https://opensearch.org/docs/latest/opensearch/install/index/[Self-Managed OpenSearch]
|
||||
** link:https://docs.aws.amazon.com/opensearch-service/[Amazon OpenSearch Service]
|
||||
* `EmbeddingModel` instance to compute the document embeddings. Several options are available:
|
||||
- If required, an API key for the xref:api/embeddings.adoc#available-implementations[EmbeddingModel] to generate the
|
||||
embeddings stored by the `OpenSearchVectorStore`.
|
||||
|
||||
== Dependencies
|
||||
|
||||
Add the OpenSearch Vector Store dependency to your project:
|
||||
|
||||
[source,xml]
|
||||
----
|
||||
<dependency>
|
||||
<groupId>org.springframework.ai</groupId>
|
||||
<artifactId>spring-ai-opensearch-store</artifactId>
|
||||
</dependency>
|
||||
----
|
||||
|
||||
or to your Gradle `build.gradle` build file.
|
||||
|
||||
[source,groovy]
|
||||
----
|
||||
dependencies {
|
||||
implementation 'org.springframework.ai:spring-ai-opensearch-store'
|
||||
}
|
||||
----
|
||||
|
||||
TIP: Refer to the xref:getting-started.adoc#dependency-management[Dependency Management] section to add the Spring AI BOM to your build file.
|
||||
|
||||
== Configuration
|
||||
|
||||
To connect to OpenSearch and use the `OpenSearchVectorStore`, you need to provide access details for your instance.
|
||||
A simple configuration can either be provided via Spring Boot's `application.yml`,
|
||||
[source,yaml]
|
||||
----
|
||||
spring:
|
||||
opensearch:
|
||||
uris: <opensearch instance URIs>
|
||||
username: <opensearch username>
|
||||
password: <opensearch password>
|
||||
indexName: <opensearch index name>
|
||||
mappingJson: <JSON mapping for opensearch index>
|
||||
# API key if needed, e.g. OpenAI
|
||||
ai:
|
||||
openai:
|
||||
api:
|
||||
key: <api-key>
|
||||
----
|
||||
TIP: Check the list of xref:#_configuration_properties[configuration parameters] to learn about the default values and configuration options.
|
||||
|
||||
== Auto-configuration
|
||||
|
||||
Spring AI provides Spring Boot auto-configuration for the OpenSearch Vector Store.
|
||||
To enable it, add the following dependency to your project's Maven `pom.xml` file:
|
||||
|
||||
[source,xml]
|
||||
----
|
||||
<dependency>
|
||||
<groupId>org.springframework.ai</groupId>
|
||||
<artifactId>spring-ai-opensearch-store-spring-boot-starter</artifactId>
|
||||
</dependency>
|
||||
----
|
||||
|
||||
or to your Gradle `build.gradle` build file.
|
||||
|
||||
[source,groovy]
|
||||
----
|
||||
dependencies {
|
||||
implementation 'org.springframework.ai:spring-ai-opensearch-store-spring-boot-starter'
|
||||
}
|
||||
----
|
||||
|
||||
TIP: Refer to the xref:getting-started.adoc#dependency-management[Dependency Management] section to add the Spring AI BOM to your build file.
|
||||
|
||||
Here is an example of the needed bean:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
@Bean
|
||||
public EmbeddingModel embeddingModel() {
|
||||
// Can be any other EmbeddingModel implementation
|
||||
return new OpenAiEmbeddingModel(new OpenAiApi(System.getenv("SPRING_AI_OPENAI_API_KEY")));
|
||||
}
|
||||
----
|
||||
|
||||
Now you can auto-wire the `OpenSearchVectorStore` as a vector store in your application.
|
||||
|
||||
[source,java]
|
||||
----
|
||||
@Autowired VectorStore vectorStore;
|
||||
|
||||
// ...
|
||||
|
||||
List <Document> documents = List.of(
|
||||
new Document("Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!!", Map.of("meta1", "meta1")),
|
||||
new Document("The World is Big and Salvation Lurks Around the Corner"),
|
||||
new Document("You walk forward facing the past and you turn back toward the future.", Map.of("meta2", "meta2")));
|
||||
|
||||
// Add the documents to OpenSearch
|
||||
vectorStore.add(List.of(document));
|
||||
|
||||
// Retrieve documents similar to a query
|
||||
List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(5));
|
||||
----
|
||||
|
||||
=== Configuration properties
|
||||
|
||||
You can use the following properties in your Spring Boot configuration to customize the PGVector vector store.
|
||||
|
||||
[cols="2,5,1"]
|
||||
|===
|
||||
|Property| Description | Default value
|
||||
|
||||
|`spring.opensearch.uris`| URIs of the OpenSearch cluster endpoints. | -
|
||||
|`spring.opensearch.username`| Username for accessing the OpenSearch cluster. | -
|
||||
|`spring.opensearch.password`| Password for the specified username. | -
|
||||
|`spring.opensearch.indexName`| Name of the default index to be used within the OpenSearch cluster. | `spring-ai-document-index`
|
||||
|`spring.opensearch.mappingJson`| JSON string defining the mapping for the index; specifies how documents and their
|
||||
fields are stored and indexed. |
|
||||
{
|
||||
"properties":{
|
||||
"embedding":{
|
||||
"type":"knn_vector",
|
||||
"dimension":1536
|
||||
}
|
||||
}
|
||||
}
|
||||
|===
|
||||
|
||||
=== Customizing OpenSearch Client Configuration
|
||||
|
||||
In cases where the Spring Boot auto-configured OpenSearchClient with `Apache HttpClient 5 Transport` bean is not what
|
||||
you want or need, you can still define your own bean.
|
||||
Please read the link:https://opensearch.org/docs/latest/clients/java/[OpenSearch Java Client Documentation]
|
||||
|
||||
for more in-depth information about the configuration of Amazon OpenSearch Service.
|
||||
To enable it, add the following dependency to your project's Maven `pom.xml` file:
|
||||
|
||||
[source,xml]
|
||||
----
|
||||
<dependency>
|
||||
<groupId>software.amazon.awssdk</groupId>
|
||||
<artifactId>apache-client</artifactId>
|
||||
<version>2.25.40</version>
|
||||
</dependency>
|
||||
----
|
||||
|
||||
or to your Gradle `build.gradle` build file.
|
||||
|
||||
[source,groovy]
|
||||
----
|
||||
dependencies {
|
||||
implementation 'software.amazon.awssdk:apache-client:2.25.40'
|
||||
}
|
||||
----
|
||||
|
||||
Here is an example of the needed bean:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
@Bean
|
||||
public OpenSearchClient openSearchClient() {
|
||||
return new OpenSearchClient(
|
||||
new AwsSdk2Transport(
|
||||
ApacheHttpClient.builder().build(),
|
||||
"search-...us-west-2.es.amazonaws.com", // OpenSearch endpoint, without https://
|
||||
"es",
|
||||
Region.US_WEST_2, // signing service region
|
||||
AwsSdk2TransportOptions.builder().build())
|
||||
);
|
||||
}
|
||||
----
|
||||
|
||||
== Metadata Filtering
|
||||
|
||||
You can leverage the generic, portable xref:api/vectordbs.adoc#metadata-filters[metadata filters] with OpenSearch as well.
|
||||
|
||||
For example, you can use either the text expression language:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
vectorStore.similaritySearch(SearchRequest.defaults()
|
||||
.withQuery("The World")
|
||||
.withTopK(TOP_K)
|
||||
.withSimilarityThreshold(SIMILARITY_THRESHOLD)
|
||||
.withFilterExpression("author in ['john', 'jill'] && 'article_type' == 'blog'"));
|
||||
----
|
||||
|
||||
or programmatically using the `Filter.Expression` DSL:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
FilterExpressionBuilder b = new FilterExpressionBuilder();
|
||||
|
||||
vectorStore.similaritySearch(SearchRequest.defaults()
|
||||
.withQuery("The World")
|
||||
.withTopK(TOP_K)
|
||||
.withSimilarityThreshold(SIMILARITY_THRESHOLD)
|
||||
.withFilterExpression(b.and(
|
||||
b.in("john", "jill"),
|
||||
b.eq("article_type", "blog")).build()));
|
||||
----
|
||||
|
||||
NOTE: Those (portable) filter expressions get automatically converted into the proprietary OpenSearch link:https://opensearch.org/docs/latest/query-dsl/full-text/query-string/[Query string query].
|
||||
|
||||
For example, this portable filter expression:
|
||||
|
||||
[source,sql]
|
||||
----
|
||||
author in ['john', 'jill'] && 'article_type' == 'blog'
|
||||
----
|
||||
|
||||
is converted into the proprietary OpenSearch filter format:
|
||||
|
||||
[source,text]
|
||||
----
|
||||
(metadata.author:john OR jill) AND metadata.article_type:blog
|
||||
----
|
||||
Reference in New Issue
Block a user