otari（Otari）是一个开源的 OpenAI 兼容 LLM 网关，它的**路由策略（routing policy）**允许你用一个名字代表多个真实模型，实现加权分流、故障切换与智能选择。本文将带你完整掌握 otari 的三类高级路由：加权路由（weighted）、优先级溢出路由（priority）和学习路由（knn），并给出可直接落地的配置与排查方法。

otari 路由策略是什么

otari 把「调用方看到的模型名」和「真正干活的模型」解耦。你在config.yml的routing.policies下定义一条策略，客户端只要发送model: fast，otari 就会决定这次请求实际发给哪个供应商的哪个模型。策略由两条轴组成：

• select：决定请求从哪里开始，支持条件判断与路由器后端
• on_failure：候选失败后的兜底链，按顺序逐个尝试

下图展示了 otari 在整体架构中的位置：应用通过标准 OpenAI/Anthropic SDK 接入，由网关统一鉴权、计费、路由到 40+ 供应商。

📄 官方文档：docs/routing.md 配置模板参考：config.example.yml

加权路由：按比例在多个模型间分流

加权路由（router: weighted）对每个请求独立抽签，按配置权重归一化后选择候选，适合多供应商负载均衡或成本分摊：

routing: policies: balanced: select: - router: weighted candidates: - openai:gpt-5 - anthropic:claude-sonnet-4-6 weights: openai:gpt-5: 7 anthropic:claude-sonnet-4-6: 3 - default: openai:gpt-5 on_failure: - gemini:gemini-2.5-flash

关键行为：

• 7:3和70:30等价，权重会被自动归一化
• 某个候选不写入 weights 时权重为 0，但保留在失败链中——这是"排水式下线某供应商"的标准做法
• 每个请求都是独立抽签，没有会话粘性
• 选中候选失败后会继续尝试剩余加权池，最后才走on_failure

条件选择与速率溢出：按需挑模型

基于预算的条件选择

select支持按请求上下文挑选目标，例如预算快用尽时自动降级到便宜模型：

thrifty: select: - when: budget_used_pct: {gte: 80} target: openai:gpt-5-nano - default: openai:gpt-5-mini

支持的when条件有budget_used_pct、budget_remaining_usd、user_id、key_id，同一块内的所有条件必须同时满足；default条目必须放在最后。

速率限制溢出（priority）

优先级路由保持候选书写顺序，请求总是发给限流额度还有余量的第一个模型，用满的候选会被直接跳过（不发起调用），流量"溢出"给下一个：

summarize: select: - router: priority candidates: - vertex:gemini-2.5-flash # 每分钟最多接 100 个请求 - together:llama-3.3-70b # 承接剩余流量 - default: together:llama-3.3-70b

被跳过的候选会显示在 Activity 路由计划里（标记为 skipped 并注明是哪条限流规则满了），Prometheus 可用gateway_rate_limit_model_full{rule, model}计数。

学习路由（knn）：让网关越用越懂你

knn 路由器是 otari 的"智能选择"能力。它为每个用户的流量做最近邻投票：把请求向量化，在该用户已打分的样例库中找出最相似的 k 条记录，用公式score(m) = 平均质量 - alpha × 归一化成本为每个候选打分，选出"够好且最便宜"的模型：

routing: policies: smart: select: - router: knn candidates: - openai:gpt-5-nano - openai:gpt-5 - default: openai:gpt-5 on_failure: - anthropic:claude-haiku-4-5

使用学习路由的几个要点：

• 每个候选都必须配置价格，路由器靠成本做权衡
• 学习记忆按用户 + 工作区隔离，可用task_id进一步分区；它不会从线上流量自动学习，而是通过POST /api/v1/routing/preferences/rank提交"提示词 + 每个候选 0~1 分"来喂养
• 样例池不够暖（默认 20 条预热）、或置信度不足时，路由器会放弃决策、直接走default，因此学习路由永远不比普通故障切换策略更差
• 每请求控制头：Otari-Router: off跳过学习选择；Otari-Router-Task指定任务分区
• 可调部署参数：router_k（默认 5）、router_alpha、router_confidence_floor、router_granularity等

想快速体验，可以直接跑仓库里自带的可运行演示脚本：scripts/seed_routing_demo.py，它会创建覆盖各种形态的策略、给学习路由喂样例，并灌入流量填充 Activity 页面。

如何排查路由决策：explain 命令

不用真的调用供应商，就能"干跑"一条策略，查看有序候选、被过滤的候选及原因、有效权重份额：

otari routing explain fast otari routing explain thrifty --budget-used-pct 85 otari routing explain balanced --allowed-model "anthropic:*"

API 等价物是POST /api/v1/routing/policies/explain，还能校验未保存的草稿。配置策略的源码逻辑在 src/gateway/models/routing.py，knn 后端实现在 src/gateway/services/routing/knn.py，加权后端在 src/gateway/services/routing/weighted.py。

计费、可观测性与硬性规则

计费看真实模型，响应名保持策略名。每次成功响应的头里都带路由信息，方便你自建监控：

失败兜底前每次未成功的尝试会记一条absorbed用量行（不计成本、不计请求数），所有尝试共享同一个request_group_id。

需要注意的硬性限制：

• 一条策略最多5 个候选（含路由池与on_failure）
• 目标必须是具体供应商/实例，策略与别名不能链式嵌套
• 策略名不能包含:或/
• 调用方的模型白名单会先过滤候选，再归一化权重
• 兜底只在响应字节到达客户端之前生效；流式输出开始后失败会直接返回，避免中途换模型弄乱响应

总结

otari 的路由体系覆盖了从简单到智能的完整光谱：加权路由做多供应商流量分摊，条件选择 + priority 溢出实现成本与容量治理，knn 学习路由让网关按用户偏好持续优化模型选择。配合otari routing explain干跑排查和Otari-*响应头观测，你可以在不改业务代码的前提下，把"用哪个模型"变成一个可运营、可度量的网关策略。

• 完整文档：docs/routing.md
• 演示脚本：scripts/seed_routing_demo.py
• 策略数据模型：src/gateway/models/routing.py