一次性读懂读透 Spring AI Alibaba 及 Spring AI Alibaba Admin

2025-2026 年，大模型能力正在从"尝鲜玩具"变成"生产基础设施"。对于 Java 开发者而言，Spring AI Alibaba 是将 AI 能力工程化落地的核心框架——它不仅封装了模型调用的复杂性，更提供了从 Agent 编排到可观测性的完整企业级能力栈。本文将从"为什么需要它"出发，一路深入架构源码、核心 API、实战代码，直至 Admin 管理平台的全功能拆解，帮助你建立对 Spring AI Alibaba 的全局认知和实战能力。

目录

第一部分：认知建立——为什么需要 Spring AI Alibaba

本章导读：在动手写代码之前，我们先回答三个根本问题：Java 开发者在 AI 应用开发中遇到了什么痛点？Spring AI 解决了哪些问题但还不够？Spring AI Alibaba 如何补全最后一块拼图？理解这些背景，才能在实际项目中做出正确的技术选型。

1.1 AI 应用开发的 Java 困境

当 Python 生态的开发者用 LangChain、LlamaIndex 三五行代码就能接上大模型、搭一个 RAG 应用时，Java 开发者面对的却是另一番景象。

痛点一：SDK 碎片化严重。 每家模型厂商（通义千问、DeepSeek、OpenAI、百度文心……）都提供自己的 Java SDK，接口风格各异，鉴权方式不同，错误处理逻辑也不统一。接入一个模型就要写一套适配代码，切换模型几乎等于重写。

痛点二：缺乏工程化抽象。 Python 框架已经沉淀了 Chain、Agent、Memory、Tool 等一系列工程化抽象，而 Java 侧长期缺乏对标方案。开发者不得不自己实现对话记忆管理、工具调用编排、流式输出处理等通用逻辑——这些本该是框架层面的工作。

痛点三：企业级能力缺失。 真实的业务场景要求可观测性（调用链路追踪、Token 用量统计）、高可用（重试、降级、限流）、安全合规（数据脱敏、权限控制）。这些能力在 Python 框架中往往也是短板，在 Java 侧更是几乎空白。

痛点四：中文生态薄弱。 主流 AI 框架以英文模型和海外云服务为主，对中国本土模型（通义千问系列）、云服务（阿里云百炼平台、DashScope）的支持要么没有，要么需要大量额外适配。

1.2 Spring AI 的出现与局限

2024 年，Spring 官方推出了 Spring AI 项目（spring.io/projects/spring-ai），这是 Spring 生态对 AI 应用开发的正式回应。它的核心理念是：用 Spring 的方式构建 AI 应用——统一的抽象接口、自动配置（Auto-Configuration）、依赖注入（DI）、声明式编程。

Spring AI 做了几件关键的事：定义了 ChatModel、EmbeddingModel、ImageModel 等统一接口来屏蔽不同模型提供商的差异；提供了 ChatClient Fluent API 让调用大模型变得像写 SQL 一样流畅；引入了 Advisor 机制作为拦截器链来增强 AI 交互；内置了 RAG、Function Calling、Structured Output 等核心能力的支持。

然而 Spring AI 作为一个通用框架，存在一些可以理解的局限：

  • 本土模型支持有限：对通义千问、百度文心等中国模型的集成需要社区自行贡献，官方优先级不高
  • 云服务集成不足：与阿里云百炼平台、DashScope 等国内云 AI 服务的深度集成不在其覆盖范围
  • Agent 编排能力初级：Spring AI 原生更侧重"模型调用"层面，对复杂 Agent 工作流编排的支持还在演进中
  • 管理运维工具缺失：缺乏配套的 Prompt 管理、评估测试、可观测性等生产运维工具

1.3 Spring AI Alibaba 的定位与价值主张

Spring AI Alibaba（以下简称 SAA）正是为解决上述局限而生的。它由阿里云团队主导开发，定位是：

基于 Spring AI 构建的企业级 AI 应用开发框架，深度集成阿里云通义系列模型与云原生服务，同时兼容主流开源和商业模型，提供从 Agent 开发到生产运维的完整能力栈。

可以用一个公式来理解它的价值：

Spring AI Alibaba = Spring AI 核心抽象
                  + 阿里云通义模型深度集成
                  + Agent 编排与工作流引擎
                  + 可观测性与生产保障
                  + Admin 管理平台

它不是一个"另起炉灶"的新框架，而是站在 Spring AI 肩膀上的增强层——继承了 Spring AI 的所有核心抽象和设计理念，同时向上延伸出了 Agent Framework、Graph 工作流引擎和 Admin 管理平台。

1.4 与主流框架横向对比

在做技术选型之前，我们有必要将 SAA 与当前 Java 生态中的主要替代方案做一个客观对比：

维度 Spring AI Alibaba Spring AI（原生） LangChain4j 直接调用 SDK
模型支持 通义千问全系列、DeepSeek、OpenAI、Ollama 等 OpenAI、Anthropic、Ollama 等（通义需社区插件） OpenAI、Anthropic、Google、Ollama 等 取决于具体 SDK
API 抽象 ChatClient Fluent API + Advisor 链 ChatClient Fluent API + Advisor 链 自定义 API（非 Spring 风格） 无统一抽象
Agent 能力 ReactAgent + Graph 工作流 + 多 Agent 编排 基础 ChatClient + 工具调用 AgentExecutor + 工具调用 需自行实现
RAG 支持 完整（DocumentReader → Splitter → Embedding → VectorStore → Advisor） 完整 完整 需自行实现
MCP 协议 原生支持（stdio / SSE / Streamable HTTP） 原生支持 社区支持 需自行实现
可观测性 OpenTelemetry + Micrometer + Prometheus OpenTelemetry 基础支持 有限 需自行实现
管理平台 SAA Admin（Prompt/数据集/评估/Agent/工作流/知识库管理） 无 无 无
中文生态 优秀（阿里云官方支持、中文文档完善） 一般 一般 取决于模型
学习曲线 中等（需 Spring Boot 基础） 中等 较高（非 Spring 风格） 低（但重复造轮子）
企业级特性 完善（限流、降级、灰度、多租户） 基础 基础 需自行实现

