Gemini Model Integration:从 Google Gen AI SDK 到企业级 AI Gateway

Gemini Model Integration 深入实践:从 Google Gen AI SDK 到企业级 AI Gateway

摘要

Gemini Model Integration 的核心并不是“调用 Gemini API”,而是如何把 Gemini 作为一个可靠的 Model Provider 集成到企业 AI Platform 中。

对 Java/Spring Boot 后端工程师而言,更值得关注的是:Google Gen AI SDK、Gemini API、Vertex AI、Model Routing、Multimodal、Structured Output、Function Calling、Long Context、Streaming、错误处理、Cost Optimization、OpenTelemetry,以及如何设计统一的 LLM Provider Abstraction。

本文以企业级 AI Platform 为目标,重点讨论 Gemini 集成的架构方法,而不仅仅是 SDK API 的罗列。


1. 什么是 Model Integration?

在传统微服务系统中,我们经常做:

Application
Database Integration
MySQL

或者:

Application
Message Integration
Kafka

AI 系统同样存在:

Application
Model Integration
Gemini

但 AI Model Integration 比数据库、Kafka 集成复杂得多。

因为一个 Model Provider 不只是:

Request → Response

还包括:

Model
Prompt
Context
Token
Streaming
Tool Calling
Structured Output
Multimodal
Reasoning
Safety
Quota
Rate Limit
Cost

因此可以把 Model Integration 定义为:

将外部 AI Model Provider 封装成企业内部统一、可靠、可观测、可治理的 AI Runtime 能力。


2. Gemini 在 AI Architecture 中处于什么位置?

一个企业 AI 系统可以抽象成:

                         AI Application
                         AI Runtime
             ┌────────────────┼────────────────┐
             ↓                ↓                ↓
          Prompt            RAG              Agent
             │                │                │
             └────────────────┼────────────────┘
                       Model Abstraction
              ┌───────────────┼───────────────┐
              ↓               ↓               ↓
           OpenAI           Gemini         Anthropic
              │               │               │
              ↓               ↓               ↓
           Provider         Provider        Provider

这里:

Gemini 是 Model Provider,而不是整个 AI Application。

这一区别非常重要。

很多项目一开始直接:

Spring Boot
Gemini SDK

后期却发现:

需要 OpenAI
需要 Azure OpenAI
需要 Anthropic
需要本地模型

最终业务代码全部与 Gemini API 耦合。

因此企业项目更合理的设计是:

Business
AI Service
LLM Abstraction
Gemini Adapter
Google Gen AI SDK
Gemini

3. 当前 Gemini API 的 SDK 体系

截至目前,Google 推荐使用新的 Google Gen AI SDK,而不是继续围绕旧 SDK 设计新的应用。官方迁移文档将新的 SDK 作为统一入口,并通过 Client 提供模型调用能力。([Google AI for Developers][1])

Google Gen AI SDK 支持多个语言,包括:

Python
JavaScript / TypeScript
Go
Java

Google Cloud 文档也提供了 Java google-genai SDK,并可用于 Gemini API / Vertex AI 场景。([Google Cloud Documentation][2])

Java 项目中可以使用:

<dependency>
    <groupId>com.google.genai</groupId>
    <artifactId>google-genai</artifactId>
    <version>...</version>
</dependency>

生产项目应该根据官方 Maven Central 当前版本进行锁定,而不要长期使用动态版本。


4. Gemini API 与 Vertex AI

这是企业集成 Gemini 时必须首先理解的问题。

Google 生态中常见两条路线:

                    Gemini
          ┌────────────┴────────────┐
          ↓                         ↓
     Gemini API                Vertex AI
          │                         │
     API Key                  Google Cloud
                                IAM
                                Project
                                Region

可以简单理解:

Gemini API

更适合:

快速开发
Prototype
个人开发
独立 AI Application

认证通常:

API Key

Vertex AI

更适合:

Enterprise
Google Cloud
IAM
Project Governance
Regional Deployment
Enterprise Security

认证更偏向:

Google Cloud IAM
Service Account
Application Default Credentials

因此企业 Java 系统如果已经运行在 Google Cloud 中,Vertex AI 通常是更值得重点评估的部署方式。


5. API Version:为什么企业项目必须关注?

