Gemini 中转平台:长上下文和多模态上传,卡住的不是模型
Gemini 这条线在国内用,最常见的三个现场:传一张高清图等半天、长文档塞进去被截断、视频分析请求传到一半连接重置。都容易被归成「中转不靠谱」,实际拆开看,很多是配置和协议差异。
上传慢,慢在哪
多模态请求的体积和文本不在一个量级。图片 base64 编码后膨胀约三分之一,一段视频或几十页 PDF 更容易到几十 MB。这道数据要先完整到达中转节点,再由节点转给上游,中间任何一层有请求体大小限制或超时,都会在前半段就失败。
几个能自己排查的点:
- 反向代理或网关的
client_max_body_size、请求超时设置。自搭链路时这是头号嫌疑。 - 图片能传 URL 就别传 base64,能压就压;但别为了体积把分辨率压到模型看不清关键细节。
- 大文件走异步任务而不是同步等返回,视频类尤其如此。
- 用流式接口时,上传阶段本来就没有 token 返回,别把这段时间当成「首字延迟」写进监控。
长上下文被截断,通常是这几个原因
不是模型窗口不够,是链路里的某一层先动手了:
- 客户端自己设了
max_tokens,输出还没展开就被finish_reason: "length"掐掉。 - 聚合网关对单次请求做了体积或 token 数限制,返回一个不明显的错误。
- 模型 ID 选错,选到了上下文窗口更小的变体。
- 协议翻译时,超长
messages被折叠或丢弃了尾部内容。
排查顺序:先从后台拿到这条请求的原始 usage,看 prompt_tokens 是不是和你本地 tokenizer 估算的量级对得上;对不上,就是输入侧被动过。再看 finish_reason。最后才怀疑上游。
协议差异要提前知道
Gemini 原生接口是 /v1beta/models/{model}:generateContent 那一套,contents / parts 结构和 OpenAI 的 messages 差别不小。多数聚合平台会把它翻译成 OpenAI 兼容格式对外暴露,好处是老代码零改动,代价是有些原生参数(比如特定的生成配置、思考预算、文件处理方式)在翻译层可能没有一一对应。
所以接之前先跑一组最小验证:
curl -sS "https://token173.net/v1/models" \
-H "Authorization: Bearer sk-你的令牌" | head -c 2000
拿到当前可用的模型 ID,再分别测纯文本、图片输入、工具调用、流式四种请求。别只看「能返回」——要看返回里的 usage 字段、finish_reason 和图片理解的结果是否完整。
型号选择
gemini-3.8-flash 这一类适合高频、大批量、对延迟敏感的任务:文档分类、批量摘要、图片初筛。真需要啃几百页材料或做复杂推理时,再换更强的型号,别默认全用旗舰。
一个很实用的组合:先用轻量型号把长文档切成结构化的块,再只对可疑片段调强模型。比一整份塞进去省钱,也更不容易触发截断。
平台侧
国内调用这条线我放在 token173.net 上跑。它是 OpenAI 兼容入口,Gemini 和 GPT、Claude、Grok、国产型号共用一个 Key,做上面的多型号对照时不用换地址,账单和调用记录也归在一处;控制台里 gemini-3.8-flash 和图像、视频那几个 ID 都在,境内访问不用自己配代理。
看后台时我主要盯两列:单条请求的 prompt_tokens(判断长上下文有没有被截断)和耗时分段(判断慢在上传还是生成)。有一回一批 PDF 摘要的结果明显偏短,就是靠 prompt_tokens 比本地估算少了一大截发现的 —— 网关对单次请求做了体积限制,尾部内容被丢了,模型老老实实按剩下的部分回答。这两列拿不到,多模态的故障基本只能靠猜。
型号 ID 会上下架,参数支持范围也会变,接之前拉一次 /v1/models,以控制台当前列表和文档为准。
顺带一句
涉及客户资料、合同扫描件、内部图纸这类文件,别走任何第三方中转。多模态请求的原文是整份上传的,和文本 prompt 一样会经过中间服务器。这条不是针对某一家,是这个结构的边界。
多模态请求的体积账
文本请求几 KB,多模态动辄几 MB 到几十 MB,排查思路得换一套:
- 图片 base64 编码后大约膨胀三分之一,一段参考视频或几十页 PDF 更夸张;
- 请求体先完整到达中转节点,再由节点转给上游,任何一层有
client_max_body_size或上传超时都会在前半段失败; - 常见返回是 413,或者干脆连接重置,错误信息经常含糊;
- 上传阶段本来就没有 token 返回,别把这段时间当成 TTFT 写进监控。
能传 URL 就别传 base64;必须传文件时,先确认平台有没有独立上传端点。也别为了压体积把分辨率降到模型看不清关键细节 —— 省下的几秒,会在返工上加倍还回来。
截断问题看 finish_reason
长上下文输出不完整,先看结束原因再决定动作:
| finish_reason | 含义 | 该改什么 |
|---|---|---|
length | 撞到输出上限 | 调 max_tokens,或拆任务 |
stop 但内容偏短 | 输入侧可能已被截断 | 核对 prompt_tokens 与本地估算 |
content_filter | 内容策略拦截 | 看任务详情里的 error 字段 |
| 无(流式中断) | 连接或网关问题 | 查 end_reason、EOF、keep-alive |
第 2 行最阴。返回是正常结束,模型也认真答了,只是它根本没看到后面的材料。所以多模态和长文任务,把 prompt_tokens 的量级核对做成上线前的固定动作,比事后调 prompt 有效得多。
另外,涉及客户资料、合同扫描件、内部图纸这类文件,别走任何第三方中转 —— 原文是整份上传的,和文本 prompt 一样会经过中间服务器。