如需最新的快照版本，请使用 Spring AI 1.1.3！spring-doc.cadn.net.cn

Azure AI 服务

本节将引导您设置AzureVectorStore，以使用 Azure AI Search Service 存储文档嵌入并执行相似性搜索。spring-doc.cadn.net.cn

Azure AI Search 是一个多功能的云托管信息检索系统，属于微软更大规模 AI 平台的一部分。除其他功能外，它允许用户使用基于向量的存储和检索来查询信息。spring-doc.cadn.net.cn

前置条件

  1. Azure 订阅：您需要一个 Azure 订阅 才能使用任何 Azure 服务。spring-doc.cadn.net.cn

  2. Azure AI Search Service：创建AI Search 服务。服务创建完成后，从Settings下的Keys部分获取管理员 apiKey，并从Overview部分的Url字段中检索终结点。spring-doc.cadn.net.cn

  3. （可选）Azure OpenAI 服务：创建一个 Azure OpenAI 服务。注意：您可能需要填写单独的表格以获得 Azure OpenAI 服务的访问权限。服务创建完成后，从 Resource Management 下的 Keys and Endpoint 部分获取端点和 apiKey。spring-doc.cadn.net.cn

配置

启动时，如果通过在构造函数中将相关的 initialize-schema boolean 属性设置为 true opted in，或者在使用 Spring Boot 时在 application.properties 文件中设置 …​initialize-schema=true，AzureVectorStore 会尝试在您的 AI Search 服务实例中创建新索引。spring-doc.cadn.net.cn

这是一个破坏性变更！在早期版本的 Spring AI 中，此架构初始化是默认发生的。

或者，您也可以手动创建索引。spring-doc.cadn.net.cn

要设置 AzureVectorStore，您需要上述前提条件中检索到的设置以及您的索引名称：spring-doc.cadn.net.cn

您可以将这些值作为操作系统环境变量提供。spring-doc.cadn.net.cn

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 实现替换为任何支持 Embeddings 接口的有效 OpenAI 实现。例如，您可以使用 Spring AI 的 Open AI 或 TransformersEmbedding 实现来替代 Azure 实现进行嵌入处理。spring-doc.cadn.net.cn

依赖项

Spring AI自动配置和starter模块的artifact名称有了重大变化。 请参阅升级说明获取更多信息。spring-doc.cadn.net.cn

将以下依赖项添加到您的项目中：spring-doc.cadn.net.cn

1. 选择一个 Embeddings 接口实现。您可以在以下选项中进行选择：

<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) 向量存储

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-azure-store</artifactId>
</dependency>
请参阅依赖管理部分，将Spring AI BOM添加到您的构建文件中。

配置属性

您可以在 Spring Boot 配置中使用以下属性来自定义 Azure 向量存储。spring-doc.cadn.net.cn

<property> </property> 默认值

spring.ai.vectorstore.azure.urlspring-doc.cadn.net.cn

spring.ai.vectorstore.azure.api-keyspring-doc.cadn.net.cn

spring.ai.vectorstore.azure.useKeylessAuthspring-doc.cadn.net.cn

falsespring-doc.cadn.net.cn

spring.ai.vectorstore.azure.initialize-schemaspring-doc.cadn.net.cn

falsespring-doc.cadn.net.cn

spring.ai.vectorstore.azure.index-namespring-doc.cadn.net.cn

spring_ai_azure_vector_storespring-doc.cadn.net.cn

spring.ai.vectorstore.azure.default-top-kspring-doc.cadn.net.cn

4spring-doc.cadn.net.cn

spring.ai.vectorstore.azure.default-similarity-thresholdspring-doc.cadn.net.cn

0.0spring-doc.cadn.net.cn

spring.ai.vectorstore.azure.embedding-propertyspring-doc.cadn.net.cn

嵌入spring-doc.cadn.net.cn

spring.ai.vectorstore.azure.index-namespring-doc.cadn.net.cn

spring-ai-document-indexspring-doc.cadn.net.cn

示例代码

要在您的应用程序中配置 Azure SearchIndexClient，您可以使用以下代码：spring-doc.cadn.net.cn

@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。spring-doc.cadn.net.cn

@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。spring-doc.cadn.net.cn

如果可过滤的元数据字段扩展了新条目，您必须（重新）上传或更新带有此元数据的文档。spring-doc.cadn.net.cn

在您的主代码中，创建一些文档：spring-doc.cadn.net.cn

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

将文档添加到您的向量存储中：spring-doc.cadn.net.cn

vectorStore.add(documents);

最后，检索与查询相似的文档：spring-doc.cadn.net.cn

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

如果一切顺利，您应该能检索到包含文本"Spring AI rocks!!"的文档。spring-doc.cadn.net.cn

元数据过滤

您也可以将通用的、可移植的元数据过滤器与 AzureVectorStore 一起使用。spring-doc.cadn.net.cn

例如，您可以使用文本表达式语言：spring-doc.cadn.net.cn

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

或以编程方式使用表达式 DSL：spring-doc.cadn.net.cn

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 筛选器。例如，以下可移植的筛选表达式：spring-doc.cadn.net.cn

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

已转换为以下 Azure OData 筛选表达式：spring-doc.cadn.net.cn

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

访问原生客户端

Azure 向量存储实现通过 getNativeClient() 方法提供对底层原生 Azure Search 客户端（SearchClient）的访问：spring-doc.cadn.net.cn

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 搜索特有的功能和操作，这些功能和操作可能未通过 VectorStore 接口公开。spring-doc.cadn.net.cn