Azure AI Service

本节将指导您设置 AzureVectorStore 以存储文档嵌入，并使用 Azure AI 搜索服务执行相似度搜索。

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 是作为 Microsoft 更大 AI 平台的一部分的多功能云托管云信息检索系统。除了其他功能外，它还允许用户使用基于向量的存储和检索来查询信息。

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

  1. Azure 订阅：你需要 Azure subscription 才能使用任何 Azure 服务。

  2. Azure Subscription: You will need an Azure subscription to use any Azure service.

  3. Azure AI 搜索服务：创建一个 AI Search service.服务创建好后，从 Settings 下的 Keys 部分获取管理员 apiKey，并从 Overview 部分下的 Url 字段获取终结点。

  4. Azure AI Search Service: Create an AI Search service. Once the service is created, obtain the admin apiKey from the Keys section under Settings and retrieve the endpoint from the Url field under the Overview section.

  5. （可选）Azure OpenAI 服务：创建一个 Azure OpenAI service. NOTE: 你可能需要填写一份单独的表单才能获得对 Azure Open AI 服务的访问权限。服务创建好后，从 Resource Management 下的 Keys and Endpoint 部分获取终结点和 apiKey。

  6. (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 under Resource Management.

Configuration

以下是用 Gemini 翻译的中文版本：在启动时， AzureVectorStore 可以尝试在您的 AI 搜索服务实例中创建一个新索引，如果您已选择启用，则可以在构造函数中将相关的 initialize-schema boolean 属性设置为 true ，或者如果使用 Spring Boot，则可以在 application.properties 文件中设置 …​initialize-schema=true 。

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.

这是一个重大更改！在早期版本的Spring AI中，此架构初始化是默认发生的。

this is a breaking change! In earlier versions of Spring AI, this schema initialization happened by default.

使用Gemini翻译，这段文字的中文是：或者，您可以手动创建索引。

Alternatively, you can create the index manually.

要设置 AzureVectorStore，您需要从上述先决条件中检索到的设置以及您的索引名称：

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

  • （可选）Azure OpenAI API 端点

  • (optional) Azure OpenAI API Endpoint

  • （可选）Azure OpenAI API 密钥

  • (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)

您可以用支持 Embeddings 接口的任何有效的 OpenAI 实现替换 Azure Open AI 实现。例如，您可以使用 Spring AI 的 Open AI 或 TransformersEmbedding 实现作为嵌入，而不是 Azure 实现。

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 TransformersEmbedding implementations for embeddings instead of the Azure implementation.

Dependencies

Spring AI 自动配置、启动器模块的工件名称发生了重大变化。请参阅 upgrade notes 以获取更多信息。

There has been a significant change in the Spring AI auto-configuration, starter modules' artifact names. Please refer to the upgrade notes for more information.

将这些依赖项添加到你的项目中：

Add these dependencies to your project:

1. Select an Embeddings interface implementation. You can choose between:

  • OpenAI Embedding

  • Azure AI Embedding

  • Local Sentence Transformers Embedding

<dependency>
   <groupId>org.springframework.ai</groupId>
   <artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>
<dependency>
 <groupId>org.springframework.ai</groupId>
 <artifactId>spring-ai-starter-model-azure-openai</artifactId>
</dependency>
<dependency>
 <groupId>org.springframework.ai</groupId>
 <artifactId>spring-ai-starter-model-transformers</artifactId>
</dependency>

2. Azure (AI Search) Vector Store

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-azure-store</artifactId>
</dependency>

  1. 参见 Dependency Management 部分，将 Spring AI BOM 添加到你的构建文件中。

Refer to the Dependency Management section to add the Spring AI BOM to your build file.

Configuration Properties

以下是使用Gemini翻译的中文版本：你可以在 Spring Boot 配置中使用以下属性来自定义 Azure 向量存储。

You can use the following properties in your Spring Boot configuration to customize the Azure vector store.

Property Default value

spring.ai.vectorstore.azure.url

spring.ai.vectorstore.azure.api-key

spring.ai.vectorstore.azure.useKeylessAuth

false

spring.ai.vectorstore.azure.initialize-schema

false

spring.ai.vectorstore.azure.index-name

spring_ai_azure_vector_store

spring.ai.vectorstore.azure.default-top-k

4

spring.ai.vectorstore.azure.default-similarity-threshold

0.0

spring.ai.vectorstore.azure.embedding-property

embedding

spring.ai.vectorstore.azure.index-name

spring-ai-document-index

Sample Code

要在您的应用程序中配置 Azure SearchIndexClient ，可以使用以下代码：

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();
}

