别再手写 HTTP 客户端调 AI 了!Spring AI 官方出手,一行代码搞定多模型切换

发布于 更新于 1,907 字 7 分钟阅读

image

#别再手写 HTTP 客户端调 AI 了!Spring AI 官方出手,一行代码搞定多模型切换

#介绍


Spring AI 是 Spring 生态体系下的官方 AI 工程化框架,旨在为大语言模型(LLM)集成提供标准化的解决方案。该框架的核心价值在于将复杂的 AI 模型调用逻辑封装为符合 Spring 设计哲学(如依赖注入、自动配置)的组件,从而降低 Java 技术栈接入 AI 能力的工程成本。

其核心特性主要体现在三个维度。首先是多模型兼容性,框架提供了统一的 API 抽象,支持 OpenAI、Azure OpenAI、Google Gemini 及本地模型(如 Ollama),允许在不修改业务代码的情况下灵活切换底层模型。其次是生态深度融合,它并非独立的 SDK,而是与 Spring Boot、Spring Security 等原生组件无缝衔接,开发者可以直接利用现有的 Spring 基础设施来管理 AI 上下文、安全认证和监控。最后是企业级工程保障,框架内置了可观测性、流控、重试机制等生产环境必需特性,满足企业对稳定性和可维护性的严苛要求。

  1. 多模型兼容:内置对 OpenAI、Google Gemini、百度文心一言等主流厂商模型的适配,支持本地化模型对接,统一接口可灵活切换模型;
  2. 生态深度融合:与 Spring 生态(如依赖注入、Spring Security、监控组件)无缝衔接,现有 Spring 项目可零侵入集成,开发者无需学习新框架思想;
  3. 企业级保障:提供 API 密钥加密存储、权限控制、调用监控等生产级特性,同时支持流程编排与异常重试,满足企业对安全性、稳定性的需求。

目前,该框架已被广泛应用于智能客服、RAG(检索增强生成)知识库、代码辅助生成等企业级场景。

#环境依赖与版本基线


image

tips:SpringAI至少需要SpringBoot 3.2,而SpringBoot3.2至少需要Java17

重要版本限制:Spring AI 对运行环境有严格的要求,必须使用 Java 17 及以上版本,且对应的 Spring Boot 版本需为 3.2 及以上。这是由于框架大量使用了现代 Java 特性及 Spring Boot 3.x 的自动配置机制,低版本环境无法兼容。

#项目依赖配置

在 Maven 项目中,引入 spring-ai-openai-spring-boot-starter 依赖即可快速集成。为了保证依赖版本的一致性,建议通过 BOM(Bill of Materials) 进行版本管理:

pom.xml 中编写:

xml
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
            <version>1.0.0-M5</version>
        </dependency>
    </dependencies>
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.ai</groupId>
                <artifactId>spring-ai-bom</artifactId>
                <version>1.0.0-M5</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

#模型参数配置

application.yml 中配置 API Key 及模型参数。以下配置展示了如何接入兼容 OpenAI 协议的第三方模型(如 SiliconFlow 提供的 DeepSeek):

YAML
server:
  port: 8080
spring:
  ai:
    openai:
      api-key: sk-xxxxxxxxxxxxxxxxxxxxxxxx # 生产环境建议使用环境变量或配置中心注入
      base-url: https://api.siliconflow.cn
      chat:
        options:
          model: deepseek-ai/DeepSeek-R1-Distill-Qwen-14B
          temperature: 0.7 # 控制生成随机性的核心参数

关于 temperature​ 参数:它决定了模型输出的随机性和创造性。取值范围通常在 0.0 到 1.0 之间。较低的值(如 0.2)会使模型输出更加确定、严谨,适用于代码生成或事实性问答;较高的值(如 0.8)则增加了输出的多样性,适用于创意写作或头脑风暴场景。在实际工程中,需根据业务对准确性和创造性的需求进行权衡。

#快速集成示例

Java
@Slf4j
@RestController
@RequestMapping("/ai")
public class DemoController {

    @Resource
    private OpenAiChatModel chatModel;

    @GetMapping("/generate")
    public String generate(@RequestParam(value = "message", defaultValue = "hello") String message) {
        String response = chatModel.call(message);
        log.info("response: {}", response);
        return response;
    }

}

