omni-combos-routing

概述

使用 19 种策略（优先级、加权、轮询、自动组合等）创建和管理路由组合。配置回退链、测试路由结果并获取组合指标。

身份验证

所有请求都需要有效的 Bearer 令牌或会话 Cookie。通过 POST /api/auth/login 获取令牌，或在本地开发时配置 REQUIRE_API_KEY=false。

端点

GET /api/combos

列出路由组合

curl http://localhost:20128/api/combos \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"

POST /api/combos

创建路由组合

curl -X POST http://localhost:20128/api/combos \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

GET /api/combos/{id}

按 ID 获取组合

curl http://localhost:20128/api/combos/{id} \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"

PUT /api/combos/{id}

更新组合

部分更新：请求正文会与存储的组合合并，因此未提供的字段会保留当前值。已发送的数组会直接替换存储的数组。

curl -X PUT http://localhost:20128/api/combos/{id} \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

PATCH /api/combos/{id}

更新组合

部分更新：请求正文会与存储的组合合并，因此未提供的字段会保留当前值。已发送的数组会直接替换存储的数组。

curl -X PATCH http://localhost:20128/api/combos/{id} \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

DELETE /api/combos/{id}

删除组合

curl -X DELETE http://localhost:20128/api/combos/{id} \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"

GET /api/combos/metrics

获取组合指标

curl http://localhost:20128/api/combos/metrics \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"

POST /api/combos/test

测试组合配置

curl -X POST http://localhost:20128/api/combos/test \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

GET /api/fallback/chains

列出回退链

返回所有已注册的模型路由回退链。

curl http://localhost:20128/api/fallback/chains \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"

POST /api/fallback/chains

创建回退链

为模型注册一条回退路由链。

curl -X POST http://localhost:20128/api/fallback/chains \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

DELETE /api/fallback/chains

删除回退链

curl -X DELETE http://localhost:20128/api/fallback/chains \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"

GET /api/combos/auto

GET 组合 › 自动

curl http://localhost:20128/api/combos/auto \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"

GET /api/combos/builder/options

GET 组合 › 构建器 › 选项

curl http://localhost:20128/api/combos/builder/options \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"

POST /api/combos/duplicate

POST 组合 › 复制

curl -X POST http://localhost:20128/api/combos/duplicate \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

POST /api/combos/reorder

POST 组合 › 重新排序

curl -X POST http://localhost:20128/api/combos/reorder \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

请求载荷

有关详细的请求／响应架构，请参阅 GET /api/openapi/spec 或 docs/openapi.yaml 中的完整 OpenAPI 规范。

OmniRoute — 路由与组合

需要 OMNIROUTE_URL 和 OMNIROUTE_KEY。有关设置，请参阅入口 SKILL。

什么是组合？

组合是由多个提供商／模型组成的命名组，并带有路由策略。通过组合发出的所有请求都会自动分发、故障转移并进行负载均衡——调用方只需使用一个模型 ID，例如 my-combo。

列出现有组合

curl $OMNIROUTE_URL/api/combos \
  -H "Authorization: Bearer $OMNIROUTE_KEY"

响应包含 id、name、strategy、enabled 和每个目标的统计信息。

创建组合

curl -X POST $OMNIROUTE_URL/api/combos \
  -H "Authorization: Bearer $OMNIROUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-combo",
    "strategy": "priority",
    "targets": [
      { "provider": "anthropic", "model": "claude-opus-4-7", "weight": 1 },
      { "provider": "openai",    "model": "gpt-4o",           "weight": 1 }
    ]
  }'

19 种公开路由策略

策略	描述
priority	始终使用 target[0]；出错时回退
weighted	按权重百分比分配
round-robin	按顺序轮换目标
context-relay	串联模型以处理超长上下文
fill-first	填满 target[0] 的配额后再溢出到其他目标
p2c	二选一：抽取两个目标并选择较优者
random	均匀随机选择
least-used	路由到观测使用量最低的目标
cost-optimized	根据令牌估算选择符合条件且成本最低的目标
reset-aware	根据配额重置状态优先选择目标
reset-window	按配置的重置窗口排列目标
headroom	优先选择剩余配额更多的目标
strict-random	随机选择，所有目标都使用过之前不会重复
auto	基于 16 个因素进行自动组合评分
lkgp	基于最后已知正常提供商的粘性路由
context-optimized	为请求的上下文大小选择最佳模型
cache-optimized	优先选择缓存亲和性更强的目标
fusion	并行运行一个评审组，并综合生成一条经评判的响应
pipeline	按配置顺序将多个目标作为管道运行

自动组合（推荐用于生产环境）

自动组合会在每次请求时根据 16 个因素为每个候选目标评分：

curl -X POST $OMNIROUTE_URL/api/combos \
  -H "Authorization: Bearer $OMNIROUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-auto",
    "strategy": "auto",
    "targets": [
      { "provider": "anthropic", "model": "claude-sonnet-4-6" },
      { "provider": "openai",    "model": "gpt-4o-mini" },
      { "provider": "google",    "model": "gemini-2.0-flash" }
    ]
  }'

然后调用它：

curl -X POST $OMNIROUTE_URL/v1/chat/completions \
  -H "Authorization: Bearer $OMNIROUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "prod-auto", "messages": [{ "role": "user", "content": "Hello" }] }'

激活／停用组合

# Activate
curl -X PUT $OMNIROUTE_URL/api/combos/{id}/toggle \
  -H "Authorization: Bearer $OMNIROUTE_KEY" \
  -d '{ "enabled": true }'

获取组合指标

curl $OMNIROUTE_URL/api/combos/{id}/metrics \
  -H "Authorization: Bearer $OMNIROUTE_KEY"

返回 p50/p95/p99 延迟、成功率、成本和各目标的明细。

模拟路由（试运行）

curl -X POST $OMNIROUTE_URL/api/routing/simulate \
  -H "Authorization: Bearer $OMNIROUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "comboId": "{id}", "messages": [{ "role": "user", "content": "test" }] }'

返回将选择哪个提供商以及原因——不会发起实际 API 调用。

通过 MCP（如果 OmniRoute 是你的 MCP 服务）

omniroute_list_combos     → list all combos
omniroute_switch_combo    → enable/disable a combo
omniroute_set_routing_strategy → change strategy at runtime
omniroute_simulate_route  → dry-run routing decision
omniroute_best_combo_for_task → get recommendation by task type

错误

• 404 combo not found → 检查 /api/combos 中的 id
• 400 invalid strategy → 使用上述 19 种策略之一
• 409 name conflict → 组合名称已存在