格式化输出(Structured Output)¶

类别	词条	详细说明
核心概念	结构化输出(Structured Output)	通过特定格式指令指导大语言模型（LLM）生成可被下游应用程序可靠解析的结构化数据（如JSON、XML、Java类实例等）的机制
	输出格式指令	附加在用户提示中的指导性文本，用于明确指定LLM生成响应时应遵循的结构化格式要求
	转换器(Converter)	将LLM输出的原始文本转换为结构化数据类型的工具，包含格式指令生成和结果反序列化两个阶段
API类	BeanOutputConverter	通过Java类或ParameterizedTypeReference配置，将LLM输出的JSON反序列化为对应Java对象的转换器实现
	MapOutputConverter	将LLM输出的JSON转换为`java.util.Map<String, Object>`结构的转换器实现
	ListOutputConverter	将LLM输出的逗号分隔文本转换为`java.util.List`的转换器实现
技术实现	JSON模式(DRAFT_2020_12)	BeanOutputConverter使用的JSON模式规范，用于验证LLM输出与目标Java类的匹配性
	RFC8259标准	MapOutputConverter遵循的JSON合规性标准，确保输出的JSON能被标准解析器处理
	ObjectMapper	在BeanOutputConverter中用于JSON反序列化的工具类，实现文本到Java对象的转换
数据格式	JSON	最常用的结构化输出格式，支持键值对结构和嵌套数据表示
	XML	可扩展标记语言，支持树形结构数据表示（文中未展开但属于支持范畴）
	Java类实例	通过反序列化将LLM输出转换为具体的Java对象，如`ActorsFilms`记录类实例
功能模块	提示工程(Prompt Engineering)	在用户提示中插入格式指令的技术，用于控制LLM输出的数据结构
	反序列化	将LLM输出的结构化文本（如JSON）转换为程序可操作的数据对象的过程
使用方式	ChatClient	高级API接口，通过链式调用实现结构化输出转换（如`.entity(Class)`直接获取对象结果）
	ChatModel	底层原子API，需手动处理提示模板构建和转换器调用（如`chatModel.call()`配合`convert()`方法）
开发实践	ParameterizedTypeReference	用于处理泛型类型的容器类，在转换复杂结构（如`List<ActorsFilms>`）时提供类型安全支持
	DefaultConversionService	ListOutputConverter依赖的类型转换服务，实现文本到List的解析
应用场景	下游应用程序	依赖可靠解析LLM输出值的系统，需要结构化数据作为输入来源（如工作流、智能体应用等）
示例组件	ActorsFilms记录类	示例中定义的数据结构`record ActorsFilms(String actor, List<String> movies)`，用于接收演员电影作品结构化数据
操作指令	生成(Generate)	LLM根据格式指令创建结构化数据的核心动作
	转换(Convert)	将LLM原始输出文本映射到目标数据结构的处理过程
	解析(Parse)	对LLM输出的结构化文本进行语法分析和数据提取
特性说明	可靠解析	结构化输出的核心价值，确保下游系统能稳定处理AI模型的返回结果
	快速集成	通过自动类型转换减少开发工作量，加速AI功能与现有系统的整合

向量存储(Vector Store)¶

类别	词条	详细说明
核心概念	向量存储（VectorStore）	一种用于存储和检索高维向量数据的数据库或存储解决方案，适用于处理嵌入模型转换后的数据，支持相似性搜索而非精确匹配。
	高维向量数据	经过嵌入模型转化的数值数组（如`float[]`），用于表示文本、图像等非结构化数据的特征。
	嵌入模型（EmbeddingModel）	将文本内容转换为数值向量的模型，用于生成向量存储中的高维数据。
	相似性搜索	根据向量之间的距离或相似度进行检索，返回与查询向量最接近的文档。
	检索增强生成（RAG）	技术流程：先检索相似文档作为上下文，再结合用户查询发送给AI模型生成答案。
接口类与方法	VectorStore接口	Spring AI提供的抽象接口，包含数据加载、删除和相似性搜索的核心方法。
	`add(List<Document>)`	将文档列表添加到向量存储中，需结合嵌入模型生成向量。
	`delete(List<String>)`	根据文档ID列表删除向量存储中的文档。
	`similaritySearch()`	执行相似性搜索，支持通过`SearchRequest`或直接传入查询字符串进行检索。
	SearchRequest构建器	用于配置搜索参数的类，支持设置`topK`、相似度阈值和过滤表达式。
文档处理	Document类	封装文本内容及其元数据（如文件名、来源格式），是向量存储操作的基本单元。
	元数据（Metadata）	键值对形式的附加信息（如`country == 'UK'`），用于过滤或增强文档检索。
接口参数与选项	`topK`	返回相似文档的最大数量（默认为4），用于控制检索结果的规模。
	相似度阈值（threshold）	仅返回相似度高于该值的文档（范围0-1，默认0.75）。
	Filter.Expression	类SQL的过滤表达式，基于文档元数据进行条件筛选（如`year >= 2020`）。
配置与集成	Auto-configuration	Spring Boot自动配置功能，简化向量存储的依赖注入和初始化流程。
	VectorStore Properties	配置前缀`spring.ai.dashscope`，用于设置API密钥等连接参数。
	Runtime Options	通过`DashScopeStoreOptions`动态配置参数（如指定知识库名称）。
	DashScopeCloudStore	阿里云百炼平台的具体向量存储实现类，需传入API实例和配置选项。
框架与注解	@RestController	Spring MVC注解，标记类为处理HTTP请求的控制器。
	@Autowired	Spring依赖注入注解，自动装配`DashScopeCloudStore`实例。
	@GetMapping	定义HTTP GET请求的端点映射，如示例中的`/ai/search`路径。