选型建议：如果你的项目基于 Spring 技术栈、需要集成中国模型、需要企业级生产保障和管理平台，SAA 是当前的最优选择。如果项目不依赖 Spring 生态且需要更灵活的定制，LangChain4j 是值得评估的替代方案。

本节小结：Java 生态在 AI 应用开发中长期缺乏统一的工程化框架。Spring AI 奠定了基础抽象，而 Spring AI Alibaba 在此基础上提供了中国模型深度集成、Agent 编排引擎、可观测性和管理平台，形成了从开发到运维的完整闭环。

第二部分：架构深度剖析——三层架构与设计哲学

本章导读：理解一个框架最快的方式是看它的架构分层。SAA 采用清晰的三层架构设计——从底层的增强型 LLM 抽象，到中间的 Graph 工作流引擎，再到顶层的 Agent Framework。本章将从源码层面剖析每一层的设计意图和核心类，帮助你建立"框架是怎么运转的"全局认知。

2.1 三层架构总览

基础层 — Augmented LLM

编排层 — Graph 工作流引擎

应用层 — Agent Framework

ReactAgent
推理+行动

Multi-Agent
多智能体协作

DeepResearch
深度研究Agent

StateGraph
状态图定义

Node / Edge
节点与边

Conditional Branch
条件分支

ChatClient
Fluent API

Advisor Chain
拦截器链

ChatModel / EmbeddingModel
模型抽象

ToolCallback
工具回调

从下到上理解：

  • 基础层（Augmented LLM）：负责与模型的一切交互。ChatClient 是开发者最常用的入口，Advisor 链提供了请求/响应的拦截增强能力，ChatModel 等接口屏蔽了不同模型提供商的差异。
  • 编排层（Graph）：提供了基于有向图（DAG）的工作流引擎。复杂的 AI 任务往往不是一次模型调用就能完成的，需要将多个步骤组织成可预测、可测试的工作流。Graph 层就是这个"流程编排引擎"。
  • 应用层（Agent Framework）：在 Graph 之上构建了 Agent 抽象。ReactAgent 实现了 ReAct（推理 + 行动）范式，让智能体能够自主推理下一步该做什么、调用哪个工具、何时给出最终答案。

2.2 基础层：Augmented LLM 详解

基础层是整个框架的"地基"，它的核心设计可以类比为 Spring MVC 中的 DispatcherServlet——所有请求最终都会经过这里。

ChatClient：你的万能入口

ChatClient 是 SAA（继承自 Spring AI）提供的 Fluent API，它把模型调用变成了一种流畅的链式编程体验：

// 最简单的对话调用
String response = ChatClient.create(chatModel)
    .prompt("解释一下什么是 RAG？")
    .call()
    .content();

// 进阶：带系统提示词、参数、流式输出
Flux<String> stream = ChatClient.create(chatModel)
    .prompt()
    .system("你是一位资深 Java 架构师，擅长用通俗的比喻解释技术概念。")
    .user("请解释 Spring AI 中的 Advisor 机制")
    .advisors(new LoggingAdvisor())        // 添加日志拦截器
    .advisors(new QuestionAnswerAdvisor(vectorStore))  // 添加 RAG 拦截器
    .stream()
    .content();

这段代码展示了几个关键设计：prompt() 方法构建提示词，system() 和 user() 分别设置系统角色和用户输入，advisors() 添加拦截器（后面详解），call() 同步调用，stream() 流式调用。

Advisor：AI 交互的拦截器链

如果说 ChatClient 是 Controller，那 Advisor 就是 Interceptor / Filter。它遵循责任链模式（Chain of Responsibility），每个 Advisor 可以在请求发送给模型前做预处理，也可以在模型返回后做后处理。

ChatModel(大模型) MemoryAdvisor RAGAdvisor LoggingAdvisor 用户请求 ChatModel(大模型) MemoryAdvisor RAGAdvisor LoggingAdvisor 用户请求 原始请求 记录请求日志 传递请求 向量检索相关文档 将检索结果注入上下文 增强后的请求 加载历史对话记忆 完整上下文请求 模型响应 传递响应 传递响应 记录响应日志并返回

SAA 内置了几类核心 Advisor：

Advisor 类型 作用 典型场景
QuestionAnswerAdvisor 将向量检索结果注入提示词，实现 RAG 知识库问答
MessageChatMemoryAdvisor 自动管理多轮对话记忆 多轮对话
LoggingAdvisor 记录请求和响应日志 调试和审计
自定义 Advisor 实现任意预处理/后处理逻辑 数据脱敏、限流、翻译
ChatModel：模型抽象的核心接口

ChatModel 是所有模型提供商的统一抽象。无论你接入的是通义千问、DeepSeek 还是 OpenAI，对上层代码来说都是同一个接口：

public interface ChatModel {
    ChatResponse call(Prompt prompt);
    Flux<ChatResponse> stream(Prompt prompt);
}

切换模型只需要修改配置文件，无需改动任何业务代码——这就是 Spring 依赖注入的威力。

2.3 编排层：Graph 工作流引擎

当你需要构建一个复杂的 AI 应用——比如"先分析用户意图 → 根据意图选择不同的处理路径 → 调用不同的工具 → 汇总结果 → 输出"——单次模型调用就远远不够了。Graph 工作流引擎就是为解决这类问题而设计的。

Graph 的核心概念：

  • StateGraph：状态图，定义整个工作流的结构
  • Node（节点）：工作流中的一个处理步骤，通常是一次模型调用或一个工具执行
  • Edge（边）：连接节点，定义执行流向
  • Conditional Edge（条件边）：根据运行时状态动态决定下一步走向
// 构建一个简单的工作流
StateGraph graph = new StateGraph(AgentState::new)
    .addNode("analyze", analyzeNode)      // 分析用户意图
    .addNode("search", searchNode)        // 搜索相关信息
    .addNode("generate", generateNode)    // 生成回答
    .addEdge(START, "analyze")           // 从起点开始
    .addConditionalEdges("analyze",       // 条件分支
        state -> state.needsSearch() ? "search" : "generate")
    .addEdge("search", "generate")        // 搜索后进入生成
    .addEdge("generate", END);           // 生成后结束

