Spring AI 应用框架


一、框架基础定位
Spring AI 是Spring 官方出品、面向 Java/Spring 生态的生成式 AI 工程化开发框架，
2025 年 5 月发布 1.0 GA 稳定版，2026 年 6 月升级至Spring AI 2.0 GA，
核心设计思想延续 Spring 经典理念：模块化、可移植、POJO 编程、依赖注入、自动配置，
解决企业业务系统与大模型、向量库、知识库、AI Agent 打通的工程化痛点，
对标 Python 生态的 LangChain、LlamaIndex，但原生适配 Java 后端技术栈。


Spring AI核心定位
核心使命：
打通企业自有业务数据、内部 API 与各类生成式大模型，
避免开发者对接各家大模型异构 SDK、重复封装重试、鉴权、向量库适配、Prompt 管理等基建代码。

核心优势
模型无感切换：
一套业务代码，仅修改配置即可在 OpenAI、Ollama 本地模型、通义千问、DeepSeek 之间切换，类似 Spring Data 切换数据库；

Spring 生态无缝融合：
完美兼容 SpringBoot、SpringCloud、SpringSecurity、Actuator 监控、AOP、事务、配置中心；
开箱即用 AI 全链路组件：
对话、向量化、RAG 知识库、函数调用（Agent）、结构化输出、流式返回一站式封装；
生产级能力：内置请求重试、超时熔断、链路埋点（Micrometer）、日志审计、内容安全审核；

模块化可插拔：
Advisor 拦截器链实现日志、缓存、Prompt 润色、权限校验横向扩展。


二、整体三层架构


Spring AI三层架构
1. 上层：应用 API 层（开发者直接使用）
面向业务编码的流式 API，核心组件：
ChatClient：对话核心入口（Fluent 链式调用，主流使用）
PromptTemplate：Prompt 模板管理，支持变量渲染、角色设定
Structured Output：大模型输出直接映射 Java POJO 对象，手动解析 JSON
Advisor Chain：可插拔拦截器（日志、记忆、RAG 检索、安全过滤、函数调用）
Tool Calling：大模型主动调用 Java 业务方法（AI 智能 Agent 基础）

2. 中层：统一抽象层（可移植核心）
屏蔽不同模型、向量库的接口差异，定义标准接口：
模型接口：ChatModel对话模型、EmbeddingModel向量化模型、ImageModel文生图、AudioModel语音模型
向量存储接口：VectorStore统一向量库操作（插入、相似度检索、元数据过滤）
RAG 顶层封装：文档加载、文本切片、向量化入库、召回问答一体化


3. 底层：厂商实现层
对各家 AI 服务商、向量数据库做适配器实现：
（1）支持大模型厂商
公有云：
OpenAI、Anthropic Claude、Google Gemini、Azure OpenAI、AWS Bedrock、阿里通义千问、讯飞星火、DeepSeek、智谱 AI

本地私有化：Ollama（本地运行 Llama3、Qwen、Mistral 等开源模型）

模型能力覆盖：对话补全、Embedding 向量、文生图、语音转文字、TTS 语音合成、内容审核

（2）支持向量数据库
PGVector (Postgres)、Redis、Milvus、Qdrant、Chroma、Neo4j、MongoDB Atlas、Pinecone、Weaviate、Cassandra，
统一 SQL 风格元数据过滤语法。

三、核心功能模块

1. ChatClient 对话交互（最基础）
分为同步返回、SSE 流式打字机返回两种模式，SpringBoot 自动装配 Bean，直接注入使用。

2. Prompt 工程管理
硬编码 Prompt、外部文件 Prompt 模板；
系统角色 Prompt（设定 AI 身份：客服、数据分析、法律顾问）；
变量动态填充模板，避免字符串拼接。

3. 结构化输出 Structured Output
强制大模型返回固定 JSON 结构，框架直接转为 Java 实体类，用于业务结构化数据（订单分析、报表、分类标签）。

4. 对话记忆 Memory
实现多轮上下文对话，内置内存记忆、Redis 持久化记忆，适配聊天机器人会话。

5. RAG 检索增强生成（企业知识库核心）
完整链路：
文档(PDF/Markdown/Word)加载 
文本分片 
Embedding向量化 
写入Vector向量库 
用户提问向量化 
相似文档召回 
拼接上下文Prompt 
LLM回答

解决大模型知识过时、私有业务数据问答幻觉问题。


