Spring AI 实战:Java 开发者如何构建企业级 LLM 应用

0 阅读

为什么 Java 开发者需要 Spring AI

过去两年,大语言模型(LLM)的热度让很多后端团队感到焦虑。Python 似乎是 AI 的唯一语言,而 Java 开发者往往被 relegated 到“只负责调 API”或者“等待 Python 团队封装好服务”的位置。

这种局面正在改变。Spring AI 的出现,不是为了取代 Python 在数据科学领域的地位,而是为了解决一个非常具体的工程问题:如何在现有的 Java/Spring 生态中,安全、规范地集成大模型能力。

对于大多数企业应用来说,AI 只是业务逻辑的一部分。你可能需要一个智能客服入口,或者一个基于内部文档的问答助手。为了这些功能去维护一套独立的 Python 微服务,意味着额外的运维成本、跨语言通信的延迟以及团队技能树的割裂。Spring AI 的核心价值就在于“就地解决”——它让 Java 开发者用熟悉的依赖注入、配置管理和安全机制来处理 AI 交互。

这篇文章不聊宏大的行业趋势,我们直接看代码和架构,看看 Spring AI 到底是怎么把复杂的 LLM 交互简化成几个 Bean 的。

核心设计:抽象是为了不被厂商绑定

Spring AI 的设计哲学很明确:抽象即自由。这和当年 Spring JDBC 或 JPA 的思路一脉相承。

如果你直接调用 OpenAI 的 HTTP API,你的代码里会充斥着 Authorization: Bearer sk-... 这样的头信息,以及特定于 OpenAI 的请求体结构。一旦老板说“我们要换成阿里云通义千问以降低成本”,你就得重写大量代码。

Spring AI 通过两层核心抽象解决了这个问题:

  1. Model 层(ChatModel/EmbeddingModel):这是最底层的接口,负责与具体的 LLM 提供商通信。它屏蔽了不同厂商 API 的差异。
  2. Client 层(ChatClient):这是更高级的抽象,类似于 RestTemplate 或 WebClient。它提供了链式调用、提示词模板管理、消息历史记忆等功能。

分层架构解析

我们可以把 Spring AI 的应用结构看作四层:

  • 应用层:你的 Controller 或 Service,处理业务逻辑,比如“用户提问”、“生成报表”。
  • 增强层:这里包含了 PromptTemplate(提示词模板)、Function Calling(函数调用)、Structured Output(结构化输出)和 RAG 流程。这些是让 LLM 变得“有用”的关键组件。
  • 抽象层:ChatClient 和 ChatModel。你在这里决定用哪个模型,但不需要关心具体的 HTTP 请求细节。
  • 基础设施层:VectorStore(向量数据库)、DocumentReader(文档解析器)。这是 RAG 应用的基石。

这种分层的好处是,你可以随时替换底层的模型提供商(比如从 OpenAI 切换到 Ollama 本地模型),而上层的业务逻辑几乎不需要改动。只需要修改 application.yml 中的配置,Spring AI 会自动加载对应的 Starter。

快速上手:从依赖配置开始

创建一个 Spring AI 项目最简单的方式是使用 Spring Initializr。你需要添加 spring-ai-starter 以及具体模型的 starter,比如 spring-ai-openai-spring-boot-starter 或 spring-ai-ollama-spring-boot-starter。

在 Maven 中,建议使用 BOM 来管理版本,避免依赖冲突:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-bom</artifactId>
            <version>1.0.0-M3</version> <!-- 请检查最新稳定版 -->
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

配置文件 application.yml 非常直观。以使用本地 Ollama 为例:

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

如果你使用的是 OpenAI,只需替换为 openai 节点并填入 API Key。Spring AI 支持通过环境变量注入敏感信息,这在生产环境中是必须的。

核心功能实战

1. 基础对话:ChatClient vs ChatModel

对于简单的问答,ChatClient 是最推荐的方式。它提供了流畅的 API,自动处理消息列表的管理。

