Gemini API 多模态应用开发完全教程

适用版本： Gemini 2.5 Pro / Gemini 2.5 Flash / Gemini 2.0 系列
最后更新： 2025 年 5 月
阅读时间： 约 25 分钟

目录

1. Gemini API 架构总览
2. 环境准备与快速接入
3. 多模态输入：图像处理
4. 多模态输入：视频理解
5. 多模态输入：音频分析
6. 长上下文窗口：100 万 Token 实战
7. Function Calling：工具调用与代理
8. JSON 模式与结构化输出
9. 流式输出
10. Grounding with Google Search
11. Gemini 2.5 Pro 与 Flash 对比
12. Gemini 与 GPT-4o 全面对比
13. 企业级集成方案
14. 最佳实践与常见陷阱
15. 总结与资源

1. Gemini API 架构总览

Gemini 是 Google DeepMind 推出的原生多模态大模型系列。与"先训练文本、再接视觉编码器"的拼接方案不同，Gemini 从预训练阶段就将文本、图像、音频和视频视为统一的 token 序列，实现了真正意义上的多模态理解。

1.1 核心架构特征

1.2 API 接入层级

Google 提供两种主要接入方式：

• Google AI Studio / Gemini API：面向开发者，适合快速原型与中小规模应用。通过 generativelanguage.googleapis.com 端点访问。
• Vertex AI：面向企业，提供 SLA 保障、私有网络、IAM 权限管理、数据驻留等企业级特性。

┌──────────────────────────────────────────────────┐
│                  应用层                            │
├──────────────┬───────────────────────────────────┤
│  Google AI   │         Vertex AI                 │
│  Studio API  │  (GCP 集成, 企业 SLA)              │
├──────────────┴───────────────────────────────────┤
│              Gemini 模型服务                       │
│  ┌──────────┐  ┌──────────┐  ┌───────────────┐   │
│  │ 2.5 Pro  │  │ 2.5 Flash│  │ 2.0 Flash/Lite│   │
│  └──────────┘  └──────────┘  └───────────────┘   │
└──────────────────────────────────────────────────┘

2. 环境准备与快速接入

2.1 获取 API Key

前往 Google AI Studio 创建 API Key。免费层级包含慷慨的配额，适合开发与测试。

2.2 Python SDK 安装

pip install -q -U google-genai

注意： Google 已将 SDK 从 google-generativeai 迁移到 google-genai。新项目请使用新包。

2.3 第一个调用

from google import genai

# 配置 API Key（也可通过环境变量 GOOGLE_API_KEY 设置）
client = genai.Client(api_key="YOUR_API_KEY")

# 基本文本生成
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="用一句话解释量子计算的核心原理"
)

print(response.text)

2.4 环境变量配置（推荐）

export GOOGLE_API_KEY="your-api-key-here"

# 无需在代码中硬编码 Key
from google import genai
import os

client = genai.Client(api_key=os.environ["GOOGLE_API_KEY"])

3. 多模态输入：图像处理

Gemini 可以直接理解图像内容，无需额外的 OCR 或目标检测预处理。

3.1 从本地图像分析

from google import genai
from google.genai import types
import pathlib

client = genai.Client()

# 读取本地图片
image_path = pathlib.Path("product_photo.jpg")
image_bytes = image_path.read_bytes()

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents=[
        types.Part.from_bytes(
            data=image_bytes,
            mime_type="image/jpeg"
        ),
        "详细描述这张图片中的产品，包括颜色、材质和可能的用途。"
    ]
)

print(response.text)

3.2 从 URL 分析图像

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents=[
        types.Part.from_uri(
            file_uri="https://example.com/chart.png",
            mime_type="image/png"
        ),
        "解读这张图表的关键数据趋势。"
    ]
)

3.3 多图对比分析

# 同时传入多张图片进行对比
response = client.models.generate_content(
    model="gemini-2.5-pro",
    contents=[
        types.Part.from_bytes(data=before_img, mime_type="image/jpeg"),
        types.Part.from_bytes(data=after_img, mime_type="image/jpeg"),
        "对比这两张图片，分析它们的差异并给出改进建议。"
    ]
)

