跳转到主要内容
OrcaRouter 允许你把一个路由策略保存为命名路由器。在你代码里以 orcarouter/{name} 调用，OrcaRouter 会在请求时按你配置的规则把它 解析为一个具体的模型。 这在以下场景特别有用：
  • 不重新部署应用就切换路由行为（在控制台里改路由器即可，代码不动）。
  • 让不同的团队或服务独立选择自己的路由策略，不依赖调用应用。
  • 引用那些复杂到无法在 extra_body 里内联的路由逻辑。

​
使用路由器

response = client.chat.completions.create(
    model="orcarouter/production-chat",
    messages=[...],
)
要知道路由器解析到了哪个具体模型，请查看 X-Orca-Router 和 X-Orca-Resolved-Model 响应头——详见响应头。 响应体里的 model 字段反映的是上游返回的内容（往往是裸的上游名， 比如 gpt-4o-mini-2024-07-18）。

​
创建路由器

路由器在控制台的 Routing 中创建。每个路由器有：
  • 名称 —— orcarouter/{name} 中的 {name}。必须在你的工作区内 唯一；只能含小写字母、数字、_ 和 -（1-50 字符）。orcarouter 这个名字被保留。
  • 允许的模型 —— 一个或多个 glob 模式（用逗号或换行分隔，大小写 不敏感），限制这个路由器能挑选的模型。示例：openai/* 或 openai/*, anthropic/claude-haiku-*。留空表示匹配你账户能访问的 所有模型。
  • 策略 —— 如何在匹配的模型中挑选。见下方策略。
  • Mundane models / Hard models —— 仅供 Adaptive · Gated 策略 使用的附加模型列表。见下方 Adaptive。
  • 默认模型 —— 当 pattern 解析为空时使用的兜底模型。
  • 启用 —— 不删除地禁用该路由器。

​
策略

编辑器里展示四张策略卡。Adaptive 内部其实包含两种后端子模式， 通过 API 可持久化的总共五个枚举值。

​
Cheapest（最便宜）

在仍在线的候选里挑每 token 单价最低的模型。这是预置的 orcarouter/auto 路由器的默认值。最适合：你只想每次请求都用最便宜 的在线 chat 模型，且不在意跨次调用之间输出风格的一致性。

​
Quality（最高质量）

在在线候选里挑质量分最高的模型，不计价格。最适合：输出质量比成本 更重要的场景。

​
Balanced（均衡）

挑选满足质量门槛的低成本选项；若无人达到门槛，则回退到质量最高的 选项。这是你自己新建路由器时的默认值。无需逐项调参就能跑。

​
Adaptive（自适应）

一个按路由器维度运行的 LinUCB 上下文 bandit，从你的真实生产流量里 学习。它在每次请求上权衡质量、成本、延迟和可靠性来挑模型。新路由 器会有一段短暂的冷启动期（每个模型都要预热），期间行为类似 Balanced，再之后 bandit 才开始引导挑选——这是预期行为，不是 bug。 两种子模式：
  • Standard（API 枚举：linucb）—— 对每次请求都考虑所有 Allowed 模型。最适合流量分布大致均匀，希望路由器在你完整模型列表里寻找 最优解的场景。
  • Gated（API 枚举：gated_adaptive）—— 请求先被分类为 mundane 或 hard；mundane 请求从较小的 Mundane models 池中抽取，hard 请求从更强的 Hard models 池中抽取，中等难度的请求从完整的 Allowed 列表中抽取。最适合你的流量混合了简单与复杂调用的场景。 每个池都会与 Allowed models 取交集；空集或无重叠的池会静默回退 到完整的 Allowed 列表，因此请求绝不会被饿死。挑选 Gated 后在 编辑器里配置两个池（API 层叫 weak_pool 和 strong_pool， 各最长 2000 字符）。

​
预置路由器：orcarouter/auto

每个 OrcaRouter 账户在注册时都会得到一个名为 auto 的默认路由器 ——见自动路由器。无需任何配置即可立即 使用。