#MoonRoute

• 模型能力、成本、延迟和健康状态路由；
• Token Bucket 限流、并发控制和预算治理；
• 超时、重试、Circuit Breaker 和 Provider Fallback；
• 非流式与流式响应统一处理；
• OpenAI-compatible HTTP Gateway 与 SSE 输出；
• Token、费用、延迟、错误和路由决策记录。

#项目状态

1. Provider 统一请求模型、响应模型和适配器边界；
2. 基于能力过滤、成本、延迟、健康状态和优先级的确定性路由器；
3. Token Bucket、并发限制和单进程内存预算控制；
4. 重试退避配置、自动重试、Circuit Breaker 和 Provider Fallback；
5. 统一流式事件、Mock Provider 和 SSE 编码；
6. /healthz、/metrics 和 /v1/chat/completions Gateway 核心处理；
7. 请求审计记录中的 Provider、重试次数和 Fallback 状态；
8. native async HTTP 服务 Demo。

#当前实现与验证

moon fmt
moon check
moon test

#安装与快速开始

moon update
moon check --deny-warn
moon test

#Provider 接入

#策略配置

#Gateway API

• GET /healthz：返回健康状态；
• GET /metrics：返回基础请求、成功、失败和费用统计；
• POST /v1/chat/completions：接收 model、messages 和可选 stream，非流式返回 JSON，流式返回 SSE；
• 非法 JSON、字段类型错误、空消息、未知模型返回结构化 HTTP 400；限流或预算拒绝返回 HTTP 429。

moon run examples/gateway_demo

Invoke-WebRequest http://127.0.0.1:3000/healthz

Invoke-WebRequest -Method Post `
  -ContentType 'application/json' `
  -Body '{"model":"demo", "stream": true, "messages": [{"role":"user","content":"hello"}]}' `
  http://127.0.0.1:3000/v1/chat/completions

#发布到 Mooncakes

moon publish

#为什么需要 MoonRoute

请求能力判断
  -> Provider 选择
  -> 预算与限流检查
  -> 请求执行
  -> 超时、重试、熔断或 Fallback
  -> 流式响应转发
  -> Token、费用、延迟和错误记录

#架构

OpenAI-compatible Client / MoonBit API
                  |
             HTTP Gateway
                  |
         请求解析与治理策略
                  |
       能力过滤与路由评分
                  |
        弹性执行与流式处理
                  |
        Provider Adapter / Mock Provider
                  |
       调用记录、用量和指标统计

• Gateway 负责 HTTP 请求、响应编码和 SSE 输出；
• 治理核心负责限流、预算、并发和策略判断；
• 路由器负责 Provider 能力过滤与评分；
• 弹性执行器负责重试、熔断和 Fallback；当前超时调度仍属于后续迭代；
• Provider 适配器负责连接具体的底层客户端；
• 观测层负责记录每次请求的路由与执行结果。

#研究基础

#1. FrugalGPT：模型级联与成本—效果权衡

#2. RouteLLM：基于偏好数据的模型路由

#3. The Tail at Scale：尾延迟治理

#4. Token Bucket：限流标准

#5. Circuit Breaker 与指数退避

#现有语言实现对比

• Python：LiteLLM 提供统一 LLM 调用和 Gateway Proxy，RouteLLM 提供基于偏好数据的路由模型；
• TypeScript / JavaScript：Portkey AI Gateway 提供多 Provider Gateway，支持路由、Fallback、重试、预算、限流和流式输出；
• Go：Envoy AI Gateway 面向 Envoy/Kubernetes 体系，Bifrost 提供多 Provider OpenAI-compatible Gateway；
• Rust：Shepherd Model Gateway 面向高性能模型路由，AISIX AI Gateway 提供静态二进制、路由、故障转移、预算、限流和观测；
• MoonBit：Mooncakes 中已有 llm_interop，提供多供应商协议抽象、流式调用、工具调用和协议转换，但不承担 MoonRoute 规划的完整请求治理职责。

#MoonRoute 的实现边界

底层 Provider SDK / llm_interop
              |
       MoonRoute Governance Core
              |
       Gateway / AI Application

• 训练 LLM Router；
• 重新实现 Provider SDK；
• 复制 LiteLLM、Portkey 或 Envoy 的完整 Gateway；
• 实现 Kubernetes 控制器；
• 实现分布式 Redis 配额；
• 实现完整管理控制台；
• 实现模型推理、Agent、MCP、RAG 或向量数据库。

#Demo

#成本权重路由

#延迟权重路由

#熔断与 Fallback

#HTTP Gateway 流式响应

#测试计划

• 路由能力过滤和评分；
• 成本、延迟、健康状态和优先级权重；
• 相同配置下的确定性选择；
• Token Bucket 补充和突发边界；
• 并发额度耗尽；
• Token 配额和预算超限；
• 重试次数和指数退避；
• Circuit Breaker 关闭、打开和半开状态；
• Fallback 链路；
• 流式事件正常结束和中途失败；
• Provider 未返回实际 Token 用量；
• HTTP 非法请求和 Gateway 健康检查；
• Mock Provider 故障注入。

#开发计划

• v1.0：Provider 抽象、请求模型、Mock Provider 和路由器；
• v1.1：Token Bucket、并发控制、Token 配额和预算；
• v1.2：超时、重试、指数退避、Circuit Breaker 和 Fallback；
• v1.3：统一流式事件和 SSE Gateway；
• v1.4：调用记录、指标统计、故障注入和完整回归测试；
• v2.0：持久化配额、动态配置、更多 Provider 适配和分布式治理。

#许可证

#参考资料

1. Chen, Lingjiao; Zaharia, Matei; Zou, James. FrugalGPT: How to Use Large Language Models While Reducing Cost and Improving Performance. 2023.
2. Ong, Isaac et al. RouteLLM: Learning to Route LLMs with Preference Data. ICLR 2025.
3. Dean, Jeffrey; Barroso, Luiz André. The Tail at Scale. Communications of the ACM, 2013.
4. Heinanen, Juha; Guerin, Ron. RFC 2697: A Single Rate Three Color Marker. 1999.
5. LiteLLM.
6. Portkey AI Gateway.
7. Envoy AI Gateway.
8. Bifrost.
9. Shepherd Model Gateway.
10. AISIX AI Gateway.
11. MoonBit llm_interop.