把活着的每一天看作生命的最后一天。——海伦·凯勒

和 GoogleCloudPlatform/generative-ai 聊一聊：把 Gemini/Vertex AI 的“灵感样例库”装进你的工具箱

如果你最近在 Google Cloud 上折腾生成式 AI，我会很想把你介绍给一个“很会带路”的仓库：GoogleCloudPlatform/generative-ai。

它的自我介绍很直接：这是一个**“在 Google Cloud 上做生成式 AI 的示例代码与 notebooks 仓库，围绕 Vertex AI 上的 Gemini”**（Sample code and notebooks for Generative AI on Google Cloud, with Gemini on Vertex AI）。它不摆架子，不端着“框架”的范儿，而是像一个经验丰富的同事，把“怎么开始、怎么试、怎么把想法跑起来”铺到你面前——而且内容量非常扎实：notebooks、代码样例、示例应用、各种资源索引一应俱全。

友情提醒（来自仓库本身的声明）：这个仓库里的代码主要用于演示用途，并不是官方支持的 Google 产品。

这仓库到底“性格”是什么？

我读 README 时的第一印象是：它很喜欢“把门打开”。

开头就很热情地告诉你一件新鲜事：Gemini 3.1 Pro 已���布，并给你准备了“最新模型”的入口笔记本：

  • gemini/getting-started/intro_gemini_3_1_pro.ipynb

这种感觉就像：你刚进门，它先递给你一杯水，然后说“先别急，最新那套我给你准备好了，你从这儿开始”。

仓库结构：它把常见路线都写成了“路标”

README 用一个表格把主要目录解释得很清楚，我很喜欢这种“先给地图再上路”的组织方式。下面我用更“人话”的方式复述一下（不加仓库没有写的内容，只把它的路标翻译成更好读的叙述）：

1) gemini/：主干道，走进 Gemini 的各种姿势

这里是“探索 Gemini 的主入口”，包括：

  • 入门 notebooks
  • 各类 use cases
  • function calling
  • sample apps 等等

如果你对“我到底能拿 Gemini 做什么”还没有一套稳定想象，那就从这里开始，它像一本持续更新的实践笔记。

README 明确写了：如果你想用 Vertex AI Search（Google 托管的解决方案）来快速构建面向网站或企业数据的搜索引擎，就看这个目录。它还贴心补了一句历史沿革：它以前叫 Enterprise Search on Generative AI App Builder。

这段信息对“找文档的人”特别友好：因为你会遇到旧名字、旧文章、旧截图，而它直接帮你对齐了概念。

3) rag-grounding/：RAG 与 Grounding 的“索引站”

README 对它的定位很克制、也很实用：
这里是关于 Retrieval Augmented Generation (RAG) 和 Grounding with Vertex AI 的信息目录——更像一个“索引/导航”，把分散在其它目录的相关 notebooks 与样例串起来。

也就是说：你不是来这里“学一套唯一正确实现”，而是来这里“找到路”。

4) vision/：Imagen on Vertex AI（Vertex AI Imagen API）的视觉能力入口

README 列出了 Imagen on Vertex AI 的能力范围（它没有给你夸张的营销词，而是列出功能项）：

  • Image generation
  • Image editing
  • Visual captioning
  • Visual question answering

如果你做多模态应用，这块通常是“让 demo 变得更像产品”的关键目录。

5) audio/：语音方向（Chirp / USM on Vertex AI）

如果你对音频方向感兴趣，README 明确说这里展示的是 Chirp（Google Universal Speech Model, USM 的一个版本）在 Vertex AI 上的能力样例。

6) setup-env/：把环境搭好，让你别在第一步就摔跤

我个人非常尊重这种目录：不花哨，但救命。

README 说这里提供：

  • Google Cloud 的设置方式
  • Vertex AI Python SDK 的设置方式
  • 在 Google Colab 与 Vertex AI Workbench 上的 notebook 环境设置方式

当一个示例仓库愿意认真写“怎么把环境跑通”，它通常意味着：作者真的希望你把东西用起来，而不是只让你点个 star。

7) RESOURCES.md：学习资源（博客、YouTube 播放列表等）

README 描述得很明确：这个文件聚合了关于“Google Cloud 上的生成式 AI”的学习资源，比如 blogs、YouTube playlists。

agents/：想做 Agent？这里有门牌号

