此版本仍在开发中，尚不被认为是稳定的。对于最新的快照版本，请使用 Spring AI 1.0.1！spring-doc.cadn.net.cn

Azure AI 服务

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

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

前提条件

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

  2. Azure AI 搜索服务：创建 AI 搜索服务。创建服务后，从Keys部分Settings并从Url字段Overview部分。spring-doc.cadn.net.cn

  3. （可选）Azure OpenAI 服务：创建 Azure OpenAI 服务。注意：可能需要填写单独的表单才能访问 Azure Open AI 服务。创建服务后，从Keys and Endpoint部分Resource Management.spring-doc.cadn.net.cn

配置

启动时，AzureVectorStore如果已通过设置相关initialize-schema boolean属性设置为true在构造函数中，或者，如果使用 Spring Boot，则将…​initialize-schema=true在你的application.properties文件。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 实现替换为支持嵌入接口的任何有效 OpenAI 实现。例如，您可以使用 Spring AI 的 Open AI 或TransformersEmbedding嵌入的实现，而不是 Azure 实现。spring-doc.cadn.net.cn

依赖

Spring AI 自动配置、入门模块的工件名称发生了重大变化。 有关更多信息，请参阅升级说明。spring-doc.cadn.net.cn

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

1. 选择“嵌入”接口实现。您可以选择：

<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 搜索）矢量存储

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

配置属性

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

属性 默认值

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-文档索引spring-doc.cadn.net.cn

示例代码

配置 AzureSearchIndexClient在应用程序中，可以使用以下代码：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 以及EmbeddingModel由实现所需 Embeddings 接口的 Spring AI 库提供。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();
}

必须显式列出筛选器表达式中使用的任何元数据键的所有元数据字段名称和类型。上面的列表注册了可过滤的元数据字段：country类型TEXT,year类型INT64和active类型BOOLEAN.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 搜索 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 矢量存储实现提供对基础本机 Azure 搜索客户端 （SearchClient） 通过getNativeClient()方法：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