Spring AI 全方位指南：从基础入门到高级实战

摘要

本文是一份关于 Spring AI 的综合性指南，旨在为 Java 开发者提供一个从零开始、逐步深入到高级应用的完整学习路径。文章将首先介绍 Spring AI 的核心价值、基础概念、核心依赖及基础用法。随后，将深入探讨如何通过引入智能顾问 (Intelligent Consultant) 、外部工具 (External Tools) 和 模型上下文协议 (MCP - Model Context Protocol) 等高级概念，并结合编排器 (Orchestrator) 实现复杂业务逻辑，构建能够执行复杂任务的真正智能的应用。

1. Spring AI 是什么？

Spring AI 是一个旨在简化 AI 应用开发的 Spring 项目。其核心目标是提供一个统一的、遵循 Spring 设计哲学的编程模型，让开发者可以用一套标准的接口与多种背后的大语言模型（LLM）及 AI 服务进行交互。

2. 核心依赖解析 (Maven)

要使用 Spring AI，你需要在项目中添加对应的依赖。

Spring AI BOM (Bill of Materials)

在 dependencyManagement 中引入 BOM 以统一管理版本。

xml 复制代码

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-bom</artifactId>
            <version>1.0.0-M1</version> <!-- 请使用最新版本 -->
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

核心与模型依赖
- spring-ai-spring-boot-starter: 必需的核心依赖。
- spring-ai-openai-spring-boot-starter 或 spring-ai-tongyi-spring-boot-starter: 根据你选择的 LLM 提供商添加。
MCP 与工具依赖 (关键)
- spring-ai-mcp-client-boot-starter: 在你的主 AI 应用中添加，用于连接到远程的 MCP 服务器。
- spring-ai-mcp-server-boot-starter: 用于创建一个独立的 Spring Boot 应用，作为 MCP 服务器来托管工具。

3. 基础核心概念

ChatClient / EmbeddingClient: 分别用于聊天和向量化文本的核心接口。
Prompt / PromptTemplate: 用于构建发送给模型的输入。
记忆与上下文 (Memory and Context): LLM 本身是无状态的，必须在每次请求中手动传递对话历史。
RAG (检索增强生成): 让模型基于私有知识库回答问题的技术。

4. 基础使用方式

此部分与之前版本相同，主要展示不含外部工具时的 ChatClient 基础用法。

5. 高级概念：构建智能应用核心

智能顾问 (Intelligent Consultant) - 决定"我是谁" : 通过系统提示 (System Prompt)，为 AI 设定一个精准的专家角色和行为准则。
外部工具 (External Tools) - 决定"我能做什么": 指的是 AI 可调用的 Java 方法。这些工具通过 MCP 协议暴露给 AI 模型。
模型上下文协议 (MCP - Model Context Protocol) - 连接 AI 与真实世界 :

根据 Spring AI 官方文档，MCP 是一套标准化协议 ，它使 AI 模型能够通过一致的接口 与外部工具和资源（如数据库、API）进行交互。它充当了 AI 模型与真实世界之间的桥梁。MCP 最强大的特性在于它支持客户端/服务器 (Client/Server) 架构，允许将工具的实现与 AI 的核心逻辑解耦。
编排器 (Orchestrator) - 业务流程的指挥官 :

你应用中的业务逻辑层（如@Service），负责组合"顾问"身份、管理对话历史，并利用 MCP 机制（函数调用）与外部工具交互，以完成复杂任务。

6. 高级实战：打造智能顾问

此部分与之前版本相同，主要展示如何使用 SystemMessage 设定角色。

7. 高级实战：通过 MCP 集成外部工具

MCP 提供了两种集成外部工具的方式：本地函数 和客户端/服务器架构。

方式一：本地函数 (In-Process) - 简单、一体化

这是最简单的方式，工具的定义和 AI 的调用逻辑在同一个 Spring Boot 应用中。

步骤 1: 在主应用中定义工具 Bean

java 复制代码

// 在你的主 AI 应用中
@Configuration
public class AiToolsConfig {
    @Bean
    @Description("获取指定城市的实时天气信息")
    public Function<WeatherRequest, String> weatherService() {
        return request -> {
            // ... 实际业务逻辑 ...
            return request.city() + "目前晴，25°C。";
        };
    }
}