CompiledGraph app = graph.compile();

Graph 引擎的设计借鉴了 LangGraph 的理念，但完全基于 Java 和 Spring 生态实现，与 Spring 的依赖注入和自动配置无缝集成。

2.4 应用层：Agent Framework

Agent Framework 是面向开发者的最上层抽象，它的核心是 ReactAgent——实现了 ReAct（Reasoning + Acting）范式的智能体。

ReAct 的核心思路是让模型交替进行"推理"和"行动"：

  1. 思考（Thought）：模型分析当前状态，决定下一步该做什么
  2. 行动（Action）：模型调用一个工具或执行一个操作
  3. 观察（Observation）：模型获取行动的结果
  4. 重复：直到模型判断信息足够，给出最终答案

用户提问

思考
我需要查天气

行动
调用天气API

观察
北京: 28°C 晴

思考
信息已足够

最终回答
北京今天28°C,晴天

用户

SAA 还提供了更高级的 Agent 模式，如 DeepResearch（深度研究 Agent），它包含子 Agent 和拦截器（TodoList、Filesystem 等），能够自主完成复杂的研究任务。

2.5 核心设计模式

SAA 的架构中运用了多个经典设计模式，理解它们有助于你更好地使用框架甚至进行自定义扩展：

  • 策略模式（Strategy）：ChatModel 接口是策略模式的典型应用。不同的模型提供商（DashScope、OpenAI、Ollama）实现了同一个 ChatModel 接口，通过 Spring 的条件装配（@ConditionalOnProperty）在运行时切换策略。
  • 责任链模式（Chain of Responsibility）：Advisor 链是责任链模式的应用。每个 Advisor 决定是处理请求、修改请求还是传递给下一个 Advisor。
  • 工厂模式（Factory）：Spring Boot 的自动配置类（AutoConfiguration）充当工厂角色，根据配置文件中的参数自动创建和组装所需的 Bean。
  • 观察者模式（Observer）：流式输出（Streaming）基于 Reactor 的 Flux 实现，本质上是观察者模式的异步实现。

本节小结：SAA 的三层架构——Augmented LLM（基础层）、Graph（编排层）、Agent Framework（应用层）——每一层都有清晰的职责边界。ChatClient + Advisor 处理单次交互，Graph 编排复杂工作流，Agent 实现自主推理。理解这三层的关系，是深入使用 SAA 的前提。

第三部分：核心能力实战——从 Hello World 到生产级应用

本章导读：从这一章开始，我们进入实战环节。每一节都从一个具体的需求场景出发，给出完整可运行的代码示例（含 Maven 依赖、配置文件、Java 代码），并对关键代码做逐行注释。建议你在阅读时跟着代码动手实践。

3.1 快速起步：5 分钟搭建第一个 AI 对话应用

目标：创建一个能与通义千问对话的 Spring Boot 应用。

Step 1：创建项目并添加依赖

<!-- pom.xml 关键依赖 (适用于 Spring AI Alibaba 1.x) -->
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.4.0</version>
</parent>

<dependencies>
    <!-- Spring AI Alibaba Starter：一键集成通义千问 -->
    <dependency>
        <groupId>com.alibaba.cloud.ai</groupId>
        <artifactId>spring-ai-alibaba-starter</artifactId>
        <version>1.0.0.3</version>
    </dependency>
    <!-- Spring Boot Web（提供 REST API） -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
</dependencies>

Step 2：配置模型密钥

# application.yml
spring:
  ai:
    dashscope:
      api-key: ${DASHSCOPE_API_KEY}  # 从阿里云百炼平台获取
      chat:
        options:
          model: qwen-plus  # 默认使用 qwen-plus 模型
          temperature: 0.7  # 控制输出的创造性

Step 3：编写 Controller

@RestController
@RequestMapping("/ai")
@RequiredArgsConstructor
public class ChatController {

    private final ChatClient chatClient;

    // 同步对话
    @GetMapping("/chat")
    public String chat(@RequestParam String message) {
        return chatClient.prompt()
            .user(message)
            .call()
            .content();  // 提取文本内容
    }

    // 流式对话（SSE）
    @GetMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public Flux<String> stream(@RequestParam String message) {
        return chatClient.prompt()
            .user(message)
            .stream()
            .content();  // 返回文本流
    }
}

启动应用后访问 http://localhost:8080/ai/chat?message=你好 即可看到模型返回的回答。流式接口可以通过浏览器的 EventSource API 或 curl 来测试。

3.2 多模型接入与运行时切换

SAA 的一大优势是支持多模型接入，并且可以在运行时切换。除了通义千问，你还可以接入 DeepSeek、OpenAI、本地 Ollama 等。

<!-- 添加 Ollama 支持 -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-ollama-spring-boot-starter</artifactId>
</dependency>

<!-- 添加 OpenAI 支持 -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
</dependency>

# application.yml - 多模型配置
spring:
  ai:
    dashscope:
      api-key: ${DASHSCOPE_API_KEY}
    ollama:
      base-url: http://localhost:11434
      chat:
        model: qwen2.5:7b  # 本地运行的模型
    openai:
      api-key: ${OPENAI_API_KEY}
      chat:
        options:
          model: gpt-4o

在代码中通过指定不同的 ChatModel Bean 来切换模型：

@Service
@RequiredArgsConstructor
public class MultiModelService {

    // Spring 会根据配置自动注入不同的 ChatModel 实现
    @Qualifier("dashScopeChatModel")
    private final ChatModel qwenModel;

    @Qualifier("ollamaChatModel")
    private final ChatModel ollamaModel;

    public String chatWithQwen(String message) {
        return ChatClient.create(qwenModel).prompt().user(message).call().content();
    }

    public String chatWithLocal(String message) {
        return ChatClient.create(ollamaModel).prompt().user(message).call().content();
    }
}

3.3 多轮对话与 ChatMemory

真实场景中的对话不是一次性的问答，而是多轮交互。用户说"他"的时候，模型需要知道"他"指的是谁。这就需要对话记忆（ChatMemory）。

@Configuration
public class ChatMemoryConfig {

