入门版原理介绍

SAG是SQL驱动的新一代 RAG 引擎，可以在查询时自动构建知识图谱

• 把原始文本自动拆解成“语义原子事件”
• 为每个事件抽取多维“自然语言向量（多维度实体）”
• 在 查询时动态构建关系网络，而不是预先维护知识图谱

• 自动理解：AI自动将文档拆解为原子性的事件
• 智能关联：检索时动态构建关系网络，无需预先维护图谱
• 精准召回：三阶段搜索（Recall → Expand → Rerank），找到最相关的信息
• 完整溯源：每个结果都能追溯来源和关联链路
• 灵活扩展：支持自定义实体类型，适配任何业务场景

• 👨‍💻 普通开发者：想要一个好用、易部署、可定制的本地 / 企业 RAG 引擎
• 🏢 企业技术团队：需要可审计、可控、私有化部署的知识中台
• 🧑‍🔬 研究人员：对 GraphRAG / RAG+KG 感兴趣，想深入算法与数学分析

SAG 最初来源于一个核心问题：如何在不维护庞大知识图谱的前提下，让机器真正“理解”和“关联”海量文本？

• 从产品视角：一个可以托管你所有文档、对话、业务数据的“数据智能引擎”
• 从技术视角：一种 Event-Centric 的动态知识图谱构建算法，在查询时按需生成图结构
• 从实现视角：组合 SQL 精确检索 + 向量语义搜索 + PageRank 的三阶段搜索系统

痛点：
• 笔记分散，难以查找
• 信息孤岛，关联性差
• 手动整理费时费力

解决：
✓ 自动拆分知识卡片
✓ 智能标注实体关系
✓ 秒级多维度检索

痛点：
• 版本混乱，信息冗余
• 决策分散，难以追溯
• 新人上手成本高

解决：
✓ 自动提取决策点
✓ 追踪信息演进
✓ 快速生成报告

痛点：
• 文献量大，难抽重点
• 手动标注耗时长
• 关系发现靠直觉

解决：
✓ 自动提取论点
✓ 构建主题网络
✓ 发现隐含关联

SAG 的系统设计直接对应其算法设计：存储时“事件化”，查询时“图谱化”。

┌─────────────────────────────────────────────┐
│                Data Processing 数据处理     │
│  LOAD   ─→   EXTRACT   ─→   INDEX          │
│  加载        事件提取        索引（向量+SQL）│
└────────────────────┬───────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────┐
│                Storage 存储层              │
│  • MySQL: 事件 / 实体 / 事件-实体关系      │
│  • Elasticsearch / VecDB: 向量检索         │
└────────────────────┬───────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────┐
│               Search 检索层                │
│  Recall  ─→  Expand  ─→  Rerank            │
│  实体召回      多跳扩展      智能排序       │
└─────────────────────────────────────────────┘

系统默认（5W1H）：

自定义扩展：

# 项目管理场景
custom_entities = [
    EntityType(type="project_stage", name="项目阶段", weight=1.2),
    EntityType(type="risk_level", name="风险等级", weight=1.3)
]

# 医疗场景
custom_entities = [
    EntityType(type="symptom", name="症状", weight=1.4),
    EntityType(type="diagnosis", name="诊断", weight=1.5)
]

阶段1: Recall - 实体召回
├─ LLM理解查询意图
├─ 提取结构化实体
├─ 向量检索相关实体
└─ 定位关联事件
    
阶段2: Expand - 多跳扩展
├─ 从初始事件出发
├─ 通过共同实体发现关联
├─ BFS多跳探索（深度可配）
└─ 构建完整关系网络
    
阶段3: Rerank - 智能排序
├─ PageRank计算重要性
├─ 综合：实体权重+时间+相似度
├─ 方向性权重（重要事件权重大）
└─ 返回Top-N + 线索链

可解释性示例：

{
  "event": "MoE架构的稀疏专家层设计",
  "score": 0.89,
  "clues": [
    {
      "stage": "recall",
      "from": "Query: 大模型优化",
      "to": "Entity: MoE架构",
      "confidence": 0.92
    },
    {
      "stage": "expand", 
      "from": "Event: MoE架构优势",
      "to": "Event: 稀疏专家层设计",
      "shared_entities": ["MoE架构", "专家层"],
      "confidence": 0.85
    }
  ]
}

# 1. 克隆项目
git clone https://github.com/Zleap-AI/SAG.git
cd SAG

# 2. 配置环境
cp .env.example .env
# 编辑 .env：
#   LLM_API_KEY=sk-xxx
#   MYSQL_PASSWORD=your_password

# 3. 下载资源 （首次执行）
python scripts/download_nltk_data.py

# 4. 启动服务
docker compose up -d

# 5. 访问
# 前端: http://localhost
# API: http://localhost/api/docs

import asyncio
from sag import SAGEngine
from sag.modules.load.config import LoadBaseConfig
from sag.modules.extract.config import ExtractBaseConfig
from sag.modules.search.config import SearchBaseConfig

