多供应商路由与回退配置

provider 对象字段详解

在多供应商路由配置中，provider 对象是控制请求分发的核心结构。它通过一系列字段精确指定哪些供应商参与处理、以何种顺序尝试、是否允许回退以及如何筛选符合条件的端点。这些字段共同构成一个灵活的路由策略层，允许开发者根据成本、性能、数据合规性或可用性等维度定制请求路径。

order 字段接受一个字符串数组，其中每个元素是供应商的标识符（slug），例如 "anthropic" 或 "openai"。路由器将严格按照数组中列出的顺序尝试这些供应商。如果第一个供应商不可用或响应超时，系统会立即转向列表中的下一个供应商，直到成功响应或列表耗尽。该字段的优先级高于默认负载均衡策略，一旦设置，负载均衡机制将被禁用，转而采用严格的顺序尝试模式。

allow_fallbacks 字段是一个布尔值，默认为 true。当设置为 true 时，如果主供应商（由 order 或默认策略选出）无法提供服务，系统会自动启用备用供应商。备用供应商的选择基于系统内部维护的可用性状态，通常包括最近无故障记录的供应商。若设置为 false，则仅尝试主供应商，若失败则直接返回错误，不进行任何回退操作。

require_parameters 字段默认为 false。当设置为 true 时，路由器会过滤掉所有不支持请求中全部参数的供应商。这意味着如果请求中包含某些供应商模型不支持的参数（如特定的温度值、上下文长度或自定义字段），该供应商将被排除在候选列表之外。该字段有助于避免因参数不兼容导致的请求失败，但可能缩小可选供应商范围。

data_collection 字段控制是否使用可能存储数据的供应商。其值可为 "allow" 或 "deny"。"allow" 表示允许使用任何供应商，包括那些可能记录请求数据的供应商；"deny" 则排除已知会存储数据的供应商，适用于对数据隐私有严格要求的场景。该字段与 zdr 字段配合使用时，可进一步细化数据处理策略。

zdr 字段是一个布尔值，用于强制仅路由到支持零数据保留（Zero Data Retention）的端点。启用后，所有不满足 ZDR 标准的供应商将被排除。ZDR 端点保证不会持久化请求或响应数据，适用于处理敏感信息的场景。该字段与 data_collection 字段协同工作，形成多层数据保护机制。

enforce_distillable_text 字段默认为 false。启用后，仅允许使用支持文本蒸馏（text distillation）的模型。文本蒸馏是指从模型输出中提取结构化信息或摘要的能力，某些供应商的模型可能不支持此功能。该字段适用于需要后续处理模型输出的流程，确保输出格式符合预期。

only 字段是一个字符串数组，用于显式指定本次请求允许使用的供应商列表。任何未列入该列表的供应商将被完全忽略，即使其性能或价格更优。该字段与 ignore 字段互补，only 用于白名单控制，ignore 用于黑名单排除。

ignore 字段是一个字符串数组，用于排除特定供应商。被列入该列表的供应商将不会被考虑，即使其在默认策略中表现优异。该字段适用于已知某些供应商不稳定或不符合特定需求的情况。

quantizations 字段接受一个字符串数组，如 ["int4", "int8"]，用于筛选符合特定量化精度的供应商端点。量化级别影响模型的计算精度与推理速度，int4 表示 4 位整数精度，int8 表示 8 位整数精度。该字段允许用户在精度与性能之间做出权衡，适用于对延迟或资源消耗有严格要求的场景。

sort 字段可以是字符串或对象，用于指定供应商的排序依据。字符串形式可为 "price"、"throughput" 或 "latency"，分别表示按价格、吞吐量或延迟排序。对象形式包含 by 和 partition 两个子字段，by 指定排序策略，partition 控制排序范围。一旦设置 sort，负载均衡将被禁用，路由器将严格按照排序结果尝试供应商。

preferred_min_throughput 和 preferred_max_latency 字段用于设置性能阈值。前者指定最小吞吐量（tokens/sec），后者指定最大延迟（秒）。这些字段可以是数值或对象，数值形式适用于 p50 百分位，对象形式可指定 p50、p75、p90、p99 等多个百分位。未达标的供应商将被降级处理，排在候选列表末尾，但仍可能作为回退选项。

