Spring AI Alibaba 详尽教程：从入门到精通

作者

概述

Spring AI Alibaba 是阿里巴巴推出的企业级 AI 应用开发框架，致力于为 Java 开发者提供构建 AI 应用的完整解决方案。它主要解决两大核心问题：

  1. 统一接口：消除不同 AI 服务的 API 差异，支持阿里云通义千问、智谱 AI 等多种模型
  2. 企业级生态整合：提供企业级的观测、评估、MCP 集成等功能

核心功能

Spring AI Alibaba 具备以下核心能力：

  1. 基于图的多智能体框架：通过 Spring AI Alibaba Graph 构建工作流和多智能体应用，支持可视化调试和 Dify DSL 集成
  2. 企业级 AI 生态集成：支持阿里云百炼平台、ARMS 和 Langfuse 等观测产品，提供 Nacos MCP Registry 等企业级组件
  3. Plan-Act 智能体产品：包括 JManus（企业级智能体实现）和 DeepResearch（研究和报告智能体）

快速入门

环境搭建

创建项目：

  • 使用 IDEA 创建 Spring Boot 项目
  • JDK 17+、Spring Boot 3.2.x 或 3.3.x
  • 勾选 Spring Web 和 Spring Reactive Web

添加依赖

在 pom.xml 中添加：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.alibaba.cloud.ai</groupId>
            <artifactId>spring-ai-alibaba-bom</artifactId>
            <version>1.0.0.2</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
<dependencies>
    <dependency>
        <groupId>com.alibaba.cloud.ai</groupId>
        <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
    </dependency>
</dependencies>

配置文件

创建 application.yml：

spring:
  ai:
    dashscope:
      api-key: ${DASHSCOPE_API_KEY}
      chat:
        options:
          model: qwen-turbo

环境变量配置：

DASHSCOPE_API_KEY=你的阿里云API_KEY

后端代码编写

创建 WeatherController：

package com.example.weather.controller;
import com.alibaba.cloud.ai.dashscope.chat.DashScopeChatModel;
import org.springframework.ai.chat.messages.UserMessage;
import org.springframework.ai.chat.model.ChatResponse;
import org.springframework.ai.chat.prompt.Prompt;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.*;
import reactor.core.publisher.Flux;
@RestController
@RequestMapping("/weather")
public class WeatherController {
    private final DashScopeChatModel chatModel;

    private static final String SYSTEM_PROMPT = """
        你是一个专业的天气预报机器人,擅长:
        1. 解答天气相关的问题
        2. 提供天气预报建议
        3. 解释天气现象
        4. 提供合适的穿衣建议
        5. 分析天气对出行的影响
        请始终以专业、友好的口吻回答问题。如果问题与天气无关,请礼貌地提醒用户你是一个天气预报助手。
        """;

    public WeatherController(DashScopeChatModel chatModel) {
        this.chatModel = chatModel;
    }

    /**
     * 生成单次天气相关回复
     */
    @GetMapping("/generate")
    public String generate(@RequestParam(value = "message") String message) {
        String prompt = SYSTEM_PROMPT + "\n用户问题:" + message;
        return this.chatModel.call(prompt);
    }

    /**
     * 生成流式天气相关回复
     */
    @GetMapping(value = "/generateStream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public Flux<String> generateStream(@RequestParam(value = "message") String message) {
        String promptText = SYSTEM_PROMPT + "\n用户问题:" + message;
        var prompt = new Prompt(new UserMessage(promptText));
        Flux<ChatResponse> stream = chatModel.stream(prompt);
        return stream.map(chatResponse -> chatResponse.getResult().getOutput().getContent());
    }
}

MCP（Model Context Protocol）详解

什么是 MCP

MCP（Model Context Protocol，模型上下文协议）是由 Anthropic 提出的一种开放协议，旨在解决大型语言模型（LLM）与外部数据源及工具之间的无缝集成问题。它可以充当 AI 大模型与外部工具、数据源之间的”万能插座”，解决 AI 模型与外部资源（如数据库、API、本地文件等）的交互碎片化问题，统一通信规范。

