多供应商路由与回退配置

provider 对象的字段与作用域

`provider` 对象放在请求体内，只对这一次 Chat Completions 请求生效，不会持久化到账户或后续调用。它的作用是覆盖默认的负载均衡逻辑，向路由层表达「这次请求希望怎样挑选后端」。

字段大致可分为四类。

第一类，候选集合的裁剪。`order` 给出按顺序尝试的供应商 slug 列表，例如 `["anthropic", "openai"]`，路由会按顺序逐个尝试，前面不可用时顺延到下一个。`only` 是白名单，只允许列表内的供应商响应本次请求。`ignore` 则是黑名单，跳过列表内的供应商。`quantizations` 用于按量化等级过滤，例如 `["int4", "int8"]`，不匹配量化的端点会被排除。

第二类，回退与策略开关。`allow_fallbacks` 默认 `true`，当首选供应商不可用时，路由可切换到备份供应商；设为 `false` 则禁用回退。`require_parameters` 默认 `false`，设为 `true` 时，只选用支持请求中全部参数的供应商。`data_collection` 控制是否允许可能存储数据的供应商参与路由。`zdr` 用于把候选范围限制在零数据保留端点。`enforce_distillable_text` 把候选限制在允许文本蒸馏的端点。

第三类，排序与阈值。`sort` 可以是字符串，也可以是带 `by` 与 `partition` 字段的对象。字符串形式下，`"price"` 按价格从低到高，`"throughput"` 按吞吐从高到低，`"latency"` 按延迟从低到高。`partition` 默认 `"model"`，即先按模型分组再排序；设为 `"none"` 时跨模型全局排序。一旦显式设置 `sort` 或 `order`，默认的负载均衡会被关闭，路由改为按列表顺序尝试。`preferred_min_throughput` 是首选最低吞吐（tokens/s），可以是数字，也可以是带 p50、p75、p90、p99 分位阈值的对象。`preferred_max_latency` 类似，针对延迟。低于阈值的端点不会被直接剔除，而是被排到列表末尾，仍可作为回退。

第四类，价格上限。`max_price` 用于限定本次请求愿意支付的最高价格，超出的端点不会被选中。

默认的价格负载均衡策略

在不传入 `provider` 对象，也不显式设置 `sort` 或 `order` 的情况下，请求会走默认策略。其核心目标是「在保证可用性的前提下，按价格分配流量」。

策略分三步。第一步，剔除在最近 30 秒内出现过显著故障的供应商，只在当前表现稳定的供应商集合内挑选，避免把请求投放到刚刚抖动的端点上。第二步，在稳定集合中，取候选里价格最低的几个供应商做加权抽样，权重与价格的反平方成正比。价格越低，被选中的概率越高，但低价供应商不会被独占，其他低价端点也会分到一部分流量，从而把负载摊开。第三步，把集合中剩下的供应商作为回退，当首选与加权选中的供应商不可用时顺延兜底。

这个默认行为只针对单模型请求。如果同时指定了 `sort` 或 `order`，负载均衡自动关闭，路由改为按你指定的顺序逐个尝试，而不是按价格权重分配。

价格、吞吐量与延迟的显式排序

默认的负载均衡策略已经按价格和近 30 秒内的稳定性做了加权选择，但只要请求体里出现了 `sort` 或 `order`，负载均衡就会立刻关闭，路由器改为按声明的顺序逐个尝试供应商。`sort` 字段接受三种字符串取值，分别是 `"price"`、`"throughput"`、`"latency"`，分别表示取价格最低、吞吐量最高、延迟最低的供应商。一旦显式声明 `sort`，路由器就会把候选供应商按该维度排序，然后顺序尝试，失败再回退到下一位，这与默认的加权随机分配是两套机制。

在多模型回退场景下，`sort` 还可以写成带有 `by` 与 `partition` 的对象。`by` 字段的内容仍然是 `price`、`throughput`、`latency` 三个值之一，`partition` 控制候选端点是否按模型分组后再排序。默认 `partition` 为 `"model"`，意味着无论性能指标如何，路由器都会先把主模型的端点排到前面，直到它们全部失败才考虑回退模型。把 `partition` 设为 `"none"` 后，分组规则被取消，所有候选端点会按全局 `by` 维度混合排序，路由器会直接从任意模型里挑选当前吞吐量最高或延迟最低的那一个。该写法适用于"多个模型都能接受、只关心当下速度"的场景。

