奇 奇连 AI
学习路线图课程工具计算器企业服务关于加入会员

Gemini API 迁移到企业平台：Vertex 后端只改客户端这几行

2026-08-25

数据截至 2026-08，价格与限额以各官网为准。本文只讲计费与接入机制，不列具体价格数字。

结论先摆在这儿：Gemini 的两条产品线共用同一套 Google Gen AI SDK，所以从 Developer API 迁到 Gemini Enterprise Agent Platform，改动集中在客户端初始化那一处——Python 是给 genai.Client() 加上 vertexai、project、location 三个参数，JS/TS 是给 new GoogleGenAI({}) 的配置对象加同名字段，Go 是在 ClientConfig 里填 Project、Location 并把 Backend 设为 genai.BackendVertexAI。生成调用那部分代码不动。真正麻烦的不是这几行，而是代码之外的那一层：你在 Developer API 上熟悉的限流口径、结算方式、缓存行为，官方是写在 Developer API 自己的文档里的，切换产品线之后是否原样成立，得回企业平台自己的文档去确认，别默认继承。

先把两个名字对上号

Google 在文档里给出的是两条产品线：Gemini Developer API 和 Gemini Enterprise Agent Platform API。前者的官方定位是构建与扩缩的最快路径，后者提供企业就绪的功能与服务，由 Google Cloud Platform 支撑。

这里有个很容易把人搜懵的地方：产品名里写的是 Gemini Enterprise Agent Platform，但 SDK 里控制走哪条线的那个开关，字段名叫 vertexai，Go 那边的常量叫 genai.BackendVertexAI。名字和产品名对不上，所以你按产品名去搜代码示例，和按字段名去搜代码示例，命中的可能是不同批次的文档。遇到搜不到的情况，两个词都换着试一遍。

另外要先摆正一个预期：官方给的建议是，除非你确实需要特定的企业控制能力，多数开发者应当继续用 Developer API。也就是说，这不是一条「早晚都要走」的升级路径，而是一条按需求触发的分叉。没有明确的企业侧诉求就迁过去，你换来的只是更复杂的项目与账号结构。

三种语言各改哪几行

官方给出的迁移形态是同构的：初始化时告诉 SDK 走企业后端，并补上项目与位置两个参数。

Python 用 google-genai：

# Developer API
client = genai.Client()

# Gemini Enterprise Agent Platform
client = genai.Client(vertexai=True, project='...', location='...')

JS / TS 用 @google/genai：

// Developer API
const ai = new GoogleGenAI({});

// Gemini Enterprise Agent Platform
const ai = new GoogleGenAI({ vertexai: true, project, location });

Go 用 google.golang.org/genai：

// Developer API
genai.NewClient(ctx, nil)

// Gemini Enterprise Agent Platform
// 第二个参数改为 ClientConfig{Project, Location, Backend: genai.BackendVertexAI}

Go 这一段刻意只写到字段这一层。官方材料里给出的就是 genai.NewClient(ctx, nil) 这个调用表达式和 ClientConfig 里的三个字段名，至于返回值怎么接、错误怎么处理、配置对象是取址传还是值传，完整写法以官方示例为准，这篇不按 Go 的常见惯例替你补全——补错一个符号，你反而要花时间去怀疑是不是版本对不上。

三段代码的共同点是：变的是「客户端从哪来」，不是「客户端怎么用」。project 与 location 具体该填什么值、有哪些取值，官方示例里是占位形式，实际取值以官方文档为准，这篇同样不替你猜。

为什么调用层可以原封不动

这一点值得多说两句，因为它决定了迁移工作量的量级。

Gen AI SDK 是一套统一 SDK，两条产品线共用它。你写的生成调用——传 prompt、传多模态内容、拿响应——是挂在 client 对象上的方法，而不是绑死在某个端点上。所以 client 换了后端，方法签名不变，你那份 generate_content 调用代码就不需要跟着改。

对工程上的直接影响是：如果你的项目一开始就把「构造 client」这件事收在一个地方（一个工厂函数、一个依赖注入的 provider、一个模块级单例），那么迁移就真的只是改那一个文件。反过来，如果你在十几个业务文件里各自 genai.Client() 一遍，改动量就是十几处，还容易漏。这不是 Gemini 的问题，是任何一次换后端都会暴露的老账——所以更一般的迁移准备工作，可以先看这份更换模型厂商的迁移清单，把「客户端构造集中化」这一步提前做掉，等真要迁的时候才是几行的事。

代码之外那一层才是真成本

「只改几行」说的是代码。迁移真正需要盘的是账号侧，而这一块的麻烦在于：没有任何一行代码会提醒你去改它，编译器不报错，调用也照样发得出去。

在 Developer API 这边，官方文档写明的机制包括这些：限流是按项目应用而不是按 API 密钥应用，所以多申请几把密钥并不能拿到更多配额；层级、限流、账号上限都是在结算账号级别确定的，项目从一个结算账号换到另一个，层级和限流会跟着新结算账号变；API 密钥本身没有独立的结算设置，它继承所属项目的层级与结算状态，同一个项目里所有密钥的用量合并计入。这些规则的存在，意味着 Developer API 侧的「配额画像」是围绕项目 + 结算账号这对概念组织起来的。想把这层机制吃透，可以配合Gemini 限流是按项目算的，不是按 API 密钥算的一起看。

关键在于：上面这些是官方在 Developer API 文档里给出的规定。切到 Gemini Enterprise Agent Platform 之后，配额、层级、结算这些是否沿用同一套口径，官方事实材料里没有找到对应说明，所以本文不做任何推断。正确做法是把它当成一个必须重新确认的开放项，去企业平台自身的文档里逐条核对，而不是把 Developer API 的经验直接搬过去用。