3.4 实战案例：电商商品审核系统

def review_product_image(image_bytes: bytes) -> dict:
    """自动审核商品图片是否符合平台规范"""
    client = genai.Client()
    
    response = client.models.generate_content(
        model="gemini-2.5-flash",
        contents=[
            types.Part.from_bytes(data=image_bytes, mime_type="image/jpeg"),
            """请对这张商品图片进行审核，以 JSON 格式返回：
            {
                "quality_score": 1-10,
                "has_text_overlay": true/false,
                "background_clean": true/false,
                "product_centered": true/false,
                "issues": ["问题1", "问题2"],
                "suggestion": "改进建议"
            }"""
        ],
        config=types.GenerateContentConfig(
            response_mime_type="application/json"
        )
    )
    
    return json.loads(response.text)

4. 多模态输入：视频理解

Gemini 是目前少数能直接处理视频输入的大模型之一，能够理解视频中的动作、场景变化和时间序列信息。

4.1 上传并分析视频

import time

# 第一步：上传视频文件
video_file = client.files.upload(file="demo_video.mp4")

# 等待处理完成
while video_file.state == "PROCESSING":
    time.sleep(5)
    video_file = client.files.get(name=video_file.name)

if video_file.state == "FAILED":
    raise ValueError(f"视频处理失败: {video_file.state}")

# 第二步：分析视频
response = client.models.generate_content(
    model="gemini-2.5-pro",
    contents=[
        video_file,
        "请详细描述这个视频的内容，包括主要场景、动作和关键信息。"
    ]
)

print(response.text)

4.2 视频分段分析

response = client.models.generate_content(
    model="gemini-2.5-pro",
    contents=[
        video_file,
        """请按时间顺序分析这个视频：
        1. 0-30秒发生了什么？
        2. 30-60秒发生了什么？
        3. 整个视频的核心主题是什么？
        4. 是否有需要特别注意的细节？"""
    ]
)

4.3 实战案例：会议录像摘要

def summarize_meeting(video_path: str) -> str:
    """自动生成会议录像摘要"""
    client = genai.Client()
    
    video_file = client.files.upload(file=video_path)
    
    # 轮询等待处理
    while video_file.state == "PROCESSING":
        time.sleep(10)
        video_file = client.files.get(name=video_file.name)
    
    response = client.models.generate_content(
        model="gemini-2.5-pro",
        contents=[
            video_file,
            """请生成本次会议的结构化摘要，包含：
            - 参会人员（如可识别）
            - 讨论议题
            - 关键决策与结论
            - 待办事项与责任人
            - 会议总时长估算"""
        ],
        config=types.GenerateContentConfig(
            temperature=0.3  # 低温度以提高准确性
        )
    )
    
    return response.text

5. 多模态输入：音频分析

Gemini 支持直接输入音频文件进行理解，包括语音转录、情感分析、多语言识别等。

5.1 音频转录

audio_path = pathlib.Path("interview.mp3")
audio_bytes = audio_path.read_bytes()

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents=[
        types.Part.from_bytes(data=audio_bytes, mime_type="audio/mp3"),
        "请完整转录这段音频的内容。"
    ]
)

print(response.text)

5.2 音频情感分析

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents=[
        types.Part.from_bytes(data=audio_bytes, mime_type="audio/wav"),
        """分析这段音频中说话人的情感状态：
        - 主要情绪（如平静、激动、焦虑）
        - 语气变化的关键节点
        - 整体情感倾向评分（正面/中性/负面，1-10分）
        - 潜在的沟通意图"""
    ]
)

5.3 实战案例：客服通话质检

def quality_inspect_call(audio_bytes: bytes) -> dict:
    """客服通话自动质检"""
    client = genai.Client()
    
    response = client.models.generate_content(
        model="gemini-2.5-pro",
        contents=[
            types.Part.from_bytes(data=audio_bytes, mime_type="audio/mp3"),
            """你是一名客服质检专家。请分析这段客服通话，返回 JSON 格式报告：
            {
                "call_duration_estimate": "约X分钟",
                "customer_sentiment": "positive/neutral/negative",
                "agent_tone": "professional/friendly/neutral/poor",
                "issue_resolved": true/false,
                "key_moments": [
                    {"timestamp_desc": "通话开头", "event": "客户描述问题", "quality": "good"}
                ],
                "compliance_issues": ["违规项1"],
                "overall_score": 1-100,
                "improvement_suggestions": ["建议1", "建议2"]
            }"""
        ],
        config=types.GenerateContentConfig(
            response_mime_type="application/json",
            temperature=0.2
        )
    )
    
    return json.loads(response.text)

