search

dungeon网关策略与回退（网关 ↔ 执行器）

hashtag
什么是策略？

在 AnyInt Gateway 中，策略定义了处理请求的强制性决策路径 在 用户 API 密钥已解析到其 Binding 之后。

  • 独占：每个请求严格遵循一条策略路径。

  • 指定：

    • 路由行为（使用哪个提供商密钥 / 通道）。

    • 故障语义（在 4xx / 5xx / 超时 / 速率限制 时该如何处理）。

    • 决策权限（Gateway 与 Executor 之间的责任）。

  • 目标：可审计、可预测的处理；为经纪人和用户提供公平的归属。

部署说明：策略 A 为默认，必须先支持。策略 B 和 C 可在标志控制下逐步启用。

hashtag
可用策略

hashtag
A) 严格绑定，无回退（默认）

  • 路由：始终使用 Binding 中绑定的提供商密钥。

  • 故障：立即失败 — 不进行通道内重试，也不进行跨通道替代。

  • 决策：由 Binding 策略强制执行（默认开启）。

  • 用例：保护经纪人，简洁审计。

  • 结果：STRICT_OK / STRICT_FAIL。

hashtag
B) 通道内回退（由 Executor 驱动）

  • 路由：Executor 可尝试在同一通道内替代密钥。

  • 模式：

    • KEYSET_ONLY（推荐默认）：仅限同一提供商账户下的密钥。

    • CHANNEL_WIDE（可选）：通道中任何健康的密钥（可能改变归属）。

  • 故障：如果（有限的）重试耗尽，则返回失败。

  • 决策：需要提供商许可和用户选择加入；具体尝试由 Executor 执行。

  • 结果：INTRA_OK / INTRA_FAIL。

hashtag
C) 跨通道回退（由 Gateway 协调）

  • 路由：如果主通道失败，Gateway 可尝试一个备份通道。

  • 故障：如果备份失败，则停止 — 不进行第二次跨通道尝试。

  • 决策：需要提供商许可和用户选择加入。

  • 约束：备份必须位于提供商和用户允许列表的交集中。

  • 结果：XCHANNEL_OK / XCHANNEL_FAIL。

hashtag
配置

hashtag
提供商配置（能力 / 上限）

说明

  • 提供商授予的是许可，而非义务。用户仍可决定是否使用这些功能。

  • 平台可能会限制尝试次数（例如，通道内重试 1 次）以保护延迟表现。

hashtag
用户配置（在提供商许可范围内的选择）

有效策略 = 提供商配置与用户配置的交集。

hashtag
请求生命周期与控制流

hashtag
入口与准备

  1. Gateway 接收请求（包含用户 API 密钥）。

  2. Binding 解析：从缓存查找 Binding（包括 bindingVersion）；缓存未命中触发权威获取并填充。

  3. 收集配置：

    • 提供商：intraChannelFallback, crossChannelFallback.enabled/allowList。

    • 用户：strictBinding, allowIntraChannel, allowCrossChannel.enabled/preferredBackup。

  4. 计算有效策略：

    • 如果 strictBinding = ON ⇒ 直接为策略 A。

    • 否则：

      • 有效的通道内 = 提供商许可且用户允许（模式由提供商决定）。

      • 有效的跨通道 = 提供商许可且用户允许且备份位于两者的允许列表中。

    • 尝试预算：每个请求最多 2 次上游尝试（主 1 次 + 跨通道备份 1 次）。

    • 时间预算：每次尝试有各自的上游超时；通道内重试必须在 Executor 的整体时间预算内完成。

步骤 1 — 主尝试

  • Gateway 通过该通道的 Executor 调用绑定的提供商密钥 / 通道。

  • 成功时 → 立即返回。

    结果：STRICT_OK（策略 A）或在考虑任何回退之前的“成功”。

  • 失败时 → 根据有效策略分支处理。

hashtag
分支 A — 严格绑定（默认）

触发条件：

  • strictBinding = ON，或

  • 有效的通道内 = false 且 有效的跨通道 = false。