处理过程	向量嵌入（Embedding）	使用嵌入模型将文本内容转换为数值数组的过程，是数据加载到向量存储前的必要步骤。
	元数据过滤	通过`Filter.Expression`在搜索时筛选符合条件的文档，提升检索精准度。

智能机票助手¶

类别	词条	详细说明
框架与平台	Spring AI Alibaba	阿里云提供的AI开发框架，用于构建智能体应用，支持与大模型交互和功能扩展
	Spring Boot	Java应用开发框架，用于构建智能机票助手的核心系统
AI模型相关	AI大模型	通义等基础模型，用于自然语言理解、决策和多轮对话能力
	自然语言处理(NLP)	理解用户通过自然语言表达的机票操作需求
	多轮对话	支持连续对话并在上下文中保持意图理解
	意图识别	识别用户请求类型（如改签/退票/查询）
应用功能	机票预定	核心业务功能，需结合航空规则和用户需求完成
	问题解答	回答用户关于航班、政策等问题的能力
	机票改签	涉及规则校验（如航空公司政策、手续费计算）的复杂操作
	机票取消	需要验证用户权限和合规性的敏感操作
架构组件	Vector Store	存储机票规则等向量化数据的检索库，支持RAG模式
	业务数据库	存储用户预订记录、操作历史等结构化数据
	工具调用	执行具体业务动作（如修改数据库记录）的功能接口
技术模式	RAG(检索增强)	通过领域知识（如退改签规则）增强模型决策准确性的技术
	Function Calling	将模型决策转换为具体函数调用，实现业务操作的执行机制
	Chat Memory	对话记忆管理，维护多轮对话的上下文信息
开发概念	Prompt管理	设计优化与大模型交互的提示词模板
	决策执行	将AI决策转化为可执行的业务流程（与传统系统结合）
	持久化	业务数据存储到数据库的操作
业务规则	航空法规	必须遵守的行业法规（如运输条款、旅客权益）
	退改签规则	各航空公司差异化的政策，需严格校验的核心业务逻辑
	手续费计算	基于规则和用户条件的动态计算逻辑
系统特性	智能化能力	结合AI模型与传统系统的混合决策机制
	经济风险控制	涉及资金操作的业务需防范法律/经济风险的设计要求
	上下文感知	系统对对话历史和业务状态的整体理解能力
代码实现	ChatClient	Spring AI提供的流式API，用于集成多种AI能力组件
	Fluent API	声明式编程接口，简化智能体构建流程
	Advisor	功能扩展点（如日志记录、记忆管理、检索增强等模块）
验证机制	用户身份验证	获取预订号、客户姓名等敏感信息的安全验证过程
	规则合规校验	执行操作前对航空政策的自动核查
	操作确认	涉及费用变更时需用户明确同意的交互流程

RAG¶

以下是基于当前网页内容整理的关键概念、名词、动词及技术术语的表格，覆盖了所有技术相关内容，排除了社区资源与目录部分：

类别	词条	详细说明
核心概念	RAG（检索增强生成）	一种结合检索模型与生成模型的技术，通过外部数据源增强大语言模型（LLM）生成结果的准确性和相关性，无需重新训练模型。
	Indexing Pipeline（索引管道）	数据处理流程，包括文档加载、解析、分块（chunk）、向量化及存储到向量数据库，为后续检索提供结构化数据基础。
	RAG阶段	包含用户提问向量化、向量数据库检索、文档重排、提示词优化及调用大模型生成回答的完整流程。
技术组件	DashScopeApi	阿里云提供的API接口，用于调用文档解析、向量化、知识库操作等功能。
	DashScopeDocumentCloudReader	基于DashScope的文档解析工具，支持加载和解析PDF等格式文档。
	DashScopeEmbeddingModel	阿里云的文本嵌入模型，用于将文本转换为向量表示。
	DashScopeCloudStore	基于DashScope的云存储组件，用于管理向量数据库中的知识库文档（如添加、删除操作）。
	DocumentRetriever	文档检索接口，支持从向量数据库中检索与用户提问相关的文档片段。
	ChatClient	封装大模型调用的客户端工具，支持集成检索增强逻辑（如通过`DocumentRetrievalAdvisor`）。
技术流程	文档解析	将非结构化文档（如PDF）转换为结构化文本数据的过程。
	Chunk切分	将长文本分割为短片段（chunk），便于向量化与检索。
	向量化	使用嵌入模型将文本转换为向量表示，便于相似性计算。
	知识库导入	将处理后的文档向量存储到向量数据库（如DashScopeCloudStore）。
	文档检索	根据用户提问的向量，从向量数据库中召回相关文档片段。
	模型调用	通过ChatClient调用大模型（如DashScopeChatModel），结合检索结果生成最终回答。
技术术语	语义搜索	基于向量相似性的搜索方式，理解用户意图而非关键词匹配。
	混合搜索	结合语义搜索与传统关键词搜索的检索策略，提升结果相关性。
	知识库（向量数据库）	存储文档向量的数据库，支持高效检索（如DashScopeCloudStore中的“bailian-knowledge”索引）。
	私有数据/专有数据	RAG中补充大模型的外部数据源，如企业内部文档或未公开信息。
	生成模型（LLM）	大语言模型（如DashScopeChatModel），根据检索内容生成自然语言回答。
工具与框架	Spring AI Alibaba Graph	基于Spring生态的框架，提供RAG流程开发支持，简化智能体应用构建（如Dify工作流）。
	DocumentRetrievalAdvisor	用于集成文档检索逻辑的组件，可配置是否返回引用的文档内容。
