Mayfly - 基于 Spring AI 的企业级大模型路由治理插件

面向 Spring AI 生态的开源企业级大模型治理中间件——统一路由、熔断降级、故障转移、成本追踪。

---

📖 简介

Mayfly 是一个基于 Spring AI 的企业级大模型路由治理插件。它解决企业在多模型接入场景下的三个核心痛点：

• 统一路由调度：一个入口对接 DeepSeek、智谱 GLM、通义千问、OpenAI、Claude 等主流大模型
• 高可用治理：逐 Key 熔断、两级故障转移、PRIMARY Key 自动探测恢复
• 成本追踪：Token 真实采集、日/月成本聚合、按厂商归因

以 Spring Boot Starter 形式接入，零侵入，3 行配置即可运行。

✨ 核心特性

特性	说明
🔄 统一多模型调用	单一 ModelRouter 接口，屏蔽 8+ 厂商 API 差异
🎯 5 种路由策略	固定、权重、规则(SpEL)、内容分类、自适应权重
⚖️ 负载均衡	轮询、平滑加权轮询
🔑 多 Key 管理	一个模型配多个 API Key，独立熔断，逐 Key 切换
🛡️ 两级故障转移	KEY 级优先 → 跨模型降级
🔌 逐 Key 熔断	每个 ModelInstance 独立 CircuitBreaker + RateLimiter
🔄 自动恢复	KeyProbeScheduler 定时探测 PRIMARY Key 恢复
📊 成本追踪	Token 用量采集、日/月成本统计、Actuator 端点
🧠 自适应权重	根据延迟和错误率动态调权
🇨🇳 8 种模型适配	DeepSeek、智谱、通义、OpenAI、Claude、文心、星火、Mock
🚀 零配置接入	Spring Boot Starter 一键集成

---

🚀 快速开始

1. 添加依赖

<dependency>
    <groupId>io.mayfly</groupId>
    <artifactId>mayfly-spring-boot-starter</artifactId>
    <version>1.2.0</version>
</dependency>

2. 配置模型

mayfly:
  models:
    - name: zhipu-primary
      provider: zhipu
      api-key: ${ZHIPU_API_KEY}
      model: glm-4
      weight: 70
    
    - name: tongyi-backup
      provider: tongyi
      api-key: ${TONGYI_API_KEY}
      model: qwen-max
      weight: 30

3. 使用路由

@Service
public class ChatService {
    
    private final ModelRouter modelRouter;
    
    public ChatService(ModelRouter modelRouter) {
        this.modelRouter = modelRouter;
    }
    
    public MayflyResponse chat(String message) {
        return modelRouter.chat(new MayflyPrompt(message));
    }
    
    public Flux<MayflyResponse> stream(String message) {
        return modelRouter.stream(new MayflyPrompt(message));
    }
}

至此接入完成。路由、熔断、故障转移、监控、成本追踪全部自动生效。

---

🏗️ 系统架构

10 模块三层架构

Mayfly 经历了从 8 模块到 10 模块的架构演进，明确分离 SPI / Bridge / Impl / Integration 四层：

┌─────────────────────────────────────────────────────────────────┐
│                      应用集成层                                   │
│              mayfly-spring-boot-starter (纯自动配置)               │
├─────────────────────────────────────────────────────────────────┤
│                      业务实现层                                   │
│              mayfly-runtime                                       │
│   DefaultModelRouter  DefaultModelRegistry                        │
│   KeyProbeScheduler   CostTracker                                 │
├─────────────────────────────────────────────────────────────────┤
│                      Spring AI 桥接层                              │
│              mayfly-spring-ai-bridge                              │
│   ChatModelWrapper (ChatModel → MayflyModel)                     │
│   MayflyModelChatModel (MayflyModel → ChatModel)                 │
├─────────────────────────────────────────────────────────────────┤
│                      能力 SPI 层（可插拔）                          │
│  ┌───────────┬───────────┬───────────┬──────────────┐          │
│  │ mayfly-   │ mayfly-   │ mayfly-   │ mayfly-       │          │
│  │ router    │ load-     │ failover  │ circuit-      │          │
│  │           │ balancer  │           │ breaker       │          │
│  ├───────────┼───────────┼───────────┼──────────────┤          │
│  │ mayfly-   │ mayfly-   │ mayfly-   │               │          │
│  │ monitor   │ adapter   │ core      │               │          │
│  └───────────┴───────────┴───────────┴──────────────┘          │
├─────────────────────────────────────────────────────────────────┤
│                      模型服务层                                    │
│   DeepSeek    智谱 AI    通义千问     OpenAI     Claude         │
└─────────────────────────────────────────────────────────────────┘

模块依赖链

mayfly-core (核心接口与领域模型，零外部依赖)
  ↓
mayfly-router  mayfly-loadbalancer  mayfly-failover
mayfly-circuitbreaker  mayfly-monitor  mayfly-adapter
  ↓
mayfly-spring-ai-bridge (双向桥接模块)
  ↓
mayfly-runtime (业务编排与默认实现)
  ↓
mayfly-spring-boot-starter (纯自动配置，仅 3 个类)
  ↓
mayfly-demo (示例应用)

设计原则

1. Core 层零依赖 — MayflyPrompt、MayflyResponse、MayflyModel 为自有类型，不依赖任何框架
2. 双向桥接 — ChatModelWrapper + MayflyModelChatModel 实现与 Spring AI 无缝互操作
3. Starter 职责收敛 — 仅负责自动配置，业务逻辑全部在 runtime 模块

---

🔑 关键设计

多 Key 展开 + 逐 Key 熔断

一个模型配置多个 API Key，注册时展开为独立实例：

