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 Subscription: You will need an Azure subscription to use any Azure service.

  2. 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.

  3. (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

在启动时，AzureVectorStore 将尝试在您的 AI 搜索服务实例内新建一个索引。或者，您可以手动创建索引。

On startup, the AzureVectorStore will attempt to create a new index within your AI Search service instance. 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

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

您可以用支持 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

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

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-vector-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.

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 接口的 EmbeddingClient 。

To create a vector store, you can use the following code by injecting the SearchIndexClient bean created in the above sample along with an EmbeddingClient provided by the Spring AI library that implements the desired Embeddings interface.

@Bean
public VectorStore vectorStore(SearchIndexClient searchIndexClient, EmbeddingClient embeddingClient) {
  return new AzureVectorStore(searchIndexClient, embeddingClient,
    // Define the metadata fields to be used
    // in the similarity search filters.
    List.of(MetadataField.text("country"),
            MetadataField.int64("year"),
            MetadataField.bool("active")));
}

您必须明确列出筛选表达式中使用的任何元数据键的所有元数据字段名称和类型。上述列表注册了可筛选的元数据字段：类型为 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(List.of(document));

最后，检索与查询类似的文档：

And finally, retrieve documents similar to a query:

List<Document> results = vectorStore.similaritySearch(
    SearchRequest
      .query("Spring")
      .withTopK(5));

如果一切都顺利，你应该检索包含文本 “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
      .query("The World")
      .withTopK(TOP_K)
      .withSimilarityThreshold(SIMILARITY_THRESHOLD)
      .withFilterExpression("country in ['UK', 'NL'] && year >= 2020"));

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

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

可移植筛选器表达式会自动转换成 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