存储组件	DashScopeStoreOptions	配置向量数据库存储的参数（如索引名称“bailian-knowledge”）。
代码操作	add()	向向量数据库添加文档的方法。
	delete()	从向量数据库中删除指定文档的方法。
输出与元数据	ChatResponse	包含大模型生成回答的对象，可获取回答内容及引用的文档元数据（如标题、分数）。
	Retrieved Documents	检索后采纳的文档列表，包含元数据（如文档名称、相关性分数）。

仅用十几行代码实现 OpenManus，Spring AI Alibaba Graph 快速预览¶

https://java2ai.com/blog/spring-ai-alibaba-graph-preview/?spm=4347728f.3f2b363b.0.0.717ba35esAeuI3&source=blog/

类别	词条	详细说明
框架与组件	Spring AI Alibaba Graph	阿里巴巴基于Spring AI开发的智能体框架，支持工作流编排、多智能体系统构建，参考Langgraph设计理念。
	StateGraph	用于定义状态图的组件，可通过节点（Node）和边（Edge）构建流程控制逻辑。
	AgentStateFactory	创建智能体状态的工厂类，负责注册状态键和策略（如ReplaceStrategy）。
	ReactAgent	基于ReAct模式的智能体实现，支持工具调用与迭代执行任务，通过maxIterations控制最大循环次数。
功能模块	工作流编排	通过节点和条件边实现自动化流程，如客户评价处理系统中的分类与分流逻辑。
	智能体（Agent）	具有独立功能的程序单元，如Planning Agent（任务规划）、Supervisor Agent（任务监督）、Executor Agent（任务执行）。
	多智能体系统	多个智能体协作的系统，如OpenManus中Planning、Supervisor、Executor Agent的协同工作。
示例应用	客户评价处理系统	通过两级分类节点处理用户评论，区分正面（positive）与负面（negative）反馈，并按问题类型分流到处理节点。
	天气预报查询系统	基于ReAct Agent模式循环调用天气查询工具，直到模型返回无tool_call指令时结束流程。
	OpenManus	多智能体协作系统，新版通过Spring AI Alibaba Graph减少80%流程控制代码，支持任务规划、监督和执行。
技术概念	条件边（Conditional Edges）	根据节点输出结果动态选择下一个节点，如根据分类结果跳转到"recorder"或"specific_question_classifier"。
	全局State管理	通过OverAllState类统一管理流程中的输入、分类结果和解决方案等状态数据。
	工具调用（Tool Call）	Agent通过调用外部工具（如天气查询API）完成任务，ReAct模式下需判断工具调用状态。
开发工具与流程	Maven	项目构建工具，需通过`mvn clean install`编译未发布的Spring AI Alibaba Graph源码。
	Spring Boot	示例应用基于Spring Boot启动，通过`@SpringBootApplication`注解运行GraphApplication主类。
	API-KEY配置	使用`export AI_DASHSCOPE_API_KEY=xxx`设置大模型访问密钥，为框架提供AI服务连接能力。
流程控制	节点（Node）	流程中的执行单元，如"feedback_classifier"（反馈分类节点）、"specific_question_classifier"（具体问题分类节点）。
	边（Edge）	节点间的连接关系，包括起始边（START）、结束边（END）和条件边。
	状态注册（registerKey）	使用state.registerKeyAndStrategy()注册状态键及更新策略（如覆盖策略ReplaceStrategy）。
智能体模式	ReAct模式	结合推理（Reasoning）和行动（Action）的智能体模式，在工具调用与结果处理间循环直至任务完成。
	Supervisor模式	监督式多智能体协作模式，由Supervisor Agent协调子智能体按规划执行任务。
问题与优化	流程编排复杂度	旧版OpenManus因缺乏框架支持需手动处理80%的流程控制代码，新版通过Graph框架显著降低开发难度。
	工具覆盖度	旧版工具（如浏览器、脚本执行）功能有限，新版通过Executor Agent集成更多工具（Browser_use、FileSaver、PythonExecutor等）。

MCP 协议重大升级，Spring AI Alibaba 联合 Higress 发布业界首个 Stramable HTTP 实现方案¶

https://java2ai.com/blog/spring-ai-alibaba-mcp-streamable-http

类别	词条	详细说明
协议与标准	MCP协议	Model Context Protocol的简称，定义AI系统间的通信规范
	Streamable HTTP	新型传输层协议，支持灵活选择普通HTTP响应或SSE流式传输
	HTTP+SSE	旧版传输机制，通过HTTP请求+Server-Sent Events实现通信
技术组件	Spring AI Alibaba	阿里云开源的Java AI框架，支持MCP协议集成
	Higress网关	云原生API网关，支持Streamable HTTP协议实现
	Java SDK	MCP协议的Java语言开发工具包
	TypeScript SDK	MCP协议的TypeScript语言实现
技术机制	会话ID（Session ID）	用于标识和管理会话状态的唯一标识符，支持断线重连和状态恢复
	断线重连机制	网络中断后通过会话ID恢复之前交互状态的能力
	统一端点（/mcp）	所有通信通过单一端点完成，取代原有的多端点设计
	按需流式传输	服务器可根据场景选择立即响应或转为SSE流式传输
应用场景	无状态服务器模式	适用于简单API服务，无需维护会话状态
	流式进度反馈	处理长时间任务时实时返回进度信息的应用场景
	复杂AI会话	需要维护上下文的多轮对话场景
	断线恢复模式	弱网环境下保持会话连续性的应用场景
