Gemini API Cookbook Examples 进阶示例实战指南：从多模态理解到自主 Agent 的全景导航
Gemini API Cookbook Examples 进阶示例实战指南：从多模态理解到自主 Agent 的全景导航
本文是 Gemini API Cookbook 仓库中 examples/ 目录的完整实战指南，系统梳理了仓库内 35+ 个进阶示例的用途、核心技术栈与运行方式，并深入剖析其中最具代表性的实现细节（Batch 批处理、RAG 引用校验、混合检索路由、成本可观测性与自主视频生产等）。读完本文，你将掌握如何按功能标签快速定位示例、如何把多模态、结构化输出、函数调用、Grounding、Live API 等能力组合成真实可运行的应用，并理解每个示例在源码层面的实现逻辑。
目录定位：Examples 在 Cookbook 中的角色
整个 Gemini API Cookbook 仓库分为两大主线：quickstarts/（逐步教学的功能入门）与 examples/（进阶实战用例）。仓库根 README 明确指出：examples/ 中的示例演示的是"如何组合多个 Gemini API 特性或第三方工具来构建更复杂的应用"。
examples/README.md 的开篇也强调：这些是进阶示例，通常同时使用一种或多种 Gemini 能力，因此可能相当复杂。对于不熟悉相关特性的读者，官方建议先学习 Quickstarts 指南，特别是 Get started 入门教程，再回到这里做能力组合。
运行这些示例通常需要：
- 一个 Google 账号；
- 在 Google AI Studio 创建的 API Key（可参考 Authentication 完成配置）；
- 大多数 notebook 可直接在 Google Colab 中打开运行，也可以下载后在本地 Jupyter 环境执行。
核心示例全景：能力组合的 35 个实战样板
下表完整罗列了 examples/ 目录中当前维护的核心示例，包含各自的用途描述与所涉及的功能标签（功能标签即表格中 Features 列，用于快速识别该示例依赖哪些 Gemini 能力）：
| Cookbook 示例 | 描述 | 功能标签 |
|---|---|---|
| Sketch2Paint | 使用 Gemini 原生图像生成能力，把随手画的草图转换成精美的艺术画作 | Image Generation |
| Processing datasets with the Batch API | 使用 Batch API 处理收集到的日志数据集 | Batch API, Datasets |
| Audio chord extraction | 借助 Gemini 的音频理解与结构化输出，从音频文件中提取和弦进行 | Audio, JSON mode, File API |
| Browser as a tool | 演示 3 种把网页浏览器作为工具与 Gemini API 配合使用的方式 | Tools, Live API |
| Multi-spectral remote sensing | 学习用 Gemini 的图像理解能力做多光谱分析与遥感 | Multimodal |
| Illustrate a book | 用 Gemini 为开源书籍创作插图 | Gemini Image, structured output |
| Check citation faithfulness in RAG | 用"零 token 逐字校验门 + 可选的举证责任裁判"确定性验证 RAG 引用是否忠实于原文 | RAG, structured output, evaluation |
| Animated Story Generation | 通过组合故事生成、图像与音频，制作动画视频 | Imagen, Live API, structured output |
| Plotting and mapping Live | 用 Live API 让 Gemini 实时绘制复杂图表 | Live API, Code execution |
| Search grounding for research report | 用 Grounding 提升研究报告的质量 | Grounding |
| Market a Jet Backpack | 从一张产品草图出发，生成一整套营销方案 | Multimodal |
| 3D Spatial understanding | 使用 Gemini 的 3D 空间能力理解 3D 场景并回答问题 | Multimodal, Spatial understanding |
| Video Analysis - Classification | 用 Gemini 多模态能力对视频中的动物物种进行分类 | Video, Multimodal |
| Video Analysis - Summarization | 用 Gemini 生成视频内容摘要 | Video, Multimodal |
| Video Analysis - Event Recognition | 识别视频片段中发生的历史事件 | Video, Multimodal |
| Gradio and live API | 用 Gradio 部署你自己的 Live API 实例（Python 代码文件） | Live API |
| Gemini with Google ADK and Model Guardrails | 用 Google 的 Agent Development Kit（ADK）、Gemini 与云服务构建带全面安全护栏的生产级 Agentic AI 系统 | Model Armor, GDK, Gemini API |
| Pramagent trust layer for Gemini agents | 用 Pramagent 中间件为 Gemini Agent 循环增加确定性工具策略、人工介入（HITL）升级与哈希链审计追踪 | Gemini API, Tools, Guardrails |
| Apollo 11 - long context example | 在 400 页的阿波罗 11 号登月任务实录中转检索 | File API |
| Anomaly Detection | 用 Embeddings 检测数据集中的异常 | Embeddings |
| Invoice and Form Data Extraction | 用 Gemini API 从 PDF 中提取信息 | File API, Structured Outputs |
| Opossum search | 代码生成示例：让模型创建名为 "Opossum Search" 的 Web 应用，在查询词后追加 "opossum" 再调用 Google 搜索 | Code generation |
| Virtual Try-on | 虚拟试穿应用：用 Gemini 2.5 生成分割掩码识别衣物，再用 Imagen 3 生成与修补新衣服 | Spatial Understanding |
| Talk to documents | 用 Embeddings 在自定义数据库中检索对话 | Embeddings |
| Entity extraction | 用 Gemini API 加速任务处理，例如在文本中检索提取所需信息；实体提取只是一次简单查询，可要求模型以任意偏好形式返回结果 | Embeddings |
| Google I/O 2025 Live coding session | 复现 Google I/O 2025 现场编程直播使用的 notebook：实践 Gemini API SDK、GenMedia 模型、具备思考能力的模型与 Gemini API 工具 | Gemini API and its models and features |
| Gemini MultimodalBot Text & Image Tutorial | 学习用 Gemini 多模态能力同时处理文本与图像输入 | Multimodal |
| EU AI Act Compliance with Agent Module | 用 Gemini 函数调用 + Agent Module API 做欧盟 AI 法案合规检查 | Function Calling, Tools |
| GitHub issue analyzer | 用 Gemini API 对接 PyGitHub API，从这个仓库中提取有价值的洞察 | Gemini API, Tools |
| Cost Estimation and Health Monitoring | 用 Token 用量元数据跟踪 USD 成本并监控 API 健康状况 | Observability, Usage metadata |
| Gemini as a co-scientist (quantum biology) | Gemini 为鸟类"自由基对罗盘"设计量子电路，在模拟器与真实 IBM 硬件上运行，并诚实地评估这个问题到底需不需要量子计算机 | Interactions API, System instructions, Thinking |
| Multimodal Semantic Search | 使用 gemini-embedding-2 实现文本与图像间的多模态语义搜索与跨模态检索 |
Embeddings, Multimodal |
| Upload files to Colab | 演示在 Google Colab 中为 Gemini API 工作流上传与处理文件 | File API, Colab |
| Hybrid File Search + Google Search grounding | 混合 RAG：演示确定性回退路由与原生多工具路由两种模式，把私有文档搜索与 Web Grounding 结合起来 | File Search, Grounding, Tools |
| Autonomous Video Production with Omni and Agents | 端到端视频生产：视频生成、静态与 Agentic 双模式质检、以质量门控驱动的扩展重试循环，以及托管 Agent 执行 | Gemini Omni, Video Understanding, Managed Agents, Skills |
重点示例深度解析
1. Datasets：用 Batch API 批量处理日志数据集
Datasets.ipynb 演示了如何把下载到的 JSONL 日志数据集交给 Batch API 批量处理。从 notebook 源码结构看，其核心流程如下：
- 数据来自 Logging：使用 Batch API 前需要先开启日志记录并把日志收集成数据集，细节见官方 Logging and Datasets 文档。
- 批次要求模型同质：Batch API 要求每个批次内部模型名称保持一致，而数据集可能由多个模型产生，因此 notebook 会先清空既有输出的模型字段，再按模型拆分对比两个批次。
- 创建批量任务：通过
client.batches.create()提交，同一个数据集可复用到多个批次，从而并排比较不同模型的表现。 - 轮询完成状态：批次任务最长可能需要 24 小时完成，代码通过
client.batches.get(name=batch.name)轮询JOB_STATE_SUCCEEDED/JOB_STATE_FAILED/JOB_STATE_CANCELLED等状态；成功后在batch_job.dest.file_name拿到结果文件。
2. Audio chord extraction：音频理解 × 结构化输出的组合
Audio_chord_extraction.ipynb 展示了三个递进场景：用简单 prompt 从 YouTube 音乐视频中提取和弦、用类型化 schema 的结构化输出获得可预测的和弦数据、上传自己的音频文件并提取和弦。
其 prompt 要求模型返回包含 progression（和弦进行字符串）和 chords（元素含 root_note、chord_type、chord_notation 的列表）的 JSON 对象。从源码看，示例输出的典型结构形如：
{
"chords": [
{"chord_type": "minor", "chord_notation": "Em"},
{"chord_type": "major", "chord_notation": "C"},
{"chord_type": "major", "chord_notation": "G"},
{"chord_type": "dominant 7th", "chord_notation": "B7"}
]
}
音频文件通过 File API 上传，再用 JSON mode 拿到结构化结果——这是"音频 + JSON 结构化输出"两个能力叠加的典型范式。
3. Citation_Faithfulness_Check：确定性校验 RAG 引用忠实性
Citation_Faithfulness_Check.ipynb 解决的是 RAG 系统中"模型声称引用了某文档，但引用内容并不可靠"这一信任问题。其方案由两级组成：
- 零 Token 逐字校验门（verbatim gate）：纯 Python 实现、不调用模型、不需要 API Key，做大小写/排版/空白不敏感（case/typography/whitespace-insensitive）的逐字匹配，判定引用是否真的出现在源文档中。示例会刻意植入"忠实引用 + 三种失败模式"来验证门的判别能力，例如
"quote": "context window of up to 1 million tokens"被标记为忠实。 - 可选的举证责任裁判（burden-of-proof judge）：仅对通过逐字门但语义模糊的引用调用，默认将举证责任置于引用方——外部知识无法证实时就判为不支持。
4. Cost_Estimation_And_Health_Monitoring：Token 用量可观测性
Cost_Estimation_And_Health_Monitoring.ipynb 为 Gemini API 应用提供了一个可复用的 GeminiObservability 类，实现三个目标：从 API 响应中提取 Token 用量元数据、基于模型定价实时计算 USD 成本、执行健康检查验证 API 可用性与配额。
从源码看，成本估算的核心是读取 usage_metadata.prompt_token_count 与 usage_metadata.candidates_token_count，各自除以 1,000,000 后乘以对应模型的每百万 Token 单价（不同模型自动适配不同定价）；健康检查则是发起一次最小化的 API 调用，返回 True 表示 API 正常。这个类可以直接集成进任何 Gemini API 应用做成本与健康监控。
5. hybrid_file_search_and_google_search：混合 RAG 的两种路由模式
hybrid_file_search_and_google_search.ipynb 展示如何把两种 Grounding 工具组合成混合 RAG 系统：
- 确定性回退路由（Deterministic fallback routing）：先只启用 File Search 查询私有文档，检查返回内容；若没有命中的引用，再回退到 Google Search Grounding。路由决策完全由代码控制，可审计、推理成本低。
- 原生多工具路由（Native multi-tool routing）：在同一请求中同时传入两个工具，让 Gemini 自行决定用哪一个。
两种模式都依赖 response.candidates[0].grounding_metadata 中的引用信息：File Search 填充 chunk.retrieved_context（检索到的文本、文档标题等），Google Search 填充对应的引用字段。notebook 提供了一个辅助函数把两者归一化为统一的 dict。另外值得注意：File Search 会把上传文档关联到 API Key 所属的云项目，因此创建 store 与上传文档涉及长时运行任务，需要保存 store 名称供后续调用与清理使用。
6. Autonomous_video_production_with_omni_and_agents：自主视频生产流水线
Autonomous_video_production_with_omni_and_agents.ipynb 构建了一条自主、带质量控制的视频生产流程，组合了五项核心能力：
- Gemini Omni Flash（
gemini-omni-1.1-flash）：单次调用生成 10 秒开场镜头，包含富有表现力的台词、自然的音频节奏与连续运镜。 - 双模式质检：静态质检直接通过
previous_interaction_id复用交互上下文，由gemini-2.5-pro以"严格的法医级 VFX 质量主管"身份审查（捕捉背景纹理漂移、反向行走步态、亚秒级拟音不同步等问题）；Agentic 质检则走独立的交互审查路径。 - 质量门控的扩展重试循环：通过向
client.interactions.create()传入previous_interaction_id=turn1.id原生续接片段，模型检查上一段结尾后追加连续的 10 秒延续，扩展结果必须再次通过质检才会被采纳。 - Agent Skills 与托管 Agent：把生产工具封装进 Agent Skill，用托管 Agent 环境编排出一条完整的 30 秒连续镜头序列。
7. avian_magnetoreception：Gemini 作为科研协作者
avian_magnetoreception.ipynb 让 Gemini 扮演量子生物学研究伙伴：由 Gemini 从哈密顿量与可观测量出发设计量子电路（三自旋 1/2 粒子模型，模拟自由基对机制，需要 google-genai>=2.9.0 支持 Interactions API），配套使用 qiskit 构建/模拟电路、qiskit-ibm-runtime 对接真实 IBM 硬件。notebook 预录了真实 IBM 硬件与经典基准结果（每个数 KB 的 JSON），因此整份 notebook 无需 IBM Quantum 账号即可从笔记本完整跑通。最有趣的是结尾：Gemini 被要求诚实地评估"这个问题真的需要量子计算机吗"，而答案是不需要——把"为什么不需要"讲清楚恰恰是本例最有价值的部分。
旧版 SDK 示例：仍然值得借鉴的思路库
examples/README.md 还保留了一批基于旧版 SDK 的示例，它们应该仍可运行，且是获取创作灵感的好来源：
- Anomaly detection with embeddings：用 Embeddings 检测数据异常。
- Agents and Automatic Function Calling：创建一个帮你点咖啡的 Agent（Barista-bot）。
- Classify text with embeddings：把 Gemini API 的 Embeddings 与 Keras 结合做文本分类。
- Clustering with embeddings：用 Embeddings 对文本数据集做聚类。
- Guess the shape：在 prompt 中使用图像的简单示例。
- Search Wikipedia with ReAct：用 ReAct prompting 搭配 Gemini Flash 交互式搜索 Wikipedia。
- Story writing with prompt chaining：用 prompt chaining 与迭代生成两个工具写故事。
- Tag and Caption images：用 Gemini 视觉能力 + Embedding 模型为服装图片打标签与写说明。
- Voice Memos：基于手机录制的语音备忘录与历史文章，用 Gemini API 为下一篇博客文章生成创意。
- Search for information on documents：用 Embeddings 跨文档检索。
- Search Re-ranking with Embeddings：用 Embeddings 对搜索结果重排序。
- Talk to documents：RAG 基础入门——用 Embeddings 在自定义数据库中进行检索对话。
- Translate a public domain：把 Gemini 当作翻译工具，演示数据准备、有效 prompt 构造与把结果保存为
.txt文件。 - Working with Charts, Graphs, and Slide Decks：Gemini Flash 从各类图表图像中提取数据。
- Entity extraction：用 Gemini API 加速文本信息提取。
第三方生态集成：向量数据库与可观测性工具
examples/ 下还按目录组织了与第三方生态的集成示例，把 Gemini API 与向量数据库、检索框架、可观测性平台组合使用：
- Personalized Product Descriptions with Weaviate：把数据载入 Weaviate 向量库，用 Gemini Embeddings 构建语义搜索，创建知识图谱，并为不同用户画像生成个性化商品描述。配套的 weaviate/docker-compose.yml 可用于本地拉起 Weaviate 服务。
- Similarity Search using Qdrant：加载网站数据，用 Gemini Embeddings 构建语义搜索并存入 Qdrant 向量库执行相似度检索。
- Movie Recommendation using Qdrant：用 Gemini API 处理并 Embedding 大型电影数据集，索引到 Qdrant 后构建基于向量相似度的电影推荐器。
- MLflow Tracing for Observability：用 MLflow tracing 捕获与 Google GenAI APIs 交互的详细链路信息。
- Cross-modal Retrieval with Gemini Embedding and Haystack：用 Gemini Embedding 2 搭配 Haystack 实现文本检索、RAG 以及文本/图像/视频/PDF 的跨模态检索。
专题目录：按能力方向组织的进阶资源
examples/ 目录还包含若干按主题聚合的子目录，适合按学习路径系统性阅读：
- Prompting examples：各类提示工程技巧的示例集合（包括 Role Prompting、Few-shot、Chain-of-thought、Self-ask 等，可参考 prompting/README.md）。
- JSON Capabilities：用 JSON schema 完成不同类型任务的指南（实体提取、情感分析、文本分类、文本摘要等，详见 json_capabilities/README.md）。
- Automate Google Workspace tasks with the Gemini API：一个 codelab，教你用 Apps Script 连接 Gemini API，通过函数调用、视觉与文本能力自动化 Google Workspace 任务——包括总结文档、分析图表、发送邮件、直接生成幻灯片，全程只需一个自由文本输入（配套 main.gs 与 utils.gs 源码）。
- Langchain examples：Gemini 与 LangChain 结合的多个示例（含 SQL 对话、代码分析、问答、摘要等，见 langchain/README.md）。
- Prompting techniques：更进阶的提示工程模式（详见 prompting_techniques/README.md）。
如何高效使用这份示例清单
把 examples/ 目录当作一本"能力组合字典"来用会最高效：
- 按功能标签反查：如果你只关心 Embeddings，看 Talk to documents、Anomaly Detection、Multimodal Semantic Search 即可；如果做 Agent 相关开发，则优先看 Browser as a tool、EU AI Act Compliance with Agent Module、gemini_google_adk_model_guardrails.ipynb 与 Autonomous_video_production_with_omni_and_agents.ipynb。
- 先 Quickstart 后 Examples：表格中每个能力（File API、JSON mode、Grounding、Live API、Embeddings 等）在 quickstarts/ 中都有单点入门教程，先在 Quickstart 里弄清单一能力，再对照本文的示例组合。
- 区分新旧代码：表格上半部分是当前维护的核心示例，下半部分标注为 legacy SDK 的示例更偏思路参考，移植到新版 SDK 时注意 API 差异。
- 关注可复用的代码：
GeminiObservability类（成本/健康监控）、verbatim citation gate（引用校验）、混合路由辅助函数（grounding 归一化）等都是可以直接提取复用到自己项目中的工程组件。
总而言之，examples/ 目录是 Gemini API 从"会调用"走向"会组合"的最佳进阶素材库。沿着本文的功能标签与源码剖析，你可以按图索骥，把多模态输入、结构化输出、检索增强、函数调用与实时交互等能力组合成真正可落地的应用。