以下代码展示了最基础的调用方式。通过注入 OpenAiChatModel 接口,直接发起同步请求并获取文本响应:

PixPin_2025-09-29_21-51-04

#核心架构:ChatClient 与 ChatModel


Spring AI 提供了两种不同层级的抽象接口以适应不同的开发场景。理解这两者的差异是进行高效开发的前提。

该框架设计遵循了分层架构原则,将底层模型连接与上层业务调用逻辑解耦。这种设计不仅降低了 API 调用的复杂度,还确保了在不同模型提供商之间的可移植性,符合 Spring 模块化的设计理念。

#ChatClient:高层流式 API

ChatClient​ 是面向大多数业务场景的高层门面接口。它采用了流式设计,支持链式调用,屏蔽了底层的 Prompt 构建细节和响应解析逻辑,旨在简化常见交互场景的开发。

该接口主要用于封装客户端构建、提示词规范设定以及请求发起等通用流程。

#基础调用示例

Java
@RestController
public class ChatDeepSeekController {

    private final ChatClient chatClient;

    public ChatDeepSeekController(ChatClient.Builder chatClientBuilder) {
        this.chatClient = chatClientBuilder.build();
    }

    @GetMapping("/chat")
    public String chat(@RequestParam(value = "msg", defaultValue = "给我讲个笑话") String message) {
        return this.chatClient.prompt()
                .user(message)
                .call()
                .content();
    }
}

效果:

image

#系统提示词配置

通过配置 ChatClient.Builder​ 的 defaultSystem 属性,可以全局定义模型的角色设定和行为边界。这比在每次请求中手动拼接 System Prompt 更加规范且易于维护。

Java
@Configuration
public class AIConfig {

    @Bean
    public ChatClient chatClient(ChatClient.Builder builder) {
        return builder.defaultSystem("你是一名资深的全栈开发者,精通Java技术栈。你的名字叫zxb。").build();
    }
}

效果如下:

PixPin_2025-11-25_13-13-33

#流式响应

在用户体验要求较高的场景(如对话式交互)中,流式输出是必不可少的。Spring AI 利用 Project Reactor 的 Flux 实现了非阻塞的流式响应,将 Token 逐个推送到客户端,显著降低了首字延迟(TTFT)。

    • call():阻塞式调用,等待模型完整生成所有 Token 后一次性返回结果。
    • stream()​:流式调用,返回一个 Flux<String>,允许订阅端实时消费生成的数据流。

#流式调用示例