实现细节	GET空请求初始化	客户端通过空GET请求主动建立SSE连接
	POST请求升级响应	服务器可根据请求内容决定返回普通HTTP响应或升级为SSE流
	响应内容协商	通过Content-Type（application/json/text-event-stream）区分响应类型
	Mono响应式编程	Java实现中使用的Project Reactor响应式编程模型
问题与挑战	粘性会话连接	HTTP+SSE模式需要将相同会话请求路由到同一服务节点的限制
	长连接资源消耗	服务器维护大量SSE连接导致的高资源占用问题
	基础设施兼容性限制	传统Web设施（CDN/防火墙等）对长连接支持不足的问题
改进与优势	架构可扩展性	Streamable HTTP减少对粘性会话的依赖，提升系统扩展能力
	灵活响应模式	支持立即响应/短流/长流多种传输形态
	状态恢复能力	通过会话ID实现中断后的状态重建
	弱网可靠性提升	改进后的协议在网络不稳定时仍能保持会话连续性
示例与请求模式	初始化请求	客户端发送包含协议版本和客户端信息的初始化请求
	JSON-RPC 2.0	使用的远程调用协议规范
	SSE事件格式	遵循Server-Sent Events规范的事件流格式
	进度反馈事件	包含百分比进度信息的SSE事件（如"progress:30%"）
相关项目	OpenManus	文中提到的智能体应用开发框架
	Dify工作流	基于Spring AI Alibaba开发的智能体工作流系统
	Ollama本地模型	支持本地模型运行的AI框架（在相关文章提到，当前页面未展开）
	RAG应用	检索增强生成型应用（在相关文章提到）

谷歌发布 Agent2Agent (A2A) 协议，未来 "MCP+A2A" 成标配？¶

https://java2ai.com/blog/google-a2a-protocol/

类别	词条	详细说明
协议名称	Agent2Agent Protocol (A2A)	谷歌开源的标准化智能体交互协议，旨在实现跨平台、跨供应商的智能体协作
协议组成部分	Agent卡	用JSON格式描述智能体能力的元数据，用于智能体间的能力发现与任务匹配
	任务对象	定义任务生命周期的核心数据结构，支持从即时任务到长时间运行任务的统一管理
	工件	任务完成后输出的结构化数据或资源，包含执行结果和上下文信息
设计原则	Agentic能力	强调智能体自主协作能力，支持非结构化交互和多智能体场景扩展
	现有标准集成	基于HTTP/SSE/JSON-RPC构建，兼容企业现有IT基础设施
	默认安全机制	集成OpenAPI级身份验证和授权体系，支持企业级安全策略
	长时任务支持	设计支持数小时/天的复杂任务流程，提供实时状态反馈和人工介入机制
	多模态支持	原生兼容文本/音频/视频流等多媒体交互模式
核心技术	用户体验协商	通过消息段(content-type)协商交互界面，支持iframe/视频/Web表单等动态适配
	智能体通信框架	客户端Agent与远程Agent的标准化通信架构，包含任务分发、状态同步等核心功能
开发工具	ADK (Agent Development Kit)	谷歌开源的智能体开发套件，对标OpenAI同类产品
	Agent Engine	谷歌提供的智能体测试工具，用于验证协议兼容性和性能指标
应用场景	跨平台协作	打通Atlassian/Box/Salesforce/Workday等异构系统的自动化交互
	企业流程自动化	支持CRM/HRM/项目管理等业务场景的端到端自动化
企业生态	共建企业	50+头部企业参与协议开发，包括未具名的云服务、SaaS平台厂商
技术标准	HTTP/SSE/JSON-RPC	协议底层采用的互联网标准通信协议
	OpenAPI	作为安全机制的参考标准，实现企业级认证授权兼容
技术特性	内存隔离	智能体间不共享内存/工具/上下文的独立运行机制
	上下文感知	通过消息传递实现跨智能体的上下文信息同步
	实时反馈	长时任务执行过程中的动态状态更新能力
应用形态	iframe嵌入	用户界面协商支持的嵌入式交互组件
	Web表单	协议支持的标准化人机交互界面类型

Spring AI Alibaba MCP 市场正式上线！¶