6. 长上下文窗口：100 万 Token 实战

Gemini 的超长上下文能力是其核心竞争力之一。100 万 Token 约等于 70 万个英文单词或一整本长篇小说。

6.1 长文档处理

# 读取大型 PDF 或文本文件
with open("technical_manual.pdf", "rb") as f:
    pdf_bytes = f.read()

response = client.models.generate_content(
    model="gemini-2.5-pro",
    contents=[
        types.Part.from_bytes(data=pdf_bytes, mime_type="application/pdf"),
        "请总结这份技术手册的全部章节要点，并列出所有提到的 API 端点。"
    ]
)

6.2 多文档交叉分析

# 同时传入多个文档进行交叉分析
docs = []
for file_path in ["contract_v1.pdf", "contract_v2.pdf", "amendment.pdf"]:
    with open(file_path, "rb") as f:
        docs.append(types.Part.from_bytes(data=f.read(), mime_type="application/pdf"))

docs.append("请对比这三份文件，找出所有修改和冲突之处。")

response = client.models.generate_content(
    model="gemini-2.5-pro",
    contents=docs
)

6.3 实战案例：代码仓库分析

def analyze_codebase(repo_files: dict[str, str]) -> str:
    """
    将整个代码仓库作为上下文进行分析
    repo_files: {文件路径: 文件内容} 的字典
    """
    client = genai.Client()
    
    # 构建上下文
    context_parts = []
    for path, content in repo_files.items():
        context_parts.append(f"=== 文件: {path} ===\n{content}\n")
    
    full_context = "\n".join(context_parts)
    
    response = client.models.generate_content(
        model="gemini-2.5-pro",
        contents=[
            f"以下是项目的完整源代码：\n\n{full_context}",
            """请分析这个代码仓库：
            1. 项目架构与模块关系
            2. 潜在的 Bug 和代码异味
            3. 安全漏洞风险
            4. 性能优化建议
            5. 测试覆盖率评估"""
        ]
    )
    
    return response.text

Token 计费提示： 100 万 Token 的输入会消耗大量配额。对于超大文档，建议先用 Flash 模型做初步筛选，再用 Pro 模型深入分析关键部分。

7. Function Calling：工具调用与代理

Function Calling 让 Gemini 能够结构化地调用外部工具和 API，是构建 AI Agent 的核心能力。

7.1 定义工具函数

from google.genai import types

# 定义可用工具
def get_weather(city: str, unit: str = "celsius") -> dict:
    """获取指定城市的天气信息"""
    # 实际实现中调用天气 API
    return {"city": city, "temp": 25, "unit": unit, "condition": "晴"}

def search_products(query: str, max_results: int = 5) -> list:
    """搜索商品目录"""
    return [{"name": f"商品-{query}-1", "price": 99.9}]

# 声明工具 Schema
weather_tool = types.FunctionDeclaration(
    name="get_weather",
    description="获取指定城市的当前天气信息",
    parameters=types.Schema(
        type=types.Type.OBJECT,
        properties={
            "city": types.Schema(type=types.Type.STRING, description="城市名称"),
            "unit": types.Schema(
                type=types.Type.STRING,
                description="温度单位",
                enum=["celsius", "fahrenheit"]
            ),
        },
        required=["city"]
    )
)

search_tool = types.FunctionDeclaration(
    name="search_products",
    description="在商品目录中搜索产品",
    parameters=types.Schema(
        type=types.Type.OBJECT,
        properties={
            "query": types.Schema(type=types.Type.STRING, description="搜索关键词"),
            "max_results": types.Schema(type=types.Type.INTEGER, description="最大返回数量"),
        },
        required=["query"]
    )
)