Gemini SDK 当前默认 API version 为 v1beta,官方文档说明可以显式切换到稳定的 v1v1 同时支持 Interactions API。([Google AI for Developers][3])

这意味着:

SDK
API Version
Gemini API

不能完全忽略版本治理。

企业项目建议:

gemini:
  api-version: v1

而不是:

使用默认值

原因是:

默认版本
你的生产版本策略

对于 Production:

Explicit Version
+
Pinned SDK Version
+
Regression Test

通常比:

Latest Everything

更加可靠。


6. Gemini Model Integration 的第一原则

不要把模型名称写死在业务代码:

错误:

client.models.generateContent(
    "gemini-3.6-flash",
    ...
);

散落在:

Service A
Service B
Service C
Agent D

正确:

ai:
  default-model: gemini-3.6-flash

业务代码:

modelRouter.select(task);

然后:

Task
Model Router
Gemini Model

这样模型可以:

升级
降级
A/B Test
灰度
Fallback
Cost Optimization

7. Gemini Model Family

Gemini 模型体系正在快速演进,因此不要把架构绑定在某一个具体型号上。

当前官方模型列表包括 Gemini 3.x 系列以及 Flash、Flash-Lite、Pro 等不同定位的模型。官方模型文档也明确区分 Stable、Preview、Latest 和 Experimental 等版本类型。([Google AI for Developers][4])

从架构角度,可以抽象为:

                Gemini Model Family
        ┌──────────────┼──────────────┐
        ↓              ↓              ↓
      Pro            Flash        Flash-Lite
        │              │              │
  Complex Reasoning  Balanced      High Throughput
  High Quality       Speed         Low Cost

不要让:

所有请求
最强模型

而应该:

Easy Task
Flash-Lite

Normal Task
Flash

Complex Task
Pro

这就是:

Model Routing。


8. Stable / Preview / Latest / Experimental

Gemini 的模型版本策略非常值得企业架构师关注。

官方文档目前将模型版本大致分为:

Stable
Preview
Latest
Experimental

其中 Stable 更适合生产环境;Latest 是动态别名,可能随着模型更新发生变化;Experimental 更不适合生产环境。([Google AI for Developers][4])

例如:

Production
Stable Model

而:

Experiment
Preview

不要直接:

Production
Experimental

9. Model Registry

企业可以建立:

Model Registry

例如:

models:

  gemini-fast:
    provider: gemini
    model: gemini-3.6-flash
    tier: medium

  gemini-cheap:
    provider: gemini
    model: gemini-3.5-flash-lite
    tier: low

  gemini-reasoning:
    provider: gemini
    model: gemini-3.1-pro-preview
    tier: high

然后业务系统只使用:

gemini-fast
gemini-cheap
gemini-reasoning

而不是直接依赖:

gemini-xxx

这样模型升级只需要修改 Registry。


10. Gemini Java SDK 的基本调用模型

新的 Google Gen AI SDK 提供统一 Client。

基本结构:

Client client = Client.builder()
        .apiKey(System.getenv("GEMINI_API_KEY"))
        .build();

然后:

GenerateContentResponse response =
        client.models.generateContent(
                "gemini-3.6-flash",
                "Explain Kubernetes architecture.",
                null
        );

System.out.println(response.text());

官方迁移文档也展示了 client.models.generateContent() 这一统一调用方式。([Google AI for Developers][1])

核心思想:

Client
Models
generateContent
Response

11. Spring Boot 集成 Gemini

推荐架构:

React
Spring Boot
AI Controller
AI Service
Gemini Adapter
Google Gen AI SDK
Gemini

Controller:

@RestController
@RequestMapping("/api/ai")
public class AIController {

    private final AIService aiService;

    public AIController(AIService aiService) {
        this.aiService = aiService;
    }

    @PostMapping("/chat")
    public AIResponse chat(@RequestBody AIRequest request) {
        return aiService.chat(request);
    }
}

不要让 Controller 直接:

GeminiClient

12. AI Service

@Service
public class AIService {

    private final LLMClient llmClient;

    public AIService(LLMClient llmClient) {
        this.llmClient = llmClient;
    }

    public AIResponse chat(AIRequest request) {

        LLMRequest llmRequest =
                LLMRequest.builder()
                        .input(request.message())
                        .build();

        return llmClient.generate(llmRequest);
    }
}

