跳转至

SAGE 架构总览

最后更新: 2025-01

变更日志:

  • 2025-01: 简化为 5 层架构 (L1-L5)，独立包移至独立仓库
  • 2025-12-02: 补充 sage-llm-gateway，更新 L6 描述，添加 C++ 扩展说明
  • 2025-10-23: 初始版本

SAGE (Streaming AI aGent Engine) 采用分层单体架构（Modular Monolith），由 8 个核心包组成，支持构建高性能的流式 AI Agent 应用。

🏗️ 架构全景

┌─────────────────────────────────────────────────────────────────────────┐
│  L5: Interface Layer (接口层)                                           │
│  ┌────────────┐ ┌────────────┐                                          │
│  │ sage-cli   │ │sage-tools  │                                          │
│  │ 生产 CLI   │ │ 开发工具   │                                          │
│  └────────────┘ └────────────┘                                          │
└─────────────────────────────────────────────────────────────────────────┘
                               ▼
┌─────────────────────────────────────────────────────────────┐
│  L4: Middleware Layer (中间件层) ⚡ 含 C++ 扩展              │
│  ┌───────────────────────────────────────────────────────┐  │
│  │         sage-middleware                               │  │
│  │  RAG/LLM Operators + Components (Memory, DB, Flow)   │  │
│  │  C++: sageFlow (向量检索), NeuroMem (记忆系统)         │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                               ▼
┌─────────────────────────────────────────────────────────────┐
│  L3: Core Layer (核心层)                                    │
│  ┌──────────────┐         ┌──────────────┐                  │
│  │ sage-kernel  │         │  sage-libs   │                  │
│  │ 流式引擎      │         │ 算法库+Agents │                  │
│  └──────────────┘         └──────────────┘                  │
└─────────────────────────────────────────────────────────────┘
                               ▼
┌─────────────────────────────────────────────────────────────┐
│  L2: Platform Layer (平台层)                                │
│  ┌───────────────────────────────────────────────────────┐  │
│  │         sage-platform                                 │  │
│  │  Queue, Storage, Service 抽象                         │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                               ▼
┌─────────────────────────────────────────────────────────────┐
│  L1: Foundation Layer (基础设施层)                          │
│  ┌───────────────────────────────────────────────────────┐  │
│  │         sage-common                                   │  │
│  │  Core Types, Config, Utils, Components               │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│  独立仓库 (Independent Repositories)                        │
│  sage-benchmark, sage-examples, sage-studio, sageLLM       │
└─────────────────────────────────────────────────────────────┘

📦 核心组件

L1: sage-common (基础设施)

  • 职责: 提供通用工具、配置、核心类型
  • 关键模块: core, config, utils, components
  • 依赖: 无
  • 文档: Common 用户指南 →

L2: sage-platform (平台服务)

  • 职责: 消息队列、存储、服务抽象
  • 关键模块: queue, storage, service
  • 依赖: common
  • 特性: 使用工厂模式解决 L2→L3 跨层依赖（register_rpc_queue_factory）
  • 文档: Platform 用户指南 →

L3: sage-kernel (流式引擎)

  • 职责: 流式数据处理、任务调度、分布式执行
  • 关键模块: api, operators, runtime
  • 依赖: common, platform
  • 文档: Kernel 用户指南 →

L3: sage-libs (算法库)

  • 职责: Agents 框架、RAG 工具、I/O 工具、工作流优化
  • 关键模块: agents, rag, io, workflow, integrations
  • 依赖: common, kernel (可选)
  • 文档: Libs 用户指南 →

L4: sage-middleware (中间件) ⚡

  • 职责: 领域特定算子（RAG, LLM）和组件（Memory, VectorDB）
  • 关键模块: operators, components
  • 依赖: common, platform, kernel, libs
  • C++ 扩展: sageFlow (向量检索), NeuromMem (记忆系统)
  • 文档: Middleware →

L5: 接口层

  • sage-cli: 生产 CLI（集群管理、作业部署）
  • sage-tools: 开发工具（sage-dev 命令，质量检查）

独立仓库 (不在 SAGE 核心)

  • sageLLM: LLM 推理引擎 (PyPI: isagellm)
  • sage-benchmark: 性能基准测试 (PyPI: isage-benchmark)
  • sage-examples: 教程和应用示例 (原 sage-apps)
  • sage-studio: Web 可视化界面

更多详情请参考 用户指南。

🎯 设计原则

1. 分层架构 (Layered Architecture)

  • 单向依赖: 高层可以依赖低层，反之不可
  • 清晰边界: 每层职责明确，互不越界
  • 可替换性: 同层组件可独立替换

2. 接口优先 (Interface-First)

  • 通过 __init__.py 明确公共 API
  • 低层提供稳定接口
  • 高层通过接口使用低层

3. 最小依赖 (Minimal Dependencies)

  • 只依赖必需的包
  • 减少耦合，提高独立性
  • 支持增量部署

🔗 依赖规则

✅ 允许

L5 → L4, L3, L2, L1
L4 → L3, L2, L1
L3 → L2, L1
L2 → L1

❌ 禁止

L1 → 任何其他层
L2 → L3+
L3 → L4+
同层互相依赖

📊 架构指标

指标 数值 状态
核心包数 8 ✅
总模块数 679+ ✅
测试数 1,329+ ✅
架构违规 0 ✅
Layer标记覆盖 100% ✅
测试通过率 99.7% ✅
C++ 扩展 2 ✅

📚 深入阅读

🚀 快速开始

从这里开始使用 SAGE: