omni-combos-routing

用途

OmniRoute 的路由组合（combo）功能用于将多个提供商/模型组织为一个命名的路由组，并为其指定一种路由策略。通过组合，调用方只需使用一个模型 ID（例如 my-combo），所有请求就会自动进行分发、故障转移和负载均衡。该技能提供创建、管理、测试和监控这些组合的 API 与 MCP 工具。

主要能力

• 创建和管理路由组合，支持 19 种公开路由策略：priority、weighted、round-robin、context-relay、fill-first、p2c、random、least-used、cost-optimized、reset-aware、reset-window、headroom、strict-random、auto、lkgp、context-optimized、cache-optimized、fusion、pipeline。
• 配置回退链（fallback chains），为模型注册回退路由链。
• 测试组合配置，并通过模拟路由（dry run）查看会选中哪个提供商及原因，不实际发起 API 调用。
• 获取组合指标，包括 p50/p95/p99 延迟、成功率、成本以及按目标拆分的统计。
• 激活/停用组合，复制、重排序组合。
• 通过 MCP 工具操作：omniroute_list_combos、omniroute_switch_combo、omniroute_set_routing_strategy、omniroute_simulate_route、omniroute_best_combo_for_task。

使用方式

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

主要端点包括：

• GET /api/combos：列出路由组合
• POST /api/combos：创建路由组合
• GET /api/combos/{id}：按 ID 获取组合
• PUT /api/combos/{id} 和 PATCH /api/combos/{id}：更新组合（部分更新，未提供的字段保留原值，提供的数组会整体替换）
• DELETE /api/combos/{id}：删除组合
• GET /api/combos/metrics：获取组合指标
• POST /api/combos/test：测试组合配置
• GET /api/fallback/chains：列出回退链
• POST /api/fallback/chains：创建回退链
• DELETE /api/fallback/chains：删除回退链
• GET /api/combos/auto、GET /api/combos/builder/options、POST /api/combos/duplicate、POST /api/combos/reorder
• PUT /api/combos/{id}/toggle：激活/停用组合
• GET /api/combos/{id}/metrics：获取指定组合指标
• POST /api/routing/simulate：模拟路由（dry run）

创建组合示例：

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 }
    ]
  }'

使用组合调用：

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" }] }'

Auto-combo 策略会在每次请求时对候选目标按 16 个因素进行评分，推荐用于生产环境。

适用场景

• 需要统一模型入口，将多个提供商/模型聚合为一个模型 ID 调用。
• 需要自动分发、故障转移和负载均衡。
• 需要按成本、延迟、配额、上下文大小、缓存亲和性等维度优化路由。
• 需要在不实际调用的情况下预演路由决策。
• 需要监控组合的延迟、成功率和成本指标。

限制

• 所有请求需要认证，需提供 Bearer token 或会话 cookie。
• 组合名称冲突会返回 409 错误。
• 无效策略会返回 400 错误。
• 组合不存在会返回 404 错误。
• 详细的请求/响应模式需参考 GET /api/openapi/spec 或 docs/openapi.yaml。
• 使用该技能需要配置 OMNIROUTE_URL 和 OMNIROUTE_KEY，具体设置参见入口 SKILL。