路由与故障转移¶
Legate 当前只有一种路由模式：tiered_failover。它先过滤不兼容或不可用的 Endpoint Model，再从最小可用 tier 中按 weight 选择候选，并根据结构化失败分类决定是否继续。
请求路径¶
Authorization Bearer
→ API Key / Workspace / Model Group authorization
→ inbound Protocol Contract
→ compatible Endpoint Model mappings
→ lowest eligible tier
→ deterministic weighted choice
→ frozen Driver Attempt
→ upstream HTTP
→ success, final error, or failover
候选必须同时满足 Endpoint 状态与调度开启、模型存在、kind 一致、Driver Binding 可用、精确 Contract 覆盖，以及 Endpoint / Mapping breaker 允许尝试。
Tier¶
Tier 数字越小优先级越高：
tier = 0是主用池；tier = 1及以后是备选池；- 只要较高优先级还有可尝试候选，就不会直接选择较低优先级；
- 较高优先级全部被排除、breaker open，或尝试产生可重试失败后，才会降级。
Weight¶
Weight 只在同一个 tier 内表达相对流量份额，必须大于 0。选择器按 Workspace、模型组、kind、invocation 和 tier 维护确定性序列；长期分布接近权重比例，但单个短窗口不保证精确百分比。
一次调用中同一个 Endpoint 最多尝试一次，避免同一故障域因多个模型映射被重复击中。
可故障转移失败¶
当前默认分类：
| 情况 | 作用域 | 是否继续尝试 | 原因 |
|---|---|---|---|
HTTP 429 |
Endpoint | 是 | rate_limited |
HTTP 408 或 5xx |
Endpoint | 是 | upstream_unavailable |
HTTP 401 / 403 |
Endpoint | 是 | endpoint_credentials |
HTTP 404 且错误表明模型不存在 |
Mapping | 是 | model_unavailable |
| 上游响应超过总限制，或提取后的 Driver JSON skeleton 超过 inline 限制 | Mapping | 是 | response_too_large |
| 网络错误或上游 deadline | Endpoint | 是 | network_error / timeout |
| 调用方取消或 deadline | 无 | 否 | client_canceled / timeout |
其他 4xx |
无 | 否 | non_retryable |
Driver 可以用协议原生响应和受约束 Outcome 覆盖供应商特殊语义，但不能指示“重试哪个候选”。Core 独占故障转移决策。
所有候选都失败时，原始上游响应超过总限制返回 HTTP 502 与 upstream_response_too_large；图片字段提取后仍无法装入 Driver inline JSON skeleton 时返回 HTTP 502 与 endpoint_driver_response_too_large。两者都不会伪装成 endpoint_driver_unavailable 或 network_error。
对于 buffered 响应，Legate 可在响应提交前切换候选。SSE 一旦向调用方提交下游流，就不能透明换到另一个 Endpoint；后续失败记录为 partial failure 或其他终止状态。
熔断器¶
Breaker 分为两个作用域：
- Endpoint：网络、认证、限流或上游服务级故障；
- Mapping：某个 Endpoint 与上游模型组合不可用。
Mapping 失败首次即可打开；Endpoint 的 429、401、403 首次打开，其他服务故障通常累计 2 次打开。open 后按退避时间拒绝普通请求，恢复窗口只允许原子 half-open probe；成功关闭，失败继续退避。Retry-After 会参与退避，上限 5 分钟。
Redis 配置后多个进程共享 breaker 状态；未配置则各进程独立。配置 generation 变更会重置对应 Workspace 的旧 breaker 状态。
资源容量错误¶
当前 Endpoint 没有 QPS 或 maxCapacity 字段，也没有基于 Endpoint 的容量租约。capacity_error 表示 Legate 自身有界资源预算不足，例如：
- 文本并发流或保留内存达到进程 / Workspace 上限；
- Sidecar 请求重放的内存、spool、文件或 FD 预算不足；
- 图片 multipart/blob 预算不足；
- Driver 报告
driver_resource_exhausted。
这类错误不会作为上游 Endpoint 故障写入 breaker。
运行统计¶
每个 Request 记录最终结果；每个 Attempt 记录 routing tier、mapping weight、attempt index、failover reason、breaker state/key、上游与下游状态、Driver 和 Usage。排障时从 origin Request 展开 attempts，避免把内部转发当作第二次业务调用。