Spring AI 入门

Spring AI 的核心是把大模型能力接进 Spring Boot 项目，用统一的 Java API 完成聊天、Prompt 模板、模型配置和后端接口封装。

Spring AI 入门

Spring AI 是什么

Spring AI，中文可以理解为“Spring 生态里的 AI 应用开发框架”。

它不是一个大模型本身。

它的作用是把不同模型服务接入 Spring 应用，提供比较统一的开发方式。

可以先按这个结构理解：

Spring Boot 项目
  -> Spring AI
  -> ChatClient
  -> 模型服务
  -> Qwen / DeepSeek / OpenAI 兼容接口

结论：

Spring AI 解决的是 Java 后端怎么更方便地调用大模型，而不是训练模型。

为什么 Java 后端要学 Spring AI

前面几天已经用 HTTP 直接调用过大模型 API。

直接 HTTP 调用的好处是能看清底层。

但项目复杂后，会遇到这些问题：

请求对象重复封装
Prompt 模板不好维护
流式输出要自己处理
Tool Calling 要自己解析
模型配置分散
日志和观测难统一

Spring AI 的价值是把这些能力放到 Spring 生态里。

后端项目可以继续保持熟悉的结构：

Controller
Service
Configuration
application.yml
日志
异常处理
权限校验

AI 能力只是进入原来的工程体系。

ChatClient 是什么

ChatClient，中文可以理解为“聊天客户端”。

它是 Spring AI 里调用聊天模型的常用入口。

最小调用：

String content = chatClient.prompt()
        .user("什么是 Spring AI？")
        .call()
        .content();

这里的链路是：

prompt()：开始构造请求
user()：设置用户问题
call()：发起同步调用
content()：取出模型回答文本

如果要加 system prompt：

String content = chatClient.prompt()
        .system("你是一个严谨的 Java 后端工程师，回答要简洁。")
        .user("Spring AI 适合解决什么问题？")
        .call()
        .content();

创建 ChatClient

Spring AI 在 Spring Boot 项目里可以自动配置 ChatClient.Builder。

常见写法：

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.stereotype.Service;

@Service
public class AiChatService {

    private final ChatClient chatClient;

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

    public String chat(String message) {
        return chatClient.prompt()
                .user(message)
                .call()
                .content();
    }
}

这样业务代码不需要直接关心底层 HTTP 请求。

Prompt Template 是什么

Prompt Template，中文一般翻译为“提示词模板”。

它的作用是把固定 Prompt 和动态参数分开。

不建议每次都拼字符串：

String prompt = "请解释这个概念：" + name;

更适合写成模板：

String content = chatClient.prompt()
        .user(u -> u
                .text("请用 Java 后端视角解释 {concept}")
                .param("concept", "Spring AI"))
        .call()
        .content();

模板的好处：

规则更清楚
变量更明确
方便复用
方便后期优化

配置模型

模型配置不要写死在业务代码里。

通常放到 application.yml 或环境变量里。

示例：

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      chat:
        options:
          model: gpt-4o-mini
          temperature: 0.3

如果使用 OpenAI 兼容接口，一般还会配置 base URL。

具体配置项要以当前模型供应商和 Spring AI 文档为准。

学习阶段需要先记住：

API Key 放环境变量
模型名放配置
temperature 放配置
不要在代码里写死密钥

完成聊天接口

Controller 示例：

import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/chat")
public class ChatController {

    private final AiChatService aiChatService;

    public ChatController(AiChatService aiChatService) {
        this.aiChatService = aiChatService;
    }

    @PostMapping
    public ChatResponse chat(@RequestBody ChatRequest request) {
        String answer = aiChatService.chat(request.message());
        return new ChatResponse(answer);
    }
}

请求对象：

public record ChatRequest(String message) {
}

响应对象：

public record ChatResponse(String answer) {
}

Service：

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.stereotype.Service;

@Service
public class AiChatService {

    private final ChatClient chatClient;

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

    public String chat(String message) {
        return chatClient.prompt()
                .system("你是一个严谨的 Java 后端工程师，回答要简洁。")
                .user(message)
                .call()
                .content();
    }
}

用 curl 测试接口

curl -X POST http://localhost:8080/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message":"什么是 Spring AI？"}'

期望返回：

{
  "answer": "Spring AI 是 Spring 生态中用于接入大模型能力的应用开发框架。"
}

先跑通普通聊天，再考虑流式输出、Tool Calling、RAG。

常见问题

ChatClient 和直接 HTTP 调用有什么区别

直接 HTTP 调用适合学习底层请求。

ChatClient 更适合放进 Spring Boot 项目。

区别：

HTTP 调用：自己组装请求和解析响应
ChatClient：用 Spring AI 封装好的 API 调用模型

Prompt 模板什么时候用

只要 Prompt 里有变量，就建议用模板。

比如：

用户问题
知识库上下文
分类范围
输出格式
业务规则

模型参数放哪里

优先放配置文件和环境变量。

不要写死在 Controller 或 Service 里。

API Key 怎么处理

API Key 只放环境变量、密钥管理服务或部署平台配置。

.env、application-local.yml 这类本地文件不要提交到 Git。

练习清单

完成几件事情：

知道 Spring AI 是 Java 应用接入大模型的框架
知道 ChatClient 是聊天模型调用入口
能用 ChatClient 完成一次同步聊天
能区分 system prompt 和 user prompt
能用 Prompt Template 传入动态参数
能把模型名和 API Key 放到配置里
能写一个 /api/chat 接口

建议目录：

ai-agent-study
├── java
│   └── spring-ai-chat-demo
│       ├── ChatController.java
│       ├── AiChatService.java
│       ├── ChatRequest.java
│       └── ChatResponse.java
└── docs
    └── spring-ai-intro.md

小结

Day06 的结论：

Spring AI 入门先抓住 ChatClient、Prompt Template、模型配置和聊天接口四件事。

最小链路：

前端 / curl
  -> Spring Boot Controller
  -> AiChatService
  -> ChatClient
  -> 模型服务
  -> 返回回答

这一步完成以后，Java 后端就可以用熟悉的 Spring Boot 结构接入大模型。

06 Spring AI 入门