文档接口与模型

路由与会话保持

网关在多个上游账号之间分配请求:同一会话尽量留在同一个账号上,账号出错或限流时换一个重试。了解这些行为,排查问题和控制缓存费用会更容易。

更新于

请求怎么分配

同一个分组背后有多个上游账号。网关在可用的账号之间轮流分配新请求,单个账号出问题时,不会让所有请求一起失败。

会话保持

同一段对话的请求,网关会尽量发给同一个上游账号。这样上游的提示词缓存更容易命中,长对话里重复的上下文按更便宜的缓存价计费。

网关根据请求里的会话标识判断“同一段对话”:session_id、conversation_id 请求头,或 Responses 请求里的 prompt_cache_key。Codex 会自动带上这些标识;自己写代码时,同一段对话固定传同一个 prompt_cache_key 即可。没有带标识的请求,网关会根据请求内容做近似判断。

可用性优先于会话保持:原来的账号不可用时,请求会改发给其他账号,这一次可能无法命中缓存。

出错时自动换账号

上游账号返回限流或临时错误时,网关会把这次请求换一个账号重试,换号次数有上限。所有账号都在限流时,会返回 429,提示稍后重试。

并发与排队

每个账户有同时进行的请求数上限,新账户默认是 5 个。超过上限的请求会先排队,队列也满了就返回 429(Too many pending requests)。批量任务请控制并发,并在收到 429 时等一会儿再重试。

重试建议

  • 只对 429、502、503、504 和网络超时重试;401、403、404 重试没有用,先修配置。
  • 用递增的等待时间,例如 1 秒、2 秒、4 秒,最多重试三到五次。
  • 流式请求已经开始输出后再中断,重试会重新计费,先确认是否真的需要。