Spring AI 集成 Gemini：配置即用，无需重写

大多数"向后端添加 LLM"的教程最后都是一堆手写的 HTTP 客户端、JSON 映射和重试逻辑，一旦提供商改动了某个字段就会腐烂。Spring AI 采取了完全不同的思路：像 Spring 已经对待数据源或消息代理一样对待模型——一个通过属性配置、需要时注入的 bean。下面展示如何用 Google 的 Gemini 实现这套方案，以及两个容易让人卡上半天的配置陷阱。

一个启动器，两种身份验证方式

截至 2026 年，你需要的模块是 Google GenAI 启动器。它同时支持免费的 Gemini Developer API（只需一个 API 密钥）和付费的 Vertex AI 路径（GCP 凭证）——代码完全相同，只是配置不同。

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-google-genai</artifactId>
</dependency>

在 pom.xml 中配合 Spring AI BOM，这样就不用手动管理版本了。如果用免费层级，到 aistudio.google.com/apikey 获取密钥（仅支持 Google 账户，无需信用卡），然后只配置这个密钥就行：

spring:
  ai:
    google:
      genai:
        api-key: ${GEMINI_API_KEY}
        chat:
          model: gemini-2.5-flash
          temperature: 0.7

如果选择 Vertex AI，去掉 API 密钥，改为指定项目和地区——Spring AI 会自动发现你的 gcloud 应用默认凭证，完全不需要写身份验证代码：

spring:
  ai:
    google:
      genai:
        project-id: your-gcp-project
        location: us-central1
        chat:
          model: gemini-2.5-flash

实际调用很简洁——这正是关键

启动器会自动配置一个 ChatClient.Builder。注入它、构建一次，之后的调用代码和你为 OpenAI 或 Anthropic 写的代码看起来完全一样：

@Service
public class GeminiService {

    private final ChatClient chatClient;

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

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

以后换提供商，你只需改依赖和配置块——这个服务一点都不用改。这就是整套方案的价值所在：模型变成了一个可替换的细节，不再是贯穿整个代码库的硬依赖。

结构化输出而不是字符串解析

在后端真正省时间的地方是把模型的答案直接映射到 Java 类型，这样就不用正则表达式去解析文本了：

public record Summary(String headline, List<String> keyPoints) {}

public Summary summarize(String article) {
    return chatClient.prompt()
            .user(u -> u.text("Summarize this: {doc}").param("doc", article))
            .call()
            .entity(Summary.class);
}

Spring AI 会生成对应的模式，要求 Gemini 按这个格式输出，然后把响应反序列化到你的 record 里。从这里开始支持工具调用和 RAG 只需再跨一小步——还是用同一个 ChatClient，再配几个构建器方法就行。

两个看着像 bug 但其实不是的坑

模型弃用。gemini-2.0-flash 已经弃用并将关闭——Gemini 1.x 的标识符已经返回 404。要用 gemini-2.5-flash。有一个限制要注意：返回 0 配额错误通常不是你的账户被限流，而是这个模型本身在免费层已经满容了。

身份验证模式混淆。如果你在任何地方设置了 project-id 或 location——即使只是从之前的实验中遗留下来——客户端会悄悄切换到 Vertex AI 模式，然后你的免费 Developer API 密钥就会被拒绝，返回一个 400 错误，看起来像是配额问题。用免费层级时，只设置 API 密钥，把 project 和 location 的每一处都删干净。

这两个问题都坑过认为是密钥有问题的人，其实真正的罪魁祸首是配置。

Spring AI 这层抽象的价值在于这样的时刻体现：你要从 Gemini 换成另一个模型，只需改一个依赖和一个 YAML 块。前置成本就是一个启动器、几个配置属性，以及记住 project-id 是一个模式开关，不只是元数据。

你是倾向于用免费的 Developer API 做原型，还是直接用 Vertex AI 这样生产和开发共用一套代码路径？什么因素影响了你的选择？