Spring AI 深度实践：Java 生态中原生 AI 应用开发的全链路解析

原创

资源大佬 jzit-top

发布于 2026-09-02 13:41:46

1780

在 AI 应用开发领域，Python 长期占据主导地位，LangChain、LlamaIndex 等框架已成为事实标准。然而，对于 Java 开发者而言，在熟悉的 Spring 生态中构建 AI 应用的需求始终存在。Spring AI 正是为此而生——它不是对 Python 项目的简单移植，而是一个从零设计的、深度融入 Spring 生态的 AI 工程框架。

本文将从 ChatClient 核心抽象、结构化输出、Tool Calling 机制、RAG 集成 到 生产级特性 五个维度，深入解析 Spring AI 的技术内核，并附上可直接运行的代码示例。

一、ChatClient：AI 交互的统一入口

ChatClient 是 Spring AI 最核心的抽象，它提供了与 WebClient、RestClient 风格一致的流式 API，让 Java 开发者用最熟悉的方式接入 AI 能力。通过 Spring Boot 的自动配置，只需注入 ChatClient.Builder 即可获得一个开箱即用的客户端。

基础调用示例：

@RestController
public class ChatController {
    private final ChatClient chatClient;

    public ChatController(ChatClient.Builder builder) {
        this.chatClient = builder.build();
    }

    @GetMapping("/chat")
    public String chat(@RequestParam String message) {
        return chatClient.prompt(message).call().content();
    }
}

一个 Controller、一个注入、一行调用——这几乎是接入大模型所需的最少代码。Spring AI 支持 OpenAI、Anthropic、Google Vertex、AWS Bedrock、Ollama 等主流提供商，切换模型只需更换依赖和配置，无需改动业务代码。

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-anthropic</artifactId>
</dependency>

spring:
  ai:
    anthropic:
      api-key: ${ANTHROPIC_API_KEY}

通过 ChatOptions 可以精细控制模型输出行为：temperature 控制随机性（0.0-0.3 适合事实问答，0.8-1.0 适合创意生成），maxTokens 限制输出长度。

二、结构化输出：从 String 到 Java 对象

大模型返回的是文本，但业务系统需要的是结构化数据。Spring AI 的 .entity() 方法可以直接将 LLM 响应映射为 Java 对象，彻底告别手动解析 JSON。

public record SentimentResult(String label, double score) {}

@GetMapping("/sentiment")
public SentimentResult analyzeSentiment(@RequestParam String text) {
    return chatClient.prompt()
        .user("分析以下文本的情感倾向，返回 JSON 格式：{\"label\": \"POSITIVE/NEGATIVE/NEUTRAL\", \"score\": 0.0-1.0}\n" + text)
        .call()
        .entity(SentimentResult.class);
}

这一能力结合系统提示（System Prompt）的引导，可以高效实现信息抽取、分类、摘要等结构化任务。

三、Tool Calling：让模型“动手”做事

大模型生活在隔离的沙盒中，无法直接访问外部数据或执行操作。Tool Calling（函数调用）让模型能够请求执行客户端定义的函数，从而获取实时信息并采取行动。这是构建 Agentic AI 系统的核心能力。

在 Spring AI 2.0 中，Tool Calling 被重构为 Advisor 链中的一等公民——ToolCallingAdvisor 是一个递归顾问，它会反复调用模型直到模型不再产生工具调用为止。

定义工具：只需在方法上添加 @Tool 注解，Spring AI 会自动生成参数的 JSON Schema。

@Component
public class WeatherTools {
    private final WeatherService weatherService;

    @Tool(description = "获取指定城市的当前天气")
    public String getWeather(String city) {
        return weatherService.fetch(city);
    }

    @Tool(description = "预订两个城市之间的航班")
    public BookingConfirmation bookFlight(
            String origin,
            String destination,
            @ToolParam(description = "日期格式：YYYY-MM-DD") String date) {
        return flightService.book(origin, destination, date);
    }
}

使用工具：将工具实例通过 .tools() 方法传递给 ChatClient。

@RestController
public class AgentController {
    private final ChatClient chatClient;
    private final WeatherTools weatherTools;

    public AgentController(ChatClient.Builder builder, WeatherTools weatherTools) {
        this.chatClient = builder.build();
        this.weatherTools = weatherTools;
    }

    @GetMapping("/agent")
    public String agent(@RequestParam String query) {
        return chatClient.prompt(query)
            .tools(weatherTools)
            .call()
            .content();
    }
}

当用户问“阿姆斯特丹天气如何？如果晴天就从伦敦订机票”，模型会自动调用 getWeather 获取天气，再根据结果决定是否调用 bookFlight——整个过程由 ToolCallingAdvisor 自动编排。

四、RAG：为模型外挂知识库

大模型无法感知企业私有数据。检索增强生成（RAG）通过在调用模型前从向量数据库中检索相关文档，为模型提供上下文依据。

Spring AI 通过 QuestionAnswerAdvisor 提供了开箱即用的 RAG 支持：

@Configuration
public class RagConfig {
    @Bean
    public ChatClient ragChatClient(ChatModel chatModel, VectorStore vectorStore) {
        var advisor = QuestionAnswerAdvisor.builder(vectorStore)
            .searchRequest(SearchRequest.builder()
                .similarityThreshold(0.8)
                .topK(6)
                .build())
            .build();

        return ChatClient.builder(chatModel)
            .defaultAdvisors(advisor)
            .build();
    }
}

@RestController
public class RagController {
    private final ChatClient ragChatClient;

    @GetMapping("/rag")
    public String ask(@RequestParam String question) {
        return ragChatClient.prompt(question).call().content();
    }
}

QuestionAnswerAdvisor 会自动查询向量数据库，将检索到的文档附加到用户问题中，为模型提供生成答案的上下文。Spring AI 支持 Chroma、Elasticsearch、Milvus、PGVector、Redis 等主流向量数据库。

五、生产级特性：可观测性与 MCP 协议

Spring AI 继承了 Spring Boot 的生产力基因，支持虚拟线程、GraalVM 原生镜像，并通过 Micrometer 提供 AI 操作的可观测性。

在 可观测性 方面，Spring AI 提供了对 ChatClient、Model、Tool、Embedding 等核心操作的观测支持，开发者可以轻松接入 Prometheus 等监控系统，实时追踪 Token 消耗、延迟和错误率。

MCP（Model Context Protocol） 是 Spring AI 的另一项重要能力，它允许 AI 应用消费 MCP 服务器提供的服务，或将 Spring 服务暴露给 AI 生态系统。Spring AI 提供了 MCP 的 stdio 和 WebFlux 两种客户端/服务端实现。

六、总结

Spring AI 的价值在于让 Java 开发者用最自然的方式构建 AI 应用。其技术内核可以概括为三个层次：

抽象层：ChatClient 统一了不同模型提供商的 API 差异，ChatOptions 精细控制模型行为。
增强层：结构化输出（.entity()）将文本响应转化为 Java 对象；@Tool 注解让模型获得执行能力；QuestionAnswerAdvisor 为模型外挂知识库。
工程层：自动配置、可观测性、MCP 协议、虚拟线程支持，保障了生产级部署的可行性与可靠性。

从一行代码调用大模型，到构建具备工具调用和知识检索能力的 Agentic 系统，Spring AI 正在重新定义 Java 在 AI 时代的角色——正如 Spring 框架曾经重新定义了企业级 Java 开发一样。

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

spring

javac