前言

现在再看 Java 后端接入 AI，已经不只是“调一个大模型接口”这么简单了。

Spring AI 现在已经形成了比较完整的工程抽象。官方文档里能看到当前稳定版本线包括 2.0.0、1.1.x、1.0.x。2.0.0 是最新稳定主线，但它要求更新的 Spring 基线；如果项目仍然在 Spring Boot 3.4 或 3.5，1.1.x 仍然是更现实的生产选择。

所以这篇不是写“赶紧升级某个版本”。我更想先说清楚 Spring AI 是什么，它解决什么问题，Java 后端为什么需要这样一层抽象。

先说它不是什么

Spring AI 不是一个大模型。

它不会让模型突然变聪明，也不会替你解决业务知识质量、提示词设计、权限控制、成本治理这些问题。

它更像 Spring 生态里连接 AI 能力的一套统一工程抽象。就像 Spring Data 不是数据库，Spring AMQP 不是 RabbitMQ，Spring AI 也不是模型本身。

它主要解决的是：Java 应用如何用相对统一的方式调用不同模型、处理对话、接入 Embedding、做向量检索、实现 RAG、声明工具调用、管理结构化输出和观测模型调用。

如果只写一个 demo，直接用模型厂商 SDK 也能做。但进入真实项目后，统一抽象就很有价值。

为什么 Java 项目需要它

很多 Java 后端系统本来就有清晰分层：Controller、Service、Repository、Client、Config、Monitor。AI 能力进来以后，也应该进入这套工程结构。

如果业务代码里到处都是这样的东西：

String prompt = "请总结：" + content;
HttpRequest request = buildModelRequest(prompt, apiKey, model);
String response = httpClient.send(request);

短期能跑，长期会乱。

因为后面你一定会遇到：

1.模型要切换。 2.同一功能要 A/B 测试。 3.输入输出要审计。 4.调用要限流。 5.失败要降级。 6.token 成本要统计。 7.输出 JSON 要校验。 8.知识库要接入。

这些都不是简单 HTTP 请求能优雅处理的。

核心能力有哪些

从 Java 后端视角看，Spring AI 的核心能力可以按场景理解。

第一类是模型调用。也就是通过 ChatClient 或底层模型接口完成对话、文本生成、结构化输出。

第二类是 Embedding。把文本转换成向量，用于语义检索、相似度计算和 RAG。

第三类是向量库集成。Spring AI 提供了统一的 VectorStore 抽象，方便接 PostgreSQL/pgvector、Redis、Milvus、Elasticsearch、OpenSearch 等不同存储。

第四类是 RAG。也就是把文档读取、切分、检索、上下文组装、模型回答串起来。

第五类是工具调用。让模型在需要时调用后端声明出来的函数或服务。

第六类是 MCP。MCP 已经成为连接模型和外部工具的重要协议，Spring AI 也提供了相关支持。

这些能力合在一起，才像一个能落地的 AI 工程框架。

版本选择要现实

谈 Spring AI，一定要把版本选择说清楚。

如果你是新项目，并且整体技术栈已经准备进入更新的 Spring 基线，那么可以研究 Spring AI 2.0.0。

但如果现有后端项目还在 Spring Boot 3.4 或 3.5，我不会为了 Spring AI 2.0.0 单独推动大版本迁移。更现实的做法是使用 Spring AI 1.1.x，把 ChatClient、RAG、Embedding、VectorStore、工具调用这些能力先落到业务里。

技术选型不能只看“最新”。还要看项目当前基线、团队熟悉度、依赖兼容性和回归成本。

所以这组笔记会按当前的能力视角来写，但不会假设所有项目都已经升级到最新框架基线。

一个最小工程边界

我比较推荐先把 AI 能力放到单独的应用服务里。

比如：

public interface AiAssistantService {

    String answer(String userId, String question);
}

业务 Controller 只调用这个服务，不直接接触模型 SDK。

在实现层里再组合 ChatClient、知识库检索、工具调用和结果校验。

public class SpringAiAssistantService implements AiAssistantService {

    public String answer(String userId, String question) {
        // 检索、权限、模型调用、结果校验
        return "";
    }
}

这个边界很朴素，但很重要。它让 AI 能力像普通业务能力一样被管理，而不是散落在各个模块里。

Prompt 也要进入工程管理

很多人把 prompt 当成一段字符串。

在 demo 阶段没问题。到了生产环境，prompt 应该像配置和模板一样管理。它要有版本，要能回滚，要能和场景绑定，要能测试。

比如客服助手、合同摘要、工单分类、SQL 解释，每个场景的系统提示、输出格式、失败处理都不同。

不要把所有提示词塞到一个工具类里。更好的方式是按业务场景管理模板，并在代码里明确输入变量。

public record SummaryPromptInput(String title, String content) {
}

这样后续做效果评估、提示词调整和灰度时，边界会清楚很多。

输出不能直接信

模型输出进入业务系统前一定要校验。

比如模型返回分类结果：

public record TicketClassifyResult(
        String category,
        String priority,
        String reason) {
}

后端必须检查 category 是否在枚举里，priority 是否合法，reason 是否超长。不要因为模型“看起来很懂”就直接写库。

对高风险场景，比如自动退款、自动审批、自动发通知，模型最多参与建议，最终执行应该由规则、人或明确业务流程确认。

小结

Spring AI 已经不是简单模型调用封装，而是 Java 后端接入 AI 能力的一套工程化入口。

它解决的不是“模型聪不聪明”，而是模型调用、RAG、向量库、工具调用、结构化输出、观测和版本管理这些工程问题。

我的理解是：新项目可以关注最新 2.0.0 主线，现有 Spring Boot 3.x 项目可以用 1.1.x 稳定落地。版本不是重点，先把边界、校验、权限和观测做好，AI 功能才不会变成一堆不可控的接口调用。

Spring AI学习笔记（一）它到底解决什么问题

前言