要创建向量存储，您可以使用以下代码，通过注入在上述示例中创建的 SearchIndexClient bean 和 Spring AI 库提供的实现所需 Embeddings 接口的 EmbeddingModel 。

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 AzureVectorStore.builder(searchIndexClient, embeddingModel)
    .initializeSchema(true)
    // Define the metadata fields to be used
    // in the similarity search filters.
    .filterMetadataFields(List.of(MetadataField.text("country"), MetadataField.int64("year"),
            MetadataField.date("activationDate")))
    .defaultTopK(5)
    .defaultSimilarityThreshold(0.7)
    .indexName("spring-ai-document-index")
    .build();
}

您必须明确列出筛选表达式中使用的任何元数据键的所有元数据字段名称和类型。上述列表注册了可筛选的元数据字段：类型为 TEXT 的 country、类型为 INT64 的 year、类型为 BOOLEAN 的 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: country of type TEXT, year of type INT64, and active of type BOOLEAN.

如果可过滤元数据字段通过新条目展开，则必须使用此元数据（重新）上传/更新文档。

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.builder()
      .query("Spring")
      .topK(5).build());

如果一切都顺利，你应该检索包含文本 “Spring AI rocks!!” 的文档。

If all goes well, you should retrieve the document containing the text "Spring AI rocks!!".

Metadata filtering

您也可以将通用的、可移植的 metadata filters 与 AzureVectorStore 结合使用。

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.builder()
      .query("The World")
      .topK(TOP_K)
      .similarityThreshold(SIMILARITY_THRESHOLD)
      .filterExpression("country in ['UK', 'NL'] && year >= 2020").build());

或使用表达式 DSL 以编程方式：

or programmatically using the expression DSL:

FilterExpressionBuilder b = new FilterExpressionBuilder();

vectorStore.similaritySearch(
    SearchRequest.builder()
      .query("The World")
      .topK(TOP_K)
      .similarityThreshold(SIMILARITY_THRESHOLD)
      .filterExpression(b.and(
         b.in("country", "UK", "NL"),
         b.gte("year", 2020)).build()).build());

可移植筛选器表达式会自动转换成 Microsoft Azure Search 专有的 OData filters。例如，以下可移植筛选器表达式：

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

会转换成以下 Azure OData filter expression：

is converted into the following Azure OData filter expression:

$filter search.in(meta_country, 'UK,NL', ',') and meta_year ge 2020

Accessing the Native Client

Azure 向量存储实现通过 getNativeClient() 方法提供对底层原生 Azure Search 客户端 ( SearchClient ) 的访问：

The Azure Vector Store implementation provides access to the underlying native Azure Search client (SearchClient) through the getNativeClient() method:

AzureVectorStore vectorStore = context.getBean(AzureVectorStore.class);
Optional<SearchClient> nativeClient = vectorStore.getNativeClient();

if (nativeClient.isPresent()) {
    SearchClient client = nativeClient.get();
    // Use the native client for Azure Search-specific operations
}

原生客户端允许您访问 Azure Search 特定的功能和操作，这些功能和操作可能未通过 VectorStore 接口公开。

The native client gives you access to Azure Search-specific features and operations that might not be exposed through the VectorStore interface.