Spring AI 多模型集成与 RAG 与 AI 工程基础

• 工具 Schema 的自动生成与精确描述
• 模型传入参数的校验与容错
• 工具执行错误的规范化回传

Schema 生成应基于方法签名自动推导，通过注解补充参数描述、必填项与类型约束，使模型能准确理解工具能力与参数要求。参数校验在工具执行前基于 Schema 的约束（类型、必填、枚举、范围）进行，对模型传入的非法参数给出明确错误。错误回传采用结构化方式：把工具执行异常转换为对模型可读的错误信息，以 ToolResponseMessage 回传，让模型据此修正参数或调整策略，而不是直接中断对话。

健壮的工具协议要闭环处理"描述→调用→失败"。Schema 决定模型能否正确调用，校验决定是否执行，错误回传决定失败后能否恢复。错误信息应结构化、可解释，让模型在下轮能自我纠正。

• 两者在框架定位上的差异
• 与 Spring 生态的契合度
• 多模型支持与工程化能力

Spring AI 是 Spring 官方推出的 AI 框架，深度融入 Spring Boot 生态，利用自动配置、依赖注入、Actuator 可观测性等能力，对已使用 Spring 的团队学习成本低、集成顺畅。LangChain4j 是社区驱动、与框架无关的库，设计上更贴近 LangChain 的理念，强调多模型适配与丰富组件，但需自行集成到 Spring 或做装配。在模型支持广度上两者都持续扩展，工程化上 Spring AI 更强调 Spring 原生体验，LangChain4j 更强调组件灵活性与跨框架使用。

选择的关键看团队栈与偏好。已在 Spring 技术栈的可优先选 Spring AI 以获得自动化配置与可观测性；需要更灵活组件或脱离 Spring 的选 LangChain4j。二者解决的问题高度重叠，差异主要在生态契合度与抽象风格。

• 文本向量化与写入的协作流程
• 写入一致性与索引更新的时序
• 故障重试与一致性兜底

协作流程是先用 EmbeddingModel 把文本编码为向量，再与元数据一起写入 VectorStore。为保证一致性，可采用"先写原始数据，再写向量"或"事务内同步编码写入"的策略，避免向量与源数据不一致。索引更新可以是同步实时，也可以是异步批量重建，需根据实时性要求选择。故障恢复上，向量写入失败应有重试与补偿（如幂等写、失败队列），索引重建可定期对账，确保新增数据能及时被检索到。

RAG 的写入链路要保证"数据可见性"与"向量新鲜度"。一致性设计决定检索结果是否反映最新数据，索引策略平衡实时性与性能，故障恢复保证链路的可靠性。三者共同决定 RAG 数据管道的健壮性。

• Claude 模型的接入配置
• 工具调用与流式支持的差异
• 与统一抽象的一致性

Spring AI 通过 spring-ai-starter-anthropic 提供 Claude 的适配，配置 API Key、模型名等属性后即可创建 ChatModel Bean。适配层处理 Claude 的协议差异，包括消息格式、streaming 流式响应、tool use 工具调用等，并映射到 Spring AI 的统一抽象。业务代码依然面向 ChatClient/ChatModel 编程，切换 Claude 只需改依赖与配置，沿用统一的 Advisor、记忆与观测能力。

适配的价值在于把 Claude 的专有协议收敛到统一接口。开发者无需关心 Claude 报文细节，即可获得与 OpenAI 等一致的编程体验，同时利用 Claude 的上下文窗口与推理能力。

• Azure OpenAI 的接入配置
• 认证（API Key/Entra ID）方式
• 通过 Azure 底座获得的企业级能力

Spring AI 通过 spring-ai-starter-azure-openai 接入 Azure OpenAI，配置端点、部署名（deployment name）与认证信息。认证可采用 API Key，也可用 Entra ID（Azure AD）的托管身份/服务主体，实现无密钥的 RBAC 认证。通过 Azure 接入能获得企业级能力，如数据驻留、私有网络、合规、内容过滤与限流治理，适合对安全合规要求高的企业场景。

Azure OpenAI 的价值不仅在于模型本身，更在于把它接入企业云基础设施。认证方式、网络隔离与治理能力是企业选择 Azure 的关键考量，Spring AI 适配让这些能力以统一编程模型暴露。

• 开源 Embedding 模型的自托管优势
• 数据隐私与成本控制
• 中文语义效果与部署方式

BGE、M3E 等开源 Embedding 模型可本地或私有化部署，避免了数据外发给第三方，满足数据隐私与合规要求，同时可按需横向扩展、控制调用成本。它们对中文语义有较好支持，能通过 ONNX 或专门的推理服务在 CPU/GPU 上运行。工程上可通过统一 EmbeddingModel 接口接入，切换不同模型只影响向量质量，不影响上层检索逻辑。

开源 Embedding 的核心价值是"数据不出域 + 成本可控"。自托管天然契合隐私敏感场景，且可通过统一抽象与闭源模型互换。选择时需评估维度、语义效果与部署资源。

• Ollama 本地模型运行方式
• 与 Spring AI 的接入
• 本地开发与离线场景的适用性