https://java2ai.com/blog/spring-ai-mcp-marketplace | 类别 | 词条 | 详细说明 | |--------------|-------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| | 产品/服务 | Spring AI Alibaba MCP 市场 | 阿里云推出的标准化MCP服务平台，提供MCP Server的检索与接入功能，帮助开发者快速集成模型与数据源，支持通过Higress网关实现在线接入。 | | 技术协议 | 模型上下文协议（MCP） | 一种开放协议，用于标准化LLM应用与外部数据源/工具的集成，解决AI模型与数据孤岛问题，替代零散的自定义实现，支持语义描述、入参/返回值格式定义等核心能力。 | | 技术组件 | Higress | 阿里云开源的AI网关，支持MCP协议代理转换，可将存量应用通过配置化方式升级为MCP服务（如与Nacos结合），实现零代码改造。 | | 技术组件 | Nacos | 动态服务发现与配置管理平台，用于存储MCP服务的元数据（如服务描述、参数语义），与Higress结合实现存量Java应用的MCP协议适配。 | | 开发框架 | Spring AI Alibaba | 阿里云开源的Java AI开发框架，支持快速构建MCP Server和智能体应用，提供注解式开发、观测性工具链，并与JDK17+深度集成。 | | 技术概念 | Stramable HTTP | Spring AI Alibaba联合Higress提出的创新型HTTP实现方案，支持流式数据传输，是MCP协议底层通信的核心技术之一。 | | 技术概念 | Agent2Agent (A2A) | 谷歌发布的智能体间通信协议，与MCP形成互补关系，未来可能成为"协议标准组合" ，用于构建复杂AI协作系统。 | | 开发工具 | Dify 工作流 | 基于Spring AI Alibaba Graph的可视化智能体开发工具，支持通过低代码方式快速搭建AI工作流，与MCP服务无缝集成。 | | 开发工具 | OpenManus | Spring AI Alibaba开源的智能体应用开发框架，提供Java版Manus实现，支持通过标准MCP协议调用外部工具和数据源。 | | 技术方法 | RAG 应用 | 检索增强生成（Retrieval-Augmented Generation）应用，结合Ollama本地模型与Spring AI Alibaba实现，通过MCP协议集成私有数据源提升模型响应准确性。 | | 技术方法 | 协议代理转换 | 通过Higress网关将传统HTTP请求转换为MCP协议请求的技术方案，使未改造的Java应用也能接入MCP生态，需配合Nacos元数据管理实现。 | | 开发流程 | MCP Server 发布 | 使用Spring AI Alibaba框架将Java应用升级为MCP服务的流程，涉及JDK17升级、注解添加（语义描述/参数定义）、服务重新部署等步骤。 | | 开发流程 | 零代码修改 MCP 升级 | 通过Nacos配置服务元数据+Higress协议转换的非侵入式MCP适配方案，避免对存量Java应用进行代码改造，实现快速MCP协议兼容。 | | 技术特性 | 可观测性 | Spring AI Alibaba提供的AI应用监控能力，支持追踪MCP链路调用过程、分析工具调用性能，帮助开发者优化智能体应用的运行效率。 | | 技术特性 | 工具调用链路 | MCP协议的核心执行流程，包含服务发现、语义解析、参数映射、结果封装等环节，Spring AI Alibaba通过标准化API和注解配置简化该流程开发。 | | 行业概念 | 智能体私域数据集成 | 通过MCP协议将企业私有数据（如本地文件、数据库）安全接入AI应用的方案，Spring AI Alibaba支持40+插件实现不同数据源的快速对接。 | | 行业概念 | 智能体IDE | 基于MCP协议构建的开发环境（如Claude、Clinet），支持可视化编排AI能力与数据源连接，Dify工作流和OpenManus均属此类工具的Java实现方案。 |

Java开发基于Spring AI Alibaba玩转MCP：从发布、调用到 Claude 集成¶

https://java2ai.com/blog/spring-ai-alibaba-mcp | 类别 | 词条 | 详细说明 | |-------------|-----------------------------|---------------------------------------------------------| | 协议规范 | Model Context Protocol(MCP) | Anthropic公司提出的标准化协议，用于连接AI应用与各类工具/数据源，实现跨平台对接的通信规范 | | | JSON-RPC 2.0 | MCP协议基于的通信协议标准，定义了请求-响应模式的消息格式 | | 架构组件 | MCP客户端 | 集成在AI应用中的组件（如Claude/Spring AI），负责通过协议与MCP服务端通信 | | | MCP服务端 | 对接具体数据源/工具的服务程序（如天气服务/Github），处理客户端请求并返回操作结果 | | 技术实现 | stdio模式 | 通过标准输入输出流进行进程间通信的MCP服务实现方式，适用于本地轻量级工具集成 | | | SSE模式 | 基于Server-Sent Events的远程服务访问模式，支持HTTP协议通信，适用于需要独立部署的复杂工具 | | Spring AI组件 | ToolCallbackProvider | Spring框架中管理MCP工具的核心接口，负责注册和调用工具方法 | | | MethodToolCallbackProvider | 具体实现类，通过反射机制将@Tool注解的方法转换为可调用工具 | | 开发配置 | @Tool注解 | 标记Spring Bean方法为MCP可调用工具，包含工具描述元数据 | | | @ToolParameter注解 | 定义工具方法参数的元数据，包括参数描述和约束条件 | | 通信协议 | 同步通信 | 请求-响应即时交互模式，适用于需要立即返回结果的操作场景 | | | 异步通信 | 非阻塞式交互模式，支持长时间任务处理，通过回调/事件通知机制实现 | | 工具集成 | 天气服务工具 | 示例实现的MCP服务，集成OpenMeteo API提供天气数据查询功能 | | | Github集成工具 | 通过MCP协议实现仓库创建/代码管理等Git操作的标准服务 | | 开发实践 | mcp-servers-config.json | MCP客户端配置文件，定义服务器启动命令、参数和环境变量 | | | WebClient配置 | Spring WebFlux的HTTP客户端，用于服务端集成第三方API（如天气API） | | 异常处理 | 工具重复注册异常 | 因自动配置冲突导致同名工具多次注册引发的IllegalStateException，需排除多余配置类解决 | | 生态集成 | Open Manus | Spring AI Alibaba的智能体框架，通过集成MCP工具扩展能力（如路线规划） | | 企业服务集成 | 百度地图MCP服务 | 国内首个兼容MCP协议的地图服务，提供逆地理编码/路线规划等8个核心API | | Claude集成 | claude_desktop_config.json | Claude客户端的MCP服务配置文件，定义本地/远程MCP服务器启动参数 | | 性能优化 | 请求超时配置 | 客户端设置服务调用超时时间（默认1分钟），防止长时间阻塞 | | 测试验证 | 工具加载验证 | 通过Claude界面检查注册工具是否成功加载的验证流程 | | | 端到端测试 | 完整执行工具调用链（如创建仓库->验证结果）的测试方法 | | 部署模式 | 本地进程部署 | 将MCP服务作为子进程启动的部署方式（stdio模式特点） | | | 独立服务部署 | 将MCP服务部署为独立Web应用的部署方式（SSE模式特点） | | 协议扩展 | 自定义工具协议 | 开发者根据MCP规范扩展实现特定领域工具服务的机制 | | 跨平台支持 | 多OS路径配置 | 配置文件路径支持macOS（~/Library）和Windows（%APPDATA%）不同系统的适配 | | 安全机制 | 令牌管理 | 敏感凭证（如GITHUB_PERSONAL_ACCESS_TOKEN）通过环境变量注入的保密方式 | | 开发工具 | WebClient.Builder | Spring框架的响应式HTTP客户端构建器，用于创建自定义API调用实例 | | 监控调试 | 通信日志 | 记录JSON-RPC消息交互过程的调试日志，用于排查协议通信问题 | | 架构模式 | 模块化架构 | Spring AI MCP的分层设计，包含应用层/客户端层/服务端层等独立模块 | | 版本管理 | 服务版本声明 | 在配置中声明MCP服务版本号（如0.0.1），用于兼容性管理 | | 生态资源 | awesome-mcp-servers | 官方推荐的MCP服务资源库，收录经过验证的第三方服务 | | | mcp.so | MCP协议相关的社区平台/服务市场 | | 应用场景 | 数据库集成 | 通过MCP服务实现大模型对MySQL/ES/Redis等数据库的操作能力 | | | 自动化测试 | 集成Puppeteer等工具实现网页自动化操作的MCP应用场景 |

