Spring AI 介绍

这一篇把"在 Spring / Spring Boot 项目里怎么用上大模型、怎么做 Agent"这件事讲清楚:Spring AI 是什么、能解决什么、什么时候该用、什么时候不该用,以及它在整个 Java AI 生态里的位置。

1. 什么是 Spring AI

Spring AI 是 Spring 团队(VMWare / Broadcom)在 2023–2024 年推出的官方项目,目的是把大模型(LLM)能力以一套符合 Spring 编程模型的方式接入到 Java 应用里。

它做的事情可以一句话概括:

让"调用一个大模型 / 跑一个 Agent / 接一个向量库 / 做一次 RAG",在写法上跟写一个 RestTemplate / JdbcTemplate / RedisTemplate 一样熟悉。

它的核心抽象借鉴自 Python 生态中已经成熟的方案(尤其是 Spring AI 的早期 API 设计参考了 LangChain / LlamaIndex 的思路),并通过 Spring 的 ChatClient、EmbeddingModel、VectorStore 等接口把"模型无关"作为一等公民来对待。

2. 它解决的核心问题

在没有 Spring AI 之前,Java 团队接入大模型常见的痛点是:

痛点	没有 Spring AI 的典型做法	Spring AI 的对应能力
多模型切换要改业务代码	OpenAiClient / AnthropicClient 各写一套	统一 ChatModel 接口,改 starter 即可换模型
Prompt 拼接混乱	StringBuilder / 模板引擎手动拼	PromptTemplate + Message / SystemPrompt
输出不可控	自己正则 / JSON.parse 抓结果	OutputParser / BeanOutputParser 结构化映射到 POJO
函数调用靠手撕	自己 parse 工具调用 JSON 再 invoke	@Tool 注解,自动把方法注册为可调用工具
RAG 自己拼	自己读文档 -> 自己切 -> 自己嵌 -> 自己检	DocumentReader / EmbeddingModel / VectorStore 链路抽象
观测/可观测性	自己打日志	与 Spring Boot Actuator / Micrometer 集成

它不是要做一个"AI 框架",而是要让 Spring 程序员用 Spring 的方式做 AI 集成。

3. 核心模块一览

Spring AI 的能力面大致可以分成下面几块。

3.1 模型接入层(Chat / Embedding / Image / Audio)

• ChatModel:统一的对话模型接口,屏蔽了 OpenAI、Azure OpenAI、Anthropic、Google Vertex(Ollama、HuggingFace、Tongyi、DeepSeek 等也有社区 starter)。
• EmbeddingModel:统一的嵌入模型接口,用于把文本转向量。
• ImageModel / AudioModel:图像/语音多模态的接口层。
• 切换厂商的方式是换 starter 依赖 + 改配置,业务代码几乎不动。

3.2 Prompt 与消息模型

• Message 体系:SystemMessage、UserMessage、AssistantMessage、ToolResponseMessage,与 OpenAI 的多角色协议对齐。
• PromptTemplate:支持 String 模板,也能与 Spring 的 Resource 配合读取外部 prompt 文件,方便做提示词版本管理与复用。
• Advisor(顾问):类似 AOP 的"环绕"概念,在调用前后插入日志、上下文增强、问答重写、安全审查等横切逻辑。

3.3 结构化输出

• BeanOutputConverter<T>:把模型输出按 POJO / record 字段做映射。
• MapOutputConverter / ListOutputConverter:通用集合映射。
• 减少了"自己写正则 + 重试"的样板代码,是落地业务时最直接受益的一块。

3.4 工具调用(Function Calling / Tool)

• 用 @Tool 注解把一个普通 Bean 方法声明为可被模型调用的工具。
• Spring AI 会自动生成 JSON Schema、把调用结果回灌给模型、必要时多次往返直到模型给出最终回答。
• 这是构建 Agent 的基础——"模型决定什么时候调哪个工具"。

3.5 RAG(检索增强生成)

链路抽象大致对应:

外部源 -> DocumentReader -> DocumentTransformer(Optional)
       -> EmbeddingModel -> VectorStore
       -> 检索时:SearchRequest -> 相似文档 -> Advisor/上下文拼装 -> ChatModel

• 内置 VectorStore 实现:内存版、Redis、PGvector、Milvus、Chroma、Elasticsearch、Neo4j 等都有官方/社区支持。
• QuestionAnswerAdvisor / RetrievalAugmentationAdvisor 是最常用的"检索 -> 拼上下文"顾问。