这里故意不出现:

Gemini
OpenAI
Anthropic

这样业务层实现 Provider Neutral。


13. LLM Abstraction

定义:

public interface LLMClient {

    LLMResponse generate(LLMRequest request);

    Flux<LLMEvent> stream(LLMRequest request);
}

然后:

LLMClient
    ├── GeminiClient
    ├── OpenAIClient
    ├── AnthropicClient
    └── LocalModelClient

这实际上就是你之前学习的:

Adapter Pattern + Strategy Pattern


14. Gemini Adapter

@Component
public class GeminiClient implements LLMClient {

    private final Client client;

    public GeminiClient(Client client) {
        this.client = client;
    }

    @Override
    public LLMResponse generate(LLMRequest request) {

        GenerateContentResponse response =
                client.models.generateContent(
                        request.model(),
                        request.input(),
                        request.config()
                );

        return convert(response);
    }
}

业务层只知道:

LLMClient

不知道:

Google Gen AI SDK

这是企业架构中非常重要的边界。


15. Multimodal:Gemini 的核心优势之一

Gemini API 不应该仅仅被理解成:

Text → Text

官方 Gemini API 当前支持文本、图像等多模态输入,并进一步覆盖视频、文档等能力。([Google AI for Developers][5])

架构可以:

                 Gemini
       ┌────────────┼────────────┐
       ↓            ↓            ↓
     Text         Image        Video
       │            │            │
       └────────────┼────────────┘
                 Reasoning
                  Output

因此 Gemini 非常适合:

Document AI
Image Understanding
Video Analysis
Multimodal RAG
UI Understanding
Visual Agent

16. Multimodal Application Architecture

例如:

User
Upload PDF
Spring Boot
Object Storage
Gemini
Document Understanding
Structured JSON
Database

进一步:

PDF
Gemini
Invoice
{
   invoiceNo,
   supplier,
   amount,
   items
}

这比传统:

PDF
OCR
Regex
Parser

更加灵活。


17. Long Context

Gemini 的一个重要能力是长上下文处理。官方 Gemini API 文档将 Long Context 作为核心能力之一,可处理大量非结构化文本、图像、视频和文档。([Google AI for Developers][5])

但:

支持 Long Context ≠ 应该无限发送 Context。

例如:

1M tokens

不代表:

每次请求都发送 1M

应该建立:

Context Budget

例如:

context:
  maxTokens: 50000
  history: 10000
  documents: 30000
  userInput: 5000
  system: 5000

18. Gemini Context Caching

如果一个系统反复使用:

Large Document
Large System Prompt
Large Knowledge Base

可以考虑 Context Caching。

典型:

Large Context
Cache
Gemini

而不是:

Request 1 → 100K
Request 2 → 100K
Request 3 → 100K
Request 4 → 100K

可以转化为:

Context
Cached Context
Multiple Requests

这也是前面 Cost Optimization 中:

减少重复 Token

的重要方法。


19. Structured Output

企业系统非常不适合:

Gemini
String
Regex
Object

应该:

Gemini
Schema
Structured Output
Java Object

Gemini API 当前提供 Structured Outputs 能力,可以约束模型返回 JSON 等结构化数据。([Google AI for Developers][5])

例如:

{
  "customerName": "Alice",
  "riskLevel": "HIGH",
  "score": 87
}

对应:

public record RiskAssessment(
        String customerName,
        String riskLevel,
        Integer score
) {}

最终:

Gemini
JSON Schema
Jackson
RiskAssessment

20. 为什么 Structured Output 对 Java 很重要?

Java 企业系统强调:

Type Safety
Validation
Contract
Schema

而 LLM 默认输出:

Natural Language

两者天然冲突。

Structured Output 正好建立:

LLM
Schema
Java DTO
Business Logic

因此:

Structured Output 是 LLM 与传统 Enterprise Software 之间的重要桥梁。


21. Function Calling

Gemini 同样支持 Function Calling,官方 API 将其作为构建 Agentic Workflow 的重要能力。([Google AI for Developers][5])

流程:

User
Gemini
Function Call
Application
Function Executor
Result
Gemini
Answer

例如:

User:
查询订单 12345

Gemini:
getOrder(orderId=12345)

Java:
orderService.getOrder("12345")

Result:
SHIPPED

