技术之家

Spring AI Azure Cosmos DB

Thu, 28 May 2026 11:57:03 +0800

什么是 Azure Cosmos DB？

Azure Cosmos DB 是微软推出的全球分布式云原生数据库服务，专为关键业务应用设计。它具备高可用性、低延迟的特性，支持水平扩展以满足现代应用的需求。该服务从底层构建时就以全球分布式部署、细粒度多租户和水平扩展为核心。它是 Azure 的基础服务之一，被微软大多数全球级关键业务应用使用，包括 Teams、Skype、Xbox Live、Office 365、必应、Azure 活动目录、Azure 门户、微软应用商店等。同时，数千家外部客户也在使用该服务，其中包括 OpenAI 的 ChatGPT 及其他需要弹性扩展、一键式全球部署、全球低延迟和高可用性的关键人工智能应用。

什么是 DiskANN？

DiskANN（基于磁盘的近似最近邻搜索）是 Azure Cosmos DB 中用于提升向量搜索性能的创新技术。它通过为存储在 Cosmos DB 中的嵌入向量建立索引，实现对高维数据高效、可扩展的相似度搜索。

DiskANN 具备以下优势：

高效性：与传统方法相比，DiskANN 采用基于磁盘的结构，大幅缩短了查找最近邻的时间。
可扩展性：能够处理超出内存容量的大型数据集，适用于机器学习、人工智能驱动解决方案等各类应用。
低延迟：DiskANN 最大限度降低搜索操作的延迟，确保应用即使在数据量庞大的情况下也能快速获取结果。

在 Spring AI 集成 Azure Cosmos DB 的场景中，向量搜索会创建并使用 DiskANN 索引，保障相似度查询的最优性能。

通过自动配置设置 Azure Cosmos DB 向量存储

以下代码演示了如何通过自动配置方式设置 CosmosDBVectorStore：

package com.example.demo;

import io.micrometer.observation.ObservationRegistry;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.ai.document.Document;
import org.springframework.ai.vectorstore.SearchRequest;
import org.springframework.ai.vectorstore.VectorStore;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Lazy;

import java.util.List;
import java.util.Map;
import java.util.UUID;

import static org.assertj.core.api.Assertions.assertThat;

@SpringBootApplication
@EnableAutoConfiguration
public class DemoApplication implements CommandLineRunner {

    private static final Logger log = LoggerFactory.getLogger(DemoApplication.class);

    @Lazy
    @Autowired
    private VectorStore vectorStore;

    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }

    @Override
    public void run(String... args) throws Exception {
        Document document1 = new Document(UUID.randomUUID().toString(), "Sample content1", Map.of("key1", "value1"));
        Document document2 = new Document(UUID.randomUUID().toString(), "Sample content2", Map.of("key2", "value2"));
		this.vectorStore.add(List.of(document1, document2));
        Listresults = this.vectorStore.similaritySearch(SearchRequest.builder().query("Sample content").topK(1).build());

        log.info("Search results: {}", results);

        // 从向量存储中删除文档
		this.vectorStore.delete(List.of(document1.getId(), document2.getId()));
    }

    @Bean
    public ObservationRegistry observationRegistry() {
        return ObservationRegistry.create();
    }
}

自动配置

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

将以下依赖添加到你的 Maven 项目中：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-vector-store-azure-cosmos-db</artifactId>
</dependency>

配置属性

Cosmos DB 向量存储支持以下配置属性：

属性	描述
spring.ai.vectorstore.cosmosdb.databaseName	要使用的 Cosmos DB 数据库名称
spring.ai.vectorstore.cosmosdb.containerName	要使用的 Cosmos DB 容器名称
spring.ai.vectorstore.cosmosdb.partitionKeyPath	分区键路径
spring.ai.vectorstore.cosmosdb.metadataFields	以英文逗号分隔的元数据字段列表
spring.ai.vectorstore.cosmosdb.vectorStoreThroughput	向量存储的吞吐量
spring.ai.vectorstore.cosmosdb.vectorDimensions	向量的维度数量
spring.ai.vectorstore.cosmosdb.endpoint	Cosmos DB 的服务终结点
spring.ai.vectorstore.cosmosdb.key	Cosmos DB 的访问密钥（若未配置密钥，将使用 DefaultAzureCredential 进行身份验证）

带过滤器的复杂搜索

你可以在 Cosmos DB 向量存储中使用过滤器执行更复杂的搜索。以下示例演示了如何在搜索查询中使用过滤器：

Map<String, Object> metadata1 = new HashMap<>();
metadata1.put("country", "UK");
metadata1.put("year", 2021);
metadata1.put("city", "London");

Map<String, Object> metadata2 = new HashMap<>();
metadata2.put("country", "NL");
metadata2.put("year", 2022);
metadata2.put("city", "Amsterdam");

Document document1 = new Document("1", "A document about the UK", this.metadata1);
Document document2 = new Document("2", "A document about the Netherlands", this.metadata2);

vectorStore.add(List.of(document1, document2));

FilterExpressionBuilder builder = new FilterExpressionBuilder();
List<Document> results = vectorStore.similaritySearch(SearchRequest.builder().query("The World")
    .topK(10)
    .filterExpression((this.builder.in("country", "UK", "NL")).build()).build());

不使用自动配置设置 Azure Cosmos DB 向量存储

以下代码演示了如何不依赖自动配置设置 CosmosDBVectorStore。建议使用 DefaultAzureCredential 进行 Azure Cosmos DB 的身份验证。

@Bean
public VectorStore vectorStore(ObservationRegistry observationRegistry) {
    // 创建 Cosmos DB 客户端
    CosmosAsyncClient cosmosClient = new CosmosClientBuilder()
            .endpoint(System.getenv("COSMOSDB_AI_ENDPOINT"))
            .credential(new DefaultAzureCredentialBuilder().build())
            .userAgentSuffix("SpringAI-CDBNoSQL-VectorStore")
            .gatewayMode()
            .buildAsyncClient();

    // 创建并配置向量存储
    return CosmosDBVectorStore.builder(cosmosClient, embeddingModel)
            .databaseName("test-database")
            .containerName("test-container")
            // 配置用于过滤的元数据字段
            .metadataFields(List.of("country", "year", "city"))
            // 设置分区键路径（可选）
            .partitionKeyPath("/id")
            // 配置性能参数
            .vectorStoreThroughput(1000)
            .vectorDimensions(1536)  // 与你的嵌入模型维度保持一致
            // 添加自定义批处理策略（可选）
            .batchingStrategy(new TokenCountBatchingStrategy())
            // 添加用于指标监控的观测注册表
            .observationRegistry(observationRegistry)
            .build();
}

@Bean
public EmbeddingModel embeddingModel() {
    return new TransformersEmbeddingModel();
}

该配置展示了所有可用的构建器选项：

databaseName：Cosmos DB 数据库名称
containerName：数据库内的容器名称
partitionKeyPath：分区键路径（如 "/id"）
metadataFields：用于过滤的元数据字段列表
vectorStoreThroughput：向量存储容器的吞吐量（RU/s）
vectorDimensions：向量维度（需与嵌入模型匹配）
batchingStrategy：文档操作批处理策略（可选）

手动依赖配置

在你的 Maven 项目中添加以下依赖：

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

访问原生客户端

Azure Cosmos DB 向量存储实现通过 getNativeClient() 方法提供对底层原生 Azure Cosmos DB 客户端（CosmosClient）的访问：

CosmosDBVectorStore vectorStore = context.getBean(CosmosDBVectorStore.class);
Optional<CosmosClient> nativeClient = vectorStore.getNativeClient();

if (nativeClient.isPresent()) {
    CosmosClient client = nativeClient.get();
    // 使用原生客户端执行 Azure Cosmos DB 专属操作
}

原生客户端允许你访问 VectorStore 接口未暴露的 Azure Cosmos DB 专属特性和操作。

Spring AI Azure AI 服务

Thu, 28 May 2026 11:54:43 +0800

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

Azure AI 搜索是一款多功能的云托管信息检索系统，隶属于微软大型人工智能平台。其核心特性之一是支持用户基于向量的存储与检索方式查询信息。

前提条件

Azure 订阅：使用任何 Azure 服务都需要具备 Azure 订阅权限。

Azure AI 搜索服务：创建一个 AI 搜索服务。服务创建完成后，在「设置」下的「密钥」部分获取管理员 API 密钥，并在「概述」部分的「URL」字段中获取服务终结点。

（可选）Azure OpenAI 服务：创建一个 Azure OpenAI 服务。注意：你可能需要填写单独的申请表单才能获取 Azure OpenAI 服务的访问权限。服务创建完成后，在「资源管理」下的「密钥和终结点」部分获取终结点地址和 API 密钥。

配置

启动时，如果你通过在构造函数中将相关的 initialize-schema 布尔属性设置为 true 启用了该功能，AzureVectorStore 会尝试在你的 AI 搜索服务实例中创建新索引；若使用 Spring Boot，则在 application.properties 文件中设置 …initialize-schema=true。

这是一项不兼容变更！在早期版本的 Spring AI 中，该索引结构初始化是默认执行的。

你也可以手动创建索引。

配置 AzureVectorStore 时，你需要上述前提条件中获取的配置信息以及索引名称：

Azure AI 搜索终结点
Azure AI 搜索密钥
（可选）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 OpenAI 实现替换为任意支持 Embeddings 接口的有效 OpenAI 实现。例如，你可以使用 Spring AI 的 OpenAI 或 TransformersEmbedding 实现替代 Azure 实现来生成嵌入向量。

依赖项

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

将以下依赖项添加到你的项目中：

1. 选择一个 Embeddings 接口实现，可选项包括：

OpenAI 嵌入向量
Azure AI 嵌入向量
本地句子转换器嵌入向量

<dependency>
   <groupId>org.springframework.ai</groupId>
   <artifactId>spring-ai-starter-model-openai</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.ai.vectorstore.azure.url
spring.ai.vectorstore.azure.api-key
spring.ai.vectorstore.azure.useKeylessAuth	false
spring.ai.vectorstore.azure.initialize-schema	false
spring.ai.vectorstore.azure.index-name	spring_ai_azure_vector_store
spring.ai.vectorstore.azure.default-top-k	4
spring.ai.vectorstore.azure.default-similarity-threshold	0.0
spring.ai.vectorstore.azure.content-field-name	content
spring.ai.vectorstore.azure.embedding-field-name	embedding
spring.ai.vectorstore.azure.metadata-field-name	metadata

示例代码

在应用中配置 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)
    // 定义用于相似度搜索过滤器的元数据字段
    .filterMetadataFields(List.of(MetadataField.text("country"), MetadataField.int64("year"),
            MetadataField.date("activationDate")))
    .defaultTopK(5)
    .defaultSimilarityThreshold(0.7)
    .indexName("spring-ai-document-index")
    .build();
}

你必须显式列出过滤表达式中使用的所有元数据字段名称和类型。上述代码注册了可过滤的元数据字段：文本类型的 country、64 位整型的 year 以及布尔类型的 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 搜索专用的 OData 过滤器。例如，以下可移植过滤表达式：

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

会被转换为以下 Azure OData 过滤表达式：

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

自定义字段名

默认情况下，Azure 向量存储在 Azure AI 搜索索引中使用以下字段名：

content - 存储文档文本
embedding - 存储向量嵌入
metadata - 存储文档元数据

但是，当使用已存在的、采用不同字段名的 Azure AI 搜索索引时，你可以配置自定义字段名以匹配索引结构。这让你无需修改现有索引，即可将 Spring AI 与之集成。

使用场景

自定义字段名在以下场景中尤为实用：

集成现有索引：你的组织已拥有遵循既定字段命名规范（如 chunk_text、vector、meta_data）的 Azure AI 搜索索引。
遵循命名标准：你的团队使用与默认值不同的特定命名规范。
从其他系统迁移：你正在从其他向量数据库或搜索系统迁移，并希望保持字段名一致。

通过属性配置

你可以通过 Spring Boot 应用属性配置自定义字段名：

spring.ai.vectorstore.azure.url=${AZURE_AI_SEARCH_ENDPOINT}
spring.ai.vectorstore.azure.api-key=${AZURE_AI_SEARCH_API_KEY}
spring.ai.vectorstore.azure.index-name=my-existing-index
spring.ai.vectorstore.azure.initialize-schema=false

# 匹配现有索引结构的自定义字段名
spring.ai.vectorstore.azure.content-field-name=chunk_text
spring.ai.vectorstore.azure.embedding-field-name=vector
spring.ai.vectorstore.azure.metadata-field-name=meta_data

使用带有自定义字段名的现有索引时，设置 initialize-schema=false，避免 Spring AI 尝试使用默认结构创建新索引。

通过构建器 API 配置

此外，你可以通过构建器 API 编程配置自定义字段名：

@Bean
public VectorStore vectorStore(SearchIndexClient searchIndexClient, EmbeddingModel embeddingModel) {

	return AzureVectorStore.builder(searchIndexClient, embeddingModel)
		.indexName("my-existing-index")
		.initializeSchema(false) // 不创建结构 - 使用现有索引
		// 配置自定义字段名以匹配现有索引
		.contentFieldName("chunk_text")
		.embeddingFieldName("vector")
		.metadataFieldName("meta_data")
		.filterMetadataFields(List.of(
			MetadataField.text("category"),
			MetadataField.text("source")))
		.build();
}

完整示例：使用现有索引

以下是一个完整示例，展示如何将 Spring AI 与带有自定义字段名的现有 Azure AI 搜索索引配合使用：

@Configuration
public class VectorStoreConfig {

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

	@Bean
	public VectorStore vectorStore(SearchIndexClient searchIndexClient,
			EmbeddingModel embeddingModel) {

		return AzureVectorStore.builder(searchIndexClient, embeddingModel)
			.indexName("production-documents-index")
			.initializeSchema(false) // 使用现有索引
			// 映射到现有索引字段名
			.contentFieldName("document_text")
			.embeddingFieldName("text_vector")
			.metadataFieldName("document_metadata")
			// 定义现有结构中的可过滤元数据字段
			.filterMetadataFields(List.of(
				MetadataField.text("department"),
				MetadataField.int64("year"),
				MetadataField.date("created_date")))
			.defaultTopK(10)
			.defaultSimilarityThreshold(0.75)
			.build();
	}
}

之后你可以正常使用向量存储：

// 使用带有自定义字段名的现有索引进行搜索
List<Document> results = vectorStore.similaritySearch(
	SearchRequest.builder()
		.query("artificial intelligence")
		.topK(5)
		.filterExpression("department == 'Engineering' && year >= 2023")
		.build());

// 结果包含来自 document_text 字段的文档文本
results.forEach(doc -> System.out.println(doc.getText()));

使用自定义字段名创建新索引

你也可以通过设置 initialize-schema=true，使用自定义字段名创建新索引：

@Bean
public VectorStore vectorStore(SearchIndexClient searchIndexClient,
		EmbeddingModel embeddingModel) {

	return AzureVectorStore.builder(searchIndexClient, embeddingModel)
		.indexName("new-custom-index")
		.initializeSchema(true) // 使用自定义字段名创建新索引
		.contentFieldName("text_content")
		.embeddingFieldName("content_vector")
		.metadataFieldName("doc_metadata")
		.filterMetadataFields(List.of(
			MetadataField.text("category"),
			MetadataField.text("author")))
		.build();
}

这会创建一个包含你自定义字段名的新 Azure AI 搜索索引，让你从一开始就确立专属的命名规范。

访问原生客户端

Azure 向量存储实现通过 getNativeClient() 方法提供对底层原生 Azure 搜索客户端（SearchClient）的访问：

AzureVectorStore vectorStore = context.getBean(AzureVectorStore.class);
Optional<SearchClient> nativeClient = vectorStore.getNativeClient();

if (nativeClient.isPresent()) {
    SearchClient client = nativeClient.get();
    // 使用原生客户端执行 Azure 搜索专属操作
}

原生客户端允许你访问 VectorStore 接口未暴露的 Azure 搜索专属特性和操作。

Spring AI 向量数据库

Wed, 20 May 2026 16:20:00 +0800

向量数据库是一种专用数据库类型，在人工智能应用中发挥着至关重要的作用。

在向量数据库中，查询方式与传统关系型数据库不同。向量数据库不进行精确匹配，而是执行相似度搜索。当传入一个向量作为查询条件时，向量数据库会返回与该查询向量“相似”的向量。关于相似度的高层级计算方式，将在向量相似度部分进一步说明。

向量数据库用于将数据与人工智能模型进行集成。使用向量数据库的第一步是将数据加载到其中。之后，当用户查询需要发送至AI模型时，系统会先检索出一批相似文档。这些文档将作为用户问题的上下文，与用户查询一同发送给AI模型。该技术被称为检索增强生成（RAG）。

后续章节将介绍Spring AI中可适配多种向量数据库实现的接口，以及部分高层级使用示例。

最后一部分旨在揭秘向量数据库中相似度搜索的底层实现方式。

接口概述

本章节对Spring AI框架内的VectorStore接口及其相关类进行说明。

Spring AI通过VectorStore接口及其只读子接口VectorStoreRetriever，提供了一套可与向量数据库交互的抽象API。

VectorStoreRetriever接口

Spring AI提供了名为VectorStoreRetriever的只读接口，该接口仅暴露文档检索功能：

@FunctionalInterface
public interface VectorStoreRetriever {

    List<Document> similaritySearch(SearchRequest request);

    default List<Document> similaritySearch(String query) {
        return this.similaritySearch(SearchRequest.builder().query(query).build());
    }
}

该函数式接口适用于仅需从向量存储库检索文档、无需执行任何修改操作的场景。它遵循最小权限原则，仅开放文档检索所需的必要功能。

VectorStore接口

VectorStore接口继承自VectorStoreRetriever，并新增了数据修改能力：

public interface VectorStore extends DocumentWriter, VectorStoreRetriever {

    default String getName() {
		return this.getClass().getSimpleName();
	}

    void add(List<Document> documents);

    void delete(List<String> idList);

    void delete(Filter.Expression filterExpression);

    default void delete(String filterExpression) { ... }

    default <T> Optional<T> getNativeClient() {
		return Optional.empty();
	}
}

VectorStore接口整合了读写操作，支持在向量数据库中添加、删除和检索文档。

SearchRequest构建器

public class SearchRequest {

	public static final double SIMILARITY_THRESHOLD_ACCEPT_ALL = 0.0;

	public static final int DEFAULT_TOP_K = 4;

	private String query = "";

	private int topK = DEFAULT_TOP_K;

	private double similarityThreshold = SIMILARITY_THRESHOLD_ACCEPT_ALL;

	@Nullable
	private Filter.Expression filterExpression;

