Azure AI Service
This section will walk you through setting up the AzureVectorStore
to store document embeddings and perform similarity searches using the Azure AI Search Service.
Azure AI Search is a versatile cloud-hosted cloud information retrieval system that is part of Microsoft’s larger AI platform. Among other features, it allows users to query information using vector-based storage and retrieval.
Prerequisites
-
Azure Subscription: You will need an Azure subscription to use any Azure service.
-
Azure AI Search Service: Create an AI Search service. Once the service is created, obtain the admin apiKey from the
Keys
section underSettings
and retrieve the endpoint from theUrl
field under theOverview
section. -
(Optional) Azure OpenAI Service: Create an Azure OpenAI service. NOTE: You may have to fill out a separate form to gain access to Azure Open AI services. Once the service is created, obtain the endpoint and apiKey from the
Keys and Endpoint
section underResource Management
.
Configuration
On startup, the AzureVectorStore
can attempt to create a new index within your AI Search service instance if you’ve opted in by setting the relevant initialize-schema
boolean
property to true
in the constructor or, if using Spring Boot, setting …initialize-schema=true
in your application.properties
file.
this is a breaking change! In earlier versions of Spring AI, this schema initialization happened by default. |
Alternatively, you can create the index manually.
To set up an AzureVectorStore, you will need the settings retrieved from the prerequisites above along with your index name:
-
Azure AI Search Endpoint
-
Azure AI Search Key
-
(optional) Azure OpenAI API Endpoint
-
(optional) Azure OpenAI API Key
You can provide these values as OS environment variables.
export AZURE_AI_SEARCH_API_KEY=<My AI Search API Key>
export AZURE_AI_SEARCH_ENDPOINT=<My AI Search Index>
export OPENAI_API_KEY=<My Azure AI API Key> (Optional)
You can replace Azure Open AI implementation with any valid OpenAI implementation that supports the Embeddings interface. For example, you could use Spring AI’s Open AI or |
Dependencies
Add these dependencies to your project:
1. Select an Embeddings interface implementation. You can choose between:
-
OpenAI Embedding:
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-openai-spring-boot-starter</artifactId>
</dependency>
-
Or Azure AI Embedding:
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-azure-openai-spring-boot-starter</artifactId>
</dependency>
-
Or Local Sentence Transformers Embedding:
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-transformers-spring-boot-starter</artifactId>
</dependency>
2. Azure (AI Search) Vector Store
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-azure-store</artifactId>
</dependency>
Refer to the Dependency Management section to add the Spring AI BOM to your build file. |
Configuration Properties
You can use the following properties in your Spring Boot configuration to customize the Azure vector store.
Property | Default value |
---|---|
|
|
|
|
|
false |
|
spring_ai_azure_vector_store |
|
4 |
|
0.0 |
|
embedding |
|
spring-ai-document-index |
Sample Code
To configure an Azure SearchIndexClient
in your application, you can use the following code:
@Bean
public SearchIndexClient searchIndexClient() {
return new SearchIndexClientBuilder().endpoint(System.getenv("AZURE_AI_SEARCH_ENDPOINT"))
.credential(new AzureKeyCredential(System.getenv("AZURE_AI_SEARCH_API_KEY")))
.buildClient();
}
To create a vector store, you can use the following code by injecting the SearchIndexClient
bean created in the above sample along with an EmbeddingModel
provided by the Spring AI library that implements the desired Embeddings interface.
@Bean
public VectorStore vectorStore(SearchIndexClient searchIndexClient, EmbeddingModel embeddingModel) {
return new AzureVectorStore(searchIndexClient, embeddingModel,
// Define the metadata fields to be used
// in the similarity search filters.
List.of(MetadataField.text("country"),
MetadataField.int64("year"),
MetadataField.bool("active")));
}
You must list explicitly all metadata field names and types for any metadata key used in the filter expression. The list above registers filterable metadata fields: If the filterable metadata fields are expanded with new entries, you have to (re)upload/update the documents with this metadata. |
In your main code, create some documents:
List<Document> documents = List.of(
new Document("Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!!", Map.of("country", "BG", "year", 2020)),
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("country", "NL", "year", 2023)));
Add the documents to your vector store:
vectorStore.add(documents);
And finally, retrieve documents similar to a query:
List<Document> results = vectorStore.similaritySearch(
SearchRequest
.query("Spring")
.withTopK(5));
If all goes well, you should retrieve the document containing the text "Spring AI rocks!!".
Metadata filtering
You can leverage the generic, portable metadata filters with AzureVectorStore as well.
For example, you can use either the text expression language:
vectorStore.similaritySearch(
SearchRequest
.query("The World")
.withTopK(TOP_K)
.withSimilarityThreshold(SIMILARITY_THRESHOLD)
.withFilterExpression("country in ['UK', 'NL'] && year >= 2020"));
or programmatically using the expression DSL:
FilterExpressionBuilder b = new FilterExpressionBuilder();
vectorStore.similaritySearch(
SearchRequest
.query("The World")
.withTopK(TOP_K)
.withSimilarityThreshold(SIMILARITY_THRESHOLD)
.withFilterExpression(b.and(
b.in("country", "UK", "NL"),
b.gte("year", 2020)).build()));
The portable filter expressions get automatically converted into the proprietary Azure Search OData filters. For example, the following portable filter expression:
country in ['UK', 'NL'] && year >= 2020
is converted into the following Azure OData filter expression:
$filter search.in(meta_country, 'UK,NL', ',') and meta_year ge 2020