    @Bean
    public ChatMemory chatMemory() {
        // InMemoryChatMemory 适用于开发和测试
        // 生产环境建议使用 Redis 或数据库实现
        return new InMemoryChatMemory();
    }

    @Bean
    public ChatClient chatClientWithMemory(ChatModel chatModel, ChatMemory chatMemory) {
        return ChatClient.builder(chatModel)
            .defaultAdvisors(
                new MessageChatMemoryAdvisor(chatMemory)  // 自动管理对话记忆
            )
            .build();
    }
}

使用时需要为每次对话指定 conversationId，框架会自动管理同一会话的上下文：

@GetMapping("/chat-with-memory")
public String chatWithMemory(
        @RequestParam String message,
        @RequestParam String conversationId) {
    return chatClient.prompt()
        .user(message)
        .advisors(spec -> spec.param("chat_memory_conversation_id", conversationId))
        .call()
        .content();
}

3.4 Structured Output：让大模型返回 Java 对象

在业务场景中，我们通常不希望模型返回一段自由格式的文本，而是希望它返回结构化的 Java 对象。比如让模型分析一段用户反馈，返回一个包含评分、分类、关键信息的结构化结果。

// 定义结构化输出的 Java 类
public record FeedbackAnalysis(
    int rating,           // 1-5 分
    String category,      // 分类：bug / feature / compliment
    String summary,       // 摘要
    List<String> keywords // 关键词
) {}

// 调用模型，获取结构化输出
@GetMapping("/analyze-feedback")
public FeedbackAnalysis analyze(@RequestParam String feedback) {
    return chatClient.prompt()
        .user("请分析以下用户反馈：" + feedback)
        .call()
        .entity(FeedbackAnalysis.class);  // 自动反序列化为 Java 对象
}

SAA 底层会自动将 Java 类的结构信息转换为 JSON Schema，注入到模型的提示词中，引导模型输出符合格式的 JSON，然后自动反序列化为 Java 对象。整个过程对开发者透明。

3.5 Function Calling / Tool Use：让大模型"动手做事"

大模型再聪明，也有一个根本缺陷：它只知道训练数据截止那一刻的世界。它不知道今天北京的天气，查不了你的数据库，更不能帮你下单。Function Calling 就是让大模型拥有"动手能力"的机制。

核心原理：你告诉模型"你有这些工具可以用"（描述函数的名称、参数、作用），模型在推理过程中判断需要调用某个工具时，会输出一段结构化的函数调用请求，框架负责实际执行这个函数并把结果返回给模型。

// Step 1: 定义工具方法
@Component
public class WeatherTools {

    // @Tool 注解标记这是一个可供模型调用的工具
    @Tool(description = "查询指定城市的实时天气信息，包括温度、天气状况和湿度")
    public WeatherInfo getWeather(
            @ToolParam(description = "城市名称，如'北京'") String city) {
        // 实际项目中这里会调用真实的天气 API
        return weatherService.query(city);
    }
}

// Step 2: 在对话中使用工具
@GetMapping("/weather")
public String askWeather(@RequestParam String question) {
    return chatClient.prompt()
        .user(question)  // 例如："北京今天天气怎么样？"
        .tools(weatherTools)  // 注册工具
        .call()
        .content();
    // 模型会自动判断需要调用 getWeather("北京")
    // 框架执行后把结果返回给模型
    // 模型基于天气数据生成自然语言回答
}

@Tool 注解和 @ToolParam 注解是 SAA 提供的声明式工具注册方式。框架会自动提取注解中的描述信息，转换为模型能理解的函数签名。

多工具编排的场景更强大——你可以同时注册天气查询、数据库查询、邮件发送等多个工具，模型会根据用户的问题自主决定调用哪个工具、以什么顺序调用。

3.6 RAG：让大模型"读懂"你的私有知识

RAG（Retrieval Augmented Generation，检索增强生成）是 AI 应用中最核心的模式之一。它解决的是大模型"不知道你的私有数据"的问题——比如公司内部文档、产品手册、历史工单等。

RAG 全链路：

在线阶段（Retrieval & Generation）

离线阶段（Indexing）

文档加载
DocumentReader

文档切分
DocumentSplitter

向量化
EmbeddingModel

存储
VectorStore

用户提问

问题向量化

相似度检索

检索结果
注入上下文

模型生成
回答

离线阶段——构建知识库：

@Service
@RequiredArgsConstructor
public class KnowledgeBaseService {

    private final VectorStore vectorStore;
    private final EmbeddingModel embeddingModel;

    public void buildKnowledgeBase(Resource document) {
        // 1. 加载文档
        DocumentReader reader = new TikaDocumentReader(document);
        List<Document> documents = reader.get();

        // 2. 切分文档（按 Token 数量切分，保留重叠区域）
        DocumentSplitter splitter = new TokenTextSplitter(
            800,   // 每块最大 Token 数
            200,   // 重叠 Token 数
            5,     // 最小块大小
            10000, // 最大块大小
            true   // 保留段落完整性
        );
        List<Document> chunks = splitter.apply(documents);

        // 3. 向量化并存储（VectorStore 会自动调用 EmbeddingModel）
        vectorStore.add(chunks);
    }
}

在线阶段——基于知识库的问答：

@Service
@RequiredArgsConstructor
public class RagQaService {

    private final ChatClient chatClient;
    private final VectorStore vectorStore;

    public String answer(String question) {
        return chatClient.prompt()
            .user(question)
            .advisors(new QuestionAnswerAdvisor(vectorStore,
                SearchRequest.builder()
                    .topK(5)              // 检索最相关的 5 个文档块
                    .similarityThreshold(0.7)  // 相似度阈值
                    .build()))
            .call()
            .content();
    }
}

QuestionAnswerAdvisor 是一个内置的 RAG Advisor。它在请求发送给模型之前，自动用用户的问题去向量数据库做相似度检索，把检索到的相关文档注入到提示词的上下文中。模型看到这些上下文后，就能基于你的私有数据给出回答。

向量数据库选型：