步骤 2: 在主应用中启用工具

在 application.properties 中启用该函数。

properties 复制代码

spring.ai.openai.chat.options.model=gpt-4o
spring.ai.openai.chat.options.functions=weatherService

这种方式简单直接，适用于小型项目或工具与主业务逻辑紧密耦合的场景。

方式二：客户端/服务器架构 (Distributed) - 灵活、可扩展

这是 MCP 更强大、更推荐的用法，它将工具的实现与 AI 应用完全分离。

步骤 1: 创建一个独立的 MCP 服务器应用

这是一个全新的、独立的 Spring Boot 项目，它的职责就是托管和暴露工具。

添加依赖 : 在这个新项目的 pom.xml 中，添加 spring-ai-mcp-server-boot-starter。
暴露工具 : 使用 @McpController 和 @McpTool 注解来暴露你的工具方法。

java 复制代码

// 在 MCP 服务器应用中
import org.springframework.ai.mcp.McpController;
import org.springframework.ai.mcp.McpTool;
import org.springframework.stereotype.Component;

@Component
@McpController
public class WeatherToolProvider {

    public record WeatherRequest(String city, String unit) {}
    public record WeatherResponse(String temperature, String condition) {}

    @McpTool(name = "getRealTimeWeather", description = "获取指定城市的实时天气")
    public WeatherResponse getWeather(WeatherRequest request) {
        // ... 实际调用天气API的逻辑 ...
        return new WeatherResponse("25°" + request.unit(), "晴朗");
    }
}

配置并启动 : 在 application.properties 中配置服务器端口（例如 server.port=8081），然后像普通 Spring Boot 应用一样启动它。

步骤 2: 在主 AI 应用中配置 MCP 客户端

现在回到你的主 AI 应用（包含 ChatClient 的那个）。

添加依赖 : 确保 pom.xml 中有 spring-ai-mcp-client-boot-starter。
配置客户端 : 在 application.properties 中，不再需要 spring.ai.openai.chat.options.functions。取而代之的是配置 MCP 客户端，指向刚刚创建的服务器。

properties 复制代码

# 在主 AI 应用的 application.properties 中
spring.ai.mcp.client.base-url=http://localhost:8081 # 指向你的 MCP 服务器地址
spring.ai.mcp.client.name=weather-client
# 启用该客户端发现的工具
spring.ai.openai.chat.options.mcp=weather-client

优势

关注点分离: AI 逻辑与工具的业务逻辑完全解耦。
独立扩展: 工具服务器可以独立于 AI 应用进行部署、扩展和更新。
集中管理: 可以创建一个中央工具服务器，为公司内的多个 AI 应用提供服务。
多语言潜力: 理论上，任何能够实现 MCP 协议的服务都可以作为工具服务器。

8. 高级实战：业务编排 (Orchestrator)

无论你使用本地函数还是 C/S 架构，编排器的代码保持不变。这就是 Spring AI 抽象的强大之处。

java 复制代码

@Service
public class TravelOrchestrator {

    private final ChatClient chatClient;

    public TravelOrchestrator(ChatClient chatClient) {
        this.chatClient = chatClient;
    }

    public String planTrip(String destination) {
        String query = "我下周要去 " + destination + " 旅行，当地天气怎么样？帮我规划下行程。";
        
        // 这段代码完全不知道 getRealTimeWeather 工具是本地的还是远程的。
        // Spring AI 和 MCP 客户端在底层处理了所有发现和调用细节。
        return chatClient.call(query);
    }
}

9. 优化与最佳实践

提示工程: 依然是第一要素。
工具描述质量 : @Description 或 @McpTool 中的描述必须清晰、准确。
架构选择: 根据项目规模和团队结构，在"本地函数"和"C/S架构"之间做出明智选择。新项目或复杂系统推荐使用 C/S 架构。
上下文管理: 在长对话中，需要考虑上下文窗口限制，采用滑动窗口或总结等策略。

结论

Spring AI 通过模型上下文协议（MCP）提供了一套强大且灵活的工具集成方案。从简单的本地函数到功能完善的客户端/服务器架构，MCP 真正地将 AI 的推理能力与 Spring 应用的工程能力、以及真实世界的业务系统连接在了一起，为构建能够处理复杂、多步骤任务的下一代企业级智能应用铺平了道路。