@RestController
public class SimpleChatController {

    private final ChatClient chatClient;

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

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

这段代码看起来和普通的服务调用没什么两样。ChatClient 背后会自动将 message 封装为 UserMessage,发送给配置的模型,并提取返回的内容。

如果你需要更细粒度的控制,比如设置系统提示词(System Message)或调整温度参数,可以使用底层的 ChatModel:

Prompt prompt = new Prompt(
    List.of(
        new SystemMessage("你是一个严谨的技术专家,回答要简洁。"),
        new UserMessage(message)
    )
);
ChatResponse response = chatModel.call(prompt);

2. 流式响应(SSE)

在聊天界面中,用户不希望盯着屏幕等几秒直到整个句子生成完毕。Server-Sent Events (SSE) 是解决这个问题的标准方案。

Spring AI 对 Reactor 的支持使得实现流式响应非常简单:

@GetMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<String> streamChat(@RequestParam String message) {
    return chatClient.prompt()
            .user(message)
            .stream()
            .content();
}

前端只需订阅这个 SSE 端点,就能实时接收到生成的文本片段。注意,这里返回的是 Flux<String>,Spring WebFlux 会自动将其转换为 SSE 格式。

3. 结构化输出:告别 JSON 解析噩梦

LLM 通常返回纯文本,但业务系统往往需要结构化的数据(如 JSON 对象)。以前,开发者不得不编写复杂的正则表达式或提示词来强制模型输出 JSON,然后还要处理解析失败的情况。

Spring AI 引入了 BeanOutputConverter 或直接利用模型的结构化输出能力(如果模型支持,如 GPT-4o 或较新的 Ollama 模型)。

定义一个 POJO:

public class WeatherInfo {
    private String city;
    private double temperature;
    private String condition;
    // getters and setters
}

然后在调用时指定输出类型:

WeatherInfo info = chatClient.prompt()
    .user("查询北京今天的天气")
    .call()
    .entity(WeatherInfo.class);

Spring AI 会在后台处理提示词的构造(告诉模型“请返回符合以下 JSON Schema 的数据”)以及结果的反序列化。这极大地提高了代码的健壮性。

4. 函数调用(Function Calling)

这是让 LLM 从“聊天机器人”变成“Agent”的关键。通过函数调用,模型可以决定何时调用外部工具(如查询数据库、调用天气 API)。

在 Spring AI 中,你只需要定义一个带有 @Tool 注解的方法:

@Service
public class WeatherService {

    @Tool(description = "获取指定城市的当前天气状况")
    public String getWeather(String city) {
        // 模拟调用外部 API
        return "{\"temperature\": 22, \"condition\": \"Sunny\"}";
    }
}

当你在 ChatClient 中注册了这个 Tool,模型在收到“北京今天天气怎么样?”这类问题时,会自动识别出需要调用 getWeather 函数,并将结果整合进最终的回答中。整个过程对开发者几乎是透明的。

5. RAG:检索增强生成

RAG 是解决 LLM 幻觉和知识滞后问题的标准方案。Spring AI 提供了一套完整的 RAG 流水线:

  1. Document Reader:读取 PDF、Word、Markdown 等文件。
  2. Text Splitter:将长文档切分成小块(Chunks)。
  3. Embedding Model:将文本块转换为向量。
  4. Vector Store:存储向量,支持 Milvus、Redis、Pinecone 等。
  5. Retrieval:根据用户提问检索相关文档块。
  6. Generation:将检索到的内容作为上下文,连同问题一起发给 LLM。

代码示例:

@Service
public class RagService {

    private final VectorStore vectorStore;
    private final ChatClient chatClient;

    // 注入依赖...

    public void ingestDocuments(Path filePath) {
        // 1. 读取和分割
        Document document = new Document(Files.readString(filePath));
        List<Document> chunks = new TokenTextSplitter().split(List.of(document));
        
        // 2. 嵌入并存储
        vectorStore.add(chunks);
    }

