Spring AI 入门实战：构建你的第一个 AI 应用

1. 引言

随着大语言模型（LLM）的快速发展，将 AI 能力集成到企业级 Java 应用中已成为越来越多开发者的诉求。然而，直接调用 OpenAI、通义千问等模型 API 往往需要处理繁琐的 HTTP 请求、Token 计算、上下文管理等问题。Spring AI 应运而生，它为 Java 开发者提供了一套统一的、声明式的 AI 编程接口，让构建 AI 应用变得像写普通 Spring Boot 业务代码一样简单。

本文将带你从零开始，快速上手 Spring AI，包括环境搭建、核心概念、基础调用以及一个完整的实战示例。

2. Spring AI 是什么

Spring AI 是 Spring 官方推出的 AI 应用开发框架，旨在为 Java 生态提供一套标准化的 AI 集成方案。它的设计理念与 Spring 家族一脉相承：约定优于配置、开箱即用、高度可扩展。

2.1 核心特性

统一抽象 ：屏蔽不同 AI 厂商（OpenAI、Azure、通义千问、Ollama 等）的 API 差异，提供一致的 ChatClient、EmbeddingClient 等接口。
声明式调用 ：通过 @Retryable、@Timeout 等注解或配置项，轻松管理重试、超时等非功能性需求。
结构化输出：支持将模型输出自动映射为 Java Bean、JSON、XML 等结构化数据。
Prompt 模板：内置类似 Thymeleaf 的提示词模板引擎，支持动态渲染 Prompt。
RAG 支持：提供向量存储抽象，方便实现基于检索增强生成（RAG）的知识库问答。

2.2 支持的模型提供商

Spring AI 目前支持 OpenAI、Azure OpenAI、Amazon Bedrock、Google Vertex AI、Ollama、通义千问（DashScope）等主流模型提供商，并且可以通过 spring.ai.model 配置灵活切换。

3. 环境准备

在开始之前，请确保你的开发环境满足以下要求：

JDK 17+（Spring Boot 3.x 要求）
Maven 3.6+ 或 Gradle 7.5+
IDE：IntelliJ IDEA 或 Eclipse
一个可用的模型 API Key（本文以 OpenAI 为例，你也可以使用 Ollama 本地模型）

3.1 创建 Spring Boot 项目

你可以通过 Spring Initializr 快速创建项目，并添加以下依赖：

xml 复制代码

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
    <version>1.0.0-M6</version>
</dependency>

注意：Spring AI 目前仍处于里程碑阶段，版本号以 M 结尾，请留意官方发布的最新版本。

3.2 配置文件

在 application.yml 中配置模型 API Key：

yaml 复制代码

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

如果你使用 Ollama 本地模型，则配置：

yaml 复制代码

spring:
  ai:
    ollama:
      base-url: http://localhost:11434
      chat:
        options:
          model: llama3.1

4. 第一个 AI 应用

4.1 注入 ChatClient

Spring AI 提供了 ChatClient 接口作为与模型交互的统一入口。我们可以在 Service 中直接注入：

java 复制代码

@Service
public class ChatService {

    private final ChatClient chatClient;

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

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

4.2 编写 Controller

java 复制代码

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

    private final ChatService chatService;

    public ChatController(ChatService chatService) {
        this.chatService = chatService;
    }

    @GetMapping("/{message}")
    public String chat(@PathVariable String message) {
        return chatService.chat(message);
    }
}

启动应用后，访问 http://localhost:8080/api/chat/你好，即可看到模型的回复。

5. 进阶：结构化输出

很多时候，我们希望模型返回的不是一段自由文本，而是结构化的 JSON 数据，以便直接映射为 Java 对象。Spring AI 提供了 BeanOutputConverter 来实现这一需求。

java 复制代码

public record MovieInfo(String title, String director, int year) {}

java 复制代码

@Service
public class MovieService {

    private final ChatClient chatClient;

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

    public MovieInfo getMovieInfo(String movieName) {
        var converter = new BeanOutputConverter<>(MovieInfo.class);
        String prompt = """
                请提供电影《%s》的以下信息：片名、导演、上映年份。
                请以 JSON 格式返回。
                %s
                """.formatted(movieName, converter.getFormat());

        String response = chatClient.call(prompt);
        return converter.convert(response);
    }
}

6. 实战：基于 RAG 的知识库问答

RAG（Retrieval-Augmented Generation）是目前最流行的 AI 应用模式之一。它通过检索外部知识库，将相关内容作为上下文提供给模型，从而减少幻觉、提升回答准确性。

6.1 添加依赖

xml 复制代码

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-pgvector-store-spring-boot-starter</artifactId>
    <version>1.0.0-M6</version>
</dependency>

6.2 配置向量数据库

yaml 复制代码

spring:
  ai:
    vectorstore:
      pgvector:
        uri: jdbc:postgresql://localhost:5432/ai_db
        username: postgres
        password: postgres

6.3 实现知识库问答

java 复制代码

@Service
public class RagService {

    private final ChatClient chatClient;
    private final VectorStore vectorStore;

    public RagService(ChatClient chatClient, VectorStore vectorStore) {
        this.chatClient = chatClient;
        this.vectorStore = vectorStore;
    }

    public String ask(String question) {
        // 1. 检索相关文档
        var matches = vectorStore.similaritySearch(question);

        // 2. 构建带上下文的 Prompt
        String context = matches.stream()
                .map(m -> m.getContent())
                .reduce("", (a, b) -> a + "\n" + b);

        String prompt = """
                请基于以下资料回答问题：
                ---
                %s
                ---
                问题：%s
                """.formatted(context, question);

        // 3. 调用模型
        return chatClient.call(prompt);
    }
}

7. 总结

Spring AI 为 Java 开发者打开了一扇通往 AI 应用开发的大门。通过本文，你已经掌握了：

Spring AI 的核心概念与设计理念
环境搭建与基础配置
使用 ChatClient 完成基础对话
结构化输出与 RAG 实战

Spring AI 仍在快速发展中，API 可能会随版本迭代有所调整。建议持续关注 Spring AI 官方文档，及时跟进最新特性。