max_price 字段是一个对象，用于设置本次请求的最高可接受价格。路由器将排除任何超出该价格的供应商端点。该字段与 sort: "price" 结合使用时，可实现成本最优的路由策略，确保在满足性能要求的前提下选择最经济的供应商。

默认负载均衡机制

OpenRouter 的默认负载均衡策略以价格为核心优化目标，同时兼顾供应商的近期可用性。该策略在不显式指定 order 或 sort 字段时自动启用，旨在最大化请求成功率的同时降低平均成本。

策略的第一步是过滤掉最近 30 秒内发生过显著故障的供应商。这里的“显著故障”通常指连续多个请求失败、响应超时或返回 5xx 状态码。系统通过滑动窗口机制监控每个供应商的健康状态，确保仅考虑当前稳定的端点。

在稳定供应商中，系统评估每个供应商的最低价格候选，并根据价格的反平方根进行加权选择。具体而言，价格越低的供应商权重越高，但权重递减速度随价格上升而放缓，避免过度集中于单一低价供应商。这种加权机制在成本与分布均衡之间取得平衡，防止因低价供应商过载而导致新的故障。

剩余的供应商被列为回退选项，按价格升序排列。当主选供应商失败时，系统按顺序尝试这些回退供应商，直到成功响应或列表耗尽。回退机制不依赖显式配置，是默认策略的一部分，确保在主供应商不可用时仍有备用路径。

若在 provider 对象中设置了 order 或 sort 字段，负载均衡将被完全禁用。此时路由器不再进行加权选择或动态调整，而是严格按照指定顺序或排序结果尝试供应商。这种显式控制适用于需要确定性路由路径的场景，例如强制使用特定供应商或按性能优先级排序。

负载均衡策略的设计兼顾了自动化与灵活性。默认行为适合大多数通用场景，而显式字段则允许开发者根据具体需求进行精细控制。通过组合不同字段，可实现从简单故障回退到复杂多维路由策略的多种配置。

排序策略与快捷方式

在多供应商路由配置中，排序策略决定了请求在多个候选供应商之间的尝试顺序。默认情况下，系统采用基于价格的负载均衡机制，优先选择成本较低且近期无显著故障的供应商。若需明确指定优先级，可启用排序字段，此时负载均衡将被禁用，系统将严格按照排序结果依次尝试供应商。排序策略支持三种模式：按价格优先、按吞吐量优先、或按延迟优先。选择价格优先时，系统始终尝试最低单价的供应商；选择吞吐量优先时，则优先匹配当前吞吐表现最优的节点；选择延迟优先时，则优先路由至响应延迟最低的供应商。

为提升配置效率，系统提供两种快捷方式。其一为模型标识后缀 `:nitro`，该后缀自动启用吞吐量排序，并额外激活优先服务层级端点，使请求可访问高性能通道。该后缀属于路由变体，不改变模型元数据，仅影响路由行为。其二为模型标识后缀 `:floor`，该后缀启用价格排序，并激活弹性服务层级端点，使请求可访问成本优化通道。同样属于路由变体，不新增模型条目，仅调整路由策略。两种快捷方式均覆盖默认负载均衡行为，适用于对性能或成本有明确偏好的场景。

分区排序与多模型回退

当配置多模型回退策略时，排序字段可扩展为对象形式，以支持更精细的控制。默认情况下，系统在排序前将端点按模型分组，确保主模型的所有端点优先于备用模型的端点被尝试，无论其性能表现如何。此行为由 `partition` 字段控制，其默认值为 `"model"`。若需打破模型分组限制，实现跨模型全局排序，可将 `partition` 设置为 `"none"`。此时系统将所有模型的端点视为统一候选池，按指定排序策略（价格、吞吐量或延迟）全局择优。