# 创建工具集
tools = types.Tool(function_declarations=[weather_tool, search_tool])

7.2 执行 Function Calling 循环

def chat_with_tools(user_message: str):
    """完整的 Function Calling 对话循环"""
    client = genai.Client()
    
    # 工具函数映射
    available_functions = {
        "get_weather": get_weather,
        "search_products": search_products,
    }
    
    config = types.GenerateContentConfig(tools=[tools])
    contents = [types.Content(role="user", parts=[types.Part(text=user_message)])]
    
    # 对话循环
    while True:
        response = client.models.generate_content(
            model="gemini-2.5-flash",
            contents=contents,
            config=config
        )
        
        # 检查是否有函数调用
        candidate = response.candidates[0]
        has_function_call = False
        
        for part in candidate.content.parts:
            if part.function_call:
                has_function_call = True
                func_name = part.function_call.name
                func_args = dict(part.function_call.args)
                
                print(f"🔧 调用工具: {func_name}({func_args})")
                
                # 执行函数
                func_result = available_functions[func_name](**func_args)
                
                # 将结果追加到对话
                contents.append(candidate.content)
                contents.append(types.Content(
                    role="user",
                    parts=[types.Part.from_function_response(
                        name=func_name,
                        response={"result": func_result}
                    )]
                ))
        
        if not has_function_call:
            # 没有更多函数调用，返回最终回答
            return candidate.content.parts[0].text

# 使用
answer = chat_with_tools("北京今天天气怎么样？顺便帮我搜一下雨伞")
print(answer)

8. JSON 模式与结构化输出

Gemini 原生支持 JSON 格式输出，确保返回数据可直接被程序解析。

8.1 基本 JSON 模式

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="列出世界上人口最多的5个国家，包含名称、人口和首都",
    config=types.GenerateContentConfig(
        response_mime_type="application/json"
    )
)

import json
data = json.loads(response.text)
print(json.dumps(data, ensure_ascii=False, indent=2))

8.2 Schema 约束输出

from pydantic import BaseModel

class MovieReview(BaseModel):
    title: str
    year: int
    rating: float
    genres: list[str]
    summary: str
    recommended: bool

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="评价电影《盗梦空间》",
    config=types.GenerateContentConfig(
        response_mime_type="application/json",
        response_schema=MovieReview
    )
)

review = MovieReview.model_validate_json(response.text)
print(f"评分: {review.rating}/10, 推荐: {review.recommended}")

8.3 实战案例：简历解析器

from pydantic import BaseModel
from typing import Optional

class WorkExperience(BaseModel):
    company: str
    title: str
    start_date: str
    end_date: Optional[str]
    highlights: list[str]

class Education(BaseModel):
    institution: str
    degree: str
    field: str
    graduation_year: int

class Resume(BaseModel):
    name: str
    email: Optional[str]
    phone: Optional[str]
    skills: list[str]
    experience: list[WorkExperience]
    education: list[Education]
    total_years_experience: float

def parse_resume(pdf_bytes: bytes) -> Resume:
    """从 PDF 简历中提取结构化数据"""
    client = genai.Client()
    
    response = client.models.generate_content(
        model="gemini-2.5-pro",
        contents=[
            types.Part.from_bytes(data=pdf_bytes, mime_type="application/pdf"),
            "请从这份简历中提取所有信息。"
        ],
        config=types.GenerateContentConfig(
            response_mime_type="application/json",
            response_schema=Resume,
            temperature=0.1
        )
    )
    
    return Resume.model_validate_json(response.text)

9. 流式输出

流式输出可以在模型生成过程中逐步获取结果，显著改善用户体验。

9.1 基本流式输出

# 使用流式生成
for chunk in client.models.generate_content_stream(
    model="gemini-2.5-flash",
    contents="写一篇关于人工智能发展史的短文"
):
    print(chunk.text, end="", flush=True)

print()  # 换行

9.2 流式 + Function Calling