Gemini:
订单已经发货。

22. Function Calling 的安全边界

非常重要:

Gemini
Tool Call

不是:

Gemini
Direct Java Execution

正确:

Gemini
Tool Dispatcher
Authorization
Validation
Business Logic
Database

例如:

if (!permissionService.allowed(user, tool)) {
    throw new SecurityException();
}

LLM 永远不能绕过:

Authentication
Authorization
Validation
Audit

23. Gemini Agent Architecture

完整 Agent:

                    User
                  Agent
           ┌─────────┼─────────┐
           ↓         ↓         ↓
         Gemini     Memory     Tools
           │                   │
           ↓                   ↓
       Reasoning          Tool Executor
           │                   │
           └─────────┬─────────┘
                  Result

Gemini 在这里承担:

Reasoning
Planning
Tool Selection
Response Generation

而 Java Runtime 负责:

State
Security
Tool Execution
Persistence
Transaction
Observability

24. Streaming

企业 Chat UI 基本都需要 Streaming。

架构:

Gemini
Streaming API
Spring WebFlux
SSE
React

前端体验:

User
Request
First Token
...
Final Token

而不是:

User
等待 10 秒
一次性 Response

25. Streaming Event Architecture

不要只把 Streaming 当成:

String chunks

应该设计成:

AIEvent
 ├── START
 ├── TEXT_DELTA
 ├── TOOL_CALL
 ├── TOOL_RESULT
 ├── ERROR
 └── COMPLETE

这样前端可以:

Agent Thinking
Tool Execution
Progress
Final Answer

分别渲染。


26. Gemini Tools

Gemini 当前 API 的工具能力不仅包括 Function Calling,也包括 Google 提供的部分内置工具,例如 Google Search、URL Context、Google Maps、Code Execution 和 Computer Use 等。([Google AI for Developers][5])

因此可以:

Agent
 ├── Function Tool
 ├── Search
 ├── URL Context
 ├── Code Execution
 └── Computer Use

这意味着 Model Integration 已经从:

LLM Integration

逐渐变成:

AI Runtime Integration


27. Model Routing

企业真正需要的不是:

GeminiClient

而是:

ModelRouter

例如:

public interface ModelRouter {

    ModelEndpoint route(TaskContext context);
}

实现:

Simple Query
Flash-Lite

Normal Query
Flash

Complex Reasoning
Pro

28. Cost-aware Model Routing

可以加入成本:

Task
Complexity
Quality Requirement
Latency Requirement
Cost Budget
Model

例如:

                Task
        ┌─────────┼─────────┐
        ↓         ↓         ↓
      Easy     Medium      Hard
        │         │         │
        ↓         ↓         ↓
   Flash-Lite   Flash       Pro

最终:

[ Model^*

argmax(Quality - \lambda Cost) ]

这就是:

Cost-aware Model Routing


29. Multi-Provider Model Routing

更进一步:

                    Model Router
          ┌──────────────┼──────────────┐
          ↓              ↓              ↓
       Gemini         OpenAI        Anthropic
          │              │              │
       Flash           GPT           Claude

根据:

Cost
Quality
Latency
Availability
Region
Data Policy

选择模型。

例如:

Simple Task
Gemini Flash

Complex Reasoning
OpenAI / Gemini Pro

Enterprise Google Cloud
Vertex AI Gemini

这就是企业 AI Platform 最重要的能力之一。


30. OpenAI Compatibility:一个非常有价值的集成策略

Google 当前提供 OpenAI-compatible endpoint,可以使用 OpenAI libraries 访问 Gemini;不过官方明确说明这一兼容层仍处于 Beta,功能支持并非完全等同于原生 Gemini API。([Google AI for Developers][6])

这意味着:

Application
OpenAI SDK
Gemini OpenAI-Compatible Endpoint
Gemini

可以降低 Provider 切换成本。

但这里有一个非常重要的架构原则:

Compatibility Layer 适合快速迁移,不应该成为企业长期能力抽象的唯一基础。

因为不同模型厂商的:

Tool Calling
Multimodal
Reasoning
Context
Structured Output
Streaming
Safety

并不完全一致。


31. Native API vs OpenAI Compatibility

可以这样理解:

方案优点缺点
Gemini Native SDKGemini 能力最完整Provider coupling
OpenAI Compatibility迁移成本低能力存在差异
自建 Abstraction企业治理最好开发成本高