同样属于「需要重新确认」的还有几处，它们在 Developer API 文档里都有明确限定：

  • Batch API 目前仅适用于 generateContent API，这是官方在批量页首的注意事项里点明的；
  • Interactions API 只支持隐式缓存，不支持显式缓存，要用显式缓存必须改走 generateContent；
  • 隐式缓存对 Gemini 2.5 及更新型号默认启用，但有最低输入 token 门槛，且门槛因模型而异；
  • 计费依据里包含缓存 token 的存储时长这一项，也就是缓存的存储是单独计价的。

这些条目在企业平台上是否一字不差地成立，官方文档里没有找到跨产品线的对照说明。迁移前把它们列成一张待核清单，比迁完了再发现某个功能不通要省事得多。

鉴权这一层：一边写明了，另一边得自己去查

Developer API 侧的鉴权形态，官方是写明的：原生 REST 走请求头 x-goog-api-key，OpenAI 兼容层走 Authorization: Bearer，配合兼容端点 https://generativelanguage.googleapis.com/v1beta/openai/。这两种形态各自对应哪种接入方式，是没有歧义的。

企业平台侧则要说得更保守一些。官方材料在迁移这一格给出的全部内容，就是客户端初始化多出 vertexai、project、location（Go 侧对应 Project、Location、Backend）这几个参数，至于企业平台用的是哪种凭据形态、怎么签发、怎么轮换，官方事实材料里没有找到相应说明。这里要提醒的是：既不要默认它和 Developer API 一样还是一把 API 密钥走天下，也不要反过来默认它一定换了另一套凭据体系——初始化多出几个参数，和鉴权方式是否改变，本来就是两件可以互不相干的事，从前者推后者两个方向都缺依据。鉴权属于必须去企业平台自身文档单独确认的一项，确认之前不要动手改部署。

不过有一件事不依赖上面那个未知项也成立：迁移必然要动客户端构造这段代码，而客户端构造正是凭据从环境变量、配置中心、CI 变量里被读进来的地方。既然这段代码本来就要改，顺手把凭据的存放位置、有没有被硬编码进仓库、CI 里是不是明文，这几项一次过一遍，边际成本几乎为零。具体做法参考API Key 的安全管理。

顺带提一句 OpenAI 兼容层：Developer API 有那个 /v1beta/openai/ 端点，官方也说明了从 OpenAI 库切过来只需要改 api_key、base_url、model 三处；官方同时给了一条选型建议——如果你还没有在用 OpenAI 库，推荐直接调用 Gemini 原生 API，而不是特意绕一层兼容层。但企业平台是否提供对应的兼容端点，官方文档里没有找到说明。如果你的代码是走 OpenAI SDK 而不是 Gen AI SDK 接进来的，那「只改客户端几行」这个结论就不一定适用于你——本文讲的迁移路径，前提是你用的是 Gen AI SDK。

区域这一条得单独说

有一类迁移动机跟企业控制无关，纯粹是因为区域。

官方事实是这样的：Gemini API 与 Google AI Studio 在官方页列出的国家/地区推出，该列表中不包含中国大陆；对于不在支持区域的用户，官方给出的路径是改用 Gemini Enterprise Agent Platform 中的 Gemini API。除区域之外还有两条非区域的准入条件——最低年龄 18 周岁，以及需要在 Google 账号中完成年龄验证。另有一个 Colab 特例值得知道：区域限制是按 Colab 实例所在区域判定的，不是按用户所在区域，官方给的自查命令是 !curl ipinfo.io。

这里只转述官方陈述，不展开任何别的东西。国内团队如果确实有这方面需求，走的应该是企业采购这条正规路径，或者直接评估国内合规的替代平台。本站也写了不少篇国产平台的接入与计费机制，选型时可以横着比一比。区域政策本身的更多细节，另见Gemini API 的区域可用性怎么看。

迁之前先过一遍这张单子

把上面的内容压成可执行的顺序，大概是这样：

  1. 先确认动机。官方的建议是，没有特定企业控制需求就留在 Developer API。动机不清楚，迁过去只是把架构搞复杂。
  2. 确认你走的是 Gen AI SDK。是，那「改客户端初始化」这条路成立；不是（比如走 OpenAI 兼容层接入），先解决 SDK 这一层。
  3. 把 client 构造收敛到一处。这一步做完，真正的代码改动才是几行。
  4. 列出你依赖的每一个平台侧行为——批量、缓存、限流口径、错误码处理，逐条去企业平台文档里确认，别默认继承 Developer API 的规则。
  5. 顺手盘一次凭据。企业平台用什么凭据形态要另行确认，但客户端构造这段代码既然要动，凭据的存放方式正好一并检查。
  6. 留一条回退路径。既然改的只是客户端初始化，那用一个环境变量控制走哪条后端、保留双向切换能力，是几乎零成本的保险。

最后强调一次本文的边界：这篇能给出的确定结论只有一条——两条产品线共用统一 SDK，模型调用代码不用动，改的是客户端初始化那几行。至于企业平台上的配额、结算、缓存、兼容端点具体是什么规则，官方事实材料里没有覆盖，本文一个字都没有替你补。迁移这种事，改错一行代码很快就会暴露出来，把上一个平台的假设原样带到下一个平台却不会当场报错——这才是需要提前列清单的原因。

想系统学会用 AI？报名体系课或加入会员，照着学、照着用。

浏览课程 加入会员