Spring AI 源码解析：MCP链路调用流程及示例¶

https://java2ai.com/blog/spring-ai-mcp-desc

类别	词条/概念	详细说明
协议相关	MCP (Model Context Protocol)	模型上下文协议，用于AI模型与外部系统交互的标准化协议，定义工具调用、资源访问等规范。
	LATEST_PROTOCOL_VERSION	MCP协议的最新版本号，在初始化阶段用于版本协商。
	协议版本协商	客户端与服务端在初始化时交换支持的协议版本，选择双方兼容的版本进行通信。
客户端组件	McpClient	客户端工厂类，提供同步/异步客户端创建方法，支持配置请求超时、客户端能力、工具发现、资源访问等功能。
	McpAsyncClient	异步客户端实现，基于Project Reactor的Mono/Flux类型，支持非阻塞操作，如工具调用、资源订阅等。
	McpSyncClient	同步客户端实现，封装McpAsyncClient提供阻塞式操作，功能与异步客户端一致。
	SyncSpec/AsyncSpec	客户端配置构建器类，分别用于同步/异步客户端的超时、能力、根路径等参数设置。
服务端组件	McpServer	服务端工厂类，支持同步/异步服务端构建，提供工具暴露、资源管理、提示模板管理等功能。
	McpAsyncServer	异步服务端实现，基于非阻塞操作处理客户端请求，支持动态添加工具/资源/提示，并通过通知机制推送变更。
	McpSyncServer	同步服务端实现，封装McpAsyncServer提供阻塞式操作，功能与异步服务端一致。
	AsyncSpecification/SyncSpecification	服务端配置构建器类，用于定义服务端信息、能力、工具/资源/提示处理器等参数。
传输层	McpTransport	传输层核心接口，管理连接生命周期（连接/关闭）和消息处理，支持自定义传输机制实现。
	McpClientTransport	客户端传输层接口，扩展McpTransport，定义连接方法，用于建立客户端与服务器的通信通道。
	StdioClientTransport	基于标准输入输出的传输实现，通过子进程stdin/stdout通信，支持启动外部服务器进程并处理JSON-RPC消息流。
功能模块	工具调用 (callTool)	客户端通过指定工具名称和参数调用服务端工具，服务端通过注册的处理器执行具体逻辑。
	资源访问 (listResources/readResource)	客户端可列出服务端资源列表或读取特定资源内容，资源包括文件、数据库等上下文数据。
	提示模板管理 (listPrompts/getPrompt)	服务端提供结构化提示模板，客户端可按名称获取模板内容，用于标准化与AI模型的交互。
	根路径管理 (Root)	客户端配置的根URI集合，标识可访问的资源路径，支持动态添加/移除并触发通知。
配置与初始化	Initialization	客户端与服务端建立连接时的初始化流程，协商协议版本、交换能力信息，并确认双方实现细节。
	ClientCapabilities	客户端能力声明，包含支持的协议功能（如工具调用、资源订阅等），在初始化时与服务端能力匹配。
	ServerCapabilities	服务端能力声明，描述支持的功能（如工具暴露、资源提供等），客户端根据此调整交互逻辑。
	Implementation	实现信息对象，包含客户端/服务端的名称和版本号，用于初始化阶段的信息交换。
动态管理机制	变更消费者 (Change Consumers)	客户端注册的监听器，用于接收工具/资源/提示列表变更通知，支持实时更新本地状态。
	动态添加/移除 (addTool/removeResource)	服务端运行时动态注册或注销工具/资源/提示，触发列表变更通知，支持灵活扩展功能。
	通知机制 (notifyToolsListChanged)	服务端主动推送变更事件，客户端通过预定义的消费者处理变更，保持状态同步。
日志与错误处理	LoggingMessageNotification	日志消息通知对象，包含日志级别、内容等信息，客户端/服务端可通过日志消费者记录或转发日志。
	LoggingLevel	日志级别枚举（如DEBUG/INFO/WARN），客户端可设置服务端日志级别以过滤通知。
	McpError	MCP协议定义的异常类型，表示协议交互过程中的错误（如工具未找到、资源不存在等），包含错误码和详细描述。
