跳到主要内容

Azure AI 服务

Deepseek 3.2 中英对照 Azure AI Service

本节将指导你如何设置 AzureVectorStore，用于存储文档嵌入向量，并通过 Azure AI 搜索服务执行相似性搜索。

Azure AI Search 是一个多功能的云托管信息检索系统，它是微软更广泛的 AI 平台的一部分。除其他功能外，它还允许用户使用基于向量的存储和检索来查询信息。

先决条件​

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

  2. Azure AI 搜索服务：创建一个 AI 搜索服务。服务创建完成后，从 设置 下的 密钥 部分获取管理员 apiKey，并从 概述 部分的 URL 字段检索端点。

  3. （可选）Azure OpenAI 服务：创建一个 Azure OpenAI 服务。注意： 你可能需要填写一份单独的申请表才能获得对 Azure OpenAI 服务的访问权限。服务创建完成后，从 资源管理 下的 密钥和终结点 部分获取端点和 apiKey。

配置​

启动时，如果已在构造函数中将相关 initialize-schema 布尔属性设置为 true（或在使用 Spring Boot 时，在 application.properties 文件中设置 …​initialize-schema=true），AzureVectorStore 将尝试在 AI Search 服务实例中创建新索引。

:::注意
这是一个破坏性变更！在 Spring AI 的早期版本中，此模式初始化默认会自动执行。
:::

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

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

  • Azure AI Search 终端节点
  • Azure AI Search 密钥
  • (可选) Azure OpenAI API 终端节点
  • (可选) Azure OpenAI API 密钥

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

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 Open AI实现替换为任何支持嵌入接口的有效OpenAI实现。例如，您可以使用Spring AI的Open AI或TransformersEmbedding实现来替代Azure实现。

依赖关系​

备注

Spring AI 的自动配置、Starter 模块的构件名称发生了重大变化。更多信息请参阅 升级说明。

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

1. 选择嵌入接口实现。您可以从以下选项中选择：​

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

2. Azure (AI Search) 向量存储​

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

:::提示
请参考依赖管理章节，将 Spring AI BOM 添加到你的构建文件中。
:::

配置属性​

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

属性默认值
spring.ai.vectorstore.azure.url
spring.ai.vectorstore.azure.api-key
spring.ai.vectorstore.azure.useKeylessAuthfalse
spring.ai.vectorstore.azure.initialize-schemafalse
spring.ai.vectorstore.azure.index-namespring_ai_azure_vector_store
spring.ai.vectorstore.azure.default-top-k4
spring.ai.vectorstore.azure.default-similarity-threshold0.0
spring.ai.vectorstore.azure.embedding-propertyembedding
spring.ai.vectorstore.azure.index-namespring-ai-document-index

示例代码​

要在应用程序中配置 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();
}
备注

您必须明确列出过滤表达式中使用的任何元数据键的所有元数据字段名称和类型。上面的列表注册了可过滤的元数据字段：类型为 TEXT 的 country、类型为 INT64 的 year 和类型为 BOOLEAN 的 active。

如果可过滤的元数据字段扩展了新的条目，您必须（重新）上传/更新具有此元数据的文档。

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

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

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

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

如果一切顺利，你应该能取回包含文本 "Spring AI rocks!!" 的文档。

元数据过滤​

同样，您也可以在 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 Search 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
}

原生客户端让你能够访问Azure Search特有的功能和操作，这些可能不会通过VectorStore接口公开。