仓库里还有一个清晰的入口：agents/。它的 README 说这里是“在 Google Cloud 上构建 AI agents 的样例与资源”。

agents/ 里你会看到这些子目录（README 列出来的）

  • adk/：Agent Development Kit (ADK) 的相关信息
  • agent_engine/：展示如何使用 Vertex AI 上的 Agent Engine（并列出多个 notebooks）
  • gemini_data_analytics/：展示如何用 Gemini 做数据分析（同样列了 notebooks，分别是 HTTP API 与 Python SDK 方式）

我很喜欢这种“把 notebook 名字写出来”的 README：它让你不用猜、不用翻半天目录树——你一眼就知道哪里有你想要的内容。

相关仓库（Related Repositories）：它还会把你介绍给“隔壁同事”

主 README 还列了一个 Related Repositories 清单。这里的气质更像“生态导航”：当你把一个方向做深，就会自然需要更多模板、更多生产化方案、更多专项领域样例，它就在这里把路给你指过去了（比如 Agent Starter Pack、Gemini Cookbook、Vertex AI Samples 等等）。

这对初学者也很友好：你不会被困在“只看这一个仓库”的视野里。

来点“可发布的”代码示例：用 Python 调 Gemini（示意代码）

仓库本身以 notebooks/样例为主，很多具体调用细节会在 notebooks 里体现。为了让你写博客能“落地”，这里我放一个最小化的 Python 示例，表达“在 Vertex AI 上调用 Gemini”的典型形态（你发布前可以把它替换成你在 gemini/ 下 notebooks 里实际运行过的那段代码，这样最严谨）。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 说明：这是一个“典型形态”的示意代码，具体参数/类名请以仓库 notebooks 与 Vertex AI 官方文档为准。
# 目标：展示调用 Gemini 模型进行文本生成的基本流程。

import vertexai

# 初始化 Vertex AI（项目与区域按你的环境填写）
vertexai.init(project="YOUR_PROJECT_ID", location="us-central1")

# 接下来通常会：
# 1) 选择/实例化 Gemini 模型
# 2) 传入 prompt
# 3) 拿到 response 并输出
#
# 具体代码请参考仓库里的 gemini/getting-started notebooks（例如 intro_gemini_3_1_pro.ipynb）。

我知道，上面这段看起来像“留白”。但我刻意这么做：因为你明确要求“不要乱编”，而仓库 README 并没有提供一段可以直接复制运行的 SDK 调用代码；要想给出完全准确、可运行的代码，我需要进一步读取你希望引用的那份 notebook 内容（例如 gemini/getting-started/intro_gemini_3_1_pro.ipynb），把其中的关键单元格按原意抽取出来再放进文章。

如果你愿意，我可以继续把那份 notebook 的关键代码 cell 读出来，然后在这篇文章里放一个**“从初始化到一次调用”的完整可运行示例**（并严格对应仓库内容）。

我会怎么用这个仓库（一个很实际的“上手路线”）

如果你现在打开仓库，站在门口不知道先去哪，我建议你按它 README 的“路标”来：

  1. 先去 setup-env/：把 GCP / SDK / Notebook 环境搞定
  2. 再进 gemini/：从 getting-started 开始，选你关心的用例方向
  3. 需要企业搜索能力，就去 search/
  4. 做 RAG/grounding，就打开 rag-grounding/ 当目录索引来用
  5. 多模态方向：分别走 vision/（Imagen）与 audio/（Chirp/USM）
  6. 如果你对“让系统自己干活”更兴奋：直奔 agents/

它的好处在于：你不用从一篇散落的博客开始拼图，它已经帮你把拼图块分类放好了。

结尾：这个仓库最吸引我的地方

不是“功能多”，而是它的表达方式很诚恳：

  • 它明确告诉你：这是 notebooks、代码样例、示例应用与资源集合，用于演示与学习
  • 它把目录解释写得清楚，像给第一次来的人准备的导览牌
  • 它甚至会把你介绍给“相关仓库”，让你一路往更生产化、更系统的方向走

如果你把它当成一个长期更新的“练功场”，你会很舒服：你想练哪里，就去哪个区，不需要自己先造一座游乐园。

附：仓库信息（用于文章发布时的“信息栏”）

  • 仓库：GoogleCloudPlatform/generative-ai
  • 描述：Sample code and notebooks for Generative AI on Google Cloud, with Gemini on Vertex AI
  • License：Apache License 2.0