spring-projects/spring-ai: AI 能力的企业级宿主集成¶
Spring AI 解决的核心问题不是“如何调用大模型”，而是如何将模型、向量库与工具建议，无缝且受控地集成进现有的 Spring 生态中。它将 AI 逻辑转化为 Spring 开发者熟悉的 Bean、Auto-configuration 与 Filter 模式。
1. 核心模型：ChatClient 与 Advisor 链¶
在 Spring AI 中，模型调用不再是零散的 SDK 调用，而是被抽象为了一套可插拔的执行链：
- ChatClient (应用级接口)：提供流式 API。它隐藏了不同供应商（OpenAI, Ollama, Azure）的协议差异，让业务代码只面向“意图”编程。
- Advisor (横切治理链)：这是 Spring AI 的架构灵魂。它类似于 Web 层的 Filter 或 AOP 的 Aspect，负责处理：
- Prompt 增强：自动注入 Context 或历史记录。
- 检索增强 (RAG)：在调用模型前，自动通过
VectorStore检索证据并填充。 - 可观测性：统一拦截 Metrics、Logging 与 Tracing。
- VectorStore (检索抽象)：将向量检索标准化。无论底层是 PGVector 还是 Pinecone，对宿主应用而言都是一个统一的存储接口。
2. 工程判断：为什么它是“集成框架”而非“运行时”？¶
- 生态对齐：它利用
Spring Boot的自动配置（Auto-configuration）解决模型端点与 API Key 的环境注入问题。 - 非侵入性：它允许你将 AI 能力作为一种普通的 Service 注入到现有的 Controller 或 Message Listener 中，而不必重构整个系统的控制流。
3. 与 LangChain 的受力面差异¶
- LangChain：侧重于“Agent 任务的动态编排”，倾向于让 Agent 接管控制权。
- Spring AI：侧重于“宿主系统的平滑扩展”。它假设控制权始终在 Spring 容器手中，模型只是链条中的一个组件（Component）。
4. 常见误区与失效模式¶
- 滥用 Advisor 承载复杂逻辑：将带有重副作用的业务代码（如扣费、发邮件）写在 Advisor 里，导致 AOP 链路变得极其沉重且难以调试。
- 忽略取消信号传播：虽然 Spring 提供了响应式编程支持，但如果没处理好
Flux或Mono的订阅关系，可能会导致模型调用在请求断开后依然持续运行。 - 忽略 Token 治理：过于依赖自动配置，导致在每个请求中都盲目注入全量历史记录，迅速耗尽 Context Window 并推高成本。
5. 排查顺序：从配置到链路¶
- 查 Bean 装配：
ChatClient是否注入了预期的模型版本？环境变量（API Key/URL）是否正确加载？ - 分析 Advisor 执行顺序：检索器是否在提示词模板填充之前运行？观测钩子是否捕获到了完整的请求元数据？
- 校验 VectorStore 召回：检索到的片段是否包含了关键证据？分词器是否与索引时一致？
- 查 Provider 响应：是 Spring AI 的抽象层逻辑错误，还是底层供应商返回了业务级报错（如 Content Filter）？
结论： Spring AI 是 AI 能力的“标准化转换器”。好的架构应利用其 Advisor 机制实现横切逻辑的统一收口，并将模型能力约束在 Spring 的工程治理体系之内。