def stream_with_tools(user_message: str):
    """流式输出与工具调用结合"""
    config = types.GenerateContentConfig(tools=[tools])
    
    for chunk in client.models.generate_content_stream(
        model="gemini-2.5-flash",
        contents=user_message,
        config=config
    ):
        # 检查是否有函数调用
        if chunk.candidates:
            for part in chunk.candidates[0].content.parts:
                if part.function_call:
                    print(f"\n[工具调用] {part.function_call.name}")
                elif part.text:
                    print(part.text, end="", flush=True)

9.3 实战案例：实时聊天机器人

import asyncio
from google import genai

async def chat_stream(user_input: str):
    """异步流式聊天（伪代码，展示概念）"""
    client = genai.Client()
    
    # 收集完整响应同时实时输出
    full_response = []
    
    for chunk in client.models.generate_content_stream(
        model="gemini-2.5-flash",
        contents=user_input
    ):
        if chunk.text:
            # 实时推送给用户
            yield chunk.text
            full_response.append(chunk.text)
    
    # 完整响应用于日志或后续处理
    complete = "".join(full_response)

10. Grounding with Google Search

Grounding 让 Gemini 能够访问实时互联网信息，解决知识截止日期问题。

10.1 启用 Google Search Grounding

from google.genai import types

# 配置 Google Search 工具
google_search_tool = types.Tool(
    google_search=types.GoogleSearch()
)

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="今天的比特币价格是多少？最近有什么重大新闻？",
    config=types.GenerateContentConfig(
        tools=[google_search_tool]
    )
)

print(response.text)

# 查看搜索来源
if hasattr(response, 'grounding_metadata'):
    for chunk in response.grounding_metadata.grounding_chunks:
        print(f"来源: {chunk.web.title} - {chunk.web.uri}")

10.2 Grounding + 事实验证

def fact_check_with_sources(claim: str) -> dict:
    """使用 Google Search 验证声明的事实性"""
    client = genai.Client()
    
    response = client.models.generate_content(
        model="gemini-2.5-pro",
        contents=f"""请验证以下声明是否属实，并提供依据：
        
        "{claim}"
        
        要求：
        1. 搜索最新信息
        2. 给出真实性评级：confirmed / likely / unverified / false
        3. 列出支持或反驳的证据来源""",
        config=types.GenerateContentConfig(
            tools=[types.Tool(google_search=types.GoogleSearch())],
            response_mime_type="application/json"
        )
    )
    
    return json.loads(response.text)

11. Gemini 2.5 Pro 与 Flash 对比

选择合适的模型对成本和效果至关重要。

选择建议

def choose_model(task_complexity: str, budget: str) -> str:
    """根据任务复杂度和预算推荐模型"""
    if task_complexity == "high" and budget == "flexible":
        return "gemini-2.5-pro"      # 复杂推理、代码生成
    elif task_complexity == "high" and budget == "limited":
        return "gemini-2.5-flash"    # Flash 的思考模式也能处理复杂任务
    else:
        return "gemini-2.5-flash"    # 日常任务首选

实际经验法则： 先用 Flash 跑一遍，如果结果不满意再换 Pro。大约 80% 的生产任务 Flash 完全胜任。

12. Gemini 与 GPT-4o 全面对比

何时选择 Gemini

• 需要处理长文档（超过 12.8 万 Token）
• 需要直接分析视频或音频
• 已在使用 Google Cloud 生态
• 成本敏感，需要高性价比方案

何时选择 GPT-4o

• 已深度集成 OpenAI 生态
• 需要 DALL-E 图像生成
• 需要成熟的插件市场
• 团队已有 OpenAI API 经验

13. 企业级集成方案

13.1 Vertex AI 部署

# 使用 Vertex AI（需要 GCP 项目）
from google import genai

client = genai.Client(
    vertexai=True,
    project="your-gcp-project-id",
    location="us-central1"
)

response = client.models.generate_content(
    model="gemini-2.5-pro",
    contents="企业级查询"
)

13.2 安全过滤配置

from google.genai import types