行为：

  • Executor 不得在通道内更换密钥。

  • Gateway 不得尝试任何备份通道。

  • 立即返回失败。

结果：STRICT_FAIL（错误类别例如 STRICT_KEY_UNAVAILABLE 或上游直通错误）。

hashtag
分支 B — 通道内回退（Executor）

触发（在主尝试失败后）：

  • 有效的通道内 = true。

行为：

  • Executor 在同一通道内尝试有限的替代：

    • KEYSET_ONLY（相同提供商账户）— 推荐以保留经纪人归属。

    • CHANNEL_WIDE（通道内任何健康密钥）— 可选，可能影响归属。

  • 成功时 → 立即返回；结果：INTRA_OK。

  • 失败时 → 返回给 Gateway；结果：INTRA_FAIL（例如 INTRA_CHANNEL_FALLBACK_EXHAUSTED）。

如果通道内成功，流程结束。如果失败（或未启用），评估跨通道（C）。

hashtag
分支 C — 跨通道回退（Gateway）

触发（仅在通道内未启用或失败时）：

  • 有效的跨通道 = true，且仍在两次尝试预算内。

行为：

  • Gateway 从提供商 ∩ 用户允许列表中选择一个备份通道（考虑 preferredBackup）。

  • Gateway 对该通道的 Executor 调用一次（备份尝试不进行通道内重试）。

  • 成功时 → XCHANNEL_OK。

  • 失败时 → XCHANNEL_FAIL（例如 CROSS_CHANNEL_FAILED）。

  • 如果策略禁止跨通道 → POLICY_BLOCKED（CROSS_CHANNEL_FORBIDDEN）。

hashtag
结果与错误分类

hashtag
对客户端可见的错误类别（稳定且可读）

  • STRICT_KEY_UNAVAILABLE — 严格模式；绑定密钥不可用；不允许回退。

  • INTRA_CHANNEL_FALLBACK_EXHAUSTED — 允许的通道内替代全部失败。

  • CROSS_CHANNEL_FORBIDDEN — 策略不允许跨通道回退。

  • CROSS_CHANNEL_FAILED — 尝试了一个备份通道且失败。

  • UPSTREAM_PASSTHROUGH — 上游 401/403/429/5xx 已透传。

hashtag
日志记录与审计

每个请求至少记录：

  • bindingId, bindingVersion

  • strategyPath (A|B|C)

  • finalChannel

  • providerAccountUsed, providerKeyUsed

  • outcome (STRICT_OK/FAIL, INTRA_OK/FAIL, XCHANNEL_OK/FAIL, POLICY_BLOCKED)

  • errorClass

  • latency

这些字段构成纪元快照的 Merkle 叶，以驱动准确的收入归属。

hashtag
典型预设

  1. 优先保护经纪人

  • 提供商：Intra=OFF, Cross=OFF

  • 用户：Strict=ON

    → 仅策略 A。主失败时立即返回。

  1. 仅键集弹性

  • 提供商：Intra=KEYSET_ONLY, Cross=OFF

  • 用户：Strict=OFF, AllowIntra=ON

    → 如果主失败，尝试同一提供商账户中的一个密钥。成功 ⇒ INTRA_OK；否则 INTRA_FAIL。

  1. 跨云紧急出口

  • 提供商：Cross=ON（例如，允许 "azure-openai"）

  • 用户：Strict=OFF, AllowIntra=ON（可选）, AllowCross=ON（偏好 "azure-openai"）

    → 如果主失败：尝试 B（若启用），否则恰好尝试 C 一次。成功 ⇒ XCHANNEL_OK；失败 ⇒ XCHANNEL_FAIL。

hashtag
实现说明与防护措施

  • 保持尝试预算和超时保守，以避免隐藏的延迟尾风险。

  • 除非明确需要通道范围的弹性，否则优先使用 KEYSET_ONLY 的通道内策略以保留经纪人归属。

  • 确保在返回之前写入审计字段，适用于成功和失败路径。

  • 将 Binding 缓存视为请求生命周期内的权威来源；在日志中包含 bindingVersion 以固定可审计性。

上一页结算与审计下一页社区

最后更新于