models:
  - name: deepseek
    provider: deepseek
    api-keys:
      - key: sk-primary          # PRIMARY，占 70% 权重
        role: primary
      - key: sk-secondary-1      # SECONDARY，均分 30%
        role: secondary
      - key: sk-secondary-2
        role: secondary

每个实例有独立的 CircuitBreaker，天然实现逐 Key 熔断。

deepseek#0 (PRIMARY) 请求失败
  → KEY 级故障转移: deepseek#1, deepseek#2（同模型换 Key）
  → 跨模型故障转移: zhipu#0（所有 Key 都不可用）

自适应权重路由

根据实时运行指标动态调整流量权重：

有效权重 = 配置权重 × 健康系数 × 延迟系数 × 错误率系数

• 健康系数：HEALTHY=1.0, COOLDOWN=0.1（避免突变）, UNHEALTHY=0
• 延迟系数：1 - (avgLatency / 最大容忍延迟)
• 错误率系数：1 - min(失败率 × 10, 1)（1% 失败率 → 0.9）

内容分类路由

纯规则引擎，根据 prompt 特征自动分类（代码、创作、翻译、简单、复杂），不引入外部模型。分类结果供 SpEL 规则引用：#request.metadata.classification == 'code'

PRIMARY Key 自动探测恢复

KeyProbeScheduler 定时（默认 30s）扫描处于 COOLDOWN 的 PRIMARY Key，发送轻量探测请求。成功后自动恢复 HEALTHY 状态并重置失败计数器，流量自动回流。

Spring AI 版本解耦

v1.0: core 直接暴露 Spring AI 的 ChatResponse/Prompt —— 版本升级受影响
v1.2: core 定义自有 MayflyPrompt/MayflyResponse/MayflyModel（零依赖）
      桥接模块可选引入，实现双向转换

---

📊 压测结果

三轮系统性压测验证 Mayfly 管线性能：

场景	吞吐量	P99 延迟	说明
Mock 完整管线	95,420 req/s	<5ms	路由→熔断→Mock 调用全链路
路由层基准	166 万+ req/s	<50μs	纯策略选择，无模型调用
毁灭测试(2000并发)	116,100 样本	100% 成功	唯一瓶颈：Windows 端口耗尽

结论：Mayfly 管线自身开销约 1.6ms/请求，生产瓶颈完全在 AI API 提供商侧。

---

🎯 为什么要用 Mayfly？

能力	Spring AI	Mayfly
基础调用	✅	✅（增强）
模型路由	❌	✅ 5 种策略
多 Key 管理	❌	✅ 逐 Key 熔断 + 切换
负载均衡	❌	✅ 平滑加权轮询
熔断保护	❌	✅ Resilience4j 逐实例
自适应路由	❌	✅ 实时动态调权
自动恢复	❌	✅ KeyProbeScheduler
内容分类路由	❌	✅ 规则引擎
成本追踪	❌	✅ Token + 成本聚合
国产模型	⚠️ 有限	✅ DeepSeek/智谱/通义
零配置接入	❌	✅ Spring Boot Starter
框架解耦	N/A	✅ Core 零外部依赖

---

📋 完整配置

mayfly:
  enabled: true
  
  # 模型配置
  models:
    - name: deepseek
      provider: deepseek
      model: deepseek-chat
      weight: 100
      api-keys:
        - key: ${DEEPSEEK_API_KEY_1}
          role: primary
        - key: ${DEEPSEEK_API_KEY_2}
          role: secondary
  
  # 路由配置
  router:
    strategy: adaptive-weighted  # fixed, weighted, rule-based, content-based, adaptive-weighted
    adaptive:
      max-tolerated-latency: 30s
      error-sensitivity: 10
      recovery-speed: 0.1
    content-classifier:
      rules:
        - type: code
          model: deepseek
        - type: creative
          model: claude
      default-model: zhipu-primary
  
  # 故障转移配置
  failover:
    enabled: true
    max-retries: 2
    cooldown-duration: 60s
    retryable-exceptions:
      - java.net.SocketTimeoutException
      - org.springframework.web.client.HttpServerErrorException
  
  # 熔断器配置
  circuit-breaker:
    failure-rate-threshold: 50
    wait-duration-in-open-state: 60s
    sliding-window-size: 10
    minimum-number-of-calls: 5
  
  # 限流器配置
  rate-limiter:
    limit-for-period: 100
  
  # PRIMARY Key 探测恢复
  probe:
    enabled: true
    interval: 30s
    timeout: 5s
  
  # 监控与成本配置
  monitor:
    enabled: true
    costs:
      - model: deepseek-chat
        input-price: 0.0005
        output-price: 0.002

---

🗺️ 演进路线

阶段	特性	状态
P0	连接池复用、多 Key + 逐 Key 熔断、Token 真实采集	✅ 已完成
P1	主 Key 探测恢复、自适应权重路由、成本模型、Spring AI 解耦、内容分类路由	✅ 已完成
P2	内置轻量队列、Geo 感知路由、成本感知调度	🔜 规划中
P3	外部 MQ 对接、A/B 测试灰度、配置热加载	📋 待定

---

📄 文档

• 用户手册
• API 参考文档
• 部署指南
• 开发手册
• 架构设计文档
• 演进方案

发布说明

• 版本日志
• v1.2.0 发布说明
• v1.1.0 发布说明

---

🤝 开源社区

欢迎参与贡献！请查看 贡献指南 和 行为准则。

联系方式

• Issues: 提交问题或功能请求
• 邮箱: git@xsjyby.asia

---

📄 许可证

本项目采用 Apache License 2.0 许可证。