Ollama 是在本地运行开源 LLM 的引擎，可通过命令行拉取并运行模型，暴露兼容 OpenAI 的本地 API。Spring AI 通过 spring-ai-starter-ollama 接入，配置 Ollama 的 baseUrl 与模型名即可创建 ChatModel。它适合本地开发、离线环境、数据隐私要求高或成本敏感的场景，无需调用外部 API。

Ollama 的价值在于把模型部署到本地，降低接入门槛与成本。对开发调试、离线或隐私敏感场景尤为合适，但本地效果与资源受限于硬件，适合原型与轻量应用。

• 两者服务端与模型来源的差异
• 接入方式与依赖
• 场景选择依据

OllamaChatModel 对接本地 Ollama 服务，模型在本地运行，适用于开发、离线、隐私敏感场景，无需外部 API 与费用。OpenAiChatModel 对接 OpenAI 云服务，模型在云端运行，提供更强算力与更广模型能力，适合生产级、追求高质量输出的场景。二者都通过 Spring AI 统一抽象接入，业务代码差异小，主要区别在服务端位置、模型来源与成本。

差异本质是"本地 vs 云端"。选择取决于对数据隐私、成本、效果与运维的权衡：本地省成本保隐私但受硬件限制，云端效果好但需联网与付费。统一抽象使两者可平滑切换。

• Chat 对话与 Completion 补全的接入
• Embedding 向量化的接入
• 统一抽象下的 API 使用

引入 spring-ai-starter-openai 后，配置 API Key 即可获得 OpenAiChatModel 用于对话（Chat），OpenAiEmbeddingModel 用于文本向量化（Embedding）。Completion 在 Spring AI 中作为底层补全能力被 ChatModel 封装，通常不直接暴露。业务上 Chat 用于对话生成，Embedding 用于 RAG 检索与语义相似度，二者都通过统一抽象调用，切换模型提供商时无需改动业务代码。

接入的核心是"配置即用 + 统一抽象"。Chat 与 Embedding 是两类最常见的模型能力，分别支撑生成与检索，通过 starter 自动配置即可纳入工程体系。

• UserMessage 携带 Media 实现多模态
• 文本与图像的联合输入
• 多模态对应用场景的扩展

传统 UserMessage 只承载文本，多模态演进允许 UserMessage 携带 Media 对象，将图片、音频等媒体与文本一起送入多模态模型，使模型能理解图文结合的输入。Prompt 也随之支持包含多模态内容的用户消息。这一演进使应用能处理图像理解、文档 OCR、视觉问答等场景，同时要求模型与消息构造都支持多模态。

多模态的关键是消息内容类型的扩展。通过 Media 把媒体统一承载，文本与图片在同一 UserMessage 中联合输入，既保持消息结构一致，又扩展了模型能力边界。

• 模板的版本管理与复用
• 变量的声明与校验
• 渲染失败的兜底处理

模板版本管理可通过把模板作为资源文件并纳入版本控制实现，配合命名或版本号区分迭代，避免线上模板被误改。变量校验在渲染前检查必填变量是否齐全、类型是否合法，提前暴露缺失而非渲染后再报错。渲染错误处理则捕获模板语法错误、变量缺失等异常，返回明确错误或降级为默认模板，保证提示词构建链路的健壮性。

提示词也是需治理的资产。版本管理保证可追溯，变量校验前置减少运行时失败，错误处理兜底保证可用性。三者构成提示词模板的工程化治理框架。

• 文档载入、切片与向量化的离线环节
• 查询向量化与检索的在线环节
• 上下文组装与生成的增强环节

RAG 流水线分离线与在线两段。离线阶段：文档载入（DocumentReader）、切片（TokenTextSplitter）、向量化（EmbeddingModel）并写入 VectorStore 建立索引。在线阶段：用户查询同样向量化，在 VectorStore 中做相似度检索召回相关片段，再把检索结果作为上下文与用户问题组装成提示词，交给 ChatModel 生成。检索质量与上下文组装直接影响生成的事实性与相关性。

RAG 的本质是用外部知识增强生成。离线建索引保证高效召回，在线检索保证相关性，上下文组装把知识与问题结合。每一环的质量都影响最终输出，需针对切片粒度、Top-K 与提示词拼接做调优。

• Hugging Face 推理 API 的接入
• 开源模型即服务的调用
• 与统一抽象的集成

Spring AI 通过专用 starter 或自定义适配接入 Hugging Face Inference API，可调用其托管的开源模型服务。Hugging Face 提供大量开源模型（文本、嵌入、图像等），通过推理 API 免去自建部署。接入后仍可映射到 Spring AI 的 ChatModel/EmbeddingModel 抽象，便于统一使用。

Hugging Face 的价值在于庞大的开源模型生态与即用型推理服务。通过与统一抽象集成，开发者可灵活选用不同开源模型，无需自建推理基础设施。

• 国内模型的接入方式
• 私有化部署与国内网络优势
• 统一抽象的适配价值

文心一言、ChatGLM 等国内模型可通过 Spring AI 的社区适配或通用 OpenAI 兼容接口接入。这些模型在国内部署、网络可达性更好，且支持私有化部署，能满足数据本地化与合规需求。适配层把它们的协议映射到 ChatModel 统一抽象，业务代码可复用已有的 Advisor、记忆与工具能力，并可在多模型间切换。

