核心概念¶

深入理解 SAGE 的架构设计、包组织和设计决策。

📚 本章内容¶

本章节帮助您系统性地理解 SAGE 的技术架构和设计哲学。

架构总览 ¶

了解 SAGE 的整体架构设计和分层理念：

🏗️ 分层架构 - 从 L1 基础设施到 L6 接口层的 6 层架构体系
📦 10 个核心包 - sage-common、sage-kernel、sage-libs 等各包的职责定位
🔄 数据流模型 - 声明式流式处理的核心编程范式
🎯 设计原则 - 单向依赖、接口优先、最小依赖原则

适合人群：想要全面了解 SAGE 整体架构的开发者、架构师

👉 查看架构总览

包结构与依赖¶

深入了解各包的职责边界、模块组成和依赖关系：

📊 完整包列表 - 10 个包的详细信息（职责、模块数、测试数）
🔗 依赖关系图 - Mermaid 可视化依赖关系
📋 详细规范 - 每个包的核心模块、公共 API、依赖说明
⚠️ 依赖规则 - 允许和禁止的依赖模式（向下依赖、同层独立）

适合人群：需要理解代码组织的贡献者、希望扩展 SAGE 的开发者

👉 查看包结构详情

🎯 快速导航¶

我想了解...我是...

SAGE 的整体设计

→ 架构总览 - 查看 6 层架构体系和设计原则

包之间的关系

→ 包结构与依赖 - 理解 10 个包的依赖关系和模块划分

各层级的详细用法

→ 用户指南 - 按 L1-L6 层级查看详细文档

新手开发者

先阅读架构总览建立全局认知
查看入门指南开始实践
遇到问题时参考本章内容理解设计意图

贡献者

详细阅读包结构与依赖了解代码组织
理解依赖规则（参考包结构文档）避免架构违规
查看开发者指南了解贡献流程
参考包架构文档了解最新的架构状态

架构师 / 技术决策者

系统学习架构总览和包结构
查看包架构文档了解架构演进历史
评估如何将 SAGE 的架构模式应用到自己的系统

🔍 核心概念速览¶

分层架构（Modular Monolith）¶

SAGE 采用模块化单体架构，平衡了单体应用的简单性和微服务的模块化优势：

L6: Interface Layer    → sage-studio, sage-cli, sage-tools (Web UI, CLI, 工具)
         ↓
L5: Application Layer  → sage-apps, sage-benchmark (应用实现)
         ↓
L4: Middleware Layer   → sage-middleware (领域算子与组件)
         ↓
L3: Core Layer         → sage-kernel (执行引擎) + sage-libs (算法库)
         ↓
L2: Platform Layer     → sage-platform (队列、存储、服务抽象)
         ↓
L1: Foundation Layer   → sage-common (基础工具与类型)

关键特性：

✅ 单向依赖 - 高层依赖低层，低层不依赖高层
✅ 同层独立 - 同层包之间相互独立（如 kernel ⊥ libs）
✅ 清晰边界 - 通过 __init__.py 明确公共 API
✅ 0 架构违规 - 自动化工具持续验证依赖合规性

核心包职责¶

包名	层级	核心职责	关键模块
sage-common	L1	基础工具、配置、核心类型	core, config, utils, components
sage-platform	L2	消息队列、存储、服务抽象	queue, storage, service
sage-kernel	L3	流式执行引擎，提供 DataStream API	api, operators, runtime
sage-libs	L3	AI 算法库：Agents、RAG、I/O、工作流	agents, rag, io, integrations
sage-middleware	L4	领域算子（RAG/LLM）+ 组件（Memory/DB）	operators, components
sage-apps	L5	应用实现（视频分析、医疗诊断）	video, medical_diagnosis
sage-studio	L6	Web 可视化界面	ui, models, services
sage-cli	L6	统一命令行接口（集群、作业管理）	cluster, job, deploy
sage-tools	L6	开发工具（开发、测试、Pipeline）	cli, pipeline_builder

数据流编程模型¶

SAGE 采用声明式数据流编程，类似 Apache Flink 但更轻量：

from sage.kernel.api import LocalEnvironment
from sage.libs.io import FileSource, ConsoleSink

env = LocalEnvironment()

# 声明式数据流 Pipeline
env.from_source(FileSource("data.txt"))  # 数据源
   .map(lambda x: x.upper())              # 转换操作
   .filter(lambda x: len(x) > 10)         # 过滤条件
   .sink(ConsoleSink())                   # 输出

env.execute()  # 执行

核心特性：

🔄 流式处理 - 数据逐条处理，支持无界数据流
🎯 算子链 - map、filter、join、window 等丰富算子
⚡ 延迟执行 - 构建 DAG，优化后执行
🌐 分布式 - 支持本地和远程执行环境

📖 相关阅读¶

快速入门¶

安装指南 - 安装 SAGE 开发环境
快速开始 - 5 分钟上手第一个 Pipeline
流式处理 101 - 理解数据流编程基础

深入学习¶

Kernel 用户指南 - 深入理解流式执行引擎
Libs 用户指南 - 了解 AI 算法库和 Agents
Middleware 用户指南 - 领域算子和组件使用

架构演进¶

sage-libs 重构 - L3 算法库模块规范化过程
RPC 队列重构 - 消息队列系统优化历程
L2 平台层 - 平台抽象层的设计与实现

💡 为什么需要了解核心概念？¶

对不同角色的价值¶

应用开发者

✅ 理解设计意图 - 知道为什么要这样设计，更好地使用 SAGE
✅ 选择合适的层 - 明确应该在哪个层级实现你的功能
✅ 避免反模式 - 了解哪些用法是不推荐的

系统集成者

✅ 依赖管理 - 清楚各包的依赖关系，合理组织部署
✅ 性能优化 - 理解架构后能做出更好的性能优化决策
✅ 问题定位 - 知道各层职责，快速定位问题所在