Google Cloud Vertex AI Samples：你的 Vertex AI 全链路实战百科

Google Cloud Vertex AI 官方示例库

想象一下这样的场景：你刚拿到 Google Cloud 的结算账户，想要在 Vertex AI 上跑一个 Gemini 模型做文本生成，却发现官方文档浩如烟海，SDK 文档也是英文的，看了两小时还没跑通第一个 API——这时候，vertex-ai-samples 就是你的救星。

这是 Google Cloud 官方维护的 Vertex AI 完整示例库，包含 4000+ 精选 Notebook、社区贡献的实战代码，以及面向 AI Agent 的 Skills 模块。自 2022 年上线以来已累计超过 4280 次提交，GitHub 获得 779 颗星，是 Vertex AI 开发者入门和进阶的权威参考资源。

背景：为什么 Vertex AI 需要一个专属示例库？

Vertex AI 是 Google Cloud 在 2021 年推出的统一 AI 开发平台，定位是"企业级 AI 开发的超级入口"。它整合了 AutoML、Vertex AI Pipelines、Model Garden、Vertex AI Agent Builder 等数十项服务，覆盖从数据标注、模型训练、超参调优、特征工程到模型部署、监控的全链路。

然而，Google Cloud 的产品迭代速度极快——Gemini 模型从 2023 年的首次亮相到如今的 2.5 Flash，Vertex AI Agent Engine 从预览到 GA，MLOps 组件不断新增和废弃。对于普通开发者来说，光是搞清楚"我想训练一个文本分类模型，应该用 AutoML 还是 Vertex AI Custom Training"就需要大量调研时间。

vertex-ai-samples 正是为了解决这个问题而生的：它由 Google Cloud 工程师维护，每个 Notebook 都对应一个真实的使用场景，用户可以直接在 Colab 或 Vertex AI Workbench 中打开运行，跳过"环境搭建"的痛苦阶段。

核心内容：三大板块覆盖完整 AI 工作流

notebooks/official：28 个领域的官方 Notebook

这是仓库的核心资产。notebooks/official 目录按应用场景分为 28 个子目录，每个子目录对应一个 ML 领域：

目录	内容
generative_ai	生成式 AI：Gemini API 调用、RAG、RLHF 微调
automl	AutoML 自动化机器学习
pipelines	Vertex AI Pipelines（Kubeflow Pipelines）
model_registry	模型注册与版本管理
feature_store	特征存储与共享
prediction	模型推理与端点部署
training	自定义训练任务
model_evaluation	模型评估与基准测试
workbench	Vertex AI Workbench 使用指南
vector_search	向量检索（Embedding + 近似最近邻）
mcp	Model Context Protocol 集成示例
bigquery_ml	BigQuery ML 与 Vertex AI 联动

每个 Notebook 都严格遵循 Google Cloud 的 Notebook 模板规范，包含：数据加载 → 特征工程 → 模型训练 → 评估 → 部署的完整流程，以及运行环境的说明和前置依赖。

community-content：社区贡献的实战案例

由社区开发者贡献的真实项目实战，涵盖 PyTorch 分布式训练、TensorFlow Agent 强化学习、AlphaFold 结构预测、sklearn 文本分类等场景。这些内容非官方维护，但经过 Google Cloud 工程师审核，代码质量有保障。

值得注意的是，community-content 中的许多案例展示了如何用开源框架（PyTorch、scikit-learn）替代 Vertex AI 的内置工具，实现更灵活的自定义训练。例如"PyTorch 分布式图像分类"案例详细演示了如何用 Vertex AI SDK 提交自定义 PyTorch 分布式训练任务，配合 TorchServe 进行模型服务化。

skills：面向 AI Agent 的技能模块

这是 2024 年新增的模块，也是该仓库最有前瞻性的部分。skills/ 目录下包含多个 Vertex AI 技能包：

• skills/vertex-inference：封装了 Gemini 模型调用的核心技能，包括流式输出、多轮对话、函数调用（Function Calling）、上下文窗口管理等。这是面向 AI Agent 开发者的"Vertex AI 调用手册"。
• skills/vertex-tuning：覆盖 Vertex AI 托管微调的完整流程，从数据集准备（JSONL 格式）到 LoRA/RLHF 微调任务提交，再到模型验证和部署。亮点是提供了 Axolotl Docker 镜像的集成方案，支持 Gemma 全系列（1B 到 27B）的微调。
• skills/genai-sdk：封装 GenAI SDK 的常用工作流，提供预置的 Prompt 模板、few-shot 示例和输出解析工具。
• skills/vertex-deploy：专注于 Vertex AI Endpoints 的部署操作，包括多版本 A/B 测试、流量拆分、自动扩缩容配置。