适配价值在于把国内模型纳入统一 AI 工程体系。对需要数据本地化、国内合规或较低延迟的场景，国内模型是重要选择，统一抽象降低切换成本。

• Qwen 的接入配置
• 工具调用与流式支持
• 与统一抽象的一致性

Spring AI 通过 spring-ai-starter-alibaba（Spring AI Alibaba）或通义千问的 DashScope 兼容接口接入 Qwen 模型，配置 API Key 与模型名即可创建 ChatModel。适配支持 Qwen 的对话、流式、工具调用与 Embedding 能力，并映射到统一抽象。接入后业务代码沿用统一的 ChatClient/Advisor 体系，可复用 RAG、Agent 等上层能力。

通义千问是国内覆盖较广的模型系列，适配使其融入 Spring AI 生态。统一抽象保证接入体验一致，同时支持国内部署与合规需求。

• 对模型输出的自动评估方式
• 评估维度（相关性、忠实度等）
• 在质量回归与测试中的应用

Spring AI 的 Evaluator（评估器）用于自动评估模型输出质量，可通过 LLM-as-a-judge 或多个评估器对生成结果打分，覆盖相关性、忠实度、回答质量等维度。评估结果可用于自动化测试、质量门禁与回归对比，在提示词或模型调整后快速验证效果，替代人工逐条评审，提升 AI 应用的质量保障效率。

评估是 AI 应用工程化的关键一环。把"输出好不好"从主观判断转化为可量化的自动评估，才能支撑持续迭代与质量门禁，防止模型或提示词改动引入质量回退。

• Embedding 的向量数据结构
• EmbeddingModel 的编码抽象
• 文本到向量的调用流程

Embedding 是向量化产生的数据结构，封装了浮点向量数组与相关元数据，代表文本在高维空间中的语义位置。EmbeddingModel 是执行向量化的抽象接口，负责把文本或文档编码为 Embedding。流程上调用 EmbeddingModel 的 embed 方法，传入文本，返回对应的向量，供 VectorStore 写入或检索使用。

EmbeddingModel 是"编码器"，Embedding 是"产物"。理解二者关系才能正确设计向量化流程：模型负责编码，产生可供存储与检索的向量数据，上层统一消费。

• ImageModel 的图像生成能力
• AudioModel 的语音合成/识别
• 与统一抽象的一致使用

ImageModel 抽象图像生成能力，可根据提示词生成图片，支持尺寸、质量等参数。AudioModel 抽象语音能力，包括语音合成（TTS，文本转语音）与语音识别（STT，语音转文本）。二者与 ChatModel 一样通过自动配置创建 Bean，面向统一抽象编程，可接入不同提供商的多模态模型服务。

Image/Audio 模型把 Spring AI 从纯文本扩展到多模态生成。通过统一抽象，图像与语音能力可像 Chat 一样被工程化集成，用于内容生成、语音助手等场景。

• McpClient/McpServer 的职责边界
• 跨进程的工具发现与调用
• 工具注册的集中复用

McpServer 在服务端暴露工具、资源与提示词能力，McpClient 在客户端发现并调用这些能力，二者通过 MCP 协议（stdio 或 HTTP）跨进程交互。边界在于：服务端负责"提供"，客户端负责"发现与调用"。工具发现通过 initialize 协商与 tools/list 获取注册表，调用通过 tools/call 执行，从而让一组工具被多个进程或 Agent 复用，无需重复实现。

MCP 把工具从"进程内方法"提升为"跨进程协议能力"。通过明确的客户端/服务端边界与标准协议，工具可集中注册、声明语义、被多方发现调用，实现工程上的复用与解耦。

• Moderation 对输入输出的审核
• 不当内容的过滤与拦截
• 合规与安全治理价值

Moderation 用于对模型输入与输出进行内容审核，检测暴力、色情、仇恨言论、敏感信息等不当内容，并在命中时拦截或降级处理。可配置为对用户输入进行前置审核、对模型输出进行后置审核，形成安全防线。Spring AI 支持注入 Moderation 能力，与模型调用链集成，保障应用的内容安全与合规。

内容审核是 AI 应用的安全红线。前置审核阻止恶意输入进入，后置审核防止模型产生不当输出，双闸结合在合规与品牌保护上起到关键作用。

• 按 token 而非字符切片的原理
• 切片粒度对检索质量的影响
• 与上下文窗口的适配

TokenTextSplitter 按 token 数而不是字符数对文档进行切片，保证每个切片在模型 token 预算内，避免因 token 超限被截断。切片粒度影响检索质量：粒度过大则单块信息混杂、检索定位不准，粒度过小则语义不完整、上下文割裂。合理切片需平衡信息完整性与检索精确性，并保证切片总 token 与上下文窗口匹配。

切片是 RAG 质量的关键控制点。按 token 切分贴合模型窗口约束，切片粒度决定检索引擎的召回单元。实际中常结合重叠（overlap）避免语义断裂，并针对检索效果调优切片大小。