6. Function Calling 工具调用（AI Agent 核心）
大模型根据用户问题，
主动调用后端 Java 接口（查数据库、调用第三方接口、查库存、查天气），
拿到业务数据后再整理回答，实现联网、业务操作型智能助手。

Spring AI 2.0 重大升级：
将工具调用循环纳入 Advisor 链，支持自定义 Agent 执行流程、多级工具调用、失败重试逻辑。


7. Advisor 拦截器链（AOP 式增强）
全局横向能力统一处理：
对话日志记录、上下文记忆注入、RAG 自动检索前置、敏感词过滤、请求限流、耗时统计，无需修改业务对话代码。

8. 可观测性 Observability
基于 Micrometer 埋点，对接 Prometheus+Grafana 监控：
模型调用次数、token 消耗、响应耗时、向量检索耗时、异常报错大盘，适配运维告警。

9. 多模态能力
文生图、图片理解、语音转文字、文字转语音，统一接口调用。

四、SpringBoot 快速入门示例



1. Maven 依赖（Ollama 本地模型示例，私有化无 API Key）

<!-- SpringBoot 3.x 适配 -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-ollama-spring-boot-starter</artifactId>
    <version>2.0.0</version>
</dependency>


2. application.yml 配置


spring:
  ai:
    ollama:
      base-url: http://localhost:11434
      chat:
        options:
          model: qwen:7b # 本地Ollama拉取的模型名称
          temperature: 0.7 # 随机性 0严谨-1发散


3. 基础对话 Controller

@RestController
@RequestMapping("/ai")
public class AiChatController {
    // Spring自动注入ChatClient构建器
    private final ChatClient chatClient;

    public AiChatController(ChatClient.Builder builder) {
        // 全局设定AI角色
        this.chatClient = builder.defaultSystem("你是Java技术专家，回答简洁专业").build();
    }

    // 单次同步对话
    @GetMapping("/chat")
    public String chat(@RequestParam String msg) {
        return chatClient.prompt()
                .user(msg)
                .call()
                .content();
    }

    // SSE流式输出（前端打字机效果）
    @GetMapping(value = "/stream/chat", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public Flux<String> streamChat(@RequestParam String msg) {
        return chatClient.prompt()
                .user(msg)
                .stream()
                .content();
    }
}
4. 结构化 POJO 输出示例
定义返回实体：

public class ProductAnalysis {
    private String productName;
    private List<String> advantage;
    private BigDecimal suggestPrice;
    // getter/setter
}

调用代码：

ProductAnalysis analysis = chatClient.prompt()
        .user("分析一款无线耳机产品卖点与定价")
        .call()
        .entity(ProductAnalysis.class);



五、典型落地业务场景
企业私有知识库问答（RAG）
内部手册、合同、运维文档、历史工单入库，员工提问精准检索文档回答，杜绝大模型幻觉；
智能客服系统
多轮对话记忆 + 知识库 + 工具调用（查订单、物流、售后），自动接待客户，复杂工单转人工；
业务 AI 助手集成
CRM 客户意向分析、ERP 智能报表生成、后台操作自然语言转 SQL 查询；
私有化本地 AI 部署
基于 Ollama+SpringAI 搭建内网离线 AI 服务，数据不出网，金融、政务合规场景；

AI Agent 智能应用
自然语言驱动业务流程：
“帮我查询杭州今日天气，生成出行建议文案”，
自动调用天气接口 + 文案生成；

内容生产中台
营销文案、商品标题、短视频脚本、图片描述批量生成。

六、Spring AI 1.0 VS 2.0 核心升级
Agent 能力重构：工具调用循环抽离到 Advisor 链，支持自定义 Agent 编排、循环执行、条件分支；
API 一致性优化：统一各家模型入参配置，减少配置差异化；
原生 GraalVM Native 镜像支持，容器冷启动速度大幅提升；
增强可观测性：细化 Token 消耗、工具调用步骤埋点；
Prompt 重试、结构化输出失败自动重试机制。


七、与 Spring AI Alibaba 区别
原生 Spring AI：官方主干，通用模型适配，适合通用 AI 后端、私有化 Ollama 场景；
Spring AI Alibaba：
阿里生态定制分支，深度适配通义千问、阿里云向量检索、阿里云 OSS 文档存储，适配阿里云云上业务一站式 AI 落地。


八、选型总结
适合：Java 后端存量系统改造 AI 能力、企业私有化 AI、微服务 AI 中台、传统 SpringBoot 项目快速接入大模型；

不适合：纯 Python AI 算法训练、模型微调场景（Spring AI 聚焦应用层集成，不做模型训练）。