向量数据库 特点 适用场景 SAA 集成方式
Milvus 专业向量数据库，支持亿级向量 大规模生产环境 spring-ai-milvus-store
Elasticsearch 全文检索 + 向量混合搜索 已有 ES 集群的团队 spring-ai-elasticsearch-store
Redis 内存级速度，适合低延迟场景 实时检索、小规模数据 spring-ai-redis-store
PgVector PostgreSQL 扩展，运维简单 已有 PG 的团队 spring-ai-pgvector-store
SimpleVectorStore 内存实现，无需额外依赖 开发和测试 spring-ai-core（内置）

3.7 Agent 智能体开发

Agent（智能体）是当前 AI 应用开发中最热门的方向。与普通的大模型调用不同，Agent 能够自主规划任务、调用工具、观察结果、迭代推理，直到完成复杂目标。

ReAct Agent 实战：

@Service
@RequiredArgsConstructor
public class AssistantAgent {

    private final ChatModel chatModel;
    private final WeatherTools weatherTools;
    private final OrderTools orderTools;

    public String handleRequest(String userRequest) {
        // 构建 ReactAgent
        ReactAgent agent = ReactAgent.builder()
            .chatModel(chatModel)
            .tools(weatherTools, orderTools)  // 注册可用工具
            .maxIterations(10)                // 最大推理轮次
            .build();

        // Agent 会自主决定：
        // 1. 是否需要调用工具
        // 2. 调用哪个工具、传什么参数
        // 3. 根据工具返回结果继续推理还是给出最终答案
        return agent.run(userRequest);
    }
}

多 Agent 协作：对于更复杂的场景，SAA 支持多个 Agent 协作完成任务。比如一个 Agent 负责信息收集，另一个负责数据分析，第三个负责报告生成——它们通过 Graph 工作流编排在一起。

3.8 MCP 协议：标准化的工具集成

MCP（Model Context Protocol，模型上下文协议）是 Anthropic 提出的开放标准，旨在统一 LLM 与外部工具/数据源的集成方式。可以把它理解为 AI 领域的"USB 接口标准"——只要工具实现了 MCP 协议，任何支持 MCP 的模型都能即插即用。

SAA 原生支持 MCP，提供了三种传输协议：

  • stdio：通过标准输入输出通信，适用于本地工具
  • SSE（Server-Sent Events）：基于 HTTP 的单向推送，适用于远程服务
  • Streamable HTTP：基于 HTTP 的双向通信，最新的推荐方式
<!-- 添加 MCP 客户端支持 -->
<dependency>
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>spring-ai-alibaba-starter-mcp-client</artifactId>
</dependency>

# 配置 MCP Server
spring:
  ai:
    mcp:
      client:
        stdio:
          servers:
            weather-server:
              command: npx
              args:
                - "-y"
                - "@modelcontextprotocol/server-weather"

// 注入 MCP 提供的工具
@Service
@RequiredArgsConstructor
public class McpChatService {

    private final ChatClient chatClient;
    private final ToolCallbackProvider mcpToolCallbackProvider;

    public String chat(String message) {
        return chatClient.prompt()
            .user(message)
            .toolCallbacks(mcpToolCallbackProvider.getToolCallbacks())  // 注册 MCP 工具
            .call()
            .content();
    }
}

3.9 可观测性：生产环境的生命线

AI 应用上生产，最大的挑战之一就是"出了问题怎么排查"。传统的 APM 工具只关注 HTTP 调用链路，但 AI 应用的链路更复杂——一个用户请求可能经过多次模型调用、工具执行、向量检索，每一步都需要可追踪。

SAA 集成了 OpenTelemetry + Micrometer + Prometheus，提供了完整的可观测性能力：

# application.yml - 可观测性配置
management:
  otlp:
    tracing:
      endpoint: http://localhost:4318/v1/traces  # OTel Collector 地址
  tracing:
    sampling:
      probability: 1.0  # 采样率（1.0 = 100%）
  metrics:
    export:
      prometheus:
        enabled: true
  endpoints:
    web:
      exposure:
        include: health,metrics,prometheus,traces

通过可观测性面板，你可以看到：

  • 链路追踪：一次用户请求经过了哪些 Advisor、调用了哪个模型、耗时多少、Token 消耗多少
  • 指标监控：QPS、平均延迟、P99 延迟、错误率
  • Token 统计：每次调用消耗的 prompt token 和 completion token，用于成本核算
  • 异常告警：模型超时、限流触发、错误响应等事件的实时告警

本节小结：SAA 的核心能力覆盖了 AI 应用开发的完整链路——从最基础的对话调用，到多模型切换、多轮记忆、结构化输出、工具调用、RAG、Agent 编排、MCP 集成，再到生产环境的可观测性。每一个能力都通过 Spring Boot 的自动配置和依赖注入做到了"开箱即用"。

第四部分：Spring AI Alibaba Admin——AI 应用的一站式管理平台

本章导读：前面的章节讲的是"如何开发 AI 应用"，而 Admin 平台解决的是"如何管理、评估和运维 AI 应用"。它是 SAA 生态中一个独立但紧密关联的项目，提供了可视化的 Prompt 管理、Agent 编排、模型评估、可观测性等能力。对于团队协作和生产运维来说，Admin 几乎是必选项。

4.1 Admin 平台概述

Spring AI Alibaba Admin（以下简称 SAA Admin）是一个 AI Agent 开发与评估平台。它的出现解决了一个很现实的问题：

当你用 SAA 框架开发了十几个 AI Agent，每个 Agent 有自己的一套 Prompt、工具配置、模型参数，你怎么管理它们？怎么评估它们的效果？怎么在出问题的时候快速定位？

SAA Admin 提供的答案是：一个可视化的管理平台，覆盖 AI 应用的全生命周期——从 Prompt 调试到 Agent 上线，从效果评估到生产监控。

它与 SAA 框架的关系可以类比为 Spring Boot Admin 与 Spring Boot 的关系：框架负责运行时能力，Admin 平台负责管理和可观测性。

4.2 部署与接入

环境要求：

  • Java 17+
  • Maven 3.8+
  • Docker（用于启动依赖的数据库和中间件）
  • 有效的模型 API Key（DashScope / OpenAI 等）

部署步骤：

# 1. 克隆仓库
git clone https://github.com/alibaba/spring-ai-alibaba.git
cd spring-ai-alibaba/community/admin