Java
@GetMapping(value = "/chat/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE + ";charset=UTF-8")
public Flux<String> chatStream(@RequestParam(name = "msg", defaultValue = "你好,你是谁?会什么?") String message) {
	return chatClient.prompt().user(message).stream().content();
}

效果如下:

PixPin_2025-11-25_14-14-30

#ChatModel:底层抽象接口

ChatModel​ 是直接对应底层 LLM 能力的抽象接口,例如 OpenAiChatModel​ 或 OllamaChatModel。它提供了对 Prompt 结构、模型选项(Temperature, TopP 等)以及元数据的细粒度控制。

架构定位ChatModel​ 位于底层,是 ChatClient​ 的依赖对象。ChatClient​ 内部通过调用 ChatModel 完成实际的模型交互。

#Demo:实现简单的对话

Java
@GetMapping("/openai")
public String openai(@RequestParam("msg") String msg) {
    ChatResponse response = chatModel.call(
            new Prompt(
                    msg,
                    OpenAiChatOptions.builder()
                            .model("deepseek-chat")
                            .temperature(0.8)
                            .build()
            )
    );
    return response.getResult().getOutput().getContent();
}

#Prompt 模板管理

在生产环境中,硬编码 Prompt 字符串是极不可取的。Spring AI 提供了 SystemPromptTemplate​ 和 UserMessage 等 API,支持类似 MyBatis 的占位符替换机制。这使得 Prompt 结构可以与代码逻辑分离,便于动态配置和维护。

#动态 Prompt 示例

Java
@GetMapping(value = "/prompt", produces = MediaType.TEXT_EVENT_STREAM_VALUE + ";charset=UTF-8")
public Flux<String> prompt(@RequestParam("name") String name, @RequestParam("voice") String voice) {
    String userText = """
            给我推荐xx的至少三种美食
            """;
    UserMessage userMessage = new UserMessage(userText);

    String systemText = """
            你是一个美食咨询助手,可以帮助人们查询美食信息。
            你的名字是{name}
            你应该用你的名字和{voice}的饮食习惯回复用户的请求。
            """;
    SystemPromptTemplate systemPromptTemplate = new SystemPromptTemplate(systemText);
    // 动态替换占位符
    Message systemMessage = systemPromptTemplate.createMessage(Map.of("name", name, "voice", voice));

    Prompt prompt = new Prompt(List.of(userMessage, systemMessage));
    return chatClient.prompt(prompt).stream().content();
}

效果如下:

PixPin_2025-11-25_19-41-33

#Function Calling:工具调用机制


#机制概述

Function Calling 是连接大语言模型与确定性业务逻辑的桥梁。通过该机制,模型不再局限于训练数据中的知识,而是能够根据用户意图自主判断并触发预先注册的 Java 函数(如查询数据库、调用外部 API),然后将函数执行结果整合到最终回复中。

flowchart TD A[User Input] --> B[LLM Decision Engine] B -->|Needs Tool| C[Return Function Call Request] B -->|Direct Answer| D[Generate Response] C --> E[Spring AI Executor] E --> F[Invoke Registered Java Function] F --> G[Business Logic / DB Query] G --> H[Return Result to LLM] H --> D

#实现步骤

#1. 定义并注册函数

使用 @Bean​ 和 @Description​ 注解声明函数。@Description 中的内容至关重要,LLM 正是据此判断何时调用该函数。建议使用 Java Record 定义输入参数,以确保类型的清晰和不可变性。

Java
@Configuration
public class CalculatorService {

    @Bean
    @Description("执行加法运算,输入两个整数并返回它们的和")
    public Function<AddOperation, Integer> addOperation() {
        return request -> request.a + request.b;
    }

    @Bean
    @Description("执行乘法运算,输入两个整数并返回它们的积")
    public Function<MulOperation, Integer> mulOperation() {
        return request -> request.m * request.n;
    }

    // 使用 Record 定义类型安全的数据结构
    public record AddOperation(int a, int b) {}
    public record MulOperation(int m, int n) {}
}

#2. 在 ChatClient 中启用函数

在构建请求时,通过 .functions()​ 方法将上述注册的 Bean 名称传递给 ChatClient。Spring AI 会自动处理函数元数据的序列化与模型回传结果的反序列化。

效果如下:

PixPin_2025-11-25_21-56-10

PixPin_2025-11-25_21-55-56

#本地模型集成:Ollama


#pom地址

对于对数据隐私有极高要求或希望降低 API 成本的场景,Spring AI 提供了对本地模型引擎 Ollama 的原生支持。

需引入 spring-ai-ollama-spring-boot-starter 依赖,并确保项目中配置了 Spring 的 Milestone 仓库(由于 Spring AI 尚处于快速迭代阶段,许多依赖未发布至中央仓库)。

#配置本地地址

配置指向本地 Ollama 服务实例(默认端口 11434):

YAML
spring:
  ai:
    ollama:
      base-url: http://localhost:11434
      chat:
        options:
          model: deepseek-r1:7b
          temperature: 0.7

#代码适配

由于 Spring AI 提供了统一的抽象层,从 OpenAI 切换至 Ollama 仅需替换注入的 ChatModel​ 实现类(OpenAiChatModel​ -> OllamaChatModel),业务逻辑层代码无需任何修改。

Java
@Resource
private OllamaChatModel ollamaChatModel;

@GetMapping("/api/test")
public String generateTest(@RequestParam(value = "message", defaultValue = "hello") String message) {
    String response = this.ollamaChatModel.call(message);
    System.out.println("response: " + response);
    return response;
}

zxb的博客

评论

还没有评论,来说点什么吧。

评论经发布者审核后公开
46 篇文档

文档树

25 个章节

本文目录

搜索文档

输入关键词,立即搜索当前分享。