Vertex AI SDK 已弃用：迁移截止日期 2026 年 6 月 24 日——路由团队必知

2026 年 5 月 21 日，Vertex AI 从 Google Cloud 控制台消失了。如果你的团队错过了这条新闻，以下这个细节无法再等：Vertex AI SDK 的生成式 AI 模块定于 2026 年 6 月 24 日正式移除——距今仅剩 28 天。任何在生产代码中 import vertexai.generative_models、vertexai.language_models、vertexai.vision_models、vertexai.tuning 或 vertexai.caching 的项目，都将在那天出现致命错误。控制台层面的品牌更名是视觉变化，SDK 移除则不是。

发生了什么

Google 在 2026 年 5 月完成了两项独立但相关的变更：

控制台迁移（5 月 21 日）。 Vertex AI 已不再作为 Google Cloud 控制台的顶级产品出现。搜索"Vertex AI"会跳转到新产品 Gemini Enterprise Agent Platform。模型训练、AutoML、模型注册表和 Endpoints 现在都是"以 agent 为核心"的层级下的子功能。底层 API 端点仍为 aiplatform.googleapis.com——现有 HTTP 客户端无需修改 URL——但产品品牌和控制台导航已全面替换。

SDK 弃用倒计时（6 月 24 日移除）。 google-cloud-aiplatform 中以下模块于 2025 年 6 月 24 日被弃用，将于 2026 年 6 月 24 日正式移除：

• vertexai.generative_models
• vertexai.language_models
• vertexai.vision_models
• vertexai.tuning
• vertexai.caching

替代方案是 Google Gen AI SDK（google-genai 包）。新 SDK 使用统一的 vertexai.Client（或 google.genai.Client）接口，通过同一个库同时支持 Gemini API 和 Vertex AI 后端。

此外，Google 还发布了从 OpenAI SDK 迁移到 Gen AI SDK 的官方迁移指南，专为当前通过 OpenAI-compatible proxy 调用 Gemini 的团队提供。

为什么 AI 工程团队需要重视

控制台改名令人烦恼，但无害。SDK 移除是有固定日期的破坏性变更。

如果你的代码库直接 import vertexai.generative_models，从 6 月 24 日起将抛出 ImportError 或 AttributeError。受影响场景包括：

• 通过旧版 Vertex AI SDK 调用 Gemini 模型的内部封装层
• 使用 vertexai.tuning 的微调 pipeline
• 使用 vertexai.vision_models 的视觉或多模态 pipeline
• 基于 vertexai.caching 构建的缓存层

如果你的团队通过 OpenAI-compatible proxy 调用 Gemini（包括将 /v1/chat/completions 转发给 Gemini 的 routing gateway），这次 SDK 移除不影响你——底层 HTTP API 端点没有变化。但 Google 的迁移指南积极推广迁移到 Gen AI SDK 的原生接口，对于需要访问 Gemini 特有功能（thinking budget、grounding、原生 function calling schema）的工作负载值得评估。

如果你在 requirements.txt 或 pyproject.toml 中锁定了 SDK 版本，请检查锁定的 google-cloud-aiplatform 版本是否仍然暴露这些已弃用模块。版本锁定本身无法保护你跨过 6 月 24 日，上游包一旦在包级别移除该模块，锁定版本同样受影响。请逐条检查实际的 import 路径。

新的 Gemini Enterprise Agent Platform 还发布了两项影响路由和治理决策的新功能：

• MCP Server Registry（正式可用）： Agent Platform 现在有了托管的 MCP server 注册表，无需自定义脚手架即可为 agent 挂载工具。对于正在评估是自托管 MCP 工具调度还是交由 Google 托管平面的团队，这是一个重要参考。
• Agent Identity： 每个 agent 获得一个加密标识符，用于可审计的操作记录。如果你的治理或合规工作流需要逐操作归因，这现在是 Google Cloud 的原生功能，不再需要自建。

路由与运营视角的分析

Vertex AI 改名带来了一个容易被忽视的风险：散布在代码、runbook 和 SDK 配置中的"Vertex AI"字符串，即便底层服务已改名为"Gemini Enterprise Agent Platform"，这些引用仍然存在。

需要关注以下几类具体的故障点：

1. Python 封装层中的 import 路径。 from vertexai.generative_models import GenerativeModel——这是最常见的失败路径。替换为 import vertexai; client = vertexai.Client(project=..., location=...) 并使用新 SDK 的 client.models.generate_content(...) 接口。

2. CI/CD 中的包版本。 如果你的 Docker 镜像或 CI 任务锁定了 google-cloud-aiplatform==1.x，6 月 24 日的移除会在源头影响该包。检查是否有新版本的 google-cloud-aiplatform 移除了这些模块，或者在截止日期前迁移到 google-genai。

3. 路由网关的 model ID。 Gemini model ID 本身（如 gemini-3.5-flash-preview-05-20）不会改变——只有 SDK 封装层发生变化。如果你的 gateway 通过 OpenAI-compatible 接口路由到 Gemini，model ID 和端点（https://generativelanguage.googleapis.com/v1beta/openai/）保持稳定。

4. 监控与遥测标签。 将流量分类为"Vertex AI"调用的 dashboard、成本分配标签和日志过滤器，可能需要重新标记为"Gemini Enterprise Agent Platform"或底层服务名称，以与 Google 的账单和 IAM 界面保持一致。

实际迁移决策矩阵：

TheRouter 用户应关注的内容

如果你通过 TheRouter 使用 OpenAI-compatible 接口路由 Gemini 请求，6 月 24 日的 SDK 移除不影响你的网关路由路径。Gemini 的 HTTP API 端点没有变化。

需要关注的事项：

• 审计内部 Python 代码中使用旧版 vertexai.generative_models SDK 封装 Gemini 调用的部分。即使生产路由路径是基于 gateway 的，测试环境、评估脚本或微调 pipeline 也可能仍在使用旧 SDK。

• 对照 Agent Platform 发布说明核查你的 Gemini model ID。 Vertex AI 控制台消失后，权威模型目录现在位于 Gemini Enterprise Agent Platform 文档下。之前出现在 Vertex AI Model Garden 中的任何模型名称，其文档位置可能已更新。

• 评估 Gen AI SDK 迁移指南，如果你正在构建新集成。新 SDK 的统一客户端（vertexai.Client）提供了 OpenAI-compatible proxy 无法暴露的 Gemini 特有能力——thinking budget 控制、原生 grounding、工具调用。对于这些能力至关重要的工作负载，值得建模"混合方案"：gateway 负责多 provider 路由和 fallback；原生 SDK 处理 Gemini 特有功能。

• 检查账单标签。 如果你在账本中将 Gemini 成本与其他 provider 分开追踪，请确认控制台迁移后 Google Cloud 账单仍使用相同的服务名称和 SKU。产品改名有时会导致 SKU 标签变更。