MCP 架构

MCP 由三大核心模块组成：

  1. MCP Host：发起请求的 AI 应用程序，如聊天机器人、AI 驱动的 IDE、Claude Desktop 等
  2. MCP Client：作为 MCP Host 与 MCP Server 之间的桥梁，负责与 MCP Server 建立持久连接
  3. MCP Server：提供特定功能的外部程序，能够连接各种数据源，如 Google Drive、Slack、GitHub、数据库和 Web 浏览器等

MCP 的两层结构

  1. 数据层：定义基于 JSON-RPC 的客户端-服务器通信协议，包括生命周期管理以及核心原语
  2. 传输层：定义实现客户端与服务器之间数据交换的通信机制和通道

两种传输机制

  1. Stdio 传输：使用标准输入/输出流，在同一设备上实现本地进程之间的直接过程通信
  2. SSE 传输：使用 HTTP POST 用于客户端到服务器的消息，并可选使用服务器发送事件以实现流媒体功能

Spring AI Alibaba 中的 MCP 实现

Spring AI Alibaba 提供了对 MCP 的完整支持，包括：

  1. 服务端组件：spring-ai-mcp-server-spring-boot-starter（支持 stdio/SSE 双模式）
  2. 客户端组件：spring-ai-mcp-client-spring-boot-starter（自动注入 McpClient）
  3. 生态集成：兼容阿里云 DashScope 模型、高德/百度地图等第三方 MCP 服务

MCP 服务端开发示例

以天气服务为例：

  1. 依赖配置：
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-mcp-server-spring-boot-starter</artifactId>
    <version>1.0.0-M6</version>
</dependency>
  1. 配置文件（application.yml）：
spring:
  main:
    web-application-type: none  # 关闭Web应用
  ai:
    mcp:
      server:
        stdio: true  # 启用stdio模式
        name: weather-server
        version: 1.0.0
  1. 工具实现：
@Service
public class WeatherService {
    @Tool(description = "根据经纬度获取天气预报")
    public String getWeather(
        @ToolParameter(description = "纬度") String latitude,
        @ToolParameter(description = "经度") String longitude
    ) {
        // 调用OpenMeteo API并解析结果
        return "温度：" + 25 + "℃，风速：" + 2 + "m/s";
    }
}

MCP 客户端调用示例

  1. 调用本地 Stdio 服务：
spring:
  ai:
    mcp:
      client:
        enabled: true
        servers-configuration: classpath:/mcp-servers-config.json

mcp-servers-config.json：

{
  "mcpServers": {
    "weather": {
      "command": "java",
      "args": ["-jar", "weather-server.jar"]
    }
  }
}
  1. 调用远程 SSE 服务：
// 配置远程SSE服务端点
McpClient client = new DefaultMcpClient(new SseTransport("http://api.example.com/mcp"));
client.execute("getWeather", "39.9042", "116.4074");

集成第三方 MCP 服务

以高德地图为例：

  1. 申请 API Key：高德开放平台获取 AMAP_MAPS_API_KEY
  2. 配置魔搭社区 NPM 服务：
{
  "mcpServers": {
    "amap": {
      "command": "npx.cmd",
      "args": ["-y", "@amap/amap-maps-mcp-server"],
      "env": {
        "AMAP_MAPS_API_KEY": "your_key"
      }
    }
  }
}

A2A. Agent2Agent）协议详解✅

什么是 A2A

A2A. Agent2Agent）协议是由 Google Cloud 推出的一个开放协议，旨在促进不同 AI 代理之间的互操作性。其主要目标是允许这些代理在动态的、多代理的生态系统中进行有效的通信和协作，无论它们是由不同的供应商构建的还是使用不同的技术框架。✅