在模型 slug 后追加 `:nitro` 或 `:floor` 是另一种简写形式。`:nitro` 在启用吞吐量排序之外，还会放开优先级服务层端点的使用范围，是 `provider.sort = "throughput"` 的超集；`:floor` 同理，在价格排序之外放开弹性服务层端点的资格，是 `sort = "price"` 的超集。两种简写都不需要手动改 `provider` 对象，但都属于显式排序的一种，会触发与设置 `sort` 相同的负载均衡关闭行为。

性能阈值的百分位设置

`preferred_min_throughput` 与 `preferred_max_latency` 这两个字段用于在排序之外再加一层过滤门槛，前者表示可接受的最低吞吐量（单位为 token/秒），后者表示可接受的最高延迟（单位为秒）。它们既可以直接传入一个数字，也可以写成对象形式。传入数字时，该数字会被自动绑定到 p50 分位数；写入对象时，可以针对 p50、p75、p90、p99 各自指定一个阈值。路由器对每个模型与供应商的吞吐和延迟指标都维护着滚动 5 分钟窗口的分位数统计，因此阈值的依据是最近 5 分钟内的实测样本，而不是即时单次测量。

当同时给出多个分位数阈值时，必须所有阈值都被满足，对应的模型与供应商才会进入"首选组"。例如同时设置 p50 与 p90 的延迟上限，意味着既要在中位数附近达标，也要在尾部延迟上达标。落在阈值之外的端点不会被剔除，只是被移到列表末尾，保留作为最终回退；只有当首选组中所有供应商都不可用时，这些降级端点才会被实际调用。

不同分位数反映不同的性能侧面。p50 是中位数，能体现典型水平；p90 与 p99 反映尾部情况，更接近最坏情形，可用于实时交互类场景。p50 阈值适合离线批量任务，这类场景更看重平均吞吐而非尾部抖动。把 `partition: "none"` 与 `preferred_min_throughput` 配合使用，可以让路由器在多个候选模型之间挑出满足性能下限且价格最低的那一个，而不是先把某个模型的端点全部尝试一遍后再回退到其他模型。

回退开关与禁用回退的场景

`provider` 对象里的 `allow_fallbacks` 字段是控制回退行为的总开关，默认值为 `true`。在默认负载均衡策略下，OpenRouter 会先排除最近 30 秒内出现显著故障的供应商，然后在剩余的低价候选里按价格的反平方加权选择主供应商，其余供应商作为回退备份。当这一字段被显式设为 `false` 时，路由器只会尝试被选中的那一个供应商或 `order` 列表里指定的那批供应商，不再向列表外的供应商转移请求。

`order` 字段接收一个供应商 slug 数组，路由器按数组顺序依次尝试，一旦某个供应商不可用就会移到下一个。`order` 与 `allow_fallbacks=false` 配合使用时，行为收敛到「只信任这几个供应商」，其余一概不碰，适合强一致性场景。例如一个应用要求必须走 OpenAI 的某条企业专线，不允许请求落到任何第三方聚合端，就把 `order` 与 `allow_fallbacks` 一起配死。

禁用回退的代价是可用性转嫁给所选供应商本身的健康度。当被锁定的供应商出现短暂抖动时，没有备用端可以吸收流量，请求会直接失败或返回错误。所以关闭回退通常出现在三类需求里：合规与审计要求请求只走特定供应商；调用方已经知道某个供应商在当前时刻是稳定的，回退反而会引入不可控延迟；或者把回退交给上层的自动重试逻辑统一处理，避免在网关层重复切换。

需要指出的是，回退与负载均衡在配置层面是互斥的。当用户在 `provider` 偏好里设置了 `sort` 或 `order`，默认的价格负载均衡会自动关闭，路由器改为按指定顺序逐个探测供应商，此时 `allow_fallbacks` 控制的是这份顺序列表之外的兜底是否启用。

模型回退与分区排序的高级用法

模型回退指在同一次 `chat completions` 调用里提供多个候选模型，路由器按一定顺序逐个尝试，主模型不可用时落到下一个。这个机制在 `models` 字段层面起作用，与 `provider` 层面的供应商回退是正交的：前者切换模型身份，后者在同一模型下切换承载方。