企业最佳实践通常是:

                 LLM Abstraction
             ┌─────────┴─────────┐
             ↓                   ↓
      Native Provider       Compatibility
        Gemini Adapter

也就是说:

企业抽象层 > OpenAI-compatible API。


32. OpenTelemetry Integration

Gemini 集成一定要考虑 Observability。

建议:

Spring Boot
AI Service
Gemini Adapter
Google Gen AI SDK
Gemini

OpenTelemetry:

Trace
 ├── HTTP Request
 ├── Prompt
 ├── RAG
 ├── Tool
 └── Gemini
      ├── model
      ├── latency
      ├── tokens
      ├── status
      └── provider

最终:

OpenTelemetry Collector
      Tempo
      Grafana

33. AI Trace 示例

一次用户请求:

Trace: abc123

POST /api/ai/chat
├── AIService
├── SemanticCache
├── RAG.retrieve
├── Gemini.generateContent
│      ├── model=gemini-3.6-flash
│      ├── input_tokens=5200
│      ├── output_tokens=800
│      └── latency=2.4s
├── Tool.getOrder
└── Gemini.generateContent
       ├── input_tokens=6300
       └── output_tokens=300

这就能够回答:

为什么慢?
为什么贵?
哪个 Agent 最耗 Token?
哪个 Tool 最慢?
哪个 Model 使用率最高?

34. Cost Observability

Gemini Integration 还应该记录:

Model
Provider
Input Tokens
Output Tokens
Cached Tokens
Request Count
Latency
Error Rate

然后:

cost_by_model
cost_by_service
cost_by_agent
cost_by_tenant
cost_by_api

最终:

AI FinOps

35. Retry 与 Rate Limit

企业系统一定要考虑:

429
5xx
Timeout
Network Error
Quota

推荐:

Gemini SDK
Retry Policy
Exponential Backoff
Jitter
Circuit Breaker

不要:

Exception
Immediately Retry

否则可能产生:

Retry Storm

36. Rate Limiter

可以使用:

Redis

构建:

Tenant
Rate Limiter
Gemini

例如:

ai:
  rate-limit:
    enterprise-a:
      requests-per-minute: 1000
      tokens-per-minute: 1000000

进一步:

Tenant
Token Bucket
Model Router
Gemini

这和你之前研究的 Redis Token Bucket 可以直接结合。


37. AI Gateway

最终推荐:

                     Applications
                      AI Gateway
        ┌──────────────────┼──────────────────┐
        ↓                  ↓                  ↓
     Security          Rate Limit         Cost Control
        │                  │                  │
        └──────────────────┼──────────────────┘
                     Model Router
              ┌────────────┼────────────┐
              ↓            ↓            ↓
           Gemini        OpenAI      Anthropic
        Google Gen AI SDK
            Gemini

这样 Gemini 只是:

Provider Adapter

而不是整个 AI Platform。


38. Gemini Model Integration 的核心设计模式

如果从软件设计模式来看,至少涉及:

Adapter

LLMClient
GeminiAdapter

Strategy

ModelRouter
Gemini / OpenAI / Anthropic

Factory

LLMClientFactory
Provider Client

Chain of Responsibility

Request
Cache
Router
Policy
Model

Circuit Breaker

Gemini
Failure
Circuit Open
Fallback

Observer

LLM Call
OpenTelemetry

39. 一个完整的 Gemini Enterprise Architecture

最终可以形成:

                              User
                         React / Mobile
                          API Gateway
                         AI Gateway
          ┌────────────────────┼────────────────────┐
          ↓                    ↓                    ↓
       Security            Rate Limit          Cost Control
          │                    │                    │
          └────────────────────┼────────────────────┘
                         Model Router
               ┌───────────────┼───────────────┐
               ↓               ↓               ↓
            Gemini           OpenAI         Anthropic
        Gemini Adapter
       Google Gen AI SDK
       ┌───────┼────────┐
       ↓       ↓        ↓
     Text   Multimodal Tools
       │       │        │
       └───────┼────────┘
          Gemini Model
           Response
      ┌────────┼────────┐
      ↓        ↓        ↓
    Cache    Metrics   Trace
      │        │        │
      └────────┼────────┘
        OpenTelemetry
        Collector
        Grafana / Tempo