    public static Builder from(SearchRequest originalSearchRequest) {
		return builder().query(originalSearchRequest.getQuery())
			.topK(originalSearchRequest.getTopK())
			.similarityThreshold(originalSearchRequest.getSimilarityThreshold())
			.filterExpression(originalSearchRequest.getFilterExpression());
	}

	public static class Builder {

		private final SearchRequest searchRequest = new SearchRequest();

		public Builder query(String query) {
			Assert.notNull(query, "Query can not be null.");
			this.searchRequest.query = query;
			return this;
		}

		public Builder topK(int topK) {
			Assert.isTrue(topK >= 0, "TopK should be positive.");
			this.searchRequest.topK = topK;
			return this;
		}

		public Builder similarityThreshold(double threshold) {
			Assert.isTrue(threshold >= 0 && threshold 向向量数据库插入数据时，需将数据封装为Document对象。Document类封装了PDF、Word等数据源中的文本内容，以字符串形式存储；同时以键值对形式保存元数据，例如文件名等信息。数据插入向量数据库时，文本内容会通过嵌入模型转换为数值数组（float[]），即向量嵌入。Word2Vec、GLoVE、BERT、OpenAI的text‑embedding‑ada‑002等嵌入模型，可将词语、句子或段落转换为这类向量嵌入。向量数据库的作用是存储向量嵌入并支持相似度检索，其本身不生成嵌入向量。生成向量嵌入需要使用EmbeddingModel。接口中的similaritySearch方法可检索与指定查询字符串相似的文档，可通过以下参数进行精细化配置：k：整数类型，指定返回的最大相似文档数量，常被称为Top‑K检索或K近邻（KNN）。threshold：0‑1之间的双精度数值，数值越接近1代表相似度越高。例如默认阈值设为0.75时，仅返回相似度高于该值的文档。Filter.Expression：用于传入流式领域特定语言（DSL）表达式，作用类似SQL的where子句，但仅作用于Document的元数据键值对。filterExpression：基于ANTLR4的外部DSL，支持传入字符串格式的过滤表达式。例如元数据包含国家、年份、是否启用等字段时，可使用表达式：country == 'UK' && year >= 2020 && isActive == true。关于Filter.Expression的更多信息可参考元数据过滤章节。模式初始化部分向量存储库使用前需要初始化后端模式，默认不会自动初始化。需要手动开启：传入对应构造函数的布尔参数；若使用Spring Boot，则在application.properties或application.yml中将initialize‑schema属性设为true。具体属性名需查阅对应向量存储库的文档。批处理策略使用向量存储库时，通常需要对大量文档进行嵌入处理。直接一次性调用接口处理全部文档看似简单，但会引发问题。嵌入模型以令牌为单位处理文本，存在最大令牌限制，即上下文窗口大小。该限制约束单次嵌入请求可处理的文本量，单次处理过多令牌会引发报错或嵌入向量截断。为解决令牌限制问题，Spring AI实现了批处理策略。该策略将大量文档拆分为多个小批次，确保每批文本不超出嵌入模型的最大上下文窗口。批处理不仅解决令牌限制问题，还可提升性能、高效利用API调用频率限制。Spring AI通过BatchingStrategy接口提供该功能，可根据文档令牌数量进行子批次处理。核心BatchingStrategy接口定义如下：public interface BatchingStrategy {
    List<List<Document>> batch(List<Document> documents);
}该接口仅定义一个batch方法，接收文档列表，返回分批次后的文档集合。默认实现Spring AI提供默认实现类TokenCountBatchingStrategy。该策略根据文档令牌数进行批处理，确保每批文档不超过计算后的最大输入令牌数。TokenCountBatchingStrategy核心特性：默认以OpenAI最大输入令牌数（8191）为上限。预留百分比（默认10%），用于应对潜在开销。实际最大输入令牌数计算公式：实际最大输入令牌数 = 原始最大输入令牌数 × (1 − 预留百分比)。该策略会估算每个文档的令牌数，在不超过最大输入令牌数的前提下分组；若单个文档超出限制则抛出异常。可自定义TokenCountBatchingStrategy适配业务需求，在Spring Boot的@Configuration类中创建自定义参数实例即可。自定义TokenCountBatchingStrategy Bean示例：@Configuration
public class EmbeddingConfig {
    @Bean
    public BatchingStrategy customTokenCountBatchingStrategy() {
        return new TokenCountBatchingStrategy(
            EncodingType.CL100K_BASE,  // 指定编码类型
            8000,                      // 设置最大输入令牌数
            0.1                        // 设置预留百分比
        );
    }
}配置说明：EncodingType.CL100K_BASE：指定分词编码类型，JTokkitTokenCountEstimator使用该编码精准估算令牌数量。8000：设置最大输入令牌数，需小于等于嵌入模型的最大上下文窗口。0.1：设置预留百分比，从最大输入令牌数中预留部分额度，应对处理过程中令牌数增加的情况。默认构造函数使用Document.DEFAULT_CONTENT_FORMATTER格式化内容，MetadataMode.NONE处理元数据。如需自定义，可使用包含更多参数的完整构造函数。定义完成后，该自定义TokenCountBatchingStrategy Bean会自动被应用内的EmbeddingModel实现类使用，替代默认策略。TokenCountBatchingStrategy内部使用TokenCountEstimator（具体为JTokkitTokenCountEstimator）计算令牌数以实现高效批处理，基于指定编码类型精准估算令牌数。此外，TokenCountBatchingStrategy支持传入自定义TokenCountEstimator接口实现类，适配个性化令牌统计策略。示例如下：TokenCountEstimator customEstimator = new YourCustomTokenCountEstimator();
TokenCountBatchingStrategy strategy = new TokenCountBatchingStrategy(
		this.customEstimator,
    8000,  // 最大输入令牌数
    0.1,   // 预留百分比
    Document.DEFAULT_CONTENT_FORMATTER,
    MetadataMode.NONE
);自动截断处理部分嵌入模型（如Vertex AI文本嵌入）支持auto_truncate特性。开启后，模型会静默截断超出最大长度的文本并继续处理；关闭后，超长输入会直接抛出异常。批处理策略搭配自动截断时，需将批处理策略的输入令牌数上限设置为远高于模型实际最大值，避免批处理策略对超长文档抛出异常，由嵌入模型内部完成截断。自动截断配置开启自动截断时，批处理策略的最大输入令牌数需远大于模型实际限制，避免批处理策略拦截超长文档，由嵌入模型内部处理截断。Vertex AI开启自动截断、自定义批处理策略并适配PgVectorStore的配置示例：@Configuration
public class AutoTruncationEmbeddingConfig {

    @Bean
    public VertexAiTextEmbeddingModel vertexAiEmbeddingModel(
            VertexAiEmbeddingConnectionDetails connectionDetails) {

        VertexAiTextEmbeddingOptions options = VertexAiTextEmbeddingOptions.builder()
                .model(VertexAiTextEmbeddingOptions.DEFAULT_MODEL_NAME)
                .autoTruncate(true)  // 开启自动截断
                .build();

        return new VertexAiTextEmbeddingModel(connectionDetails, options);
    }

    @Bean
    public BatchingStrategy batchingStrategy() {
        // 仅在嵌入模型开启自动截断时使用超高令牌限制
        // 设置远高于模型实际支持的令牌数
        // 例如Vertex AI实际上限20000，此处设为132900
        return new TokenCountBatchingStrategy(
                EncodingType.CL100K_BASE,
                132900,  // 人为设置的超高上限
                0.1      // 10%预留额度
        );
    }

    @Bean
    public VectorStore vectorStore(JdbcTemplate jdbcTemplate, EmbeddingModel embeddingModel, BatchingStrategy batchingStrategy) {
        return PgVectorStore.builder(jdbcTemplate, embeddingModel)
            // 此处省略其他属性
            .build();
    }
}配置说明：嵌入模型开启自动截断，可平稳处理超长输入。批处理策略使用人为设置的超高令牌上限（132900），远大于模型实际限制（20000）。向量存储库使用配置好的嵌入模型和自定义批处理策略Bean。实现原理TokenCountBatchingStrategy会校验单个文档是否超出配置上限，超出则抛出IllegalArgumentException。批处理策略设置超高上限，可避免该校验触发异常。超出模型限制的文档或批次，由嵌入模型的自动截断功能静默截断并处理。最佳实践使用自动截断时：批处理策略最大输入令牌数至少设为模型实际上限的5‑10倍，避免提前触发批处理策略异常。监控嵌入模型的截断警告日志（部分模型无截断日志）。评估静默截断对嵌入质量的影响。使用样本文档测试，确保截断后的嵌入向量满足业务需求。记录该非常规配置，便于后续维护。自动截断虽可避免报错，但会生成不完整的嵌入向量，长文档末尾的关键信息可能丢失。若应用需要完整嵌入全部内容，需在嵌入前将文档拆分为更小片段。Spring Boot自动配置使用Spring Boot自动配置时，需自定义BatchingStrategy Bean以覆盖Spring AI默认实现：@Bean
public BatchingStrategy customBatchingStrategy() {
    // 该Bean将覆盖默认批处理策略
    return new TokenCountBatchingStrategy(
            EncodingType.CL100K_BASE,
            132900,  // 远高于模型实际限制
            0.1
    );
}应用上下文内存在该Bean时，所有向量存储库会自动替换为该批处理策略。自定义实现TokenCountBatchingStrategy提供了稳健的默认实现，也可基于Spring Boot自动配置自定义批处理策略。自定义方式为在Spring Boot应用中定义BatchingStrategy Bean：@Configuration
public class EmbeddingConfig {
    @Bean
    public BatchingStrategy customBatchingStrategy() {
        return new CustomBatchingStrategy();
    }
}应用内的EmbeddingModel实现类会自动使用该自定义BatchingStrategy。Spring AI支持的向量存储库默认使用TokenCountBatchingStrategy，SAP Hana向量存储库暂未配置批处理功能。VectorStore实现类以下为VectorStore接口的可用实现：Azure Vector Search - Azure向量存储库Apache Cassandra - Apache Cassandra向量存储库Chroma Vector Store - Chroma向量存储库Elasticsearch Vector Store - Elasticsearch向量存储库GemFire Vector Store - GemFire向量存储库MariaDB Vector Store - MariaDB向量存储库Milvus Vector Store - Milvus向量存储库MongoDB Atlas Vector Store - MongoDB Atlas向量存储库Neo4j Vector Store - Neo4j向量存储库OpenSearch Vector Store - OpenSearch向量存储库Oracle Vector Store - Oracle数据库向量存储库PgVector Store - PostgreSQL/PGVector向量存储库Pinecone Vector Store - Pinecone向量存储库Qdrant Vector Store - Qdrant向量存储库Redis Vector Store - Redis向量存储库SAP Hana Vector Store - SAP HANA向量存储库Typesense Vector Store - Typesense向量存储库Weaviate Vector Store - Weaviate向量存储库SimpleVectorStore - 简易向量存储实现，仅用于测试SimpleVectorStore不可用于生产环境，仅适用于测试或演示场景。后续版本可能支持更多实现类。若需Spring AI支持其他向量数据库，可在GitHub提交Issue，或直接提交实现代码的Pull Request。各VectorStore实现类的详细信息见本章子章节。使用示例为向量数据库计算嵌入向量时，需选择与上层AI模型匹配的嵌入模型。例如使用OpenAI的ChatGPT时，需搭配OpenAiEmbeddingModel及text‑embedding‑ada‑002模型。Spring Boot Starter的OpenAI自动配置会在Spring应用上下文注入EmbeddingModel实现类，支持依赖注入。向向量存储库写入数据批量向向量存储库加载数据时，先将数据封装为Spring AI的Document类，再调用VectorStore接口的add方法。以JSON源文件为例，使用Spring AI的JsonReader读取JSON中指定字段，拆分为小片段后传入向量存储库；向量存储库计算嵌入向量，并将JSON数据与嵌入向量存入数据库：@Autowired
VectorStore vectorStore;

void load(String sourceFile) {
    JsonReader jsonReader = new JsonReader(new FileSystemResource(sourceFile),
            "price", "name", "shortDescription", "description", "tags");
    List<Document> documents = jsonReader.get();
    this.vectorStore.add(documents);
}从向量存储库读取数据用户问题传入AI模型时，系统会执行相似度检索获取相似文档，作为上下文填充至提示词中。只读操作可使用VectorStore接口或更精简的VectorStoreRetriever接口：@Autowired
VectorStoreRetriever retriever; // 此处也可使用VectorStore

String question = "<用户的问题>";
List<Document> similarDocuments = retriever.similaritySearch(question);

// 或使用更精细的检索参数
SearchRequest request = SearchRequest.builder()
    .query(question)
    .topK(5)                       // 返回前5条结果
    .similarityThreshold(0.7)      // 仅返回相似度≥0.7的结果
    .build();

List<Document> filteredDocuments = retriever.similaritySearch(request);可通过similaritySearch方法传入额外参数，指定检索文档数量及相似度阈值。读写操作分离分离的接口可清晰区分需要写入权限和仅需读取权限的组件：// 拥有完整权限、执行写入操作的服务
@Service
class DocumentIndexer {
    private final VectorStore vectorStore;

    DocumentIndexer(VectorStore vectorStore) {
        this.vectorStore = vectorStore;
    }

    public void indexDocuments(List<Document> documents) {
        vectorStore.add(documents);
    }
}

// 仅需检索、执行只读操作的服务
@Service
class DocumentRetriever {
    private final VectorStoreRetriever retriever;

    DocumentRetriever(VectorStoreRetriever retriever) {
        this.retriever = retriever;
    }

    public List<Document> findSimilar(String query) {
        return retriever.similaritySearch(query);
    }
}该关注点分离方式仅为真正需要的组件开放修改权限，便于构建更易维护、安全性更高的应用。基于VectorStoreRetriever的检索操作VectorStoreRetriever接口提供向量存储库的只读视图，仅开放相似度检索功能。该接口遵循最小权限原则，尤其适用于RAG（检索增强生成）应用——仅需检索文档、无需修改底层数据。使用VectorStoreRetriever的优势：关注点分离：清晰区分读写操作。接口隔离：仅需检索的客户端不会暴露修改方法。函数式接口：简单场景可通过Lambda表达式或方法引用实现。降低依赖：仅检索的组件无需依赖完整的VectorStore接口。使用示例仅需执行相似度检索时，可直接使用VectorStoreRetriever：@Service
public class DocumentRetrievalService {

    private final VectorStoreRetriever retriever;

    public DocumentRetrievalService(VectorStoreRetriever retriever) {
        this.retriever = retriever;
    }

    public List<Document> findSimilarDocuments(String query) {
        return retriever.similaritySearch(query);
    }

    public List<Document> findSimilarDocumentsWithFilters(String query, String country) {
        SearchRequest request = SearchRequest.builder()
            .query(query)
            .topK(5)
            .filterExpression("country == '" + country + "'")
            .build();

        return retriever.similaritySearch(request);
    }
}该示例中，服务仅依赖VectorStoreRetriever接口，明确仅执行检索操作、不修改向量存储库。与RAG应用集成VectorStoreRetriever接口在RAG应用中尤为实用，可检索相关文档为AI模型提供上下文：@Service
public class RagService {

    private final VectorStoreRetriever retriever;
    private final ChatModel chatModel;

    public RagService(VectorStoreRetriever retriever, ChatModel chatModel) {
        this.retriever = retriever;
        this.chatModel = chatModel;
    }

    public String generateResponse(String userQuery) {
        // 检索相关文档
        List<Document> relevantDocs = retriever.similaritySearch(userQuery);

        // 提取文档内容作为上下文
        String context = relevantDocs.stream()
            .map(Document::getContent)
            .collect(Collectors.joining("\n\n"));

        // 基于检索上下文生成响应
        String prompt = "上下文信息：\n" + context + "\n\n用户查询：" + userQuery;
        return chatModel.generate(prompt);
    }
}该模式可实现RAG应用中检索组件与生成组件的清晰分离。元数据过滤本章节介绍可用于过滤查询结果的各类筛选方式。字符串过滤表达式可向similaritySearch重载方法传入类SQL的字符串过滤表达式。示例如下："country == 'BG'""genre == 'drama' && year >= 2020""genre in ['comedy', 'documentary', 'drama']"Filter.Expression可通过FilterExpressionBuilder的流式API创建Filter.Expression实例。简单示例如下：FilterExpressionBuilder b = new FilterExpressionBuilder();
Expression expression = this.b.eq("country", "BG").build();可使用以下运算符构建复杂表达式：等于：==、减：‑、加：+、大于：>、大于等于：>=、小于：<、小于等于：<=、不等于：!=可通过以下运算符组合表达式：与：AND/and/&&；或：OR/or/||示例：Expression exp = b.and(b.eq("genre", "drama"), b.gte("year", 2020)).build();还支持以下运算符：包含：IN/in；不包含：NIN/nin；非：NOT/not示例：Expression exp = b.and(b.in("genre", "drama", "documentary"), b.not(b.lt("year", 2020))).build();还支持以下运算符：为空：IS/is；空值：NULL/null；非空：NOT NULL/not null示例：Expression exp = b.and(b.isNull("year")).build();
Expression exp = b.and(b.isNotNull("year")).build();并非所有向量存储库均已实现IS NULL和NOT NULL功能。从向量存储库删除文档Vector Store接口提供多种文档删除方法，可根据指定文档ID或过滤表达式删除数据。根据文档ID删除最简单的删除方式为传入文档ID列表：void delete(List<String> idList);该方法删除所有ID匹配列表的文档；列表中不存在的ID会被忽略。使用示例：// 创建并添加文档
Document document = new Document("世界很大",
    Map.of("country", "Netherlands"));
vectorStore.add(List.of(document));

// 根据ID删除文档
vectorStore.delete(List.of(document.getId()));根据过滤表达式删除复杂删除条件可使用过滤表达式：void delete(Filter.Expression filterExpression);该方法接收Filter.Expression对象，定义待删除文档的筛选条件，适用于基于元数据属性删除文档的场景。使用示例：// 创建带不同元数据的测试文档
Document bgDocument = new Document("世界很大",
    Map.of("country", "Bulgaria"));
Document nlDocument = new Document("世界很大",
    Map.of("country", "Netherlands"));

// 向存储库添加文档
vectorStore.add(List.of(bgDocument, nlDocument));

// 通过过滤表达式删除保加利亚相关文档
Filter.Expression filterExpression = new Filter.Expression(
    Filter.ExpressionType.EQ,
    new Filter.Key("country"),
    new Filter.Value("Bulgaria")
);
vectorStore.delete(filterExpression);

// 检索验证删除结果
SearchRequest request = SearchRequest.builder()
    .query("世界")
    .filterExpression("country == 'Bulgaria'")
    .build();
List<Document> results = vectorStore.similaritySearch(request);
// 结果为空，保加利亚相关文档已被删除根据字符串过滤表达式删除为方便使用，也可传入字符串格式的过滤表达式删除文档：void delete(String filterExpression);该方法内部将字符串过滤条件转换为Filter.Expression对象，适用于已有字符串格式筛选条件的场景。使用示例：// 创建并添加文档
Document bgDocument = new Document("世界很大",
    Map.of("country", "Bulgaria"));
Document nlDocument = new Document("世界很大",
    Map.of("country", "Netherlands"));
vectorStore.add(List.of(bgDocument, nlDocument));

// 通过字符串过滤删除保加利亚相关文档
vectorStore.delete("country == 'Bulgaria'");

// 检索验证剩余文档
SearchRequest request = SearchRequest.builder()
    .query("世界")
    .topK(5)
    .build();
List<Document> results = vectorStore.similaritySearch(request);
// 结果仅包含荷兰相关文档删除API异常处理所有删除方法执行出错时均可能抛出异常。最佳实践为将删除操作包裹在try‑catch代码块中：try {
    vectorStore.delete("country == 'Bulgaria'");
}
catch (Exception  e) {
    logger.error("无效的过滤表达式", e);
}文档版本管理场景常见场景为文档版本管理：上传新版本文档的同时删除旧版本。可通过过滤表达式实现，示例如下：// 创建带版本元数据的初始文档（v1）
Document documentV1 = new Document(
    "人工智能与机器学习最佳实践",
    Map.of(
        "docId", "AIML-001",
        "version", "1.0",
        "lastUpdated", "2024-01-01"
    )
);

// 将v1加入向量存储库
vectorStore.add(List.of(documentV1));

// 创建同一文档的更新版本（v2）
Document documentV2 = new Document(
    "人工智能与机器学习最佳实践——更新版",
    Map.of(
        "docId", "AIML-001",
        "version", "2.0",
        "lastUpdated", "2024-02-01"
    )
);

// 先通过过滤表达式删除旧版本
Filter.Expression deleteOldVersion = new Filter.Expression(
    Filter.ExpressionType.AND,
    Arrays.asList(
        new Filter.Expression(
            Filter.ExpressionType.EQ,
            new Filter.Key("docId"),
            new Filter.Value("AIML-001")
        ),
        new Filter.Expression(
            Filter.ExpressionType.EQ,
            new Filter.Key("version"),
            new Filter.Value("1.0")
        )
    )
);
vectorStore.delete(deleteOldVersion);

// 添加新版本
vectorStore.add(List.of(documentV2));

// 验证仅存在v2版本
SearchRequest request = SearchRequest.builder()
    .query("人工智能与机器学习")
    .filterExpression("docId == 'AIML-001'")
    .build();
List<Document> results = vectorStore.similaritySearch(request);
// 结果仅包含文档v2版本也可通过字符串过滤表达式实现相同效果：// 通过字符串过滤删除旧版本
vectorStore.delete("docId == 'AIML-001' AND version == '1.0'");

// 添加新版本
vectorStore.add(List.of(documentV2));删除文档的性能考量明确待删除文档ID时，按ID列表删除通常速度更快。基于过滤条件删除可能需要扫描索引匹配文档，具体取决于向量存储库实现。大批量删除操作建议分批执行，避免系统负载过高。基于文档属性删除时，优先使用过滤表达式，而非先收集ID再删除。

Spring AI 评估测试

Wed, 20 May 2026 16:07:58 +0800

测试人工智能应用需要对生成的内容进行评估，以确保人工智能模型没有产生幻觉式的响应。

评估响应的一种方法是使用人工智能模型本身进行评估。选择最适合评估的人工智能模型，该模型可能与生成响应所用的模型不同。

Spring AI 中用于评估响应的接口是 Evaluator，其定义如下：

@FunctionalInterface
public interface Evaluator {
    EvaluationResponse evaluate(EvaluationRequest evaluationRequest);
}

评估的输入是 EvaluationRequest，其定义如下：

public class EvaluationRequest {

	private final String userText;

	private final ListdataList;

	private final String responseContent;

	public EvaluationRequest(String userText, ListdataList, String responseContent) {
		this.userText = userText;
		this.dataList = dataList;
		this.responseContent = responseContent;
	}

  ...
}

userText：用户输入的原始文本字符串
dataList：附加到原始输入的上下文数据，例如来自检索增强生成的数据
responseContent：人工智能模型生成的响应内容字符串

事实核查评估器

FactCheckingEvaluator 是 Evaluator 接口的另一个实现类，用于评估人工智能生成的响应相对于所提供上下文的事实准确性。该评估器通过验证给定陈述（主张）是否有所提供的上下文（文档）的逻辑支持，帮助检测并减少人工智能输出中的幻觉现象。

评估时会将「主张」和「文档」提供给人工智能模型。目前已有更小、更高效的专用模型用于此任务，例如 Bespoke 的 Minicheck，与 GPT-4 等旗舰模型相比，它能降低执行此类核查的成本。Minicheck 也可通过 Ollama 使用。

用法

FactCheckingEvaluator 构造方法接收一个 ChatClient.Builder 作为参数：

public FactCheckingEvaluator(ChatClient.Builder chatClientBuilder) {
  this.chatClientBuilder = chatClientBuilder;
}

该评估器使用以下提示模板进行事实核查：

Document: {document}
Claim: {claim}

其中 {document} 是上下文信息，{claim} 是待评估的人工智能模型响应。

示例

以下是如何将 FactCheckingEvaluator 与基于 Ollama 的 ChatModel（特指 Bespoke-Minicheck 模型）结合使用的示例：

@Test
void testFactChecking() {
  // 设置 Ollama API
  OllamaApi ollamaApi = new OllamaApi("http://localhost:11434");

  ChatModel chatModel = new OllamaChatModel(ollamaApi,
				OllamaChatOptions.builder().model(BESPOKE_MINICHECK).numPredict(2).temperature(0.0d).build())


  // 创建事实核查评估器
  var factCheckingEvaluator = new FactCheckingEvaluator(ChatClient.builder(chatModel));

  // 示例上下文和主张
  String context = "The Earth is the third planet from the Sun and the only astronomical object known to harbor life.";
  String claim = "The Earth is the fourth planet from the Sun.";

  // 创建评估请求
  EvaluationRequest evaluationRequest = new EvaluationRequest(context, Collections.emptyList(), claim);

  // 执行评估
  EvaluationResponse evaluationResponse = factCheckingEvaluator.evaluate(evaluationRequest);

  assertFalse(evaluationResponse.isPass(), "The claim should not be supported by the context");

}

Spring AI ETL 流水线

Wed, 20 May 2026 15:59:41 +0800

抽取、转换与加载（ETL）框架是检索增强生成（RAG）应用场景中数据处理的核心支柱。

ETL 流水线统筹管理从原始数据源到结构化向量库的数据流，确保数据以最优格式供 AI 模型检索使用。

RAG 应用场景通过从数据集中检索相关信息来增强生成式模型的能力，以此提升生成输出的质量和相关性。

API 概述

ETL 流水线负责创建、转换并存储文档实例。

Spring AI 消息 API

文档类包含文本、元数据，以及可选的图片、音频、视频等其他媒体类型。

ETL 流水线包含三大核心组件：

文档读取器，实现了 Supplier<List<Document>> 接口
文档转换器，实现了 Function<List<Document>, List<Document>> 接口
文档写入器，实现了 Consumer<List<Document>> 接口

借助文档读取器，可从 PDF、文本文件及其他文档类型中创建文档类的内容。

构建一条简单的 ETL 流水线，你可以将这三类组件的实例串联使用。

ETL 流水线

假设我们拥有以下三种 ETL 类型的实例：

分页 PDF 文档读取器：文档读取器的一种实现
令牌文本分割器：文档转换器的一种实现
向量库：文档写入器的一种实现

若要按照检索增强生成模式将数据基础加载到向量数据库中，可使用以下 Java 函数式语法代码：

vectorStore.accept(tokenTextSplitter.apply(pdfReader.get()));

你也可以使用更贴合业务领域的自然表达方法名：

vectorStore.write(tokenTextSplitter.split(pdfReader.read()));

ETL 接口

ETL 流水线由以下接口和实现类组成。详细的 ETL 类图见 ETL 类图章节。

文档读取器

从多种来源提供文档数据。

public interface DocumentReader extends Supplier<List<Document>> {

    default List<Document> read() {
		return get();
	}
}

文档转换器

作为处理工作流的一部分，批量转换文档。

public interface DocumentTransformer extends Function<List<Document>, List<Document>> {

    default List<Document> transform(List<Document> transform) {
		return apply(transform);
	}
}

文档写入器

管理 ETL 流程的最终阶段，为文档存储做准备。

public interface DocumentWriter extends Consumer<List<Document>> {

    default void write(List<Document> documents) {
		accept(documents);
	}
}

文档读取器

JSON 格式

JSON 读取器用于处理 JSON 文档，将其转换为文档对象列表。

示例

@Component
class MyJsonReader {

	private final Resource resource;

    MyJsonReader(@Value("classpath:bikes.json") Resource resource) {
        this.resource = resource;
    }

	List<Document> loadJsonAsDocuments() {
        JsonReader jsonReader = new JsonReader(this.resource, "description", "content");
        return jsonReader.get();
	}
}

构造方法选项

JSON 读取器提供多种构造方法：

JsonReader(Resource resource)
JsonReader(Resource resource, String… jsonKeysToUse)
JsonReader(Resource resource, JsonMetadataGenerator jsonMetadataGenerator, String… jsonKeysToUse)

参数

resource：指向 JSON 文件的 Spring 资源对象
jsonKeysToUse：JSON 中需作为结果文档对象文本内容的键数组
jsonMetadataGenerator：可选的 JSON 元数据生成器，用于为每个文档创建元数据

行为

JSON 读取器处理 JSON 内容的规则如下：

可同时处理 JSON 数组和单个 JSON 对象
对每个 JSON 对象（数组内或单个对象）：
根据指定的 jsonKeysToUse 提取内容
若未指定键，则使用整个 JSON 对象作为内容
通过提供的 JSON 元数据生成器生成元数据（未提供则生成空元数据）
使用提取的内容和元数据创建文档对象

使用 JSON 指针

JSON 读取器现已支持通过 JSON 指针获取 JSON 文档的指定部分。该功能可轻松从复杂 JSON 结构中提取嵌套数据。

get(String pointer) 方法

public List<Document> get(String pointer)

该方法允许使用 JSON 指针获取 JSON 文档的指定部分。

参数

pointer：符合 RFC 6901 规范的 JSON 指针字符串，用于定位 JSON 结构中的目标元素

返回值

返回由 JSON 指针定位元素解析得到的文档列表。

行为

该方法通过传入的 JSON 指针导航至 JSON 结构的指定位置
若指针有效且指向存在的元素：
JSON 对象：返回包含单个文档的列表
JSON 数组：返回与数组元素一一对应的文档列表
若指针无效或指向不存在的元素，抛出非法参数异常

示例

JsonReader jsonReader = new JsonReader(resource, "description");
List<Document> documents = this.jsonReader.get("/store/books/0");

示例 JSON 结构

[
  {
    "id": 1,
    "brand": "Trek",
    "description": "A high-performance mountain bike for trail riding."
  },
  {
    "id": 2,
    "brand": "Cannondale",
    "description": "An aerodynamic road bike for racing enthusiasts."
  }
]

本示例中，若 JSON 读取器配置 "description" 为 jsonKeysToUse，会为数组中每辆自行车创建文档对象，内容为 "description" 字段的值。

注意事项

JSON 读取器基于 Jackson 解析 JSON
通过流式处理数组，可高效处理大型 JSON 文件
若 jsonKeysToUse 指定多个键，内容为这些键对应值的拼接结果
通过自定义 jsonKeysToUse 和 JSON 元数据生成器，可适配多种 JSON 结构

纯文本格式

文本读取器用于处理纯文本文档，将其转换为文档对象列表。

示例

@Component
class MyTextReader {

    private final Resource resource;

    MyTextReader(@Value("classpath:text-source.txt") Resource resource) {
        this.resource = resource;
    }

	List<Document> loadText() {
		TextReader textReader = new TextReader(this.resource);
		textReader.getCustomMetadata().put("filename", "text-source.txt");

		return textReader.read();
    }
}

构造方法选项

文本读取器提供两种构造方法：

TextReader(String resourceUrl)
TextReader(Resource resource)

参数

resourceUrl：表示待读取资源 URL 的字符串
resource：指向文本文件的 Spring 资源对象

配置

setCharset(Charset charset)：设置读取文本文件的字符集，默认为 UTF-8
getCustomMetadata()：返回可变映射，可添加文档的自定义元数据

行为

文本读取器处理文本内容的规则如下：

将文本文件全部内容读取到单个文档对象中
文件内容作为文档的内容
自动为文档添加元数据：
charset：读取文件使用的字符集（默认：UTF-8）
source：源文本文件的文件名
通过 getCustomMetadata() 添加的自定义元数据也会包含在文档中

注意事项

文本读取器会将文件全部内容加载到内存，不适合超大文件
若需将文本分割为更小片段，读取文档后可使用令牌文本分割器：

List<Document> documents = textReader.get();
List<Document> splitDocuments = new TokenTextSplitter().apply(this.documents);

读取器基于 Spring 资源抽象，可读取多种来源（类路径、文件系统、URL 等）
可通过 getCustomMetadata() 方法为读取器创建的所有文档添加自定义元数据

HTML 格式（基于 JSoup）

JSoup 文档读取器基于 JSoup 库处理 HTML 文档，将其转换为文档对象列表。

依赖

使用 Maven 或 Gradle 为项目添加依赖。

Maven

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-jsoup-document-reader</artifactId>
</dependency>

示例

@Component
class MyHtmlReader {

    private final Resource resource;

    MyHtmlReader(@Value("classpath:/my-page.html") Resource resource) {
        this.resource = resource;
    }

    List<Document> loadHtml() {
        JsoupDocumentReaderConfig config = JsoupDocumentReaderConfig.builder()
            .selector("article p") // 提取 article 标签内的段落
            .charset("ISO-8859-1")  // 使用 ISO-8859-1 编码
            .includeLinkUrls(true) // 在元数据中包含链接 URL
            .metadataTags(List.of("author", "date")) // 提取作者和日期元标签
            .additionalMetadata("source", "my-page.html") // 添加自定义元数据
            .build();

        JsoupDocumentReader reader = new JsoupDocumentReader(this.resource, config);
        return reader.get();
    }
}

JSoup 文档读取器配置可自定义读取器行为：

charset：指定 HTML 文档的字符编码，默认 UTF-8
selector：JSoup CSS 选择器，指定提取文本的元素，默认 body
separator：拼接多个选中元素文本的字符串，默认换行符
allElements：若为 true，提取 body 内所有文本，忽略选择器，默认 false
groupByElement：若为 true，选择器匹配的每个元素创建独立文档，默认 false
includeLinkUrls：若为 true，提取绝对链接 URL 并加入元数据，默认 false
metadataTags：需提取内容的 meta 标签列表，默认 ["description", "keywords"]
additionalMetadata：为所有创建的文档对象添加自定义元数据

示例文档：my-page.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>My Web Page</title>
    <meta name="description" content="A sample web page for Spring AI">
    <meta name="keywords" content="spring, ai, html, example">
    <meta name="author" content="John Doe">
    <meta name="date" content="2024-01-15">
    <link rel="stylesheet" href="style.css">
</head>
<body>
    <header>
        <h1>Welcome to My Page</h1>
    </header>
    <nav>
        <ul>
            <li><a href="/">Home</a></li>
            <li><a href="/about">About</a></li>
        </ul>
    </nav>
    <article>
        <h2>Main Content</h2>
        <p>This is the main content of my web page.</p>
        <p>It contains multiple paragraphs.</p>
        <a href="https://www.example.com">External Link</a>
    </article>
    <footer>
        <p>&copy; 2024 John Doe</p>
    </footer>
</body>
</html>

行为

JSoup 文档读取器处理 HTML 内容并根据配置创建文档对象：

选择器决定提取文本的元素
若 allElements 为 true，body 内所有文本提取到单个文档
若 groupByElement 为 true，选择器匹配的每个元素创建独立文档
若两者均为 false，选择器匹配的所有元素文本通过分隔符拼接
文档标题、指定 meta 标签内容、（可选）链接 URL 加入文档元数据
解析相对链接的基础 URI 从 URL 资源中提取
读取器保留选中元素的文本内容，移除内部 HTML 标签

Markdown 格式

Markdown 文档读取器用于处理 Markdown 文档，将其转换为文档对象列表。

依赖

使用 Maven 或 Gradle 为项目添加依赖。

Maven

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-markdown-document-reader</artifactId>
</dependency>

示例

@Component
class MyMarkdownReader {

    private final Resource resource;

    MyMarkdownReader(@Value("classpath:code.md") Resource resource) {
        this.resource = resource;
    }

    List<Document> loadMarkdown() {
        MarkdownDocumentReaderConfig config = MarkdownDocumentReaderConfig.builder()
            .withHorizontalRuleCreateDocument(true)
            .withIncludeCodeBlock(false)
            .withIncludeBlockquote(false)
            .withAdditionalMetadata("filename", "code.md")
            .build();

        MarkdownDocumentReader reader = new MarkdownDocumentReader(this.resource, config);
        return reader.get();
    }
}

Markdown 文档读取器配置可自定义读取器行为：

horizontalRuleCreateDocument：为 true 时，Markdown 中的水平分隔线创建新文档对象
includeCodeBlock：为 true 时，代码块与周围文本包含在同一文档；为 false 时，代码块创建独立文档
includeBlockquote：为 true 时，引用块与周围文本包含在同一文档；为 false 时，引用块创建独立文档
additionalMetadata：为所有创建的文档对象添加自定义元数据

示例文档：code.md

This is a Java sample application:

```java
package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}
```

Markdown also provides the possibility to `use inline code formatting throughout` the entire sentence.

---

Another possibility is to set block code without specific highlighting:

```
./mvnw spring-javaformat:apply
```

行为

Markdown 文档读取器处理 Markdown 内容并根据配置创建文档对象：

标题转为文档对象的元数据
段落转为文档对象的内容
代码块可分离为独立文档或与周围文本合并
引用块可分离为独立文档或与周围文本合并
水平分隔线可将内容分割为独立文档
读取器保留文档内容中的行内代码、列表、文本样式等格式

PDF 分页格式

分页 PDF 文档读取器基于 Apache PdfBox 库解析 PDF 文档。

依赖

使用 Maven 或 Gradle 为项目添加依赖。

Maven

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-pdf-document-reader</artifactId>
</dependency>

示例

@Component
public class MyPagePdfDocumentReader {

	List<Document> getDocsFromPdf() {

		PagePdfDocumentReader pdfReader = new PagePdfDocumentReader("classpath:/sample1.pdf",
				PdfDocumentReaderConfig.builder()
					.withPageTopMargin(0)
					.withPageExtractedTextFormatter(ExtractedTextFormatter.builder()
						.withNumberOfTopTextLinesToDelete(0)
						.build())
					.withPagesPerDocument(1)
					.build());

		return pdfReader.read();
    }

}

PDF 段落格式

段落 PDF 文档读取器利用 PDF 目录（如目录）信息将输入 PDF 分割为文本段落，每个段落输出一个文档。注意：并非所有 PDF 文档都包含目录。

依赖

使用 Maven 或 Gradle 为项目添加依赖。

Maven

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-pdf-document-reader</artifactId>
</dependency>

示例

@Component
public class MyPagePdfDocumentReader {

	List<Document> getDocsFromPdfWithCatalog() {

        ParagraphPdfDocumentReader pdfReader = new ParagraphPdfDocumentReader("classpath:/sample1.pdf",
                PdfDocumentReaderConfig.builder()
                    .withPageTopMargin(0)
                    .withPageExtractedTextFormatter(ExtractedTextFormatter.builder()
                        .withNumberOfTopTextLinesToDelete(0)
                        .build())
                    .withPagesPerDocument(1)
                    .build());

	    return pdfReader.read();
    }
}

Tika 格式（DOCX、PPTX、HTML 等）

Tika 文档读取器基于 Apache Tika 从多种文档格式提取文本，包括 PDF、DOC/DOCX、PPT/PPTX、HTML 等。完整支持格式列表参考 Tika 官方文档。

依赖

使用 Maven 或 Gradle 为项目添加依赖。

Maven

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-tika-document-reader</artifactId>
</dependency>

示例

@Component
class MyTikaDocumentReader {

    private final Resource resource;

    MyTikaDocumentReader(@Value("classpath:/word-sample.docx")
                            Resource resource) {
        this.resource = resource;
    }

    List<Document> loadText() {
        TikaDocumentReader tikaDocumentReader = new TikaDocumentReader(this.resource);
        return tikaDocumentReader.read();
    }
}

转换器

文本分割器

文本分割器是抽象基类，用于分割文档以适配 AI 模型的上下文窗口。

令牌文本分割器

令牌文本分割器是文本分割器的实现类，基于令牌数量分割文本，使用 CL100K_BASE 编码。

用法

基础用法

@Component
class MyTokenTextSplitter {

    public List<Document> splitDocuments(List<Document> documents) {
        TokenTextSplitter splitter = new TokenTextSplitter();
        return splitter.apply(documents);
    }

    public List<Document> splitCustomized(List<Document> documents) {
        TokenTextSplitter splitter = new TokenTextSplitter(1000, 400, 10, 5000, true, List.of('.', '?', '!', '\n'));
        return splitter.apply(documents);
    }
}

使用建造者模式

推荐使用建造者模式创建令牌文本分割器，API 更易读、更灵活：

@Component
class MyTokenTextSplitter {

    public List<Document> splitWithBuilder(List<Document> documents) {
        TokenTextSplitter splitter = TokenTextSplitter.builder()
            .withChunkSize(1000)
            .withMinChunkSizeChars(400)
            .withMinChunkLengthToEmbed(10)
            .withMaxNumChunks(5000)
            .withKeepSeparator(true)
            .build();

        return splitter.apply(documents);
    }
}

自定义标点符号

可自定义用于将文本分割为语义片段的标点符号，对国际化场景尤为实用：

@Component
class MyInternationalTextSplitter {

    public List<Document> splitChineseText(List<Document> documents) {
        // 使用中文标点符号
        TokenTextSplitter splitter = TokenTextSplitter.builder()
            .withChunkSize(800)
            .withMinChunkSizeChars(350)
            .withPunctuationMarks(List.of('。', '？', '！', '；'))  // 中文标点
            .build();

        return splitter.apply(documents);
    }

    public List<Document> splitWithCustomMarks(List<Document> documents) {
        // 中英文标点混合
        TokenTextSplitter splitter = TokenTextSplitter.builder()
            .withChunkSize(800)
            .withPunctuationMarks(List.of('.', '?', '!', '\n', ';', ':', '。'))
            .build();

        return splitter.apply(documents);
    }
}

构造方法选项

令牌文本分割器提供三种构造方法：

TokenTextSplitter()：使用默认配置创建分割器
TokenTextSplitter(boolean keepSeparator)：自定义分隔符行为创建分割器
TokenTextSplitter(int chunkSize, int minChunkSizeChars, int minChunkLengthToEmbed, int maxNumChunks, boolean keepSeparator, List<Character> punctuationMarks)：全参数自定义构造方法

推荐使用建造者模式创建自定义配置的实例。

参数

chunkSize：每个文本片段的目标令牌大小，默认 800
minChunkSizeChars：每个文本片段的最小字符数，默认 350
minChunkLengthToEmbed：需纳入的片段最小长度，默认 5
maxNumChunks：单段文本生成的最大片段数，默认 10000
keepSeparator：是否在片段中保留分隔符（如换行符），默认 true
punctuationMarks：用于句子边界分割的字符列表，默认 . ? ! 换行符

行为

令牌文本分割器处理文本内容的规则如下：

通过 CL100K_BASE 编码将输入文本转为令牌
根据 chunkSize 将编码后的文本分割为片段
对每个片段：
将片段解码为文本
仅当总令牌数超过 chunkSize 时，在 minChunkSizeChars 后通过配置的标点符号寻找合适分割点
找到分割点则在该位置截断片段
修剪片段，并根据 keepSeparator 设置可选移除换行符
若结果片段长度大于 minChunkLengthToEmbed，加入输出列表
重复流程直至所有令牌处理完成或达到 maxNumChunks
剩余文本长度大于 minChunkLengthToEmbed 时，作为最终片段加入

仅当令牌数超过片段大小时，才基于标点分割。大小等于或小于片段大小的文本直接作为单个片段返回，避免小文本无意义分割。

示例

Document doc1 = new Document("This is a long piece of text that needs to be split into smaller chunks for processing.",
        Map.of("source", "example.txt"));
Document doc2 = new Document("Another document with content that will be split based on token count.",
        Map.of("source", "example2.txt"));

TokenTextSplitter splitter = new TokenTextSplitter();
List<Document> splitDocuments = this.splitter.apply(List.of(this.doc1, this.doc2));

for (Document doc : splitDocuments) {
    System.out.println("Chunk: " + doc.getContent());
    System.out.println("Metadata: " + doc.getMetadata());
}

注意事项

令牌文本分割器使用 jtokkit 库的 CL100K_BASE 编码，兼容新版 OpenAI 模型
分割器尽可能在句子边界分割，创建语义完整的片段
原文档的元数据会保留并复制到所有派生片段
若 copyContentFormatter 设为 true（默认行为），原文档的内容格式化器会复制到派生片段
该分割器适合为有令牌限制的大语言模型准备文本，确保片段在模型处理能力范围内
自定义标点符号：默认标点适配英文文本，其他语言或专业内容可通过建造者的 withPunctuationMarks 方法自定义
性能考量：分割器可处理任意数量标点，但为优化性能，建议列表长度控制在 20 个字符以内
可扩展性：getLastPunctuationIndex 方法为保护类型，子类可重写标点检测逻辑适配特殊场景
小文本处理：2.0 版本起，令牌数小于等于片段大小的小文本不再按标点分割，避免符合大小限制的内容无意义碎片化

内容格式转换器

确保所有文档的内容格式统一。

关键词元数据增强器

关键词元数据增强器是一种文档转换器，使用生成式 AI 模型从文档内容提取关键词并作为元数据添加。

用法

@Component
class MyKeywordEnricher {

    private final ChatModel chatModel;

    MyKeywordEnricher(ChatModel chatModel) {
        this.chatModel = chatModel;
    }

    List<Document> enrichDocuments(List<Document> documents) {
        KeywordMetadataEnricher enricher = KeywordMetadataEnricher.builder(chatModel)
                .keywordCount(5)
                .build();

        // 或使用自定义模板
        KeywordMetadataEnricher enricher = KeywordMetadataEnricher.builder(chatModel)
               .keywordsTemplate(YOUR_CUSTOM_TEMPLATE)
               .build();

        return enricher.apply(documents);
    }
}

构造方法选项

关键词元数据增强器提供两种构造方法：

KeywordMetadataEnricher(ChatModel chatModel, int keywordCount)：使用默认模板提取指定数量关键词
KeywordMetadataEnricher(ChatModel chatModel, PromptTemplate keywordsTemplate)：使用自定义模板提取关键词

行为

关键词元数据增强器处理文档的规则如下：

为每个输入文档基于内容创建提示词
将提示词发送给指定的对话模型生成关键词
生成的关键词以 "excerpt_keywords" 为键加入文档元数据
返回增强后的文档

自定义

可使用默认模板或通过 keywordsTemplate 参数自定义模板。默认模板：

{context_str}. Give %s unique keywords for this document. Format as comma separated. Keywords:

其中 {context_str} 替换为文档内容，%s 替换为指定的关键词数量。

示例

ChatModel chatModel = // 初始化对话模型
KeywordMetadataEnricher enricher = KeywordMetadataEnricher.builder(chatModel)
                .keywordCount(5)
                .build();

// 或使用自定义模板
KeywordMetadataEnricher enricher = KeywordMetadataEnricher.builder(chatModel)
                .keywordsTemplate(new PromptTemplate("Extract 5 important keywords from the following text and separate them with commas:\n{context_str}"))
                .build();

Document doc = new Document("This is a document about artificial intelligence and its applications in modern technology.");

List<Document> enrichedDocs = enricher.apply(List.of(this.doc));

Document enrichedDoc = this.enrichedDocs.get(0);
String keywords = (String) this.enrichedDoc.getMetadata().get("excerpt_keywords");
System.out.println("Extracted keywords: " + keywords);

注意事项

关键词元数据增强器需要可用的对话模型生成关键词
关键词数量必须大于等于 1
增强器为每个处理后的文档添加 "excerpt_keywords" 元数据字段
生成的关键词以逗号分隔字符串返回
该增强器可提升文档检索性，用于生成文档标签或分类
建造者模式中，若设置 keywordsTemplate 参数，keywordCount 参数会被忽略

摘要元数据增强器

摘要元数据增强器是一种文档转换器，使用生成式 AI 模型为文档生成摘要并作为元数据添加。可生成当前文档及相邻文档（上一个、下一个）的摘要。

用法

@Configuration
class EnricherConfig {

    @Bean
    public SummaryMetadataEnricher summaryMetadata(OpenAiChatModel aiClient) {
        return new SummaryMetadataEnricher(aiClient,
            List.of(SummaryType.PREVIOUS, SummaryType.CURRENT, SummaryType.NEXT));
    }
}

@Component
class MySummaryEnricher {

    private final SummaryMetadataEnricher enricher;

    MySummaryEnricher(SummaryMetadataEnricher enricher) {
        this.enricher = enricher;
    }

    List<Document> enrichDocuments(List<Document> documents) {
        return this.enricher.apply(documents);
    }
}

构造方法

摘要元数据增强器提供两种构造方法：

SummaryMetadataEnricher(ChatModel chatModel, List<SummaryType> summaryTypes)
SummaryMetadataEnricher(ChatModel chatModel, List<SummaryType> summaryTypes, String summaryTemplate, MetadataMode metadataMode)

参数

chatModel：用于生成摘要的 AI 模型
summaryTypes：摘要类型枚举列表，指定生成哪些摘要（上一个、当前、下一个）
summaryTemplate：摘要生成自定义模板（可选）
metadataMode：生成摘要时处理文档元数据的方式（可选）

行为

摘要元数据增强器处理文档的规则如下：

为每个输入文档基于内容和指定摘要模板创建提示词
将提示词发送给指定的对话模型生成摘要
根据指定的 summaryTypes，为每个文档添加以下元数据：
section_summary：当前文档摘要
prev_section_summary：上一个文档摘要（可用且请求时）
next_section_summary：下一个文档摘要（可用且请求时）
返回增强后的文档

自定义

可通过提供自定义 summaryTemplate 定制摘要生成提示词。默认模板：

"""
Here is the content of the section:
{context_str}

Summarize the key topics and entities of the section.

Summary:
"""

示例

ChatModel chatModel = // 初始化对话模型
SummaryMetadataEnricher enricher = new SummaryMetadataEnricher(chatModel,
    List.of(SummaryType.PREVIOUS, SummaryType.CURRENT, SummaryType.NEXT));

Document doc1 = new Document("Content of document 1");
Document doc2 = new Document("Content of document 2");

List<Document> enrichedDocs = enricher.apply(List.of(this.doc1, this.doc2));

// 检查增强后文档的元数据
for (Document doc : enrichedDocs) {
    System.out.println("Current summary: " + doc.getMetadata().get("section_summary"));
    System.out.println("Previous summary: " + doc.getMetadata().get("prev_section_summary"));
    System.out.println("Next summary: " + doc.getMetadata().get("next_section_summary"));
}

示例展示预期行为：

两个文档的列表中，两个文档均获得 section_summary
第一个文档获得 next_section_summary，无 prev_section_summary
第二个文档获得 prev_section_summary，无 next_section_summary
第一个文档的 section_summary 与第二个文档的 prev_section_summary 一致
第一个文档的 next_section_summary 与第二个文档的 section_summary 一致

注意事项

摘要元数据增强器需要可用的对话模型生成摘要
增强器可处理任意长度的文档列表，正确处理首尾文档的边界情况
该增强器适合创建上下文感知摘要，更好理解序列中文档的关联关系
MetadataMode 参数可控制现有元数据如何纳入摘要生成流程

写入器

文件写入

文件文档写入器是文档写入器的实现类，将文档列表内容写入文件。

用法

@Component
class MyDocumentWriter {

    public void writeDocuments(List<Document> documents) {
        FileDocumentWriter writer = new FileDocumentWriter("output.txt", true, MetadataMode.ALL, false);
        writer.accept(documents);
    }
}

构造方法

文件文档写入器提供三种构造方法：

FileDocumentWriter(String fileName)
FileDocumentWriter(String fileName, boolean withDocumentMarkers)
FileDocumentWriter(String fileName, boolean withDocumentMarkers, MetadataMode metadataMode, boolean append)

参数

fileName：写入文档的目标文件名
withDocumentMarkers：是否在输出中包含文档标记，默认 false
metadataMode：指定写入文件的文档内容，默认 MetadataMode.NONE
append：为 true 时数据追加到文件末尾，否则覆盖开头，默认 false

行为

文件文档写入器处理文档的规则如下：

为指定文件名打开文件写入器
对输入列表中的每个文档：
若 withDocumentMarkers 为 true，写入包含文档索引和页码的文档标记
根据指定的 metadataMode 写入格式化后的文档内容
所有文档写入完成后关闭文件

文档标记

withDocumentMarkers 设为 true 时，写入器为每个文档添加以下格式标记：

### Doc: [index], pages:[start_page_number,end_page_number]

元数据处理

写入器使用两个特定元数据键：

page_number：文档的起始页码
end_page_number：文档的结束页码

写入文档标记时使用这两个键。

示例

List<Document> documents = // 初始化文档
FileDocumentWriter writer = new FileDocumentWriter("output.txt", true, MetadataMode.ALL, true);
writer.accept(documents);

该代码将所有文档写入 output.txt，包含文档标记、所有元数据，文件已存在时追加内容。

注意事项

写入器使用文件写入器，以操作系统默认字符编码写入文本文件
写入过程出错时，抛出运行时异常并封装原始异常
metadataMode 参数可控制现有元数据如何纳入写入内容
该写入器适合调试或创建文档集合的人类可读输出

向量库

提供与多种向量库的集成。完整列表参考向量数据库文档。

Spring AI 检索增强生成（RAG）

Mon, 18 May 2026 14:06:46 +0800

检索增强生成（RAG）是一项用于克服大语言模型局限性的技术，大语言模型在长文本内容生成、事实准确性和上下文感知方面存在短板。

Spring AI 通过提供模块化架构支持 RAG 技术，你可以自行构建自定义的 RAG 流程，也可以使用 Advisor API 开箱即用的 RAG 流程。

在概念章节中了解更多关于检索增强生成的信息。

顾问（Advisors）

Spring AI 通过 Advisor API 为常用的 RAG 流程提供开箱即用的支持。

若要使用 QuestionAnswerAdvisor 或 VectorStoreChatMemoryAdvisor，你需要在项目中添加 spring-ai-advisors-vector-store 依赖：

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

QuestionAnswerAdvisor

向量数据库用于存储 AI 模型未知的数据。当用户向 AI 模型发送问题时，QuestionAnswerAdvisor 会向向量数据库查询与用户问题相关的文档。

向量数据库返回的结果会追加到用户输入文本中，为 AI 模型生成回答提供上下文信息。

假设你已经将数据加载到 VectorStore 中，可通过为 ChatClient 提供 QuestionAnswerAdvisor 实例来实现检索增强生成（RAG）。

ChatResponse response = ChatClient.builder(chatModel)
        .build().prompt()
        .advisors(QuestionAnswerAdvisor.builder(vectorStore).build())
        .user(userText)
        .call()
        .chatResponse();

在本示例中，QuestionAnswerAdvisor 会对向量数据库中的所有文档执行相似度搜索。若要限制搜索的文档类型，SearchRequest 支持类 SQL 的过滤表达式，该表达式可在所有 VectorStore 中通用。

该过滤表达式可在创建 QuestionAnswerAdvisor 时配置（将应用于所有 ChatClient 请求），也可在每次请求运行时动态指定。

以下是创建相似度阈值为 0.8、返回前 6 条结果的 QuestionAnswerAdvisor 实例的方法：

var qaAdvisor = QuestionAnswerAdvisor.builder(vectorStore)
        .searchRequest(SearchRequest.builder().similarityThreshold(0.8d).topK(6).build())
        .build();

动态过滤表达式

通过 FILTER_EXPRESSION 顾问上下文参数，在运行时更新 SearchRequest 过滤表达式：

ChatClient chatClient = ChatClient.builder(chatModel)
    .defaultAdvisors(QuestionAnswerAdvisor.builder(vectorStore)
        .searchRequest(SearchRequest.builder().build())
        .build())
    .build();

// 在运行时更新过滤表达式
String content = this.chatClient.prompt()
    .user("Please answer my question XYZ")
    .advisors(a -> a.param(QuestionAnswerAdvisor.FILTER_EXPRESSION, "type == 'Spring'"))
    .call()
    .content();

FILTER_EXPRESSION 参数允许你根据指定的表达式动态过滤搜索结果。

自定义模板

QuestionAnswerAdvisor 使用默认模板将检索到的文档与用户问题结合。你可以通过构建器方法 .promptTemplate() 提供自定义的 PromptTemplate 对象来修改这一行为。

此处提供的 PromptTemplate 用于自定义顾问将检索到的上下文与用户查询结合的方式。这与在 ChatClient 自身（使用 .templateRenderer()）上配置 TemplateRenderer 不同，后者会在顾问运行前影响初始用户/系统提示内容的渲染。有关客户端级模板渲染的更多详情，请参阅 ChatClient 提示模板。

自定义 PromptTemplate 可使用任意 TemplateRenderer 实现（默认使用基于 StringTemplate 引擎的 StPromptTemplate）。核心要求是模板必须包含以下两个占位符：

query 占位符：用于接收用户问题
question_answer_context 占位符：用于接收检索到的上下文

PromptTemplate customPromptTemplate = PromptTemplate.builder()
    .renderer(StPromptRenderer.builder().startDelimiterToken('<').endDelimiterToken('>').build())
    .template("""
            <query>

            Context information is below.

			---------------------
			<question_answer_context>
			---------------------

			Given the context information and no prior knowledge, answer the query.

			Follow these rules:

			1. If the answer is not in the context, just say that you don't know.
			2. Avoid statements like "Based on the context..." or "The provided information...".
            """)
    .build();

    String question = "Where does the adventure of Anacletus and Birba take place?";

    QuestionAnswerAdvisor qaAdvisor = QuestionAnswerAdvisor.builder(vectorStore)
        .promptTemplate(customPromptTemplate)
        .build();

    String response = ChatClient.builder(chatModel).build()
        .prompt(question)
        .advisors(qaAdvisor)
        .call()
        .content();

QuestionAnswerAdvisor.Builder.userTextAdvise() 方法已被弃用，推荐使用 .promptTemplate() 实现更灵活的自定义配置。

RetrievalAugmentationAdvisor

Spring AI 包含一套 RAG 模块库，你可用于构建自定义的 RAG 流程。RetrievalAugmentationAdvisor 是基于模块化架构、为最常用的 RAG 流程提供开箱即用实现的顾问组件。

若要使用 RetrievalAugmentationAdvisor，你需要在项目中添加 spring-ai-rag 依赖：

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

顺序式 RAG 流程

基础 RAG

Advisor retrievalAugmentationAdvisor = RetrievalAugmentationAdvisor.builder()
        .documentRetriever(VectorStoreDocumentRetriever.builder()
                .similarityThreshold(0.50)
                .vectorStore(vectorStore)
                .build())
        .build();

String answer = chatClient.prompt()
        .advisors(retrievalAugmentationAdvisor)
        .user(question)
        .call()
        .content();

默认情况下，RetrievalAugmentationAdvisor 不允许检索到的上下文为空。若上下文为空，组件会指示模型不回答用户查询。你可以按以下方式允许空上下文：

Advisor retrievalAugmentationAdvisor = RetrievalAugmentationAdvisor.builder()
        .documentRetriever(VectorStoreDocumentRetriever.builder()
                .similarityThreshold(0.50)
                .vectorStore(vectorStore)
                .build())
        .queryAugmenter(ContextualQueryAugmenter.builder()
                .allowEmptyContext(true)
                .build())
        .build();

String answer = chatClient.prompt()
        .advisors(retrievalAugmentationAdvisor)
        .user(question)
        .call()
        .content();

VectorStoreDocumentRetriever 支持通过 FilterExpression 根据元数据过滤搜索结果。你可以在实例化 VectorStoreDocumentRetriever 时指定过滤条件，也可以在每次请求运行时通过 FILTER_EXPRESSION 顾问上下文参数动态指定。

Advisor retrievalAugmentationAdvisor = RetrievalAugmentationAdvisor.builder()
        .documentRetriever(VectorStoreDocumentRetriever.builder()
                .similarityThreshold(0.50)
                .vectorStore(vectorStore)
                .build())
        .build();

String answer = chatClient.prompt()
        .advisors(retrievalAugmentationAdvisor)
        .advisors(a -> a.param(VectorStoreDocumentRetriever.FILTER_EXPRESSION, "type == 'Spring'"))
        .user(question)
        .call()
        .content();

更多信息请参阅 VectorStoreDocumentRetriever。

高级 RAG

Advisor retrievalAugmentationAdvisor = RetrievalAugmentationAdvisor.builder()
        .queryTransformers(RewriteQueryTransformer.builder()
                .chatClientBuilder(chatClientBuilder.build().mutate())
                .build())
        .documentRetriever(VectorStoreDocumentRetriever.builder()
                .similarityThreshold(0.50)
                .vectorStore(vectorStore)
                .build())
        .build();

String answer = chatClient.prompt()
        .advisors(retrievalAugmentationAdvisor)
        .user(question)
        .call()
        .content();

你还可以使用 DocumentPostProcessor API 在将检索到的文档传递给模型之前进行后处理。例如，你可以通过该接口根据文档与查询的相关性对文档进行重排序、移除无关或冗余的文档，或压缩每个文档的内容以减少噪声和冗余信息。

模块

Spring AI 实现了模块化 RAG 架构，其设计灵感来源于论文《模块化 RAG：将 RAG 系统转变为乐高式可重构框架》中详述的模块化概念。

检索前处理（Pre-Retrieval）

检索前处理模块负责处理用户查询，以获取最优的检索结果。

查询转换

用于转换输入查询的组件，使查询更适用于检索任务，解决查询语句不规范、术语模糊、词汇复杂或语言不支持等问题。

使用 QueryTransformer 时，建议为 ChatClient.Builder 配置低温度值（例如 0.0），以确保结果更具确定性和准确性，提升检索质量。大多数对话模型的默认温度值通常过高，无法实现最优的查询转换效果，会降低检索效率。

CompressionQueryTransformer

CompressionQueryTransformer 使用大语言模型将对话历史和后续查询压缩为一个独立查询，保留对话的核心信息。

当对话历史较长且后续查询与对话上下文相关时，该转换器非常实用。

Query query = Query.builder()
        .text("And what is its second largest city?")
        .history(new UserMessage("What is the capital of Denmark?"),
                new AssistantMessage("Copenhagen is the capital of Denmark."))
        .build();

QueryTransformer queryTransformer = CompressionQueryTransformer.builder()
        .chatClientBuilder(chatClientBuilder)
        .build();

Query transformedQuery = queryTransformer.transform(query);

该组件使用的提示词可通过构建器中的 promptTemplate() 方法自定义。

RewriteQueryTransformer

RewriteQueryTransformer 使用大语言模型重写用户查询，以在向目标系统（如向量库或网络搜索引擎）查询时获得更优结果。

当用户查询冗长、模糊或包含可能影响搜索结果质量的无关信息时，该转换器非常实用。

Query query = new Query("I'm studying machine learning. What is an LLM?");

QueryTransformer queryTransformer = RewriteQueryTransformer.builder()
        .chatClientBuilder(chatClientBuilder)
        .build();

Query transformedQuery = queryTransformer.transform(query);

该组件使用的提示词可通过构建器中的 promptTemplate() 方法自定义。

TranslationQueryTransformer

TranslationQueryTransformer 使用大语言模型将查询翻译为文档嵌入模型支持的目标语言。如果查询已为目标语言，则直接返回；如果查询语言未知，也直接返回。

当嵌入模型基于特定语言训练，而用户查询为其他语言时，该转换器非常实用。

Query query = new Query("Hvad er Danmarks hovedstad?");

QueryTransformer queryTransformer = TranslationQueryTransformer.builder()
        .chatClientBuilder(chatClientBuilder)
        .targetLanguage("english")
        .build();

Query transformedQuery = queryTransformer.transform(query);

该组件使用的提示词可通过构建器中的 promptTemplate() 方法自定义。

查询扩展

用于将输入查询扩展为多个查询的组件，通过提供替代查询语句或将复杂问题拆解为简单子查询，解决查询语句不规范等问题。

MultiQueryExpander

MultiQueryExpander 使用大语言模型将一个查询扩展为多个语义不同的变体，覆盖不同视角，有助于检索更多上下文信息，提升获取相关结果的概率。

MultiQueryExpander queryExpander = MultiQueryExpander.builder()
    .chatClientBuilder(chatClientBuilder)
    .numberOfQueries(3)
    .build();
List<Query> queries = queryExpander.expand(new Query("How to run a Spring Boot app?"));

默认情况下，MultiQueryExpander 会将原始查询包含在扩展查询列表中。你可以通过构建器中的 includeOriginal 方法禁用该行为。

MultiQueryExpander queryExpander = MultiQueryExpander.builder()
    .chatClientBuilder(chatClientBuilder)
    .includeOriginal(false)
    .build();

该组件使用的提示词可通过构建器中的 promptTemplate() 方法自定义。

检索（Retrieval）

检索模块负责查询向量库等数据系统，检索最相关的文档。

文档搜索

负责从底层数据源（如搜索引擎、向量库、数据库或知识图谱）检索文档的组件。

VectorStoreDocumentRetriever

VectorStoreDocumentRetriever 从向量库中检索与输入查询语义相似的文档。它支持基于元数据过滤、相似度阈值和 Top-K 结果筛选。

DocumentRetriever retriever = VectorStoreDocumentRetriever.builder()
    .vectorStore(vectorStore)
    .similarityThreshold(0.73)
    .topK(5)
    .filterExpression(new FilterExpressionBuilder()
        .eq("genre", "fairytale")
        .build())
    .build();
List<Document> documents = retriever.retrieve(new Query("What is the main character of the story?"));

过滤表达式可以是静态或动态的。对于动态过滤表达式，你可以传入一个 Supplier。

DocumentRetriever retriever = VectorStoreDocumentRetriever.builder()
    .vectorStore(vectorStore)
    .filterExpression(() -> new FilterExpressionBuilder()
        .eq("tenant", TenantContextHolder.getTenantIdentifier())
        .build())
    .build();
List<Document> documents = retriever.retrieve(new Query("What are the KPIs for the next semester?"));

你还可以通过 Query API 使用 FILTER_EXPRESSION 参数提供请求级别的过滤表达式。如果同时指定了请求级别和检索器级别的过滤表达式，请求级别的优先级更高。

Query query = Query.builder()
    .text("Who is Anacletus?")
    .context(Map.of(VectorStoreDocumentRetriever.FILTER_EXPRESSION, "location == 'Whispering Woods'"))
    .build();
List<Document> retrievedDocuments = documentRetriever.retrieve(query);

文档合并

用于将基于多个查询、从多个数据源检索到的文档合并为单个文档集合的组件。在合并过程中，该组件还可处理重复文档和互相关排序策略。

ConcatenationDocumentJoiner

ConcatenationDocumentJoiner 通过拼接的方式，将基于多个查询、从多个数据源检索到的文档合并为单个文档集合。如果存在重复文档，保留首次出现的文档，每个文档的分数保持不变。

Map<Query, List<List<Document>>> documentsForQuery = ...
DocumentJoiner documentJoiner = new ConcatenationDocumentJoiner();
List<Document> documents = documentJoiner.join(documentsForQuery);

检索后处理（Post-Retrieval）

检索后处理模块负责处理检索到的文档，以获取最优的生成结果。

文档后处理

基于查询对检索到的文档进行后处理的组件，解决中间信息丢失、模型上下文长度限制、减少检索信息中的噪声和冗余等问题。

例如，该组件可根据文档与查询的相关性排序、移除无关或冗余的文档，或压缩每个文档的内容以减少噪声和冗余。

生成（Generation）

生成模块负责根据用户查询和检索到的文档生成最终响应。

查询增强

为输入查询补充额外数据的组件，用于为大语言模型提供回答用户查询所需的上下文。

ContextualQueryAugmenter

ContextualQueryAugmenter 使用提供的文档内容中的上下文数据增强用户查询。

QueryAugmenter queryAugmenter = ContextualQueryAugmenter.builder().build();

默认情况下，ContextualQueryAugmenter 不允许检索到的上下文为空。若上下文为空，组件会指示模型不回答用户查询。

你可以启用 allowEmptyContext 选项，允许模型在检索上下文为空时仍生成响应。

QueryAugmenter queryAugmenter = ContextualQueryAugmenter.builder()
        .allowEmptyContext(true)
        .build();

该组件使用的提示词可通过构建器中的 promptTemplate() 和 emptyContextPromptTemplate() 方法自定义。

Spring AI MCP注解示例

Mon, 18 May 2026 13:46:41 +0800

本页面提供在Spring AI应用中使用MCP注解的全面示例。

完整应用示例

简易计算器服务端

提供计算器工具的MCP服务端完整示例：

@SpringBootApplication
public class CalculatorServerApplication {
    public static void main(String[] args) {
        SpringApplication.run(CalculatorServerApplication.class, args);
    }
}

@Component
public class CalculatorTools {

    @McpTool(name = "add", description = "Add two numbers")
    public double add(
            @McpToolParam(description = "First number", required = true) double a,
            @McpToolParam(description = "Second number", required = true) double b) {
        return a + b;
    }

    @McpTool(name = "subtract", description = "Subtract two numbers")
    public double subtract(
            @McpToolParam(description = "First number", required = true) double a,
            @McpToolParam(description = "Second number", required = true) double b) {
        return a - b;
    }

    @McpTool(name = "multiply", description = "Multiply two numbers")
    public double multiply(
            @McpToolParam(description = "First number", required = true) double a,
            @McpToolParam(description = "Second number", required = true) double b) {
        return a * b;
    }

    @McpTool(name = "divide", description = "Divide two numbers")
    public double divide(
            @McpToolParam(description = "Dividend", required = true) double dividend,
            @McpToolParam(description = "Divisor", required = true) double divisor) {
        if (divisor == 0) {
            throw new IllegalArgumentException("Division by zero");
        }
        return dividend / divisor;
    }

    @McpTool(name = "calculate-expression",
             description = "Calculate a complex mathematical expression")
    public CallToolResult calculateExpression(
            CallToolRequest request,
            McpSyncRequestContext context) {

        Mapargs = request.arguments();
        String expression = (String) args.get("expression");

        // Use convenient logging method
        context.info("Calculating: " + expression);

        try {
            double result = evaluateExpression(expression);
            return CallToolResult.builder()
                .addTextContent("Result: " + result)
                .build();
        } catch (Exception e) {
            return CallToolResult.builder()
                .isError(true)
                .addTextContent("Error: " + e.getMessage())
                .build();
        }
    }
}

配置：

spring:
  ai:
    mcp:
      server:
        name: calculator-server
        version: 1.0.0
        type: SYNC
        protocol: SSE  # or STDIO, STREAMABLE
        capabilities:
          tool: true
          resource: true
          prompt: true
          completion: true

文档处理服务端

包含资源和提示词的文档处理服务端示例：

@Component
public class DocumentServer {

    private final Mapdocuments = new ConcurrentHashMap<>();

    @McpResource(
        uri = "document://{id}",
        name = "Document",
        description = "Access stored documents")
    public ReadResourceResult getDocument(String id, McpMeta meta) {
        Document doc = documents.get(id);

        if (doc == null) {
            return new ReadResourceResult(List.of(
                new TextResourceContents("document://" + id,
                    "text/plain", "Document not found")
            ));
        }

        // Check access permissions from metadata
        String accessLevel = (String) meta.get("accessLevel");
        if ("restricted".equals(doc.getClassification()) &&
            !"admin".equals(accessLevel)) {
            return new ReadResourceResult(List.of(
                new TextResourceContents("document://" + id,
                    "text/plain", "Access denied")
            ));
        }

        return new ReadResourceResult(List.of(
            new TextResourceContents("document://" + id,
                doc.getMimeType(), doc.getContent())
        ));
    }

    @McpTool(name = "analyze-document",
             description = "Analyze document content")
    public String analyzeDocument(
            McpSyncRequestContext context,
            @McpToolParam(description = "Document ID", required = true) String docId,
            @McpToolParam(description = "Analysis type", required = false) String type) {

        Document doc = documents.get(docId);
        if (doc == null) {
            return "Document not found";
        }

        // Access progress token from context
        String progressToken = context.request().progressToken();

        if (progressToken != null) {
            context.progress(p -> p.progress(0.0).total(1.0).message("Starting analysis"));
        }

        // Perform analysis
        String analysisType = type != null ? type : "summary";
        String result = performAnalysis(doc, analysisType);

        if (progressToken != null) {
            context.progress(p -> p.progress(1.0).total(1.0).message("Analysis complete"));
        }

        return result;
    }

    @McpPrompt(
        name = "document-summary",
        description = "Generate document summary prompt")
    public GetPromptResult documentSummaryPrompt(
            @McpArg(name = "docId", required = true) String docId,
            @McpArg(name = "length", required = false) String length) {

        Document doc = documents.get(docId);
        if (doc == null) {
            return new GetPromptResult("Error",
                List.of(new PromptMessage(Role.SYSTEM,
                    new TextContent("Document not found"))));
        }

        String promptText = String.format(
            "Please summarize the following document in %s:\n\n%s",
            length != null ? length : "a few paragraphs",
            doc.getContent()
        );

        return new GetPromptResult("Document Summary",
            List.of(new PromptMessage(Role.USER, new TextContent(promptText))));
    }

    @McpComplete(prompt = "document-summary")
    public ListcompleteDocumentId(String prefix) {
        return documents.keySet().stream()
            .filter(id -> id.startsWith(prefix))
            .sorted()
            .limit(10)
            .toList();
    }
}

带处理器的MCP客户端

包含各类处理器的完整MCP客户端应用：

@SpringBootApplication
public class McpClientApplication {
    public static void main(String[] args) {
        SpringApplication.run(McpClientApplication.class, args);
    }
}

@Component
public class ClientHandlers {

    private final Logger logger = LoggerFactory.getLogger(ClientHandlers.class);
    private final ProgressTracker progressTracker = new ProgressTracker();
    private final ChatModel chatModel;

    public ClientHandlers(@Lazy ChatModel chatModel) {
        this.chatModel = chatModel;
    }

    @McpLogging(clients = "server1")
    public void handleLogging(LoggingMessageNotification notification) {
        switch (notification.level()) {
            case ERROR:
                logger.error("[MCP] {} - {}", notification.logger(), notification.data());
                break;
            case WARNING:
                logger.warn("[MCP] {} - {}", notification.logger(), notification.data());
                break;
            case INFO:
                logger.info("[MCP] {} - {}", notification.logger(), notification.data());
                break;
            default:
                logger.debug("[MCP] {} - {}", notification.logger(), notification.data());
        }
    }

    @McpSampling(clients = "server1")
    public CreateMessageResult handleSampling(CreateMessageRequest request) {
        // Use Spring AI ChatModel for sampling
        Listmessages = request.messages().stream()
            .map(msg -> {
                if (msg.role() == Role.USER) {
                    return new UserMessage(((TextContent) msg.content()).text());
                } else {
                    return AssistantMessage.builder()
                        .content(((TextContent) msg.content()).text())
                        .build();
                }
            })
            .toList();

        ChatResponse response = chatModel.call(new Prompt(messages));

        return CreateMessageResult.builder()
            .role(Role.ASSISTANT)
            .content(new TextContent(response.getResult().getOutput().getText()))
            .model(request.modelPreferences().hints().get(0).name())
            .build();
    }

    @McpElicitation(clients = "server1")
    public ElicitResult handleElicitation(ElicitRequest request) {
        // In a real application, this would show a UI dialog
        MapuserData = new HashMap<>();

        logger.info("Elicitation requested: {}", request.message());

        // Simulate user input based on schema
        Mapschema = request.requestedSchema();
        if (schema != null && schema.containsKey("properties")) {
            Mapproperties = (Map) schema.get("properties");

            properties.forEach((key, value) -> {
                // In real app, prompt user for each field
                userData.put(key, getDefaultValueForProperty(key, value));
            });
        }

        return new ElicitResult(ElicitResult.Action.ACCEPT, userData);
    }

    @McpProgress(clients = "server1")
    public void handleProgress(ProgressNotification notification) {
        progressTracker.update(
            notification.progressToken(),
            notification.progress(),
            notification.total(),
            notification.message()
        );

        // Update UI or send websocket notification
        broadcastProgress(notification);
    }

    @McpToolListChanged(clients = "server1")
    public void handleServer1ToolsChanged(Listtools) {
        logger.info("Server1 tools updated: {} tools available", tools.size());

        // Update tool registry
        toolRegistry.updateServerTools("server1", tools);

        // Notify UI to refresh tool list
        eventBus.publish(new ToolsUpdatedEvent("server1", tools));
    }

    @McpResourceListChanged(clients = "server1")
    public void handleServer1ResourcesChanged(Listresources) {
        logger.info("Server1 resources updated: {} resources available", resources.size());

        // Clear resource cache for this server
        resourceCache.clearServer("server1");

        // Register new resources
        resources.forEach(resource ->
            resourceCache.register("server1", resource));
    }
}

配置：

spring:
  ai:
    mcp:
      client:
        type: SYNC
        initialized: true
        request-timeout: 30s
        annotation-scanner:
          enabled: true
        sse:
          connections:
            server1:
              url: http://localhost:8080
        stdio:
          connections:
            local-tool:
              command: /usr/local/bin/mcp-tool
              args:
                - --mode=production

异步示例

异步工具服务端

@Component
public class AsyncDataProcessor {

    @McpTool(name = "fetch-data", description = "Fetch data from external source")
    public MonofetchData(
            @McpToolParam(description = "Data source URL", required = true) String url,
            @McpToolParam(description = "Timeout in seconds", required = false) Integer timeout) {

        Duration timeoutDuration = Duration.ofSeconds(timeout != null ? timeout : 30);

        return WebClient.create()
            .get()
            .uri(url)
            .retrieve()
            .bodyToMono(String.class)
            .map(data -> new DataResult(url, data, System.currentTimeMillis()))
            .timeout(timeoutDuration)
            .onErrorReturn(new DataResult(url, "Error fetching data", 0L));
    }

    @McpTool(name = "process-stream", description = "Process data stream")
    public FluxprocessStream(
            McpAsyncRequestContext context,
            @McpToolParam(description = "Item count", required = true) int count) {

        // Access progress token from context
        String progressToken = context.request().progressToken();

        return Flux.range(1, count)
            .delayElements(Duration.ofMillis(100))
            .flatMap(i -> {
                if (progressToken != null) {
                    double progress = (double) i / count;
                    return context.progress(p -> p.progress(progress).total(1.0).message("Processing item " + i))
                        .thenReturn("Processed item " + i);
                }
                return Mono.just("Processed item " + i);
            });
    }

    @McpResource(uri = "async-data://{id}", name = "Async Data")
    public MonogetAsyncData(String id) {
        return Mono.fromCallable(() -> loadDataAsync(id))
            .subscribeOn(Schedulers.boundedElastic())
            .map(data -> new ReadResourceResult(List.of(
                new TextResourceContents("async-data://" + id,
                    "application/json", data)
            )));
    }
}

异步客户端处理器

@Component
public class AsyncClientHandlers {

    @McpSampling(clients = "async-server")
    public MonohandleAsyncSampling(CreateMessageRequest request) {
        return Mono.fromCallable(() -> {
            // Prepare request for LLM
            String prompt = extractPrompt(request);
            return prompt;
        })
        .flatMap(prompt -> callLLMAsync(prompt))
        .map(response -> CreateMessageResult.builder()
            .role(Role.ASSISTANT)
            .content(new TextContent(response))
            .model("gpt-4")
            .build())
        .timeout(Duration.ofSeconds(30));
    }

    @McpProgress(clients = "async-server")
    public MonohandleAsyncProgress(ProgressNotification notification) {
        return Mono.fromRunnable(() -> {
            // Update progress tracking
            updateProgressAsync(notification);
        })
        .then(broadcastProgressAsync(notification))
        .subscribeOn(Schedulers.parallel());
    }

    @McpElicitation(clients = "async-server")
    public MonohandleAsyncElicitation(ElicitRequest request) {
        return showUserDialogAsync(request)
            .map(userData -> {
                if (userData != null && !userData.isEmpty()) {
                    return new ElicitResult(ElicitResult.Action.ACCEPT, userData);
                } else {
                    return new ElicitResult(ElicitResult.Action.DECLINE, null);
                }
            })
            .timeout(Duration.ofMinutes(5))
            .onErrorReturn(new ElicitResult(ElicitResult.Action.CANCEL, null));
    }
}

无状态服务端示例

@Component
public class StatelessTools {

    // Simple stateless tool
    @McpTool(name = "format-text", description = "Format text")
    public String formatText(
            @McpToolParam(description = "Text to format", required = true) String text,
            @McpToolParam(description = "Format type", required = true) String format) {

        return switch (format.toLowerCase()) {
            case "uppercase" -> text.toUpperCase();
            case "lowercase" -> text.toLowerCase();
            case "title" -> toTitleCase(text);
            case "reverse" -> new StringBuilder(text).reverse().toString();
            default -> text;
        };
    }

    // Stateless with transport context
    @McpTool(name = "validate-json", description = "Validate JSON")
    public CallToolResult validateJson(
            McpTransportContext context,
            @McpToolParam(description = "JSON string", required = true) String json) {

        try {
            ObjectMapper mapper = new ObjectMapper();
            mapper.readTree(json);

            return CallToolResult.builder()
                .addTextContent("Valid JSON")
                .structuredContent(Map.of("valid", true))
                .build();
        } catch (Exception e) {
            return CallToolResult.builder()
                .addTextContent("Invalid JSON: " + e.getMessage())
                .structuredContent(Map.of("valid", false, "error", e.getMessage()))
                .build();
        }
    }

    @McpResource(uri = "static://{path}", name = "Static Resource")
    public String getStaticResource(String path) {
        // Simple stateless resource
        return loadStaticContent(path);
    }

    @McpPrompt(name = "template", description = "Template prompt")
    public GetPromptResult templatePrompt(
            @McpArg(name = "template", required = true) String templateName,
            @McpArg(name = "variables", required = false) String variables) {

        String template = loadTemplate(templateName);
        if (variables != null) {
            template = substituteVariables(template, variables);
        }

        return new GetPromptResult("Template: " + templateName,
            List.of(new PromptMessage(Role.USER, new TextContent(template))));
    }
}

集成多LLM提供商的MCP采样

本示例演示如何使用MCP采样从多个LLM提供商生成创意内容，展示基于注解的服务端和客户端实现方式。

采样服务端实现

服务端提供天气工具，通过MCP采样从不同LLM提供商生成诗歌：

@Service
public class WeatherService {

    private final RestClient restClient = RestClient.create();

    public record WeatherResponse(Current current) {
        public record Current(LocalDateTime time, int interval, double temperature_2m) {
        }
    }

    @McpTool(description = "Get the temperature (in celsius) for a specific location")
    public String getTemperature2(McpSyncServerExchange exchange,
            @McpToolParam(description = "The location latitude") double latitude,
            @McpToolParam(description = "The location longitude") double longitude) {

        // Fetch weather data
        WeatherResponse weatherResponse = restClient
                .get()
                .uri("https://api.open-meteo.com/v1/forecast?latitude={latitude}&longitude={longitude}&current=temperature_2m",
                        latitude, longitude)
                .retrieve()
                .body(WeatherResponse.class);

        StringBuilder openAiWeatherPoem = new StringBuilder();
        StringBuilder anthropicWeatherPoem = new StringBuilder();

        // Send logging notification
        exchange.loggingNotification(LoggingMessageNotification.builder()
                .level(LoggingLevel.INFO)
                .data("Start sampling")
                .build());

        // Check if client supports sampling
        if (exchange.getClientCapabilities().sampling() != null) {
            var messageRequestBuilder = McpSchema.CreateMessageRequest.builder()
                    .systemPrompt("You are a poet!")
                    .messages(List.of(new McpSchema.SamplingMessage(McpSchema.Role.USER,
                            new McpSchema.TextContent(
                                    "Please write a poem about this weather forecast (temperature is in Celsius). Use markdown format :\n "
                                            + ModelOptionsUtils.toJsonStringPrettyPrinter(weatherResponse)))));

            // Request poem from OpenAI
            var openAiLlmMessageRequest = messageRequestBuilder
                    .modelPreferences(ModelPreferences.builder().addHint("openai").build())
                    .build();
            CreateMessageResult openAiLlmResponse = exchange.createMessage(openAiLlmMessageRequest);
            openAiWeatherPoem.append(((McpSchema.TextContent) openAiLlmResponse.content()).text());

            // Request poem from Anthropic
            var anthropicLlmMessageRequest = messageRequestBuilder
                    .modelPreferences(ModelPreferences.builder().addHint("anthropic").build())
                    .build();
            CreateMessageResult anthropicAiLlmResponse = exchange.createMessage(anthropicLlmMessageRequest);
            anthropicWeatherPoem.append(((McpSchema.TextContent) anthropicAiLlmResponse.content()).text());
        }

        exchange.loggingNotification(LoggingMessageNotification.builder()
                .level(LoggingLevel.INFO)
                .data("Finish Sampling")
                .build());

        // Combine results
        String responseWithPoems = "OpenAI poem about the weather: " + openAiWeatherPoem.toString() + "\n\n" +
                "Anthropic poem about the weather: " + anthropicWeatherPoem.toString() + "\n"
                + ModelOptionsUtils.toJsonStringPrettyPrinter(weatherResponse);

        return responseWithPoems;
    }
}

采样客户端实现

客户端通过模型提示将采样请求路由至对应的LLM提供商：

@Service
public class McpClientHandlers {

    private static final Logger logger = LoggerFactory.getLogger(McpClientHandlers.class);

    @Autowired
    MapchatClients;

    @McpProgress(clients = "server1")
    public void progressHandler(ProgressNotification progressNotification) {
        logger.info("MCP PROGRESS: [{}] progress: {} total: {} message: {}",
                progressNotification.progressToken(), progressNotification.progress(),
                progressNotification.total(), progressNotification.message());
    }

    @McpLogging(clients = "server1")
    public void loggingHandler(LoggingMessageNotification loggingMessage) {
        logger.info("MCP LOGGING: [{}] {}", loggingMessage.level(), loggingMessage.data());
    }

    @McpSampling(clients = "server1")
    public CreateMessageResult samplingHandler(CreateMessageRequest llmRequest) {
        logger.info("MCP SAMPLING: {}", llmRequest);

        // Extract user prompt and model hint
        var userPrompt = ((McpSchema.TextContent) llmRequest.messages().get(0).content()).text();
        String modelHint = llmRequest.modelPreferences().hints().get(0).name();

        // Find appropriate ChatClient based on model hint
        ChatClient hintedChatClient = chatClients.entrySet().stream()
                .filter(e -> e.getKey().contains(modelHint))
                .findFirst()
                .orElseThrow()
                .getValue();

        // Generate response using the selected model
        String response = hintedChatClient.prompt()
                .system(llmRequest.systemPrompt())
                .user(userPrompt)
                .call()
                .content();

        return CreateMessageResult.builder()
                .content(new McpSchema.TextContent(response))
                .build();
    }
}

客户端应用配置

在客户端应用中注册MCP工具和处理器：

@SpringBootApplication
public class McpClientApplication {

    public static void main(String[] args) {
        SpringApplication.run(McpClientApplication.class, args).close();
    }

    @Bean
    public CommandLineRunner predefinedQuestions(OpenAiChatModel openAiChatModel,
            ToolCallbackProvider mcpToolProvider) {

        return args -> {

            ChatClient chatClient = ChatClient.builder(openAiChatModel)
                    .defaultToolCallbacks(mcpToolProvider)
                    .build();

            String userQuestion = """
                    What is the weather in Amsterdam right now?
                    Please incorporate all creative responses from all LLM providers.
                    After the other providers add a poem that synthesizes the poems from all the other providers.
                    """;

            System.out.println("> USER: " + userQuestion);
            System.out.println("> ASSISTANT: " + chatClient.prompt(userQuestion).call().content());
        };
    }
}

配置

服务端配置

# Server application.properties
spring.ai.mcp.server.name=mcp-sampling-server-annotations
spring.ai.mcp.server.version=0.0.1
spring.ai.mcp.server.protocol=STREAMABLE
spring.main.banner-mode=off

客户端配置

# Client application.properties
spring.application.name=mcp
spring.main.web-application-type=none

# Disable default chat client auto-configuration for multiple models
spring.ai.chat.client.enabled=false

# API keys
spring.ai.openai.api-key=${OPENAI_API_KEY}
spring.ai.anthropic.api-key=${ANTHROPIC_API_KEY}

# MCP client connection using stateless-http transport
spring.ai.mcp.client.streamable-http.connections.server1.url=http://localhost:8080

# Disable tool callback to prevent cyclic dependencies
spring.ai.mcp.client.toolcallback.enabled=false

演示的核心功能

多模型采样：服务端通过模型提示向多个LLM提供商请求内容
基于注解的处理器：客户端使用@McpSampling、@McpLogging和@McpProgress注解
无状态HTTP传输：采用可流式协议进行通信
创意内容生成：从不同模型生成天气相关诗歌
统一响应处理：将多个提供商的响应整合为单一结果

示例输出

运行客户端时，输出如下：

> USER: What is the weather in Amsterdam right now?
Please incorporate all creative responses from all LLM providers.
After the other providers add a poem that synthesizes the poems from all the other providers.

> ASSISTANT:
OpenAI poem about the weather:
**Amsterdam's Winter Whisper**
*Temperature: 4.2°C*

In Amsterdam's embrace, where canals reflect the sky,
A gentle chill of 4.2 degrees drifts by...

Anthropic poem about the weather:
**Canal-Side Contemplation**
*Current conditions: 4.2°C*

Along the waterways where bicycles rest,
The winter air puts Amsterdam to test...

Weather Data:
{
  "current": {
    "time": "2025-01-23T11:00",
    "interval": 900,
    "temperature_2m": 4.2
  }
}

与Spring AI集成

MCP工具与Spring AI函数调用集成示例：

@RestController
@RequestMapping("/chat")
public class ChatController {

    private final ChatModel chatModel;
    private final SyncMcpToolCallbackProvider toolCallbackProvider;

    public ChatController(ChatModel chatModel,
                          SyncMcpToolCallbackProvider toolCallbackProvider) {
        this.chatModel = chatModel;
        this.toolCallbackProvider = toolCallbackProvider;
    }

    @PostMapping
    public ChatResponse chat(@RequestBody ChatRequest request) {
        // Get MCP tools as Spring AI function callbacks
        ToolCallback[] mcpTools = toolCallbackProvider.getToolCallbacks();

        // Create prompt with MCP tools
        Prompt prompt = new Prompt(
            request.getMessage(),
            ChatOptionsBuilder.builder()
                .withTools(mcpTools)
                .build()
        );

        // Call chat model with MCP tools available
        return chatModel.call(prompt);
    }
}

@Component
public class WeatherTools {

    @McpTool(name = "get-weather", description = "Get current weather")
    public WeatherInfo getWeather(
            @McpToolParam(description = "City name", required = true) String city,
            @McpToolParam(description = "Units (metric/imperial)", required = false) String units) {

        String unit = units != null ? units : "metric";

        // Call weather API
        return weatherService.getCurrentWeather(city, unit);
    }

    @McpTool(name = "get-forecast", description = "Get weather forecast")
    public ForecastInfo getForecast(
            @McpToolParam(description = "City name", required = true) String city,
            @McpToolParam(description = "Days (1-7)", required = false) Integer days) {

        int forecastDays = days != null ? days : 3;

        return weatherService.getForecast(city, forecastDays);
    }
}

Spring AI MCP注解特殊参数

Mon, 18 May 2026 13:39:25 +0800

MCP注解支持多种特殊参数类型，这些参数可为被注解的方法提供额外上下文和功能。它们由框架自动注入，且不会被纳入JSON模式生成。

特殊参数类型

McpMeta

McpMeta类用于获取MCP请求、通知和结果中的元数据。

概述

作为方法参数使用时会被自动注入
不计入参数数量限制，且不参与JSON模式生成
通过get(String key)方法可便捷获取元数据
若请求中无元数据，将注入空的McpMeta对象

在工具中的使用

@McpTool(name = "contextual-tool", description = "Tool with metadata access")
public String processWithContext(
        @McpToolParam(description = "Input data", required = true) String data,
        McpMeta meta) {

    // Access metadata from the request
    String userId = (String) meta.get("userId");
    String sessionId = (String) meta.get("sessionId");
    String userRole = (String) meta.get("userRole");

    // Use metadata to customize behavior
    if ("admin".equals(userRole)) {
        return processAsAdmin(data, userId);
    } else {
        return processAsUser(data, userId);
    }
}

在资源中的使用

@McpResource(uri = "secure-data://{id}", name = "Secure Data")
public ReadResourceResult getSecureData(String id, McpMeta meta) {

    String requestingUser = (String) meta.get("requestingUser");
    String accessLevel = (String) meta.get("accessLevel");

    // Check access permissions using metadata
    if (!"admin".equals(accessLevel)) {
        return new ReadResourceResult(List.of(
            new TextResourceContents("secure-data://" + id,
                "text/plain", "Access denied")
        ));
    }

    String data = loadSecureData(id);
    return new ReadResourceResult(List.of(
        new TextResourceContents("secure-data://" + id,
            "text/plain", data)
    ));
}

在提示词中的使用

@McpPrompt(name = "localized-prompt", description = "Localized prompt generation")
public GetPromptResult localizedPrompt(
        @McpArg(name = "topic", required = true) String topic,
        McpMeta meta) {

    String language = (String) meta.get("language");
    String region = (String) meta.get("region");

    // Generate localized content based on metadata
    String message = generateLocalizedMessage(topic, language, region);

    return new GetPromptResult("Localized Prompt",
        List.of(new PromptMessage(Role.ASSISTANT, new TextContent(message)))
    );
}

@McpProgressToken

@McpProgressToken注解用于标记接收MCP请求进度令牌的参数。

概述

参数类型必须为String
自动接收请求中的进度令牌值
不纳入生成的JSON模式
若请求中无进度令牌，将注入null
用于追踪耗时较长的操作

在工具中的使用

@McpTool(name = "long-operation", description = "Long-running operation with progress")
public String performLongOperation(
        @McpProgressToken String progressToken,
        @McpToolParam(description = "Operation name", required = true) String operation,
        @McpToolParam(description = "Duration in seconds", required = true) int duration,
        McpSyncServerExchange exchange) {

    if (progressToken != null) {
        // Send initial progress
        exchange.progressNotification(new ProgressNotification(
            progressToken, 0.0, 1.0, "Starting " + operation));

        // Simulate work with progress updates
        for (int i = 1; i 在资源中的使用@McpResource(uri = "large-file://{path}", name = "Large File Resource")
public ReadResourceResult getLargeFile(
        @McpProgressToken String progressToken,
        String path,
        McpSyncServerExchange exchange) {

    File file = new File(path);
    long fileSize = file.length();

    if (progressToken != null) {
        // Track file reading progress
        exchange.progressNotification(new ProgressNotification(
            progressToken, 0.0, fileSize, "Reading file"));
    }

    String content = readFileWithProgress(file, progressToken, exchange);

    if (progressToken != null) {
        exchange.progressNotification(new ProgressNotification(
            progressToken, fileSize, fileSize, "File read complete"));
    }

    return new ReadResourceResult(List.of(
        new TextResourceContents("large-file://" + path, "text/plain", content)
    ));
}McpSyncRequestContext / McpAsyncRequestContext请求上下文对象提供了对MCP请求信息和服务端操作的统一访问能力。概述为有状态和无状态操作提供统一接口作为参数使用时会被自动注入不参与JSON模式生成支持日志、进度通知、采样、信息获取等高级功能兼容有状态（服务端交换）和无状态（传输上下文）模式McpSyncRequestContext功能public record UserInfo(String name, String email, int age) {}

@McpTool(name = "advanced-tool", description = "Tool with full server capabilities")
public String advancedTool(
        McpSyncRequestContext context,
        @McpToolParam(description = "Input", required = true) String input) {

    // Send logging notification
    context.info("Processing: " + input);

    // Ping the client
    context.ping();

    // Send progress updates
    context.progress(50); // 50% complete

    // Check if elicitation is supported before using it
    if (context.elicitEnabled()) {
        // Request additional information from user
        StructuredElicitResultelicitResult = context.elicit(
            e -> e.message("Need additional information"),
            UserInfo.class
        );

        if (elicitResult.action() == ElicitResult.Action.ACCEPT) {
            UserInfo userInfo = elicitResult.structuredContent();
            // Use the user information
        }
    }

    // Check if sampling is supported before using it
    if (context.sampleEnabled()) {
        // Request LLM sampling
        CreateMessageResult samplingResult = context.sample(
            s -> s.message("Process: " + input)
                .modelPreferences(pref -> pref.modelHints("gpt-4"))
        );
    }

    return "Processed with advanced features";
}McpAsyncRequestContext功能public record UserInfo(String name, String email, int age) {}

@McpTool(name = "async-advanced-tool", description = "Async tool with server capabilities")
public MonoasyncAdvancedTool(
        McpAsyncRequestContext context,
        @McpToolParam(description = "Input", required = true) String input) {

    return context.info("Async processing: " + input)
        .then(context.progress(25))
        .then(context.ping())
        .flatMap(v -> {
            // Perform elicitation if supported
            if (context.elicitEnabled()) {
                return context.elicitation(UserInfo.class)
                    .map(userInfo -> "Processing for user: " + userInfo.name());
            }
            return Mono.just("Processing...");
        })
        .flatMap(msg -> {
            // Perform sampling if supported
            if (context.sampleEnabled()) {
                return context.sampling("Process: " + input)
                    .map(result -> "Completed: " + result);
            }
            return Mono.just("Completed: " + msg);
        });
}McpTransportContext用于无状态操作的轻量级上下文。概述提供最小化上下文，不包含完整的服务端交换能力用于无状态实现作为参数使用时会被自动注入不参与JSON模式生成使用示例@McpTool(name = "stateless-tool", description = "Stateless tool with context")
public String statelessTool(
        McpTransportContext context,
        @McpToolParam(description = "Input", required = true) String input) {

    // Limited context access
    // Useful for transport-level operations

    return "Processed in stateless mode: " + input;
}

@McpResource(uri = "stateless://{id}", name = "Stateless Resource")
public ReadResourceResult statelessResource(
        McpTransportContext context,
        String id) {

    // Access transport context if needed
    String data = loadData(id);

    return new ReadResourceResult(List.of(
        new TextResourceContents("stateless://" + id, "text/plain", data)
    ));
}CallToolRequest适用于需要访问完整动态模式请求的工具的特殊参数。概述可访问完整的工具请求支持运行时动态模式处理自动注入且不参与模式生成适用于适配不同输入模式的灵活工具使用示例@McpTool(name = "dynamic-tool", description = "Tool with dynamic schema support")
public CallToolResult processDynamicSchema(CallToolRequest request) {
    Mapargs = request.arguments();

    // Process based on whatever schema was provided at runtime
    StringBuilder result = new StringBuilder("Processed:\n");

    for (Map.Entryentry : args.entrySet()) {
        result.append("  ").append(entry.getKey())
              .append(": ").append(entry.getValue()).append("\n");
    }

    return CallToolResult.builder()
        .addTextContent(result.toString())
        .build();
}混合参数@McpTool(name = "hybrid-tool", description = "Tool with typed and dynamic parameters")
public String processHybrid(
        @McpToolParam(description = "Operation", required = true) String operation,
        @McpToolParam(description = "Priority", required = false) Integer priority,
        CallToolRequest request) {

    // Use typed parameters for known fields
    String result = "Operation: " + operation;
    if (priority != null) {
        result += " (Priority: " + priority + ")";
    }

    // Access additional dynamic arguments
    MapallArgs = request.arguments();

    // Remove known parameters to get only additional ones
    MapadditionalArgs = new HashMap<>(allArgs);
    additionalArgs.remove("operation");
    additionalArgs.remove("priority");

    if (!additionalArgs.isEmpty()) {
        result += " with " + additionalArgs.size() + " additional parameters";
    }

    return result;
}携带进度令牌@McpTool(name = "flexible-with-progress", description = "Flexible tool with progress")
public CallToolResult flexibleWithProgress(
        @McpProgressToken String progressToken,
        CallToolRequest request,
        McpSyncServerExchange exchange) {

    Mapargs = request.arguments();

    if (progressToken != null) {
        exchange.progressNotification(new ProgressNotification(
            progressToken, 0.0, 1.0, "Processing dynamic request"));
    }

    // Process dynamic arguments
    String result = processDynamicArgs(args);

    if (progressToken != null) {
        exchange.progressNotification(new ProgressNotification(
            progressToken, 1.0, 1.0, "Complete"));
    }

    return CallToolResult.builder()
        .addTextContent(result)
        .build();
}参数注入规则自动注入以下参数由框架自动注入：McpMeta - 请求中的元数据@McpProgressToken String - 可用的进度令牌McpSyncServerExchange / McpAsyncServerExchange - 服务端交换上下文McpTransportContext - 无状态操作的传输上下文CallToolRequest - 动态模式的完整工具请求模式生成特殊参数不会被纳入JSON模式生成：不会出现在工具的输入模式中不计入参数数量限制对MCP客户端不可见空值处理McpMeta - 永不为null，无元数据时为空对象@McpProgressToken - 无令牌时可为null服务端交换 - 正确配置时永不为nullCallToolRequest - 工具方法中永不为null最佳实践使用McpMeta获取上下文@McpTool(name = "context-aware", description = "Context-aware tool")
public String contextAware(
        @McpToolParam(description = "Data", required = true) String data,
        McpMeta meta) {

    // Always check for null values in metadata
    String userId = (String) meta.get("userId");
    if (userId == null) {
        userId = "anonymous";
    }

    return processForUser(data, userId);
}进度令牌空值检查@McpTool(name = "safe-progress", description = "Safe progress handling")
public String safeProgress(
        @McpProgressToken String progressToken,
        @McpToolParam(description = "Task", required = true) String task,
        McpSyncServerExchange exchange) {

    // Always check if progress token is available
    if (progressToken != null) {
        exchange.progressNotification(new ProgressNotification(
            progressToken, 0.0, 1.0, "Starting"));
    }

    // Perform work...

    if (progressToken != null) {
        exchange.progressNotification(new ProgressNotification(
            progressToken, 1.0, 1.0, "Complete"));
    }

    return "Task completed";
}选择合适的上下文使用McpSyncRequestContext / McpAsyncRequestContext统一访问请求上下文，支持有状态和无状态操作，附带便捷的辅助方法仅需传输级上下文时，使用McpTransportContext处理简单无状态操作最简单的场景可完全省略上下文参数功能可用性检查使用客户端功能前务必检查支持性：@McpTool(name = "capability-aware", description = "Tool that checks capabilities")
public String capabilityAware(
        McpSyncRequestContext context,
        @McpToolParam(description = "Data", required = true) String data) {

    // Check if elicitation is supported before using it
    if (context.elicitEnabled()) {
        // Safe to use elicitation
        var result = context.elicit(UserInfo.class);
        // Process result...
    }

    // Check if sampling is supported before using it
    if (context.sampleEnabled()) {
        // Safe to use sampling
        var samplingResult = context.sample("Process: " + data);
        // Process result...
    }

    // Note: Stateless servers do not support bidirectional operations
    // (roots, elicitation, sampling) and will return false for these checks

    return "Processed with capability awareness";
}

Spring AI MCP 服务端注解

Sat, 16 May 2026 00:02:05 +0800

MCP 服务端注解提供了一种声明式的方式，通过 Java 注解实现 MCP 服务端功能。这些注解简化了工具、资源、提示词和补全处理器的创建。

服务端注解

@McpTool

@McpTool 注解将方法标记为 MCP 工具实现，并支持自动生成 JSON 模式。

基础用法

@Component
public class CalculatorTools {

    @McpTool(name = "add", description = "Add two numbers together")
    public int add(
            @McpToolParam(description = "First number", required = true) int a,
            @McpToolParam(description = "Second number", required = true) int b) {
        return a + b;
    }
}

高级特性

@McpTool(name = "calculate-area",
         description = "Calculate the area of a rectangle",
         annotations = McpTool.McpAnnotations(
             title = "Rectangle Area Calculator",
             readOnlyHint = true,
             destructiveHint = false,
             idempotentHint = true
         ))
public AreaResult calculateRectangleArea(
        @McpToolParam(description = "Width", required = true) double width,
        @McpToolParam(description = "Height", required = true) double height) {

    return new AreaResult(width * height, "square units");
}

携带请求上下文

工具可访问请求上下文以执行高级操作：

@McpTool(name = "process-data", description = "Process data with request context")
public String processData(
        McpSyncRequestContext context,
        @McpToolParam(description = "Data to process", required = true) String data) {

    // 发送日志通知
    context.info("Processing data: " + data);

    // 发送进度通知（使用便捷方法）
    context.progress(p -> p.progress(0.5).total(1.0).message("Processing..."));

    // 向客户端发送心跳
    context.ping();

    return "Processed: " + data.toUpperCase();
}

动态模式支持

工具可接收 CallToolRequest 以实现运行时模式处理：

@McpTool(name = "flexible-tool", description = "Process dynamic schema")
public CallToolResult processDynamic(CallToolRequest request) {
    Mapargs = request.arguments();

    // 基于运行时模式处理
    String result = "Processed " + args.size() + " arguments dynamically";

    return CallToolResult.builder()
        .addTextContent(result)
        .build();
}

进度跟踪

工具可接收进度令牌以跟踪长时间运行的操作：

@McpTool(name = "long-task", description = "Long-running task with progress")
public String performLongTask(
        McpSyncRequestContext context,
        @McpToolParam(description = "Task name", required = true) String taskName) {

    // 从上下文获取进度令牌
    String progressToken = context.request().progressToken();

    if (progressToken != null) {
        context.progress(p -> p.progress(0.0).total(1.0).message("Starting task"));

        // 执行任务...

        context.progress(p -> p.progress(1.0).total(1.0).message("Task completed"));
    }

    return "Task " + taskName + " completed";
}

@McpResource

@McpResource 注解通过 URI 模板提供资源访问能力。

基础用法

@Component
public class ResourceProvider {

    @McpResource(
        uri = "config://{key}",
        name = "Configuration",
        description = "Provides configuration data")
    public String getConfig(String key) {
        return configData.get(key);
    }
}

携带 ReadResourceResult

@McpResource(
    uri = "user-profile://{username}",
    name = "User Profile",
    description = "Provides user profile information")
public ReadResourceResult getUserProfile(String username) {
    String profileData = loadUserProfile(username);

    return new ReadResourceResult(List.of(
        new TextResourceContents(
            "user-profile://" + username,
            "application/json",
            profileData)
    ));
}

携带请求上下文

@McpResource(
    uri = "data://{id}",
    name = "Data Resource",
    description = "Resource with request context")
public ReadResourceResult getData(
        McpSyncRequestContext context,
        String id) {

    // 使用便捷方法发送日志通知
    context.info("Accessing resource: " + id);

    // 向客户端发送心跳
    context.ping();

    String data = fetchData(id);

    return new ReadResourceResult(List.of(
        new TextResourceContents("data://" + id, "text/plain", data)
    ));
}

@McpPrompt

@McpPrompt 注解为 AI 交互生成提示词消息。

基础用法

@Component
public class PromptProvider {

    @McpPrompt(
        name = "greeting",
        description = "Generate a greeting message")
    public GetPromptResult greeting(
            @McpArg(name = "name", description = "User's name", required = true)
            String name) {

        String message = "Hello, " + name + "! How can I help you today?";

        return new GetPromptResult(
            "Greeting",
            List.of(new PromptMessage(Role.ASSISTANT, new TextContent(message)))
        );
    }
}

携带可选参数

@McpPrompt(
    name = "personalized-message",
    description = "Generate a personalized message")
public GetPromptResult personalizedMessage(
        @McpArg(name = "name", required = true) String name,
        @McpArg(name = "age", required = false) Integer age,
        @McpArg(name = "interests", required = false) String interests) {

    StringBuilder message = new StringBuilder();
    message.append("Hello, ").append(name).append("!\n\n");

    if (age != null) {
        message.append("At ").append(age).append(" years old, ");
        // 添加年龄专属内容
    }

    if (interests != null && !interests.isEmpty()) {
        message.append("Your interest in ").append(interests);
        // 添加兴趣专属内容
    }

    return new GetPromptResult(
        "Personalized Message",
        List.of(new PromptMessage(Role.ASSISTANT, new TextContent(message.toString())))
    );
}

@McpComplete

@McpComplete 注解为提示词提供自动补全功能。

基础用法

@Component
public class CompletionProvider {

    @McpComplete(prompt = "city-search")
    public ListcompleteCityName(String prefix) {
        return cities.stream()
            .filter(city -> city.toLowerCase().startsWith(prefix.toLowerCase()))
            .limit(10)
            .toList();
    }
}

携带 CompleteRequest.CompleteArgument

@McpComplete(prompt = "travel-planner")
public ListcompleteTravelDestination(CompleteRequest.CompleteArgument argument) {
    String prefix = argument.value().toLowerCase();
    String argumentName = argument.name();

    // 根据参数名称提供不同的补全内容
    if ("city".equals(argumentName)) {
        return completeCities(prefix);
    } else if ("country".equals(argumentName)) {
        return completeCountries(prefix);
    }

    return List.of();
}

携带 CompleteResult

@McpComplete(prompt = "code-completion")
public CompleteResult completeCode(String prefix) {
    Listcompletions = generateCodeCompletions(prefix);

    return new CompleteResult(
        new CompleteResult.CompleteCompletion(
            completions,
            completions.size(),  // 总数
            hasMoreCompletions   // 是否有更多补全标识
        )
    );
}

无状态与有状态实现

统一请求上下文（推荐）

使用 McpSyncRequestContext 或 McpAsyncRequestContext 可获得适用于有状态和无状态操作的统一接口：

public record UserInfo(String name, String email, int age) {}

@McpTool(name = "unified-tool", description = "Tool with unified request context")
public String unifiedTool(
        McpSyncRequestContext context,
        @McpToolParam(description = "Input", required = true) String input) {

    // 访问请求和元数据
    String progressToken = context.request().progressToken();

    // 使用便捷方法记录日志
    context.info("Processing: " + input);

    // 进度通知（注意：客户端需在请求中设置进度令牌才能接收进度更新）
    context.progress(50); // 简单百分比

    // 向客户端发送心跳
    context.ping();

    // 使用前检查能力是否支持
    if (context.elicitEnabled()) {
        // 请求用户输入（仅在有状态模式下）
        StructuredElicitResultelicitResult = context.elicit(UserInfo.class);
        if (elicitResult.action() == ElicitResult.Action.ACCEPT) {
            // 使用诱导获取的数据
        }
    }

    if (context.sampleEnabled()) {
        // 请求大语言模型采样（仅在有状态模式下）
        CreateMessageResult samplingResult = context.sample("Generate response");
        // 使用采样结果
    }

    return "Processed with unified context";
}

简单操作（无上下文）

对于简单操作，可完全省略上下文参数：

@McpTool(name = "simple-add", description = "Simple addition")
public int simpleAdd(
        @McpToolParam(description = "First number", required = true) int a,
        @McpToolParam(description = "Second number", required = true) int b) {
    return a + b;
}

轻量级无状态（携带 McpTransportContext）

适用于需要最小传输上下文的无状态操作：

@McpTool(name = "stateless-tool", description = "Stateless with transport context")
public String statelessTool(
        McpTransportContext context,
        @McpToolParam(description = "Input", required = true) String input) {
    // 仅访问传输级上下文
    // 无双向操作（根目录、诱导、采样）
    return "Processed: " + input;
}

无状态服务端不支持双向操作：因此在无状态模式下，使用 McpSyncRequestContext 或 McpAsyncRequestContext 的方法会被忽略。

按服务端类型过滤方法

MCP 注解框架会根据服务端类型和方法特征自动过滤注解方法。这确保每个服务端配置仅注册合适的方法。每个被过滤的方法都会记录一条警告日志，便于调试。

同步与异步过滤

同步服务端

同步服务端（配置为 spring.ai.mcp.server.type=SYNC）使用同步提供者，规则如下：

接收非响应式返回类型的方法：

基本类型（int、double、boolean）
对象类型（String、Integer、自定义 POJO）
MCP 类型（CallToolResult、ReadResourceResult、GetPromptResult、CompleteResult）
集合（List
、Map）

过滤响应式返回类型的方法：

Mono
Flux
Publisher

@Component
public class SyncTools {

    @McpTool(name = "sync-tool", description = "Synchronous tool")
    public String syncTool(String input) {
        // 该方法会在同步服务端注册
        return "Processed: " + input;
    }

    @McpTool(name = "async-tool", description = "Async tool")
    public MonoasyncTool(String input) {
        // 该方法会在同步服务端被过滤
        // 会记录警告日志
        return Mono.just("Processed: " + input);
    }
}

异步服务端

异步服务端（配置为 spring.ai.mcp.server.type=ASYNC）使用异步提供者，规则如下：

接收响应式返回类型的方法：

Mono
（单个结果）
Flux
（流式结果）
Publisher
（通用响应式类型）

过滤非响应式返回类型的方法：

基本类型
对象类型
集合
MCP 结果类型

@Component
public class AsyncTools {

    @McpTool(name = "async-tool", description = "Async tool")
    public MonoasyncTool(String input) {
        // 该方法会在异步服务端注册
        return Mono.just("Processed: " + input);
    }

    @McpTool(name = "sync-tool", description = "Sync tool")
    public String syncTool(String input) {
        // 该方法会在异步服务端被过滤
        // 会记录警告日志
        return "Processed: " + input;
    }
}

有状态与无状态过滤

有状态服务端

有状态服务端支持双向通信，接收包含以下内容的方法：

双向上下文参数：

McpSyncRequestContext（同步操作）
McpAsyncRequestContext（异步操作）
McpSyncServerExchange（旧版，同步操作）
McpAsyncServerExchange（旧版，异步操作）

支持双向操作：

roots() - 访问根目录
elicit() - 请求用户输入
sample() - 请求大语言模型采样

@Component
public class StatefulTools {

    @McpTool(name = "interactive-tool", description = "Tool with bidirectional operations")
    public String interactiveTool(
            McpSyncRequestContext context,
            @McpToolParam(description = "Input", required = true) String input) {

        // 该方法会在有状态服务端注册
        // 可使用诱导、采样、根目录功能
        if (context.sampleEnabled()) {
            var samplingResult = context.sample("Generate response");
            // 处理采样结果...
        }

        return "Processed with context";
    }
}

无状态服务端

无状态服务端针对简单请求-响应模式优化，规则如下：

过滤包含双向上下文参数的方法：

携带 McpSyncRequestContext 的方法会被跳过
携带 McpAsyncRequestContext 的方法会被跳过
携带 McpSyncServerExchange 的方法会被跳过
携带 McpAsyncServerExchange 的方法会被跳过

每个被过滤的方法都会记录警告日志
接收包含以下内容的方法：

McpTransportContext（轻量级无状态上下文）
无任何上下文参数
仅常规 @McpToolParam 参数

不支持双向操作：

roots() - 不可用
elicit() - 不可用
sample() - 不可用

@Component
public class StatelessTools {

    @McpTool(name = "simple-tool", description = "Simple stateless tool")
    public String simpleTool(@McpToolParam(description = "Input") String input) {
        // 该方法会在无状态服务端注册
        return "Processed: " + input;
    }

    @McpTool(name = "context-tool", description = "Tool with transport context")
    public String contextTool(
            McpTransportContext context,
            @McpToolParam(description = "Input") String input) {
        // 该方法会在无状态服务端注册
        return "Processed: " + input;
    }

    @McpTool(name = "bidirectional-tool", description = "Tool with bidirectional context")
    public String bidirectionalTool(
            McpSyncRequestContext context,
            @McpToolParam(description = "Input") String input) {
        // 该方法会在无状态服务端被过滤
        // 会记录警告日志
        return "Processed with sampling";
    }
}

过滤总结

服务端类型	接收的方法	过滤的方法
同步有状态	非响应式返回 + 双向上下文	响应式返回（Mono/Flux）
异步有状态	响应式返回（Mono/Flux）+ 双向上下文	非响应式返回
同步无状态	非响应式返回 + 无双向上下文	响应式返回或双向上下文参数
异步无状态	响应式返回（Mono/Flux）+ 无双向上下文	非响应式返回或双向上下文参数

方法过滤最佳实践：

方法与服务端类型保持一致——同步服务端使用同步方法，异步服务端使用异步方法
将有状态和无状态实现分离到不同类中，提升代码清晰度
启动时检查日志，查看被过滤的方法警告
使用合适的上下文——有状态使用 McpSyncRequestContext/McpAsyncRequestContext，无状态使用 McpTransportContext
若同时支持有状态和无状态部署，需对两种模式都进行测试

异步支持

所有服务端注解均支持使用 Reactor 实现异步：

@Component
public class AsyncTools {

    @McpTool(name = "async-fetch", description = "Fetch data asynchronously")
    public MonoasyncFetch(
            @McpToolParam(description = "URL", required = true) String url) {

        return Mono.fromCallable(() -> {
            // 模拟异步操作
            return fetchFromUrl(url);
        }).subscribeOn(Schedulers.boundedElastic());
    }

    @McpResource(uri = "async-data://{id}", name = "Async Data")
    public MonoasyncResource(String id) {
        return Mono.fromCallable(() -> {
            String data = loadData(id);
            return new ReadResourceResult(List.of(
                new TextResourceContents("async-data://" + id, "text/plain", data)
            ));
        }).delayElements(Duration.ofMillis(100));
    }
}

Spring Boot 集成

通过 Spring Boot 自动配置，带注解的 Bean 会被自动检测并注册：

@SpringBootApplication
public class McpServerApplication {
    public static void main(String[] args) {
        SpringApplication.run(McpServerApplication.class, args);
    }
}

@Component
public class MyMcpTools {
    // 你的 @McpTool 注解方法
}

@Component
public class MyMcpResources {
    // 你的 @McpResource 注解方法
}

自动配置会执行以下操作：

扫描带有 MCP 注解的 Bean
创建对应的规范定义
将其注册到 MCP 服务端
根据配置自动处理同步和异步实现

配置属性

配置服务端注解扫描器：

spring:
  ai:
    mcp:
      server:
        type: SYNC  # 或 ASYNC
        annotation-scanner:
          enabled: true

附加资源

MCP 注解概述
客户端注解
特殊参数
MCP 服务端启动器

Spring AI MCP 客户端注解

Sat, 16 May 2026 00:01:26 +0800

MCP 客户端注解提供了一种声明式的方式，通过 Java 注解实现 MCP 客户端处理器。这些注解简化了服务端通知和客户端操作的处理逻辑。

所有 MCP 客户端注解必须包含一个 clients 参数，用于将处理器与指定的 MCP 客户端连接关联。该 clients 值必须与应用配置文件中配置的连接名称一致。

客户端注解

@McpLogging

@McpLogging 注解用于处理来自 MCP 服务端的日志消息通知。

基础用法

@Component
public class LoggingHandler {

    @McpLogging(clients = "my-mcp-server")
    public void handleLoggingMessage(LoggingMessageNotification notification) {
        System.out.println("Received log: " + notification.level() +
                          " - " + notification.data());
    }
}

独立参数接收方式

@McpLogging(clients = "my-mcp-server")
public void handleLoggingWithParams(LoggingLevel level, String logger, String data) {
    System.out.println(String.format("[%s] %s: %s", level, logger, data));
}

@McpSampling

@McpSampling 注解用于处理 MCP 服务端发送的大语言模型补全采样请求。

同步实现

@Component
public class SamplingHandler {

    @McpSampling(clients = "llm-server")
    public CreateMessageResult handleSamplingRequest(CreateMessageRequest request) {
        // 处理请求并生成响应
        String response = generateLLMResponse(request);

        return CreateMessageResult.builder()
            .role(Role.ASSISTANT)
            .content(new TextContent(response))
            .model("gpt-4")
            .build();
    }
}

异步实现

@Component
public class AsyncSamplingHandler {

    @McpSampling(clients = "llm-server")
    public MonohandleAsyncSampling(CreateMessageRequest request) {
        return Mono.fromCallable(() -> {
            String response = generateLLMResponse(request);

            return CreateMessageResult.builder()
                .role(Role.ASSISTANT)
                .content(new TextContent(response))
                .model("gpt-4")
                .build();
        }).subscribeOn(Schedulers.boundedElastic());
    }
}

@McpElicitation

@McpElicitation 注解用于处理信息诱导请求，以从用户处收集额外信息。

基础用法

@Component
public class ElicitationHandler {

    @McpElicitation(clients = "interactive-server")
    public ElicitResult handleElicitationRequest(ElicitRequest request) {
        // 向用户展示请求并收集输入信息
        MapuserData = presentFormToUser(request.requestedSchema());

        if (userData != null) {
            return new ElicitResult(ElicitResult.Action.ACCEPT, userData);
        } else {
            return new ElicitResult(ElicitResult.Action.DECLINE, null);
        }
    }
}

用户交互实现

@McpElicitation(clients = "interactive-server")
public ElicitResult handleInteractiveElicitation(ElicitRequest request) {
    Mapschema = request.requestedSchema();
    MapuserData = new HashMap<>();

    // 检查需要请求的信息
    if (schema != null && schema.containsKey("properties")) {
        Mapproperties = (Map) schema.get("properties");

        // 根据模式收集用户输入
        if (properties.containsKey("name")) {
            userData.put("name", promptUser("请输入你的姓名："));
        }
        if (properties.containsKey("email")) {
            userData.put("email", promptUser("请输入你的邮箱："));
        }
        if (properties.containsKey("preferences")) {
            userData.put("preferences", gatherPreferences());
        }
    }

    return new ElicitResult(ElicitResult.Action.ACCEPT, userData);
}

异步信息诱导

@McpElicitation(clients = "interactive-server")
public MonohandleAsyncElicitation(ElicitRequest request) {
    return Mono.fromCallable(() -> {
        // 异步用户交互
        MapuserData = asyncGatherUserInput(request);
        return new ElicitResult(ElicitResult.Action.ACCEPT, userData);
    }).timeout(Duration.ofSeconds(30))
      .onErrorReturn(new ElicitResult(ElicitResult.Action.CANCEL, null));
}

@McpProgress

@McpProgress 注解用于处理长时间运行操作的进度通知。

基础用法

@Component
public class ProgressHandler {

    @McpProgress(clients = "my-mcp-server")
    public void handleProgressNotification(ProgressNotification notification) {
        double percentage = notification.progress() * 100;
        System.out.println(String.format("进度：%.2f%% - %s",
            percentage, notification.message()));
    }
}

独立参数接收方式

@McpProgress(clients = "my-mcp-server")
public void handleProgressWithDetails(
        String progressToken,
        double progress,
        Double total,
        String message) {

    if (total != null) {
        System.out.println(String.format("[%s] %.0f/%.0f - %s",
            progressToken, progress, total, message));
    } else {
        System.out.println(String.format("[%s] %.2f%% - %s",
            progressToken, progress * 100, message));
    }

    // 更新界面进度条
    updateProgressBar(progressToken, progress);
}

客户端专属进度处理

@McpProgress(clients = "long-running-server")
public void handleLongRunningProgress(ProgressNotification notification) {
    // 跟踪指定服务端的进度
    progressTracker.update("long-running-server", notification);

    // 按需发送通知
    if (notification.progress() >= 1.0) {
        notifyCompletion(notification.progressToken());
    }
}

@McpToolListChanged

@McpToolListChanged 注解用于处理服务端工具列表发生变更时的通知。

基础用法

@Component
public class ToolListChangedHandler {

    @McpToolListChanged(clients = "tool-server")
    public void handleToolListChanged(ListupdatedTools) {
        System.out.println("工具列表已更新：可用工具数量 " + updatedTools.size());

        // 更新本地工具注册表
        toolRegistry.updateTools(updatedTools);

        // 记录新工具
        for (McpSchema.Tool tool : updatedTools) {
            System.out.println("  - " + tool.name() + ": " + tool.description());
        }
    }
}

异步处理

@McpToolListChanged(clients = "tool-server")
public MonohandleAsyncToolListChanged(ListupdatedTools) {
    return Mono.fromRunnable(() -> {
        // 异步处理工具列表更新
        processToolListUpdate(updatedTools);

        // 通知相关组件
        eventBus.publish(new ToolListUpdatedEvent(updatedTools));
    }).then();
}

客户端专属工具更新

@McpToolListChanged(clients = "dynamic-server")
public void handleDynamicServerToolUpdate(ListupdatedTools) {
    // 处理来自频繁变更工具的指定服务端的工具
    dynamicToolManager.updateServerTools("dynamic-server", updatedTools);

    // 重新评估工具可用性
    reevaluateToolCapabilities();
}

@McpResourceListChanged

@McpResourceListChanged 注解用于处理服务端资源列表发生变更时的通知。

基础用法

@Component
public class ResourceListChangedHandler {

    @McpResourceListChanged(clients = "resource-server")
    public void handleResourceListChanged(ListupdatedResources) {
        System.out.println("资源已更新：数量 " + updatedResources.size());

        // 更新资源缓存
        resourceCache.clear();
        for (McpSchema.Resource resource : updatedResources) {
            resourceCache.register(resource);
        }
    }
}

资源变更分析

@McpResourceListChanged(clients = "resource-server")
public void analyzeResourceChanges(ListupdatedResources) {
    // 分析变更内容
    SetnewUris = updatedResources.stream()
        .map(McpSchema.Resource::uri)
        .collect(Collectors.toSet());

    SetremovedUris = previousUris.stream()
        .filter(uri -> !newUris.contains(uri))
        .collect(Collectors.toSet());

    if (!removedUris.isEmpty()) {
        handleRemovedResources(removedUris);
    }

    // 更新跟踪记录
    previousUris = newUris;
}

@McpPromptListChanged

@McpPromptListChanged 注解用于处理服务端提示词列表发生变更时的通知。

基础用法

@Component
public class PromptListChangedHandler {

    @McpPromptListChanged(clients = "prompt-server")
    public void handlePromptListChanged(ListupdatedPrompts) {
        System.out.println("提示词已更新：数量 " + updatedPrompts.size());

        // 更新提示词目录
        promptCatalog.updatePrompts(updatedPrompts);

        // 按需刷新界面
        if (uiController != null) {
            uiController.refreshPromptList(updatedPrompts);
        }
    }
}

异步处理

@McpPromptListChanged(clients = "prompt-server")
public MonohandleAsyncPromptUpdate(ListupdatedPrompts) {
    return Flux.fromIterable(updatedPrompts)
        .flatMap(prompt -> validatePrompt(prompt))
        .collectList()
        .doOnNext(validPrompts -> {
            promptRepository.saveAll(validPrompts);
        })
        .then();
}

Spring Boot 集成

通过 Spring Boot 自动配置，客户端处理器会被自动检测并注册：

@SpringBootApplication
public class McpClientApplication {
    public static void main(String[] args) {
        SpringApplication.run(McpClientApplication.class, args);
    }
}

@Component
public class MyClientHandlers {

    @McpLogging(clients = "my-server")
    public void handleLogs(LoggingMessageNotification notification) {
        // 处理日志
    }

    @McpSampling(clients = "my-server")
    public CreateMessageResult handleSampling(CreateMessageRequest request) {
        // 处理采样
    }

    @McpProgress(clients = "my-server")
    public void handleProgress(ProgressNotification notification) {
        // 处理进度
    }
}

自动配置会执行以下操作：

扫描带有 MCP 客户端注解的 Bean
创建对应的规范定义
将其注册到 MCP 客户端
支持同步和异步两种实现方式
通过客户端专属处理器支持多客户端场景

配置属性

配置客户端注解扫描器和客户端连接：

spring:
  ai:
    mcp:
      client:
        type: SYNC  # 或 ASYNC
        annotation-scanner:
          enabled: true
        # 配置客户端连接 - 连接名称会作为注解中clients的值
        sse:
          connections:
            my-server:  # 该名称作为注解的clients值
              url: http://localhost:8080
            tool-server:  # 另一个clients值
              url: http://localhost:8081
        stdio:
          connections:
            local-server:  # 该名称作为注解的clients值
              command: /path/to/mcp-server
              args:
                - --mode=production

注解中的 clients 参数必须与配置中定义的连接名称匹配。在上述示例中，合法的 clients 值为："my-server"、"tool-server" 和 "local-server"。

MCP 客户端使用方式

带注解的处理器会自动与 MCP 客户端集成：

@Autowired
private ListmcpClients;

// 客户端会根据clients配置自动使用你定义的注解处理器
// 无需手动注册 - 处理器会通过名称与客户端匹配关联

对于每个 MCP 客户端连接，带有匹配 clients 值的处理器会被自动注册，并在对应事件触发时自动调用。

技术之家

Spring AI ​Azure Cosmos DB

什么是 Azure Cosmos DB？

什么是 DiskANN？

通过自动配置设置 Azure Cosmos DB 向量存储

自动配置

配置属性

带过滤器的复杂搜索

不使用自动配置设置 Azure Cosmos DB 向量存储

手动依赖配置

访问原生客户端

Spring AI Azure AI 服务

前提条件

配置

依赖项

配置属性

示例代码

元数据过滤

自定义字段名

使用场景

通过属性配置

通过构建器 API 配置

完整示例：使用现有索引

使用自定义字段名创建新索引

访问原生客户端

Spring AI 向量数据库

接口概述

VectorStoreRetriever接口

VectorStore接口

SearchRequest构建器

Spring AI 评估测试

相关性评估器

集成测试中的用法

自定义模板

事实核查评估器

用法

示例

Spring AI ETL 流水线

API 概述

Spring AI 消息 API

ETL 流水线

ETL 接口

文档读取器

文档转换器

文档写入器

文档读取器

JSON 格式

示例

构造方法选项

参数

行为

使用 JSON 指针

参数

返回值

行为

示例

示例 JSON 结构

注意事项

纯文本格式

示例

构造方法选项

参数

配置

行为

注意事项

HTML 格式（基于 JSoup）

依赖

示例

示例文档：my-page.html

行为

Markdown 格式

依赖

示例

示例文档：code.md

行为

PDF 分页格式

依赖

示例

PDF 段落格式

依赖

Spring AI Azure Cosmos DB