A2A 设计原则

  1. 拥抱代理能力：允许代理在其自然、非结构化的模式下进行协作，无需共享内存、工具或上下文
  2. 基于现有标准构建：协议建立在 HTTP、SSE 和 JSON-RPC 等广泛接受的技术标准之上
  3. 默认安全：设计支持企业级身份验证和授权
  4. 支持长时间运行的任务：灵活支持从快速任务到复杂研究的多种场景
  5. 模态无关：支持多种交互形式，包括文本、音频和视频流、form、iframe 等

A2A 的参与者

A2A 协议有三个参与者：

  1. 用户（User）：使用代理系统完成任务的用户（人类或服务）
  2. 客户端（Client）：代表用户向不透明代理请求操作的实体
  3. 服务端（Server）：不透明的远程代理，即 A2A 服务器

A2A 核心概念

Agent Card

Agent Card 是一个 JSON 文件，描述 Agent 提供的功能，官方建议托管在 https://baseurl/.well-known/agent.json。

{
  "name": "Recipe Agent",
  "description": "Agent that helps users with recipes and cooking.",
  "url": "https://example.com",
  "version": "1.0.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": true,
    "stateTransitionHistory": true
  },
  "authentication": {
    "methods": ["API_KEY"]
  }
}

任务生命周期

任务具有完整的生命周期，状态流转为：

  • submitted（已提交）
  • working（处理中）
  • input-required（需补充输入）
  • completed/failed（完成/失败）

通信机制

  1. 基础模式：HTTP + JSON-RPC 风格接口
  2. 高级功能：
  • 实时推送：SSE 协议（tasks/sendSubscribe）
  • 异步通知：Webhook 回调
  • 多模态支持：通过 Part 类型实现

A2A 与 MCP 的关系

A2A 在诞生动机、架构甚至协议方面都与 MCP 非常相似，但它们之间的关系与区别很清楚：

  • MCP 解决的是 Agent 与外部工具/数据之间的集成，是 Agent 的”内部事务”
  • A2A 解决的是 Agent 与 Agent 之间的集成，属于更高层次的集成关系
    它们之间是可以共存与协作的：Agent 通过 MCP 使用工具，Agent 与 Agent 之间则通过 A2A 产生互动与协作。

A2A 实现示例

服务端实现

@RestController
@Slf4j
public class AgentController {
    @Autowired
    private TaskService taskService;

    @GetMapping("/.well-known/agent.json")
    public Map<String, Object> getAgentCard() {
        return Map.of(
            "name", "CalculateAgent",
            "version", "1.0",
            "description", "提供计算服务",
            "endpoints", Map.of(
                "task_send", "/api/tasks/submit",
                "task_get", "/api/tasks/subscribe_sse"
            ),
            "authentication", Map.of(
                "methods", List.of("API_KEY")
            )
        );
    }

    @PostMapping("/api/tasks/submit")
    public ResponseEntity<TaskResponse> submitTask(
        @RequestHeader("Authorization") String apiKey,
        @RequestBody TaskRequest request
    ) {
        // 认证校验
        if (!"SECRET_KEY".equals(apiKey)) {
            return ResponseEntity.status(401).build();
        }

        // 异步处理任务
        CompletableFuture.runAsync(() -> 
            taskService.processTask(request.getTaskId(), request.getParams())
        );

        return ResponseEntity.accepted().body(
            new TaskResponse(request.getTaskId(), "submitted")
        );
    }
}

客户端调用

// 发现 Agent
ResponseEntity<Map> response = restTemplate.getForEntity(
    "https://agent.example.com/.well-known/agent.json", 
    Map.class
);
Map<String, Object> agentCard = response.getBody();
// 提交任务
TaskRequest request = new TaskRequest("task-123", params);
TaskResponse taskResponse = restTemplate.postForObject(
    agentCard.get("endpoints").get("task_send"),
    request,
    TaskResponse.class
);

Spring AI Alibaba 高级特性

多智能体框架