40. Gemini Integration 的六个关键原则

原则一:不要把 Gemini 当成业务 API

错误:

OrderService
Gemini

正确:

OrderService
AI Service
LLM Abstraction
Gemini

原则二:Model Name 必须配置化

不要:

"gemini-xxx"

散落在业务代码。

应该:

Model Registry

原则三:Provider 必须可替换

至少:

Gemini
OpenAI
Anthropic

应该能够通过:

ModelRouter

切换。


原则四:不要只监控 HTTP

AI Observability 必须看到:

Model
Tokens
Latency
Cost
Tool Calls
RAG
Agent Steps

原则五:不要把 SDK 当 Agent Runtime

SDK 负责:

API Integration

Runtime 负责:

State
Memory
Tool
Security
Budget
Policy

原则六:不要让模型直接拥有业务权限

永远:

Model
Tool Call
Authorization
Business Logic

而不是:

Model
Database

41. Gemini Integration 与 AI Cost Optimization

你上一篇研究的 Cost Optimization,可以直接应用到 Gemini。

完整链路:

Request
Semantic Cache
Cache Hit?
 ├── Yes → Response
 └── No
   Complexity
   Model Router
 ┌────┼─────┐
 ↓    ↓     ↓
Lite Flash  Pro
 ↓    ↓     ↓
 └────┼─────┘
    Gemini
   Response

这样可以做到:

减少调用
减少 Token
减少昂贵模型使用
减少 Context
提高 Cache Hit

42. Gemini Integration 的生产级 Checklist

Client

  • Singleton Client
  • Connection reuse
  • Timeout
  • Retry
  • API version

Security

  • API Key / IAM
  • Secret Manager
  • Authorization
  • Data classification
  • Audit

Model

  • Model Registry
  • Stable version
  • Model routing
  • Fallback
  • A/B testing

Context

  • Context budget
  • Prompt optimization
  • Context caching
  • RAG
  • Multimodal input

Agent

  • Tool calling
  • Tool authorization
  • Max steps
  • Token budget
  • Timeout

Observability

  • Trace
  • Metrics
  • Logs
  • Token usage
  • Cost

43. 最终总结

如果只把 Gemini 集成到 Java 项目中:

Spring Boot
Gemini SDK
Gemini

只能称为:

Model API Integration

而企业真正需要的是:

Spring Boot
AI Service
AI Gateway
Model Router
LLM Abstraction
Gemini Adapter
Google Gen AI SDK
Gemini

并在旁边建立:

RAG
Agent
Tool Calling
Context Management
Semantic Cache
Rate Limiting
Cost Optimization
OpenTelemetry
AI FinOps

最终:

[ Enterprise\ Gemini\ Integration

SDK + Model\ Abstraction + Runtime + Governance + Observability ]

这也是理解 Model Integration 最重要的思想:

不要把 Gemini 当成一个 SDK,而应该把 Gemini 当成 AI Platform 中的一个 Model Provider。

Google 当前的 Gemini API 已经覆盖长上下文、多模态、Structured Outputs、Function Calling、内置工具、Live API 等能力,而新的 Interactions API 也进一步朝模型与 Agent 统一交互方向发展。([Google AI for Developers][5])

对于熟悉 Java、Spring Boot、微服务、Redis、Kafka、Kubernetes 和 OpenTelemetry 的后端架构师而言,真正值得深入的下一层已经不是“怎么调用 Gemini”,而是:

                 Enterprise AI Platform
              ┌──────────┴──────────┐
              ↓                     ↓
         Model Integration      Agent Runtime
              │                     │
       ┌──────┼──────┐        ┌─────┼─────┐
       ↓      ↓      ↓        ↓     ↓     ↓
    Gemini  OpenAI  Claude   Tool  RAG  Memory
       │      │      │        │     │     │
       └──────┼──────┴────────┴─────┼─────┘
              ↓                     ↓
          Model Router          Agent Runtime
              │                     │
              └──────────┬──────────┘
                   AI Gateway
          ┌──────────────┼──────────────┐
          ↓              ↓              ↓
        Cost          Security       Observability

这才是 Model Integration → AI Platform Engineering 的真正演进路径。

Vincent zhai
Vincent zhai
Full-Stack Engineer