核心概念¶

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

📚 本章内容¶

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

架构总览 ¶

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

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

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

👉 查看架构总览

包结构与依赖¶

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

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

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

👉 查看包结构详情

🎯 快速导航¶

我想了解...

**SAGE 的整体设计**

→ [架构总览](architecture/overview.md) - 查看 5 层架构体系和设计原则

**包之间的关系**

→ [包结构与依赖](architecture/package-structure.md) - 理解 8 个核心包的依赖关系和模块划分

**各层级的详细用法**

→ [用户指南](../guides/index.md) - 按 L1-L5 层级查看详细文档

我是...

**新手开发者**

1. 先阅读 [架构总览](architecture/overview.md) 建立全局认知
2. 查看 [入门指南](../getting-started/index.md) 开始实践
3. 遇到问题时参考本章内容理解设计意图

**贡献者**

1. 详细阅读 [包结构与依赖](architecture/package-structure.md) 了解代码组织
2. 理解依赖规则（参考 [包结构文档](architecture/package-structure.md)）避免架构违规
3. 查看 [开发者指南](../developers/commands.md) 了解贡献流程
4. 参考 [包架构文档](../dev-notes/package-architecture.md) 了解最新的架构状态

**架构师 / 技术决策者**

1. 系统学习 [架构总览](architecture/overview.md) 和 [包结构](architecture/package-structure.md)
2. 查看 [包架构文档](../dev-notes/package-architecture.md) 了解架构演进历史
3. 评估如何将 SAGE 的架构模式应用到自己的系统

🔍 核心概念速览¶

分层架构（Modular Monolith）¶

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

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

独立仓库：sage-benchmark, sage-examples, sage-studio, sageLLM

关键特性：

✅ 单向依赖 - 高层依赖低层，低层不依赖高层
✅ 同层独立 - 同层包之间相互独立（如 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
✅ 选择合适的层 - 明确应该在哪个层级实现你的功能
✅ 避免反模式 - 了解哪些用法是不推荐的

系统集成者

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

贡献者

✅ 代码组织规范 - 知道代码应该放在哪个包、哪个模块
✅ 避免架构违规 - 理解依赖规则，不引入循环依赖
✅ 保持一致性 - 遵循现有的架构模式和设计原则

架构师

✅ 技术选型参考 - 了解 SAGE 的设计决策和技术选型背景
✅ 模式复用 - 将 SAGE 的架构模式应用到其他系统
✅ 演进方向 - 理解架构演进，预判未来发展方向

🚀 下一步¶

选择您感兴趣的主题深入学习：

架构总览

了解 SAGE 的 6 层架构体系、10 个核心包和设计原则

查看详情

包结构与依赖

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