高级功能	采样处理 (Sampling)	客户端可配置采样处理器（samplingHandler），在消息创建时执行自定义逻辑（如数据过滤或增强）。
	资源模板 (ResourceTemplate)	预定义的资源模板，服务端提供模板列表，客户端可根据模板快速生成资源请求参数。
	能力协商 (Capabilities Negotiation)	初始化阶段客户端与服务端交换能力信息，确保双方仅使用共同支持的功能，避免兼容性问题。
底层通信机制	JSON-RPC消息格式	基于JSON-RPC 2.规范的通信格式，所有MCP交互（请求/响应/通知）均封装为结构化消息，包含方法名和参数。
	双向通信流 (Bidirectional Communication)	客户端与服务端通过传输层建立双向通信通道，支持并行处理多个请求和异步通知，提升交互效率。

Spring AI 源码解析：Tool Calling链路调用流程及示例¶

概念、名词、动词、关键词分类表¶

https://java2ai.com/blog/spring-ai-toolcalling

类别	词条	详细说明
核心类	DefaultChatClient	`ChatClient` 接口的默认实现，负责处理工具调用请求，提供多种 `tools()`
方法重载，支持通过工具名称、回调对象、工具对象等方式注册工具。
接口	ToolDefinition	定义工具的元数据接口，包含工具名称、描述、输入模式（JSON
Schema），用于模型识别工具的输入参数格式。
接口	ToolCallback	工具回调接口，定义 `call()` 方法用于执行工具调用逻辑，包含
`getToolDefinition()` 获取工具元数据。
接口	ToolCallingManager	工具调用管理器接口，负责解析工具定义和执行工具调用，核心方法包括
`resolveToolDefinitions()` 和 `executeToolCalls()`。
注解	@Tool	标记方法为工具方法，支持自定义工具名称、描述、是否直接返回结果（`returnDirect`
）以及结果转换器（`resultConverter`）。
注解	@ToolParam	标记工具方法的参数，提供参数描述信息，辅助模型生成正确的输入参数。
工具类	ToolUtils	工具相关工具类，封装方法名称提取、描述生成、重复工具检测等功能。
配置类	TimeAutoConfiguration	时间工具自动配置类，通过 `@ConditionalOnProperty` 控制是否启用，注册
`GetCurrentTimeByTimeZoneIdService` 作为工具 Bean。
服务类	GetCurrentTimeByTimeZoneIdService	时间工具服务类，实现 `Function` 接口，根据时区 ID
返回当前时间，包含 `Request` 和 `Response` 记录类定义。
配置属性	WeatherProperties	天气工具配置属性类，从 `application.yml` 读取 `api-key` 配置，用于访问天气
API。
工具方法	getCityTimeMethod	在 `TimeTools` 类中定义，通过 `@Tool` 注解标记，根据时区 ID
返回当前时间。
工具回调相关	MethodToolCallback	处理带有 `@Tool` 注解方法的回调实现类，将模型响应 JSON
转换为方法参数，并通过反射执行方法调用。
工具回调相关	FunctionToolCallback	处理函数式工具的回调实现类，支持 `Function`、`Supplier`、`Consumer`
等函数类型，将输入 JSON 反序列化为指定类型后执行调用。
工具上下文	ToolContext	封装工具执行上下文信息，包含不可变的上下文数据（如历史消息记录），通过
`getToolCallHistory()` 获取工具调用历史。
工具调用管理器	DefaultToolCallingManager	`ToolCallingManager` 接口的默认实现，负责从
`ToolCallingChatOptions` 解析工具定义，执行工具调用，并构建工具上下文。
结果转换器	ToolCallResultConverter	工具结果转换接口，`DefaultToolCallResultConverter`
是其默认实现，将工具执行结果转换为 JSON 字符串。
工具注册与管理	ToolCallbackProvider	工具回调提供者接口，`MethodToolCallbackProvider` 和
`StaticToolCallbackProvider` 是其实现类，用于集中管理和提供工具回调实例。
工具执行流程	解析工具定义	从 `ToolCallingChatOptions`
中提取工具定义，确保模型能正确识别工具的输入模式。
工具执行流程	执行工具调用	根据模型响应中的 `ToolCalls`
信息，调用对应的工具回调，传递输入参数和上下文，返回执行结果。
工具实战示例	TimeController	时间工具控制器，提供 `/time/chat-tool-function` 和
`/time/chat-tool-method` 接口，分别演示函数式和注解式工具调用。
工具实战示例	WeatherController	天气工具控制器，通过 `getWeatherFunction`
工具查询天气信息，支持动态参数（城市、天数）。
相关配置	application.yml	配置文件，定义工具相关配置（如 API 密钥、启用开关），如
`spring.ai.toolcalling.time.enabled` 控制时间工具的启用。
工具方法参数	timeZoneId	`@ToolParam` 标记的参数，在 `getCityTimeMethod` 中表示时区 ID（如
`Asia/Shanghai`），由模型从用户输入中提取。
工具响应处理	ToolExecutionResult	封装工具执行结果，包含更新后的对话历史（`conversationHistory`
）和是否直接返回结果（`returnDirect`）标志。
工具调用结果	returnDirect	`@Tool` 注解的 `returnDirect` 属性，若为 `true`
，工具结果直接返回给用户，不经过模型处理。
工具回调提供者	MethodToolCallbackProvider	通过扫描带有 `@Tool` 注解的方法，生成对应的
`MethodToolCallback` 实例，支持动态注册工具。
工具定义生成	JsonSchemaGenerator	生成工具输入模式的 JSON Schema，描述参数类型和约束，如天气工具的
`city`（字符串）和 `days`（整数范围 1-14）。
工具元数据	ToolMetadata	工具元数据接口，`DefaultToolMetadata` 是其实现类，目前仅用于控制是否直接返回结果（
`returnDirect`）。
工具调用上下文构建	buildToolContext	在 `DefaultToolCallingManager` 中构建工具上下文，包含历史消息记录，供工具方法通过
`ToolContext` 参数访问。
工具执行结果处理	buildConversationHistoryAfterToolExecution	将工具执行结果添加到对话历史中，生成新的
`Message` 列表，用于模型生成最终响应。
工具调用链路	工具调用链路（核心）	描述从 `ChatClient` 调用 `tools()`
到模型生成最终响应的完整流程，包括工具注册、模型决策、工具执行、结果返回等步骤。
工具调用管理器配置	ToolCallingChatOptions	包含工具名称列表和回调列表，`resolveToolDefinitions()`
方法从中解析工具定义，合并重复项。
工具回调解析	ToolCallbackResolver	在 `DefaultToolCallingManager` 中用于按工具名称解析对应的
`FunctionCallback`，确保请求中未显式注册的工具能被动态加载。

