Azure AI Service

Azure AI Service

本节将引导您设置 AzureVectorStore，用于存储文档嵌入，并通过 Azure AI 搜索服务执行相似性搜索。

Azure AI 搜索 是一款多功能的云托管信息检索系统，隶属于微软更广泛的 AI 平台。它的一大特色是支持用户通过基于向量的存储与检索方式来查询信息。

先决条件

• Azure 订阅：您需要 Azure 订阅才能使用任何 Azure 服务。
• Azure AI 搜索服务：创建AI 搜索服务。创建服务后，从Keys以下部分获取 admin apiKey，并从该部分下的字段Settings检索端点。
• （可选）Azure OpenAI 服务：创建 Azure OpenAI 服务。注意：您可能需要填写单独的表格才能访问 Azure 开放 AI 服务。创建服务后，从 Resource Management 下面的 Keys and Endpoint 获取 endpoint 和 apiKey 。

配置

启动时，如果通过构造函数中设置相关的 initialize-schema 布尔属性为 true 或在 Spring Boot 中使用时，在 application.properties 文件中设置 initialize-schema=true，AzureVectorStore 可以尝试在您的 AI 搜索服务实例中创建一个新索引。

或者，您也可以手动创建索引。

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

• Azure AI Search Endpoint
• Azure AI Search Key
• (optional) Azure OpenAI API Endpoint
• (optional) Azure OpenAI API Key

您可以将这些值作为操作系统环境变量提供。

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)

注意：
您可以将 Azure OpenAI 实现替换为任何支持 Embeddings 接口的有效 OpenAI 实现。例如，您可以使用 Spring AI 的 OpenAI 或 TransformersEmbedding 实现来代替 Azure 的实现。

依赖

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

1、选择 Embeddings 接口实现。您可以选择：

• OpenAI Embedding:

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

• 或 Azure AI Embedding:

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

• 或本地化 Transformers Embedding:

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

2. Azure (AI Search) 向量存储

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

提示: 请参阅依赖管理部分将 Spring AI BOM 添加到您的构建文件中。

配置属性（Configuration Properties）

您可以在 Spring Boot 配置中使用以下属性来自定义 Azure 向量存储。

示例代码（Sample Code）

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

@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 来实现。

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

注意：
在过滤表达式中使用的所有元数据字段名称及类型必须明确列出。上述列表注册了可过滤的元数据字段：country（类型为 TEXT）、year（类型为 INT64）以及 active（类型为 BOOLEAN）。
如果可过滤元数据字段扩展了新条目，您必须（重新）上传 / 更新包含此元数据的文档。

在你的主代码中，创建一些文档：

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

将文档添加到您的向量存储中：

vectorStore.add(List.of(document));

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

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

如果一切顺利，您应能检索到包含 “Spring AI 太棒了！！” 文本的文档。

元数据过滤（Metadata filtering）

您可以同样利用 AzureVectorStore 中通用的、可移植的 元数据过滤器。

例如，您可以使用文本表达式语言：

vectorStore.similaritySearch(
   SearchRequest.builder()
      .query("The World")
      .topK(TOP_K)
      .similarityThreshold(SIMILARITY_THRESHOLD)
      .filterExpression("country in ['UK', 'NL'] && year >= 2020").build());

或通过表达式 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());

便携式过滤表达式会自动转换为专有的 Azure 搜索 OData 过滤器 。例如，以下便携式过滤表达式：

country in ['UK', 'NL'] && year >= 2020

被转换为以下 Azure OData 筛选表达式 ：

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

访问原生客户端

Azure Vector Store 实现通过 ‘getNativeClient ()‘ 方法提供了对底层原生 Azure Search 客户端（SearchClient）的访问：

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
}

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