# 2. 启动依赖服务（数据库等）
sh start.sh  # 通过 Docker Compose 启动 MySQL、Nacos 等

# 3. 配置模型密钥
# 编辑 model-config.yaml，填入你的 API Key

# 4. 启动 Admin 服务
mvn spring-boot:run

启动成功后访问 http://localhost:8080 即可进入 Admin 管理界面。

业务应用接入：你的 SAA 业务应用需要通过 Nacos 注册到 Admin 平台，并添加 OpenTelemetry 依赖以推送链路数据：

<!-- 业务应用添加可观测性依赖 -->
<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-tracing-bridge-otel</artifactId>
</dependency>
<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-exporter-otlp</artifactId>
</dependency>

4.3 核心功能模块详解

4.3.1 Prompt 管理

Prompt（提示词）是 AI 应用最重要的"配置"之一。同一个模型，不同的 Prompt 可能带来截然不同的效果。SAA Admin 提供了专业的 Prompt 管理功能：

  • 版本管理：对 Prompt 进行版本化管理，记录每次修改，支持回滚
  • A/B 测试：同时运行多个 Prompt 版本，对比效果
  • 在线调试：在管理界面上直接输入测试数据，实时查看模型输出
  • 模板变量：支持 Prompt 模板中使用变量（如 {{user_name}}、{{context}}），在运行时动态替换
4.3.2 模型配置管理

统一管理所有接入的模型配置：

  • 多模型统一视图：在一个界面看到所有已接入的模型（通义千问、DeepSeek、OpenAI 等）
  • 参数调优：可视化调整 temperature、top_p、max_tokens 等参数，实时预览效果
  • 模型路由策略：配置不同场景使用不同模型的规则（如简单问题用轻量模型，复杂问题用旗舰模型）
4.3.3 智能体管理

对 SAA 框架开发的 Agent 进行统一管理：

  • Agent 注册：自动发现通过 Nacos 注册的 Agent 实例
  • 生命周期管理：启动、停止、重启 Agent
  • 运行监控：查看 Agent 的运行状态、处理请求数、平均耗时
  • 配置热更新：在线修改 Agent 的配置（如工具列表、Prompt 模板），无需重启
4.3.4 工作流编排

基于 SAA 的 Graph 引擎，SAA Admin 提供了可视化的工作流设计器：

  • 拖拽式设计：通过拖拽节点和连线来设计工作流，无需编写代码
  • 节点类型丰富：LLM 调用节点、工具调用节点、条件分支节点、人工审核节点等
  • 在线测试：设计完成后可以直接在线运行测试
  • 版本管理：工作流也有版本管理，支持灰度发布
4.3.5 知识库管理

RAG 场景中知识库的管理平台：

  • 文档上传：支持 PDF、Word、Markdown、TXT 等多种格式
  • 向量化配置：选择 Embedding 模型、设置切分策略（块大小、重叠度）
  • 知识库检索测试：在线输入查询，测试检索结果的准确性和相关性
  • 多知识库隔离：为不同的业务场景创建独立的知识库
4.3.6 MCP / 插件 / 组件管理

统一管理所有可供 Agent 调用的工具：

  • MCP Server 注册：注册 MCP 协议的工具服务
  • 插件市场：浏览和安装社区贡献的插件
  • 权限控制：控制哪些 Agent 可以使用哪些工具
  • 调用审计：记录每个工具的调用次数、成功率、平均耗时
4.3.7 数据集与评估器

AI 应用的质量需要量化评估：

  • 数据集管理：创建和管理评测数据集（问题 + 期望答案的集合）
  • 评估器配置：配置评估指标（准确率、相关性、流畅度等）
  • 自动化评测：批量运行评测数据集，自动计算各维度得分
  • 实验对比：对比不同 Prompt、不同模型、不同配置下的评测得分变化
4.3.8 可观测性面板

比框架层面的可观测性更加直观：

  • 调用链路可视化：在 Web 界面上看到完整的请求链路图
  • Token 消耗分析：按模型、按 Agent、按时间段统计 Token 消耗和费用
  • 异常告警：配置告警规则（如错误率超过 5%、平均延迟超过 3 秒），触发通知
  • 使用趋势：可视化的 QPS、延迟分布、错误率趋势图
4.3.9 Dify 工作流转换

对于已经在 Dify 平台上构建的工作流，SAA Admin 提供了迁移工具：

  • 导入 Dify DSL：直接导入 Dify 导出的工作流定义文件
  • 自动转换：将 Dify 的节点和连线转换为 SAA Graph 的等价结构
  • 差异调整：对于无法自动转换的部分（如 Dify 特有的节点类型），标记出来供手动调整

这个功能对于"想从 Dify 迁移到 SAA 但又不想重新搭建工作流"的团队来说非常实用。

4.3.10 账号与 API 管理

多团队协作场景下的治理能力：

  • 多租户：不同团队使用独立的工作空间，数据隔离
  • 权限控制：基于角色的访问控制（RBAC）
  • API Key 管理：为外部系统生成 API Key，设置调用频率限制

4.4 Admin 实战：从模型接入到 Agent 上线

让我们通过一个完整的场景来串联 Admin 平台的使用流程：

场景：为客服团队搭建一个智能问答 Agent。

Step 1：在 Admin 平台中配置通义千问 qwen-max 模型，设置好 API Key 和基础参数。

Step 2：上传客服知识库文档（产品手册、FAQ 文档），创建知识库并完成向量化。

Step 3：在 Prompt 管理模块中创建系统提示词，定义 Agent 的角色和行为规则。

Step 4：在工作流编排器中设计流程——用户提问 → 知识库检索 → 判断是否有把握回答 → 有把握则直接回答，无把握则转人工。

Step 5：注册需要的工具（订单查询工具、退款申请工具）。

Step 6：创建评测数据集（包含 100 个真实客服问题和期望答案），运行自动化评测。

Step 7：根据评测结果调优 Prompt 和检索参数，反复迭代直到满意度达标。

Step 8：上线 Agent，在可观测性面板中持续监控运行状态。

这个流程覆盖了 Admin 平台的大部分核心功能，也体现了它作为"AI 应用 DevOps 平台"的价值。