这些 Skills 模块的设计目标是让 AI Agent（尤其是基于 Google ADK 构建的 Agent）能够"调用 Vertex AI 作为工具"，代表了 Google Cloud 在 Agentic AI 方向上的重要布局。

Vertex AI 平台架构

技术栈与架构分析

主力语言：Python（主）+ Jupyter Notebook

核心依赖：

• google-cloud-aiplatform：Vertex AI Python SDK，是所有 Notebook 的基础设施
• langchain / langchain-google-vertexai：RAG 和 Agent 开发首选
• google-generativeai：Gemini 原生 API 调用
• kfp（Kubeflow Pipelines SDK）：流水线编排
• tensorflow、torch、scikit-learn：传统 ML 框架

架构类型：这是一个"示例库"架构，不是传统的应用架构。代码按"功能域"组织（notebooks/official/*），每个 Notebook 都是独立可运行的最小单元，通过 Vertex AI SDK 与云端服务通信。这种设计的好处是零学习成本——用户打开一个 Notebook 就获得了一个完整的端到端示例。

AI 框架使用：深度依赖 Google 自家的 AI 生态（Gemini、PaLM、Tuning），同时兼容开源生态（PyTorch、TensorFlow、LangChain）。在生成式 AI 领域，已支持 RLHF（通过 skills/vertex-tuning）、RAG（通过 LangChain 集成）、Function Calling（Gemini 原生支持）和 Agentic Workflow（Vertex AI Agent Engine）。

上手指南：从零到跑通第一个 Notebook

门槛说明：这个项目本身不是一个"安装即用"的应用。你需要：

1. 一个 Google Cloud 项目（拥有结算账号）
2. 启用 Vertex AI API
3. 有 Colab 或 Vertex AI Workbench 的访问权限

如果你有上述条件，选择一个对应的 Notebook，在 Colab 中打开（Notebook 顶部有"Open in Colab"按钮），填写项目 ID 和区域，然后依次运行单元格即可。

快速入门推荐：

• 生成式 AI 新手 → notebooks/official/generative_ai/intro_gemini_sdk.ipynb
• 想微调自己的模型 → skills/vertex-tuning/README.md
• 想构建 RAG 应用 → notebooks/official/generative_ai/rag_intro_vertex_ai_rag_engine.ipynb

Skills 模块使用：skills 目录下的模块面向 AI Agent 场景。如果你正在用 Google ADK 或自定义 Agent，可以通过导入 Skills 的 Python 代码片段，让 Agent 理解如何调用 Vertex AI 服务。

争议与局限：这不是银弹

云厂商锁定：所有代码都与 Google Cloud 强绑定。一旦选定了 Vertex AI，后续的模型、微调、部署都将依赖 Google Cloud 的服务和定价策略，迁移成本较高。竞争对手 AWS SageMaker 和 Azure AI Studio 都有各自对应的示例库，如果你有多云需求，这个库的参考价值会打折扣。

文档同步问题：Google Cloud 产品迭代速度极快，Vertex AI 的 API 变化频繁。社区反馈中多次提到部分 Notebook 版本过旧，某些 API 参数已变更但 Notebook 未同步更新。官方虽在积极维护（4280 次提交），但 Notebook 的时效性仍需在使用前确认。

企业使用门槛：该库的核心受众是"有 Google Cloud 预算"的团队，而非个人开发者或初创公司。Vertex AI 的定价不低，实验一次模型的微调成本可能从几十到几百美元不等，限制了学习者的实验频率。

行业意义：从示例库到 AI Agent 技能平台

vertex-ai-samples 的演进轨迹，某种程度上反映了 Google Cloud AI 战略的变化。2022 年刚上线时，它是一个标准的"产品示例库"；2024 年 Skills 模块的加入，标志着 Google 正在将 AI 平台的能力"原子化"，让 AI Agent 能够通过 Skills 调用 Vertex AI 的各项服务。

这意味着未来企业构建 AI Agent 时，可以直接依赖 Google Cloud 的 Skills 库来调用 Gemini、部署模型、执行微调——不需要人类工程师手动编写调用代码，而是 Agent 通过 Skills "理解"并"使用"这些工具。这是一个从"开发者工具"到"AI 原生平台"的重要跨越。

如果你正在或计划使用 Google Cloud Vertex AI，这个仓库是必备的参考资源。建议重点关注 skills/ 目录的演进，以及 generative_ai 子目录中关于 Gemini 2.5 和 Vertex AI Agent Engine 的最新 Notebook。