构建智能 Web Search 应用：使用 Spring AI Alibaba 构建大模型联网搜索应用¶

类别	词条	详细说明
模块化RAG体系	Pre-Retrieval	检索前处理阶段，通过增强、改写、扩展用户输入提升检索效率
	QueryAugmenter	查询增强器，通过附加上下文数据优化原始查询，提供大模型所需的必要背景信息
	QueryTransformer	查询改写器，使用Prompt调优或大模型将用户模糊/片面的查询转化为结构化检索语句
	QueryExpander	查询扩展器，生成多个语义变体以获取不同视角的检索结果
	Retrieval	检索阶段，通过多种数据源（向量库/搜索引擎/数据库）获取与查询相关的文档
	DocumentRetriever	文档检索器，根据扩展后的查询从指定数据源（如IQS服务）获取候选文档
	DocumentJoiner	文档合并器，将多数据源/多查询变体获取的文档集合进行去重合并
	Post-Retrieval	检索后处理阶段，优化检索结果以适应大模型处理限制
	DocumentRanker	文档排序器，根据查询相关性对文档进行优先级排序（如使用DashScope的Rerank服务）
	DocumentSelector	文档选择器，过滤冗余/不相关文档以精简上下文信息
	DocumentCompressor	文档压缩器，通过内容提炼减少信息噪音和冗余数据
技术组件	Spring AI Alibaba	基于Spring框架的AI开发套件，提供RAG实现框架及阿里云服务集成
	DashScope API	阿里云模型服务平台，提供qwen-plus等大模型API接口
	阿里云IQS服务	智能搜索服务，提供联网搜索能力及结果清洗处理
	WebSearchRetriever	联网搜索检索器，封装IQS服务接口实现网页数据抓取与转换
	ConcatenationDocumentJoiner	文档合并策略实现，通过唯一性校验防止重复文档混入
	ReasoningContentAdvisor	内容生成顾问，控制大模型输出中推理内容的整合比例
算法模型	qwen-plus	通义千问增强版模型，用于查询改写、文档排序等NLP处理任务
	deepseek-r1	深度求索模型，专用于生成包含联网搜索结果的最终答案
数据处理	DataCleaner	数据清洗组件，对IQS返回的原始搜索结果进行格式标准化和内容过滤
	Metadata Key	文档元数据标识（如URL/标题），用于去重和溯源
开发模式	模块化RAG	将RAG流程分解为独立可配置模块（检索前/检索/检索后）的开发范式
	Advisors机制	Spring AI的流程拦截器，用于整合检索增强逻辑到对话流程
核心方法	查询增强(Query Augmentation)	通过上下文注入优化原始查询，解决语义模糊/格式不规范问题
	多查询扩展(Multi-Query)	生成多个查询变体提升检索覆盖率，突破单一查询视角限制
	文档分块(Document Chunking)	将长文档切分为语义段落，适配大模型上下文窗口限制
性能优化	Incremental Output	流式输出模式，支持逐步生成响应内容提升用户体验
	Fallback机制	异常降级策略（如排序失败时返回原始结果），保障服务可用性
工程实践	Prompt模板	结构化提示词设计（如DEFAULT_PROMPT_TEMPLATE），控制大模型处理逻辑
	API密钥管理	通过DashScope/IQS的API Key进行服务鉴权，属于系统安全配置
	结果限制(maxResults)	控制单次检索返回的最大文档数量（如WebSearchRetriever设置maxResults=2）
质量保障	相关性排序(Relevance Ranking)	通过语义匹配算法（如DashScope Rerank）确保最相关文档优先呈现
	上下文去重(Context Dedup)	基于文档元数据（如URL哈希值）的重复内容过滤机制
应用场景	联网搜索RAG	结合搜索引擎实时数据与大模型推理能力，解决传统RAG静态知识库更新延迟问题
	旅游推荐系统	典型应用案例，通过实时检索网络资源生成包含最新信息的景点推荐（如杭州旅游地标查询）
系统特性	可扩展架构	各模块（检索器/排序器等）支持自定义实现，便于对接不同数据源和算法
	多模型协同	不同模型分工协作（qwen-plus处理改写、deepseek-r1生成答案），发挥各自优势
异常处理	空上下文处理	CustomContextQueryAugmenter中allowEmptyContext配置控制空上下文场景下的查询传递逻辑
	服务容错	WebSearchRetriever在文档排序异常时自动降级返回原始结果，保障服务连续性