3.6 可观测性

• 与 Micrometer / Spring Boot Actuator 集成,自动暴露调用次数、token 用量、延迟等指标。
• ChatModelObservation / EmbeddingModelObservation 用 Micrometer Observation API 抽象,可对接 OpenTelemetry / Zipkin / Prometheus。

3.7 MCP(Model Context Protocol)

• Spring AI 对 Anthropic 提出的 MCP 有一等公民支持,可以作为 MCP 客户端去连接外部 MCP 服务,也可以暴露自己的能力作为 MCP 服务端。
• 适合把"内部业务工具"通过标准化协议开放给多个 Agent / IDE / 编辑器使用。

4. 一个最小可运行示例

依赖(spring-boot-starter-parent + spring-ai-openai-spring-boot-starter)准备好之后,典型的"问答 + 工具调用"代码大致是这样:

@RestController
class WeatherController {

    private final ChatClient chatClient;

    WeatherController(ChatClient.Builder builder) {
        // 用户写一段"系统提示词",模型就以这个角色来对话
        this.chatClient = builder
            .defaultSystem("你是一个简洁的天气助手,优先使用工具获取真实数据。")
            .build();
    }

    @GetMapping("/ask")
    String ask(@RequestParam String q) {
        return chatClient.prompt(q)
            // tools() 把 @Tool 方法注册为可用工具
            .tools(new WeatherTools())
            .call()
            .content();
    }
}

class WeatherTools {
    @Tool(description = "根据城市名查询当前天气,返回简短描述")
    String currentWeather(String city) {
        // 真实项目里这里调第三方气象 API
        return city + " 当前晴,25°C";
    }
}

观察一下这段代码:

• 没有 httpClient.post(...) 这种样板;
• tools(new WeatherTools()) 一行就把"一个普通方法"变成了"模型可调用的工具";
• 想换模型(OpenAI -> Azure -> Ollama)只改 starter 依赖和 application.yml,Controller 一行不改。

5. 什么时候用 / 什么时候不用

5.1 推荐用

• 现有 Spring / Spring Boot 项目想接入 LLM、Agent、RAG,又不希望引入一套和 Spring 风格格格不入的框架。
• 多模型并存的场景:同时调 OpenAI 做在线问答、用开源模型做本地 RAG,用同一个 ChatModel 抽象对接。
• 企业内落地:对可观测、安全审计、依赖收敛有要求,Spring AI 与 Spring 生态天然契合。

5.2 谨慎评估

• 追求最前沿 Agent 编排能力:Spring AI 自身更偏"工程接入层",复杂 Agent 工作流(分支、并发、人机协同)需要自己用 Advisor + 状态机组合,或者结合 LangGraph4j / AgentScope 等专门框架。
• 希望"开箱即用全套 Agent":Spring AI 不会替你做完整的 Agent Runtime,这个角色更接近 LangChain4j / LangGraph4j。
• 非 Java 栈:虽然它叫 Spring AI,但本质是 Java/Kotlin,Python/JS 团队基本不会用。

6. 在 Java AI 生态里的位置

可以粗略这样分:

层次	含义	代表
模型层	真正的 LLM	OpenAI / Anthropic / DeepSeek / Qwen / Llama
运行时层	提供 Chat/Embedding/Vector/Tool 等基础设施	Spring AI / LangChain4j / LangChain4j-Python
Agent 编排层	围绕"模型做决策 + 工具被调用"的流程框架	LangGraph4j / AgentScope / Spring AI Advisor 组合
业务层	实际解决业务问题的应用	你自己的服务

Spring AI 主要在"运行时层",与 LangChain4j 是兄弟关系——两者都做"接入 + 工程抽象",思路接近但生态和 API 风格不同。一般 Spring 包袱重的项目优先 Spring AI,更松散 / 更 Agent 化的项目优先 LangChain4j。

7. 进一步阅读

• Spring AI 官方文档:https://docs.spring.io/spring-ai/reference/
• Spring AI GitHub 主仓:https://github.com/spring-projects/spring-ai
• Anthropic MCP 协议:理解 Spring AI 中"工具调用 + MCP"的来龙去脉
• 配套的本地模型运行时:参考本目录 1-模型服务/(Ollama 等),Spring AI 可直接调 Ollama 的 OpenAI 兼容端点

(后续本子分类会按需补充:Prompt 模板工程、工具调用最佳实践、RAG 流水线、MCP 客户端/服务端、可观测性等专题。)