async def main():
    # 初始化
    engine = SAGEngine(source_config_id="my-project")
    
    # 加载文档
    await engine.load(LoadBaseConfig(
        type="path",
        origin=["./docs/article.md"],
        background="技术文档"
    ))
    
    # 提取事件
    await engine.extract(ExtractBaseConfig(
        parallel=True,
        background="AI大模型文档"
    ))
    
    # 智能检索
    result = await engine.search(SearchBaseConfig(
        query="如何优化大模型推理速度？",
        depth=2,
        top_k=10
    ))
    
    # 查看结果
    for event in result.events:
        print(f"[{event.score:.2f}] {event.title}")
        print(f"  {event.summary}\n")

asyncio.run(main())

访问 http://localhost:3000

1. 上传文档：拖拽 Markdown、PDF、HTML
2. 自动处理：系统自动加载→提取→索引
3. 智能搜索：输入自然语言查询
4. 查看结果：浏览事件、线索图谱、来源

我们相信：

• 🌍 技术共享：核心算法应该被更多人使用和改进
• 🔧 灵活部署：企业可自建私有化部署
• 🤝 社区驱动：开源社区的反馈让产品更好
• 💡 创新激励：开发者可基于SAG构建自己的应用

• 需要自动网页追踪和信息流管理
• 想接入更多信息源
• 需要团队协作和权限管理
• 希望零部署，开箱即用
• 需要专业技术支持

体验完整版：https://zleap.ai

这一节是给对算法细节感兴趣的开发者和研究人员的简版说明。

SAG 的底层思想可以用两句话概括：

• 事件原子化（Event Atomization）
  不再按字符/Token 长度“机械切块”，而是将文档转化为一个个 语义完整、彼此独立 的“事件 (Event)”。
• 自然语言向量（Natural Language Vector）
  不只把整段文本编码成向量，而是为每个 Event 抽取多维实体：时间、地点、人物、动作、话题、标签…
  它们组成了一个“由自然语言实体构成的向量”。

关键洞察：

• Event 是 原子知识单元
• Entity 是 事件的实体维度
• 事件之间的关系不提前计算，而是 在查询时动态计算

目标：从查询语句出发，找到一批高度相关的 实体 + 事件。

• 步骤概要：
  • LLM 解析查询：抽取结构化实体（TOPIC、ACTION、PERSON…）
  • 向量检索实体：在实体向量空间中搜索
  • 用实体查事件（SQL）：通过实体 ID 反查事件
  • 事件向量检索：直接在 Event 向量上查
  • 交集过滤 + 权重反向传播：兼顾语义相似度与实体匹配

目标：通过“共享实体模式”在事件-实体空间做 多跳搜索，找到更深层的相关信息。

• 做法：

  • 将高权重实体视作当前“前沿层”
  • 用这些实体在 SQL 中查找新事件
  • 对新事件计算相似度和权重，并将权重反向传播给新实体
  • 只保留“新出现”的实体，形成下一跳前沿层
  • 过程中带有 权重衰减 + 去重，无新实体时自动收敛

• 特性：

  • 与“六度空间理论”类似：任意两个事件，往往可以通过少量中间实体连接
  • 深度 2 通常在 精度 / 召回 / 延迟 上达到最优平衡

• 实体权重示意公式：

$$W(k_i) = \sum_{e_j \in E} \left[ W_{e2}(e_j) \times \frac{count(k_i, e_j)}{\ln(1 + step_{ij})} \right]$$

在 Recall + Expand 得到的事件子图上，SAG 构建隐式图并运行 加权 PageRank：

• 节点：事件 e
• 有向边：共享实体关系，边权由实体权重 + 频次决定：

$$ W(e_i \rightarrow e_j) = \sum_{k \in (e_i \cap e_j)} W_{\text{entity}}(k) \cdot \ln(1 + \text{freq}(k, e_j)) $$

• PageRank 迭代：

$$ \mathrm{PR}(e_j) = \frac{1-d}{N} + d \sum_{e_i \in \mathrm{In}(e_j)} \mathrm{PR}(e_i) \cdot \frac{W(e_i \rightarrow e_j)}{\sum\limits_k W(e_i \rightarrow e_k)} $$

• 最终综合评分（四因子加权）：

$$ S(e) = \alpha \cdot \mathrm{PR}(e) + \beta \cdot \mathrm{Sim}(Q, e) + \gamma \cdot \mathrm{EntityScore}(e) + \delta \cdot \mathrm{TimeDecay}(e) $$

其中典型配置：α=0.4，β=0.3，γ=0.2，δ=0.1。

• 🌐 官网：https://zleap.ai
• 💬 Discord：加入讨论
• 📧 邮箱：[email protected]
• 🐦 Twitter：@ZleapAI

# 1. Fork并克隆
git clone https://github.com/your-name/SAG.git

# 2. 创建分支
git checkout -b feature/amazing-feature

# 3. 提交更改
git commit -m "feat: add amazing feature"

# 4. 推送
git push origin feature/amazing-feature

# 5. 开启 Pull Request

Commit规范：feat: | fix: | docs: | refactor: | test: | chore:

• 感谢所有贡献者
• 特别感谢302.AI的算力支持

本项目采用 Apache-2.0 License