Google Cloud官方Vertex AI发布说明显示，Vertex AI Extensions已进入弃用流程，并将在2026年11月26日之后停用，官方建议迁移到Agent Platform。本文资料核验日期为2026年8月14日，面向已经使用Extensions的开发团队，给出接口盘点、权限调整、回归测试和上线回滚步骤。具体可用区域、配额和迁移工具以你的Google Cloud项目为准。
先看结论：不要等到停用前再改，先做依赖清单
迁移工作通常分为三类：调用接口变化、身份与权限变化、监控和错误处理变化。先冻结当前版本和关键样本，再建立新旧实现的并行验证环境，能显著降低一次性切换风险。
| 对象 | 迁移前记录 | 上线前验证 |
|---|---|---|
| 接口 | 端点、请求体、响应字段 | 字段映射、超时、错误码 |
| 身份 | 服务账号、角色、密钥来源 | 最小权限和审计日志 |
| 工具 | 扩展名称、参数和回调 | 工具调用与人工确认 |
| 监控 | 指标、告警和预算 | 新平台日志与成本标签 |
迁移时最容易被忽略的三个环节
响应结构和错误语义
即使业务目标相同，新平台也可能改变字段名称、分页方式、超时和错误码。把响应解析、重试和降级逻辑单独列为迁移任务，不要只替换URL。
权限与数据出口
重新检查服务账号能访问哪些项目、存储桶和第三方系统。迁移测试应使用脱敏资料，外部写操作先关闭或改为人工确认。
观测与预算
为新平台增加请求量、延迟、失败率、token和费用监控，并保留旧平台的基线。没有可比较的指标，就很难判断迁移是否完成。
四阶段迁移清单
- 盘点：导出Extensions调用、工具、服务账号和依赖项目。
- 建适配层：把请求、响应、错误和重试封装在单独模块。
- 并行回归：用固定样本比较结果、权限、延迟和成本。
- 灰度上线：先切低风险流量，保留旧实现和明确回滚开关。
适用条件
- 团队能访问项目配置、日志和IAM权限。
- 业务有可脱敏的回归样本和验收人。
- 迁移期间可以同时保留新旧两套实现。
限制与风险
- 停用日期和迁移建议来自Google Cloud官方发布说明，后续可能更新。
- Agent Platform的区域、计费、配额和功能不一定与旧扩展相同。
- 自动化写操作、支付和客户数据处理必须保留人工审批。
FAQ
现在就必须停止使用Extensions吗？
官方给出的停用时间是2026年11月26日之后，但迁移验证需要时间，建议尽早开始盘点和小流量测试。
只替换SDK就能完成迁移吗？
通常不够。接口、权限、错误处理、日志、预算和回滚都需要重新验证。
怎样判断可以关闭旧实现？
至少要有稳定回归结果、生产监控、负责人确认和可演练的回滚路径。
