写 Gemini 的接入代码时,最容易卡住的一步不是模型能力,而是地址:到底用哪条域名、路径里带不带版本号、项目 ID 和区域该放哪、走网关代理又该怎么改。这篇把接口地址拆成几个可核对的维度,给出一份从选地址到跑通第一发请求的检查顺序,顺带说清哪些写法只是碰巧能跑、什么情况下要换方案。
写 Gemini 的接入代码,真正卡住人的往往不是模型能力,而是地址那一行字符串。域名用哪条、路径里带不带版本段、项目和区域是塞进路径还是查询参数还是请求头、走网关代理又该怎么改,这些一旦混着猜,报错信息会把你往鉴权、配额、模型名上带偏,白白耗掉半天。
这篇把接口地址拆成几个能逐项核对的维度,给一份从选形态到跑通第一发请求的检查顺序。具体的模型清单、区域可用性和当前口径,到站内页面核对当时的数字,别照抄别人博客里的旧地址。
一条 Gemini 接口地址由哪几段拼出来
与其把整条地址当咒语背下来,不如拆成四段逐段确认:域名段、版本段、资源或动作路径段、查询参数段。换接入方式时,通常只有域名段和鉴权方式变,路径段的结构大概率保留,拆开看就能判断哪些能沿用、哪些必须替换。
| 地址组成段 | 典型内容 | 换形态时会不会变 |
|---|---|---|
| 域名段 | 官方端点 / 区域端点 / 中转方给的域名 | 基本必变,是区分形态的关键 |
| 版本段 | 表示接口版本的那一段路径 | 可能变,看网关是否做了版本映射 |
| 资源或动作路径 | 模型调用、流式、批量等动作 | 多数保留,但要确认大小写和前缀 |
| 查询参数 | 区域、项目、分页、流式开关等 | 看实现,身份信息位置最容易踩坑 |
身份信息放哪最容易被忽略。有的写法把项目标识放在路径里,有的放查询参数,有的干脆走请求头。同一份代码里混用两种写法的后果不是「部分生效」,而是直接报参数错误,且错误文案通常不会告诉你「位置错了」。
- 地址一律抽成配置项或环境变量,不要硬编码在业务逻辑里,换区域或换网关时才不用改代码
- 给域名段和路径段分别建常量,出问题时能一眼看出是哪一段被改坏了
- 在注释里写清这条地址来自哪个形态、对应的鉴权方式是什么,方便后来人接手
- 如果同时维护直连和中转两套配置,用不同的配置名区分,别靠改一个变量来回切
地址形态怎么选:直连、区域端点还是走中转
选形态之前先回答三个约束:调用方跑在什么网络环境、有没有数据落地区域或合规上的要求、要不要和其他模型统一计费口径。这三条基本就决定了大方向,剩下的才是细节调优。先想需求再看地址,比先抄一条地址再回头补需求省事得多。
| 地址形态 | 适合什么情况 | 什么时候不适用 |
|---|---|---|
| 官方直连端点 | 快速验证、单点接入、调用方网络出口干净 | 需要统一多模型计费,或出口有额外管控时 |
| 区域端点 | 对数据落地区域有要求,或需要就近降延迟 | 只是先跑通验证、还没定区域策略时 |
| 自建或第三方中转 | 要统一鉴权、统一计费、统一日志出口 | 对链路完全可控有硬要求、不接受中间层时 |
走中转时最容易犯的错是只换地址不换鉴权头。中转方通常有自己的 Key 格式和请求头约定,照搬官方的鉴权写法会直接 401。响应结构也可能被改写,所以请求和响应要成对调整,别只改一半就以为通了。
如果你的场景是要在多个供应商之间切换,那么中转形态带来的收益通常会盖过直连的简单性;反过来,如果只是自己跑个脚本验证想法,直连最省事。没有普适答案,看约束。
发第一发请求前的准备清单
动手写调用之前,把该备的东西备齐,否则连不上时你分不清是地址错、凭据错还是参数错。下面这份清单按「先备料、再验证、后量化」的顺序排,照着走一遍能省掉大部分来回试。
- 备齐四样东西凭据、项目或账号标识、目标模型名、超时与重试参数。四样缺一样,排查时就会多一个不确定变量。
- 跑一条最小请求用最短的提示、非流式方式发一次,只确认连通性。这一步别叠流式、别叠加并发,一次只验证一个变量。
- 切成流式再验一次非流式通了再切流式,注意流式对超时和连接复用的要求和普通请求不同,分开验证才能定位问题。
- 量一条延迟基线用 /tools/speed-test 记一次正常情况下的数值,以后遇到「变慢了」才有参照对象,否则只能凭感觉。
代理、环境变量、证书这三层特别容易互相掩盖问题:代码里设了代理,系统环境变量里又设了一层,或者本地信任的证书在容器里没有。报错信息往往只反映最外层,所以按「代码配置 → 环境变量 → 系统证书」这个顺序分层排除,比乱改地址有效。
地址写错的典型症状与对照排查
不同症状对应不同层的问题,先分类再动手,别一报错就去翻 Key 和模型名。下面这张对照表把常见症状和该查的地方列出来,按行排查能快速缩小范围。
| 症状 | 优先怀疑哪一层 | 怎么确认 |
|---|---|---|
| 404 找不到路径 | 路径多写或少写一段版本或资源段 | 对比官方文档里的路径结构,逐段删减试 |
| 401 鉴权失败 | 凭据格式或请求头写法不匹配当前形态 | 确认是否把官方鉴权写法用在了中转地址上 |
| 一直超时 | DNS 解析或出口代理没放行 | 用命令行工具测目标域名可达性,再看代理配置 |
| 本地能跑部署后不行 | 环境变量或网络出口不同 | 对比两边配置,重点看域名和代理环境变量 |
| 响应结构对不上 | 中转层做了字段改写 | 请求和响应成对调整,不要只改一端 |
还有一种情况是地址没错但就是不稳。这时候问题往往在配额、并发或连接复用上,跟地址无关。先确认地址和鉴权都对,再去查速率限制和超时设置,别把两类问题混在一起调。
地址出问题的排查顺序永远是:先看路径段,再看鉴权,最后才怀疑网络和配额。
什么情况下这套判断不适用?如果你的接入方对链路有完全可控的硬要求、或者所在环境不允许任何中间层,那么中转形态直接排除,上面的对照表里中转相关的行也用不上。反过来,如果只是自己写个脚本试模型,很多排查步骤可以跳过。
下一步地址选完、连通性验完,接下来该确认成本和速率是否符合预期了。到 /price-watch 看当前的价格追踪,到 /official-api/providers/google 核对官方口径,两处对一遍再决定长期用哪个形态。→常见问题
Gemini 的接口地址和 OpenAI 的地址能通用吗?
不能直接互换。两者路径结构和鉴权头都不一样,中间需要一个兼容层或中转来接。如果你手上是写死 OpenAI 形态的客户端,要么换成支持自定义地址且按 Gemini 协议发的客户端,要么走一层中转把协议转过去,单改域名是不会通的。
地址看起来没错,为什么还是连不上?
按四层顺序查:先确认域名能不能解析,再看出口网络是否放行,然后核对路径里的版本段和资源段有没有多写少写,最后才看鉴权头。多数「地址没错但连不上」实际卡在第二层或鉴权层,地址本身反而没问题。
地址要不要写进代码里?
建议抽成配置。原因有两个:换区域、换网关、换中转时不用动业务代码;本地和线上可以用不同值,排错时改一处就能验证。硬编码的另一个麻烦是,多环境共用同一份代码时很容易把测试环境的地址带到线上。