本节小结：SAA Admin 不是 SAA 框架的"附加品"，而是企业级 AI 应用落地不可或缺的一部分。它把 Prompt 管理、Agent 编排、模型评估、可观测性等原本散落在代码和配置文件中的工作，统一收敛到了一个可视化管理平台，极大地提升了团队协作效率和生产运维能力。

第五部分：进阶与生态——成为 Spring AI Alibaba 高手

本章导读：掌握了核心能力和 Admin 平台之后，本章将带你进入进阶领域——源码导读、自定义扩展、性能优化、企业级最佳实践，以及 SAA 在阿里云 AI 生态中的位置和未来方向。

5.1 源码导读：一次请求的完整旅程

理解一个框架最好的方式是追踪一次请求从入口到出口的完整调用链。让我们以一个带 RAG 的对话请求为例：

用户请求: "Spring AI Alibaba 支持哪些向量数据库？"
    │
    ▼
ChatClient.prompt().user(question)
    │  构建 Prompt 对象，包含用户消息
    │
    ▼
Advisor Chain（拦截器链）
    ├── LoggingAdvisor: 记录请求日志
    ├── QuestionAnswerAdvisor:
    │       ├── 将问题向量化（调用 EmbeddingModel）
    │       ├── 在 VectorStore 中做相似度检索
    │       └── 将检索到的文档块注入 Prompt 上下文
    └── MessageChatMemoryAdvisor: 加载历史对话记忆
    │
    ▼
ChatModel.call(enrichedPrompt)
    │  发送增强后的 Prompt 给模型 API
    │  （如 DashScope API → 通义千问）
    │
    ▼
模型返回 ChatResponse
    │  包含生成的文本、Token 用量、结束原因等
    │
    ▼
Advisor Chain 反向处理
    ├── MessageChatMemoryAdvisor: 保存本轮对话到记忆
    ├── QuestionAnswerAdvisor: （无后处理）
    └── LoggingAdvisor: 记录响应日志和 Token 消耗
    │
    ▼
返回最终文本给用户

在这个过程中，几个关键源码类值得关注：

  • ChatClient.DefaultChatClient：ChatClient 的默认实现，负责构建和执行请求
  • DefaultAdvisorChain：Advisor 链的执行引擎，按 order 排序依次执行
  • DashScopeChatModel：通义千问模型的具体实现，封装了 DashScope API 调用
  • QuestionAnswerAdvisor：RAG 的核心 Advisor，协调 VectorStore 检索和上下文注入

5.2 自定义扩展

SAA 的设计鼓励扩展。以下是最常见的三个扩展点：

自定义 Advisor：

// 自定义 Advisor：敏感信息脱敏
public class SensitiveDataAdvisor implements CallAroundAdvisor, StreamAroundAdvisor {

    @Override
    public AdvisedResponse aroundCall(AdvisedRequest request, CallAroundAdvisorChain chain) {
        // 请求预处理：脱敏用户输入中的手机号、身份证等
        AdvisedRequest sanitizedRequest = sanitizeRequest(request);
        // 传递给下一个 Advisor
        AdvisedResponse response = chain.nextAroundCall(sanitizedRequest);
        // 响应后处理：检查模型输出是否包含敏感信息
        return sanitizeResponse(response);
    }

    @Override
    public int getOrder() {
        return 100;  // 优先级（数字越小越先执行）
    }
}

自定义 ChatModel：如果需要接入一个 SAA 尚未内置支持的模型，可以实现 ChatModel 接口：

public class CustomChatModel implements ChatModel {

    @Override
    public ChatResponse call(Prompt prompt) {
        // 调用自定义模型 API
        // 将响应转换为 Spring AI 的 ChatResponse 格式
    }

    @Override
    public Flux<ChatResponse> stream(Prompt prompt) {
        // 流式调用实现
    }
}

自定义 ToolCallback：对于不适合用 @Tool 注解的场景（如工具列表需要动态生成），可以实现 ToolCallback 接口。

5.3 性能优化

AI 应用的性能瓶颈通常在模型调用环节（网络延迟 + 模型推理时间）。以下是几个关键的优化方向：

流式输出：始终优先使用 stream() 而非 call()。流式输出可以让用户在模型生成第一个字的时候就开始看到响应，而不是等待整个回答生成完毕。从用户体验角度，这是一个数量级的提升。

连接池管理：为模型 API 调用配置 HTTP 连接池，避免每次请求都重新建立 TCP 连接。Spring Boot 的 RestClient 支持自定义连接池配置。

语义缓存：对于相同或相似的问题，可以缓存之前的回答。SAA 的 Advisor 机制天然适合实现缓存——编写一个 CachingAdvisor，在请求到达模型之前先查缓存，命中则直接返回。

并发控制：当多个用户同时请求时，需要通过信号量或令牌桶算法控制并发数，避免超出模型的 QPS 限制导致限流错误。

5.4 企业级最佳实践

多租户架构：通过 SAA Admin 的多租户功能，为不同业务团队创建独立的工作空间。每个团队有自己的 Prompt、知识库、Agent 配置，数据完全隔离。

灰度发布：当需要更换模型或修改 Prompt 时，不要一次性全量切换。利用 Admin 的 A/B 测试功能，先让 10% 的流量走新配置，观察效果和稳定性后再逐步扩大比例。

安全合规：

  • 在 Advisor 链中添加数据脱敏 Advisor，确保用户输入和模型输出中的敏感信息（手机号、身份证号、银行卡号）被自动脱敏
  • 通过 API Key 管理功能，为外部系统分配最小权限的访问凭证
  • 配置审计日志，记录所有 AI 交互的内容用于合规审查

成本治理：

  • 利用可观测性面板的 Token 消耗分析，识别"Token 大户"
  • 配置模型路由策略：简单问题使用低成本模型（如 qwen-turbo），复杂问题使用旗舰模型（如 qwen-max）
  • 设置 Token 预算上限，超出后自动降级或限流

5.5 生态全景

SAA 在阿里云 AI 生态中的位置：

模型层

云平台层

框架层

开发者层

Java 开发者

Spring AI Alibaba

SAA Admin

百炼平台
模型服务市场