`sort` 字段除了接受字符串形式的 `"price"`、`"throughput"`、`"latency"` 之外，还可以写成对象 `{ by, partition }`。其中 `partition` 决定端点如何分组后再排，取值默认是 `"model"`。默认行为是先按模型分组，再在每个模型内部按 `by` 指定的方式排序，这保证主模型的所有端点会被穷尽之后才会尝试下一个模型，即便后者的性能指标更好。

把 `partition` 显式设为 `"none"` 时，分组被移除，排序作用于所有模型的所有端点，形成一个全局候选池。这让路由器可以无视模型边界，直接挑出当前吞吐最高或延迟最低的那条端点。典型场景是同时列出多个可接受的模型，让 OpenRouter 选当下表现最好的那一条，而不是死守用户写的第一个模型名。

`partition: "none"` 与性能阈值可以叠加使用。`preferred_min_throughput` 与 `preferred_max_latency` 只能把不达标的端点排到末尾，不能完全剔除，所以 `partition: "none"` 的全局排序在性能过滤之后仍然能挑出性价比最高的候选，淘汰的端点作为最后一层兜底。

另一个落地场景是 BYOK（Bring Your Own Key）。当用户给某个供应商配了自有密钥，但首选模型恰好没有覆盖这个供应商的 BYOK 端点时，启用 `partition: "none"` 可以让路由器跨模型挑选出真正能用用户自有密钥的端点，避免因为模型顺序写死而错失本应命中的 BYOK 通道。

多供应商路由与回退配置的落地取舍

把 `order`、`sort`、`allow_fallbacks`、`max_price`、`preferred_min_throughput`、`preferred_max_latency` 单独看都容易理解，但放进同一次请求就会互相牵制。文档对相互覆盖的规则其实写得很硬，先把这些规则捋清楚，再谈取舍才不至于猜。

第一条规则是 `sort` 与默认负载均衡互斥。默认情况下请求按价格做加权负载均衡，候选池来自过去 30 秒内没有显著故障的供应商。一旦在 `provider` 对象里显式写入 `sort` 或 `order`，负载均衡就立刻关闭，路由退化为按指定键值依次尝试。`:nitro` 与 `:floor` 这两条模型名后缀同样会强制 `sort`，并附带额外的服务层级资格，等价于在 `sort` 之外再叠加一层筛选。

第二条规则是 `order` 与 `allow_fallbacks` 共同决定候选池边界。`order` 只是一种偏好顺序，真正的边界由 `allow_fallbacks` 划定。默认 `allow_fallbacks: true` 时，`order` 之外的供应商仍可作为回退；置为 `false` 后，回退被关闭，候选池就被收紧到 `order` 列出的供应商之内，必要时还需要配合 `only` 做白名单兜底。`ignore` 与 `only` 的覆盖关系则是后者优先，写在 `only` 之外的供应商即便出现在 `order` 中也不会被选中。

第三条规则是性能阈值不直接淘汰，而是降级。不满足 `preferred_min_throughput` 或 `preferred_max_latency` 的端点不会被剔除候选集，只会被排到队尾，仍保留作为回退的资格。百分位字段支持同时给出 p50 到 p99 中的多项，全部命中才算进入「preferred」组。这意味着阈值实际扮演的是分层过滤的角色：达标的端点集中排序，未达标的端点作为兜底，避免单次抖动把整条链路掐断。

基于以上规则，几类典型取舍可以这样落地。

成本敏感的批量任务倾向于不显式设置 `sort`，让默认价格负载均衡接管；只在遇到持续故障时再用 `max_price` 收口，避免在价格与可用性之间反复横跳。对延迟敏感的用户面接口则常用 `sort: "latency"`，必要时叠 `preferred_max_latency` 的 p99 阈值，把最差情况压住，同时保留 `allow_fallbacks: true` 以防雪崩。BYOK 场景下 `sort.partition: "none"` 才有意义，它允许在多个回退模型之间按统一键值排序，从而在主模型没有自带密钥时也能命中其他模型的 BYOK 端点；若不打开这一开关，路由器会先把主模型的全部端点跑完才考虑其他模型，BYOK 利用率会被显著拉低。