    public String askQuestion(String question) {
        // 1. 检索相关文档
        List<Document> relevantDocs = vectorStore.similaritySearch(question);
        String context = relevantDocs.stream()
            .map(Document::getContent)
            .collect(Collectors.joining("\n"));

        // 2. 构建提示词
        String promptText = "基于以下上下文回答问题:\n{context}\n问题:{question}";
        
        return chatClient.prompt()
            .system(promptText)
            .user(u -> u.param("context", context).param("question", question))
            .call()
            .content();
    }
}

这段代码展示了 RAG 的核心逻辑。Spring AI 的 VectorStore 接口统一了不同向量数据库的操作,使得切换底层存储变得容易。

部署与运维:Docker 化实践

在企业环境中,我们通常希望尽量降低对外部 SaaS 服务的依赖,或者至少有一个本地的 fallback 方案。Ollama 是一个流行的本地 LLM 运行工具。

使用 Docker Compose 可以同时启动 Ollama 和 Spring Boot 应用:

version: '3.8'
services:
  ollama:
    image: ollama/ollama
    ports:
      - "11434:11434"
    volumes:
      - ollama-data:/root/.ollama

  app:
    build: .
    ports:
      - "8080:8080"
    environment:
      - SPRING_AI_OLLAMA_BASE_URL=http://ollama:11434
    depends_on:
      - ollama

volumes:
  ollama-data:

在 Dockerfile 中,只需标准的 Java 镜像打包即可。这种部署方式使得整个 AI 应用可以在内网环境中独立运行,满足了数据隐私和安全合规的要求。

可观测性:监控 AI 服务

AI 服务的不确定性比传统 CRUD 高得多。你需要知道:

  • 每次调用消耗了多少 Token?
  • 响应延迟是多少?
  • 是否有大量的错误请求?

Spring AI 原生集成了 Micrometer。只要引入了 spring-boot-starter-actuator 和 micrometer-registry-prometheus,你就可以通过 /actuator/prometheus 端点暴露指标。

关键指标包括:

  • spring.ai.chat.client.call.duration:调用耗时。
  • spring.ai.chat.client.tokens.usage:Token 使用量。

结合 Grafana,你可以搭建一个实时监控面板,观察 AI 服务的健康状态和成本消耗。这对于控制 LLM 使用成本至关重要。

最佳实践与避坑指南

  1. 版本选择:Spring AI 目前迭代速度较快。生产环境建议等待 GA 版本,或者仔细测试 M 版本的兼容性。务必使用 BOM 管理依赖。
  2. 超时设置:LLM 的响应时间波动很大。务必在 RestTemplate 或 WebClient 层面设置合理的超时时间,避免线程阻塞。
  3. 缓存策略:对于相同的问题,LLM 的回答通常是一致的。使用 Redis 缓存常见的问答对,可以显著降低 Token 成本和延迟。
  4. 安全过滤:不要信任用户的输入。在发送给 LLM 之前,应该进行基本的敏感词过滤或长度限制。同时,对 LLM 的输出也要进行校验,防止注入攻击或不当内容。
  5. 本地测试:开发阶段强烈建议使用 Ollama 或 LocalAI 进行本地测试。这样可以节省大量的 API 费用,并且调试更方便。

结语

Spring AI 并没有发明新的 AI 算法,它做的是工程化的工作。它将分散的、非标准化的 LLM 接口,整合进了 Java 开发者最熟悉的 Spring 编程模型中。

对于 Java 团队来说,这意味着你不需要招聘专门的 Python AI 工程师,也不需要重构现有的微服务架构,就可以开始构建智能应用。从简单的聊天机器人到复杂的 RAG 知识库,Spring AI 提供了一条清晰、可维护的路径。

当然,AI 应用开发仍然充满挑战,特别是提示词工程和效果评估。但至少在代码层面,Spring AI 让你能够专注于业务逻辑,而不是底层 API 的琐碎细节。这就是框架的意义所在。