Spring AI Alibaba Graph 是一个结合了 workflow 与 autonomous agent 的框架，它帮助开发者创建 agent 和 multi-agent 工作流。核心能力包括：

  1. 工作流：使用 Spring AI Alibaba Graph 编排包含 LLM、工具等节点的工作流
  2. 多 agent 协作：创建多个 agent，它们可以相互协作，以解决复杂的业务场景
  3. 支持人为介入：通过在流程执行过程中设置中断，等待人类确认或修改状态值
  4. 支持并行分支：支持嵌套子 graph

RAG（检索增强生成）

Spring AI Alibaba 支持 RAG 开发模式，包括：

  • 离线文档处理：DocumentReader、Splitter、Embedding、VectorStore 等
  • Retrieve 检索：支持多种向量数据库

函数调用（Function Calling）

支持函数调用，可让模型动态触发业务逻辑：

@FunctionDescription(name = "generateReport", description = "根据内容生成 PDF 报告")
public String generateReport(@Parameter(description = "报告内容") String content) {
    return FileUtils.saveAsPDF(content);
}
// 注册函数并调用
public String executeTask(String input) {
    return chatClient.prompt()
        .user(input)
        .tools(this::generateReport)  // 注入函数
        .call()
        .content();
}

多轮对话与记忆管理

通过 MessageChatMemoryAdvisor 实现上下文记忆：

// 初始化带记忆的 ChatClient
public ChatController(ChatClient.Builder builder) {
    this.chatClient = builder
        .defaultAdvisors(new MessageChatMemoryAdvisor(new RedisChatMemory(redisTemplate)))
        .build();
}
// 使用 Redis 持久化对话记录
@GetMapping("/memory-chat")
public Flux<String> memoryChat(@RequestParam String sessionId, @RequestParam String input) {
    return chatClient.prompt()
        .user(input)
        .advisors(spec -> spec.param("conversationId", sessionId))
        .stream()
        .map(ChatResponse::getResult)
        .map(Generation::getOutput)
        .map(AssistantMessage::getContent);
}

企业级集成

观测与监控

Spring AI Alibaba 支持多种观测产品：

  • 阿里云 ARMS
  • Langfuse
  • 自定义监控指标

安全与认证

  1. API Key 管理：支持多种方式配置 API Key
  2. 企业级认证：集成企业认证体系
  3. 权限控制：细粒度的权限管理

微服务集成

  1. 服务发现：集成 Nacos、Eureka 等注册中心
  2. 负载均衡：支持多种负载均衡策略
  3. 熔断降级：集成 Hystrix、Sentinel 等

最佳实践

性能优化

  1. 异步处理：使用 Reactor 响应式编程
  2. 连接池管理：合理配置 HTTP 连接池
  3. 缓存策略：实现多级缓存

错误处理

  1. 重试机制：实现指数退避重试
  2. 降级策略：配置合理的降级方案
  3. 监控告警：设置完善的监控告警

部署建议

  1. 容器化部署：使用 Docker 容器化
  2. Kubernetes 编排：支持 K8s 部署
  3. 云原生集成：深度集成阿里云产品

总结

Spring AI Alibaba 为 Java 开发者提供了一个功能强大、易于使用的 AI 应用开发框架。通过本教程，我们学习了：

  1. Spring AI Alibaba 的基本概念和快速入门
  2. MCP 协议的原理和实现方式
  3. A2A 协议的核心概念和应用场景
  4. 高级特性如多智能体框架、RAG、函数调用等
  5. 企业级集成的最佳实践
    这个框架不仅简化了 AI 应用的开发，还提供了企业级的功能和可靠性，是构建生产级 AI 应用的理想选择。随着 AI 技术的不断发展，Spring AI Alibaba 将继续演进，为开发者提供更强大的功能和更好的开发体验。

发表评论

Only people in my network can comment.
人生梦想 - 关注前沿的计算机技术 acejoy.com 🐾 步子哥の博客 🐾 背多分论坛 🐾 知差（chai）网 🐾 DeepracticeX 社区 🐾 老薛主机 🐾 智柴论坛 🐾