Spring AI 入门：从零开始搭建第一个AI应用

随着大语言模型（LLM）的快速发展，将 AI 能力集成到企业级 Java 应用中已成为迫切需求。Spring AI 是 Spring 生态中专门为 AI 集成打造的框架，它提供了一套统一的 API，让开发者可以轻松对接 OpenAI、Azure OpenAI、HuggingFace 等多家 AI 服务商。本文将带你从零开始，搭建你的第一个 Spring AI 应用。

概述：Spring AI 是什么

Spring AI 是一个由 Spring 团队推出的官方项目，旨在为 Java 开发者提供一种声明式、可移植的方式来构建 AI 应用。它的设计哲学与 Spring 生态一脉相承：

• 统一抽象：提供 ChatModel、EmbeddingModel 等核心接口，屏蔽底层 AI 服务商的差异
• 声明式编程：通过注解和自动配置简化集成
• 模块化设计：支持 OpenAI、Azure、HuggingFace、Ollama 等多个 AI 提供商

一句话总结：Spring AI 之于 AI 服务，就像 Spring JDBC 之于数据库——它提供了一个统一的抽象层，让你无需关心底层服务商的差异。

环境准备：前置条件

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

• JDK 17+：Spring AI 基于 Spring Boot 3.x，需要 JDK 17 或更高版本
• Maven 3.6+ 或 Gradle 7.x+：用于构建项目
• OpenAI API Key：如果你使用 OpenAI 作为 AI 提供商（也可以使用DeepSeek）
• IDE：推荐 IntelliJ IDEA 或 VS Code

快速开始：搭建项目

方式一：使用 Spring Initializr

访问 Spring Initializr（https://start.spring.io/），选择以下依赖：

• Spring Web
• Spring AI OpenAI（或你需要的 AI 提供商）

方式二：手动创建 Maven 项目

在 pom.xml 中添加 Spring AI 的 BOM 和依赖：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-bom</artifactId>
            <version>1.0.0-M2</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

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

配置 API Key

在 application.yml 中配置你的 OpenAI API Key：

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

实现：编写第一个 AI 对话接口

1. 注入 ChatClient

Spring AI 提供了 ChatClient 作为最上层的高阶 API，我们可以直接注入使用：

@RestController
@RequestMapping("/ai")
public class ChatController {

    private final ChatClient chatClient;

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

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

2. 流式响应

对于长文本生成，流式响应可以提供更好的用户体验：

@RestController
@RequestMapping("/ai")
public class StreamChatController {

    private final ChatClient chatClient;

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

    @GetMapping("/chat/stream")
    public Flux<String> streamChat(@RequestParam String message) {
        return chatClient.prompt()
                .user(message)
                .stream()
                .content();
    }
}

3. 添加系统提示词

在实际应用中，我们通常需要给 AI 设定角色和行为的上下文：

@GetMapping("/chat/with-system")
public String chatWithSystem(@RequestParam String message) {
    return chatClient.prompt()
            .system("你是一个资深的 Java 技术专家，请用简洁专业的方式回答问题。")
            .user(message)
            .call()
            .content();
}

进阶：自定义 ChatOptions

Spring AI 允许你细粒度地控制 AI 调用的参数：

@GetMapping("/chat/custom")
public String chatWithCustomOptions(@RequestParam String message) {
    return chatClient.prompt()
            .user(message)
            .options(ChatOptionsBuilder.builder()
                    .withModel("gpt-4o-mini")
                    .withTemperature(0.3)
                    .withMaxTokens(500)
                    .build())
            .call()
            .content();
}

最佳实践：异常处理

在生产环境中，我们需要处理 API 调用可能出现的异常：

@RestControllerAdvice
public class AiExceptionHandler {

    @ExceptionHandler(AiAccessDeniedException.class)
    public ResponseEntity<String> handleAccessDenied(AiAccessDeniedException e) {
        return ResponseEntity.status(403).body("API Key invalid or insufficient permissions");
    }

    @ExceptionHandler(AiServiceException.class)
    public ResponseEntity<String> handleServiceError(AiServiceException e) {
        return ResponseEntity.status(502).body("AI service unavailable: " + e.getMessage());
    }
}

总结：本文要点

通过本文，你学习了如何从零开始创建一个 Spring AI 应用：

• Spring AI 是 Spring 生态中的 AI 集成框架，提供统一的 API 抽象
• 通过 spring-ai-openai-spring-boot-starter 可以快速集成 OpenAI
• ChatClient 是 Spring AI 提供的高阶 API，封装了提示词构造和调用流程
• 支持流式响应、自定义参数和异常处理