该机制适用于多种典型场景。在性能优先场景中，若用户关注当前最优性能而非特定模型，可启用全局吞吐量或延迟排序，系统将自动选择所有模型中表现最佳的端点，而非固守主模型。在成本优化场景中，结合全局排序与性能阈值，系统可在满足最低吞吐或最高延迟要求的前提下，跨模型寻找成本最低的选项，未达标端点仍可作为回退候选。在密钥复用场景中，若用户配置了特定供应商的自带密钥（BYOK），全局排序可确保系统在主模型无可用密钥时，自动路由至支持该密钥的备用模型，提升密钥利用率。所有排序与分区配置均作用于回退链路，不影响单模型场景下的路由行为。

性能阈值与百分位控制

在多供应商路由场景中，性能阈值是筛选候选节点的关键手段。系统通过 `preferred_min_throughput` 和 `preferred_max_latency` 两个字段，对候选供应商的实时表现进行量化过滤。这两个字段均支持数值与对象两种形式，数值形式直接作用于中位数（p50）指标，而对象形式则允许 finer-grained 的百分位控制，可分别指定 p50、p75、p90、p99 四个档位的阈值。所有指定的百分位条件必须同时满足，供应商才能进入优先级队列；未达标者不会被剔除，而是被降级至回退列表末尾，仅在主路径全部失败时才被调用。

百分位数据基于过去五分钟内的滚动窗口统计，反映的是供应商在近期窗口内的稳定表现。p50 代表中位延迟或吞吐，体现典型工况；p90 与 p99 则更关注尾部延迟，适合对响应一致性要求高的实时交互场景。例如，若某供应商的 p90 延迟为 2 秒，意味着其 90% 的请求能在 2 秒内完成，剩余 10% 可能更慢。通过组合多个百分位，用户可同时约束典型性能与极端情况，实现 SLA 级别的保障。在批处理任务中，优先使用 p50 吞吐阈值可有效过滤掉偶发波动的节点，保留稳定输出的供应商；而在面向用户的前端服务中，p90 或 p99 延迟阈值更能防止卡顿体验。

结合 `sort` 字段使用时，性能阈值可作为成本优化的前置过滤器。例如设置 `sort: "price"` 并附加 `preferred_min_throughput: { p90: 50 }`，系统将仅在满足每秒 50 tokens 且 90% 请求达标的基础上，选择价格最低的供应商。这种组合避免了为追求低价而引入性能波动节点的风险，确保成本节约不以稳定性为代价。性能阈值不改变路由顺序，仅影响供应商的优先级分组，因此仍可与 `order`、`allow_fallbacks` 等字段协同工作。

BYOK 与密钥优先级配置

BYOK（Bring Your Own Key）机制允许用户注入自有 API 密钥，绕过平台默认的密钥池，实现数据隔离与合规控制。在多供应商回退场景中，BYOK 的可用性并非全局一致，而是绑定于具体供应商与模型的组合。例如，用户可能为 OpenAI 配置了自有密钥，但未在 Anthropic 端完成相同配置。此时，若请求默认优先路由至 Anthropic，即使 OpenAI 节点具备 BYOK 能力，也无法被优先调用，导致密钥资源闲置。

为解决此类错配，系统引入 `partition: "none"` 排序策略，打破默认的模型分组限制。在默认模式下，路由按模型分组排序，主模型的所有供应商优先于回退模型的供应商，即使后者具备更优的密钥匹配或性能表现。启用 `partition: "none"` 后，所有模型的供应商被置于同一排序池中，系统依据 `sort`、`order`、性能阈值等条件全局择优，不再受模型边界约束。这意味着，当主模型无 BYOK 节点可用时，系统可直接跳转至具备 BYOK 能力的回退模型供应商，无需等待主模型全部失败后再触发回退。

密钥优先级在路由决策中隐式体现：BYOK 密钥的注入使对应供应商在合规性与数据控制维度上获得隐性优势，尤其在 `data_collection` 设为 `"deny"` 或 `zdr` 启用的场景下，BYOK 节点成为唯一可选路径。此时，结合 `partition: "none"` 可确保系统在多模型间自动识别并优先调度具备密钥匹配的节点，避免因模型分组导致的密钥浪费或合规风险。该配置尤其适用于多模型回退策略中，用户希望最大化利用自有密钥、同时保持路由灵活性的场景。