# 配置安全过滤级别
safety_settings = [
    types.SafetySetting(
        category="HARM_CATEGORY_HARASSMENT",
        threshold="BLOCK_MEDIUM_AND_ABOVE"
    ),
    types.SafetySetting(
        category="HARM_CATEGORY_HATE_SPEECH",
        threshold="BLOCK_MEDIUM_AND_ABOVE"
    ),
    types.SafetySetting(
        category="HARM_CATEGORY_SEXUALLY_EXPLICIT",
        threshold="BLOCK_MEDIUM_AND_ABOVE"
    ),
    types.SafetySetting(
        category="HARM_CATEGORY_DANGEROUS_CONTENT",
        threshold="BLOCK_MEDIUM_AND_ABOVE"
    ),
]

response = client.models.generate_content(
    model="gemini-2.5-pro",
    contents="用户输入内容",
    config=types.GenerateContentConfig(
        safety_settings=safety_settings
    )
)

13.3 速率限制与重试策略

import time
from google.api_core import exceptions

def call_with_retry(client, model, contents, max_retries=3):
    """带指数退避的重试策略"""
    for attempt in range(max_retries):
        try:
            return client.models.generate_content(
                model=model,
                contents=contents
            )
        except exceptions.ResourceExhausted as e:
            if attempt < max_retries - 1:
                wait_time = 2 ** attempt * 5  # 5s, 10s, 20s
                print(f"速率限制，等待 {wait_time}s 后重试...")
                time.sleep(wait_time)
            else:
                raise
        except exceptions.ServiceUnavailable:
            if attempt < max_retries - 1:
                time.sleep(3)
            else:
                raise

13.4 企业架构参考

┌─────────────┐     ┌──────────────┐     ┌─────────────────┐
│  客户端应用   │────▶│  API 网关     │────▶│  负载均衡器       │
└─────────────┘     │  (认证/限流)   │     └────────┬────────┘
                    └──────────────┘              │
                                                  ▼
                    ┌──────────────┐     ┌─────────────────┐
                    │  缓存层       │◀───│  应用服务层        │
                    │  (Redis)     │     │  (业务逻辑)       │
                    └──────────────┘     └────────┬────────┘
                                                  │
                    ┌──────────────┐     ┌────────▼────────┐
                    │  监控告警     │◀───│  Gemini API 代理  │
                    │  (Prometheus) │     │  (重试/降级/熔断)  │
                    └──────────────┘     └─────────────────┘

14. 最佳实践与常见陷阱

✅ 最佳实践

1. 模型分级策略：简单任务用 Flash，复杂任务用 Pro，不要一刀切
2. Prompt 工程：系统指令（system instruction）定义角色和格式，用户消息专注任务
3. 温度控制：结构化输出用 0-0.3，创意生成用 0.7-1.0
4. 错误处理：捕获 ResourceExhausted、InvalidArgument 等常见异常
5. Token 预估：在发送前估算 Token 数，避免超出配额
6. 流式优先：用户体验敏感的场景一律用流式输出
7. 缓存复用：对相同输入的结果做缓存，节省 API 调用

❌ 常见陷阱

System Instruction 示例

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="用户的问题",
    config=types.GenerateContentConfig(
        system_instruction="""你是一位资深的 Python 后端工程师。
        - 回答要简洁、专业
        - 代码示例使用 Python 3.11+ 语法
        - 涉及安全问题时要特别强调
        - 如果不确定，明确说明而非猜测"""
    )
)

15. 总结与资源

核心要点

• Gemini 是原生多模态模型，图像/视频/音频无需额外编码
• 100 万 Token上下文窗口是处理长文档的杀手级特性
• Function Calling + JSON 模式让 AI 输出可靠地集成到应用中
• Grounding 解决了知识时效性问题
• Flash 模型覆盖 80% 场景，成本极低

学习资源

• Google AI Studio — 在线实验与 API Key 管理
• Gemini API 文档 — 官方技术文档
• Gemini Cookbook — 官方示例代码库
• Vertex AI 文档 — 企业级部署文档

下一步行动

1. 在 AI Studio 中用免费配额跑通第一个多模态 Demo
2. 用 Flash 模型构建你的第一个生产级应用
3. 评估是否需要 Pro 模型的深度推理能力
4. 如需企业部署，调研 Vertex AI 的 SLA 和安全特性

本教程基于 Gemini API 2025 年 5 月版本编写。API 细节可能随版本更新变化，请以官方文档为准。