DashScope
模型 API 网关

Nacos
服务发现与配置

通义千问系列

DeepSeek

开源模型
Qwen/Llama/GLM
  • 百炼平台：阿里云的模型服务市场，提供模型微调、评估、部署等全生命周期管理
  • DashScope：阿里云的模型 API 网关，统一接入各种模型
  • Nacos：阿里开源的服务发现和配置管理中间件，SAA 用它来实现 Agent 注册和配置管理
  • PAI（机器学习平台）：阿里云的机器学习平台，提供模型训练和推理能力

SAA 是连接 Java 开发者和这些云服务之间的桥梁。

5.6 社区与未来展望

SAA 目前处于快速迭代期（1.x 版本），社区活跃度很高。根据目前的发展趋势，几个值得关注的方向：

  • Spring AI 2.0 对齐：随着 Spring AI 2.0 的发布（要求 Java 21+、支持虚拟线程和 AOT 编译），SAA 也会跟进适配
  • Graph 引擎增强：更丰富的节点类型、更强大的条件编排、更好的可视化支持
  • 多模态支持：对图像理解、语音交互、视频分析等多模态能力的集成
  • A2A 协议：Agent-to-Agent 通信协议的支持，实现跨系统的 Agent 协作
  • 社区插件生态：更多社区贡献的工具插件、模型适配器、向量数据库集成

本节小结：SAA 不只是一个框架，而是一个完整的生态——框架提供开发能力，Admin 提供管理能力，阿里云服务提供运行能力。理解这个全景，才能在实际项目中充分利用它的价值。

附录

附录 A：Spring AI Alibaba 常用配置项速查表

spring:
  ai:
    dashscope:
      api-key: ${DASHSCOPE_API_KEY}        # DashScope API 密钥
      chat:
        options:
          model: qwen-plus                  # 模型名称
          temperature: 0.7                  # 温度（0-1，越高越随机）
          top-p: 0.8                        # 核采样概率
          max-tokens: 2048                  # 最大输出 Token 数
      embedding:
        options:
          model: text-embedding-v3          # Embedding 模型
      image:
        options:
          model: wanx-v1                    # 图像生成模型

# 可观测性
management:
  otlp:
    tracing:
      endpoint: http://localhost:4318/v1/traces
  tracing:
    sampling:
      probability: 1.0

# MCP 配置
  ai:
    mcp:
      client:
        stdio:
          servers:
            my-server:
              command: npx
              args: ["-y", "@my-mcp-server"]

附录 B：常见问题排查指南

Q1：调用模型报错 “Invalid API Key”
检查 DASHSCOPE_API_KEY 环境变量是否正确设置。可以在百炼平台（dashscope.console.aliyun.com）重新生成 API Key。

Q2：RAG 检索结果不相关
调高 similarityThreshold（如从 0.5 调到 0.7），减少 topK 数量，或尝试更换更高质量的 Embedding 模型。同时检查文档切分策略——块太大或太小都会影响检索质量。

Q3：Function Calling 没有被触发
检查 @Tool 注解的 description 是否足够清晰。模型是根据工具描述来判断是否需要调用的，描述越准确，触发率越高。同时确认模型支持 Function Calling（qwen-plus 和 qwen-max 支持）。

Q4：流式输出中断或不完整
检查网络连接的稳定性。流式输出依赖 SSE（Server-Sent Events）长连接，网络抖动可能导致连接中断。建议在客户端实现重连机制。

Q5：Admin 平台无法发现 Agent
确认业务应用已正确配置 Nacos 注册中心，且与 Admin 平台连接的是同一个 Nacos 实例。检查 spring.ai.alibaba.agent.proxy.nacos 相关配置。

附录 C：推荐学习路线图

专家（持续）

高级（1-2 月）

进阶（2-4 周）

入门（1-2 周）

Spring Boot 基础

SAA 快速起步

对话调用
同步+流式

多模型接入

Function Calling

RAG 完整链路

Agent 开发

MCP 集成

Graph 工作流

多 Agent 编排

自定义 Advisor

可观测性

Admin 平台

源码阅读

性能优化

企业级架构

社区贡献

推荐资源：

  • 官方文档：java2ai.com（SAA 官方站点，含教程和 API 文档）
  • 官方 GitHub：github.com/alibaba/spring-ai-alibaba（源码和示例）
  • Spring AI 官方文档：spring.io/projects/spring-ai（上游框架文档）
  • 阿里云百炼平台：dashscope.console.aliyun.com（获取 API Key 和模型信息）

附录 D：术语表（中英对照）

中文术语 英文术语 说明
大语言模型 Large Language Model (LLM) 如 GPT-4、通义千问等
检索增强生成 Retrieval Augmented Generation (RAG) 通过检索外部知识增强模型回答
函数调用 Function Calling / Tool Use 让模型调用外部工具
智能体 Agent 能自主推理和行动的 AI 系统
模型上下文协议 Model Context Protocol (MCP) LLM 与工具集成的开放标准
向量数据库 Vector Store / Vector Database 存储和检索向量嵌入的数据库
嵌入/向量化 Embedding 将文本转换为高维向量
提示词 Prompt 发送给模型的指令文本
温度 Temperature 控制模型输出随机性的参数
流式输出 Streaming 逐字/逐块返回生成结果
对话记忆 Chat Memory 管理多轮对话上下文
拦截器/顾问 Advisor SAA 中增强 AI 交互的拦截机制
有向无环图 Directed Acyclic Graph (DAG) 工作流引擎的基础数据结构
可观测性 Observability 链路追踪、指标监控、日志的综合能力
结构化输出 Structured Output 让模型返回符合特定格式的数据
# spring # 人工智能 # java
Logo
https://edu.csdn.net/learn/39067/627173?utm_source=2019755004

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

cover

AI写小说用什么模型最好？DeepSeek、Claude、豆包实测对比，别只盯着一个用

avatar AI编程社区
cover

[论文学习]ToolEmu:用语言模型模拟沙盒识别语言模型智能体的风险

avatar AI编程社区
cover

Grok 里面的表格怎么复制？用 AI 导出鸭安卓版告别粘贴错乱难题

avatar AI编程社区