~/notes/omnigate-02-streaming-retry-and-account-health.md1032 字

项目实战Omnigate 网关开发学习笔记 · 02/03

Omnigate(二):流式响应的提交点与账号健康状态

通过调度器预读首个事件的代码,理解流式故障转移的提交点,并区分限流、凭证失效和上游故障。

目录 3 节

LLM 网关通常连接多个上游账号。某个账号失败时,换一个账号继续尝试看起来很合理;但流式输出一旦开始发送,重试就不再只是重复调用一个接口。

Omnigate 在调度器中设置了明确的提交点。本篇从 attempt 的首事件判断入手,解释什么时候还能故障转移,以及为什么 429 不应该直接计入熔断失败。

一、流式响应的重试有明确边界

网关支持故障转移,但流式响应不能在任何时候都换账号重试。

假设客户端已经收到了第一段文本,上游随后断开。如果再找另一个账号重新生成,客户端可能收到两次回答拼成的一条流。对于工具调用,这还可能破坏调用 ID 和参数片段之间的对应关系。

项目在调度层先读取上游流的第一个事件。调用直接失败、首个事件读取失败,或者首个事件本身就是错误时,客户端还没有收到内容,可以尝试其他账号。首个正常事件确认后,再把它接回流的开头交给响应层。

调用上游
  → 读取首个事件
  → 错误:仍可故障转移
  → 正常:提交这条响应,后续失败交给客户端处理

这相当于为响应设置了一个提交点。代价是等待首个事件,收益是不会为了“看起来成功”而拼出一条语义损坏的响应。

crates/og-sched/src/dispatch.rs 中 attempt 的关键分支如下,省略了函数签名和注释:

let mut stream = provider.invoke(target, req).await?;
match stream.next().await {
    Some(Err(e)) => Err(e),
    Some(Ok(CirEvent::Error { kind, message })) => {
        Err(Error::new(kind, message))
    }
    Some(Ok(first)) => Ok(Box::pin(Chain::new(first, stream))),
    None => Err(Error::new(
        ErrorKind::UpstreamTransport,
        "upstream closed the stream without sending anything",
    )),
}

这里把两种错误统一交还给调度器:流读取的 Err,以及成功读取到的“错误事件”。None 则表示上游没有输出任何事件就关闭,也没有跨过提交点。

正常分支用 Chain 把预读事件放回开头,否则客户端会漏掉第一条事件。理解这个分支后,再看后续错误为什么只能在当前流内报告,重试边界就清楚了。

账号健康状态也需要分类处理。429 代表限流,项目会让账号进入限流等待,并约束 Retry-After 的等待上限;它不会直接增加连续故障计数。401 这类凭证问题则按认证失败处理。把限流和故障都算进同一个熔断计数器,会让整个账号池在高流量时失去可用性。

二、怎样检查这条重试路径

可以沿 crates/og-sched/src/dispatch.rs 的 attempt 逐项对照:调用阶段失败、首事件读取失败、首事件为错误事件、正常首事件以及无事件关闭。前三种和空流仍未提交,正常首事件则需要通过 Chain 放回流开头。

随后看 health.rs 中 ErrorKind::RateLimit 的分支。这里会给等待时间设置上限和默认值,并避免用短限流等待覆盖已有的熔断或禁用状态。它表达的是暂时不可调用,而不是把健康账号判成故障。

这些分支有对应的仓库回归测试;本文没有重新执行项目测试,也没有调用真实上游。学习重点是区分“响应是否提交”和“账号为什么不能调用”,两种状态各自决定不同动作。

本系列对应仓库目前为私有,代码片段取自已核对的实现;删去的字段或流程已在相关段落注明。

系列阅读

上一章:Omnigate(一):用 CIR 中间表示拆开协议转换

下一章:Omnigate(三):游标分页如何保持明细与汇总一致

  1. Omnigate(一):用 CIR 中间表示拆开协议转换
  2. Omnigate(二):流式响应的提交点与账号健康状态
  3. Omnigate(三):游标分页如何保持明细与汇总一致