Zleap-AI/SAG · 上手攻略

  • 仓库：Zleap-AI/SAG
  • 链接：https://github.com/Zleap-AI/SAG
  • 分类：AI 工程 / RAG 架构
  • 作者：Jay
  • 更新：2026-10-02

这是什么

SAG（SQL-Retrieval Augmented Generation）是 Zleap-AI 提出的一种全新检索架构，不是对传统 dense RAG 和 GraphRAG 的缝合，而是用事件-实体索引 + 查询时动态超边（hyperedge）的原生设计，在语义检索和关系推理上合二为一。

SAG 同时也是一个完整的知识库应用（桌面 + Docker 部署），支持文档上传、语义搜索、知识图谱探索、带引用的 Agent 对话、REST API、MCP 接口和 Python SDK。arXiv 论文：https://arxiv.org/abs/2606.15971

解决什么问题

传统 RAG 的核心局限：按语义相似性检索 chunk，关系推理能力弱。GraphRAG 试图弥补，但代价是离线图构建（三元组抽取、实体合并、关系归一化、全局维护），且增量更新困难。

SAG 的设计哲学：语义路径和结构路径是 SAG 内部原生的两部分，不是两个独立系统并排运行：

  • chunk → 一个语义完整的事件（event）：事件保留 chunk 的完整语义，不像 GraphRAG 那样碎成独立三元组
  • chunk → 多个索引实体（entity）：实体是轻量索引和扩展点，不替代事件语义
  • event ↔ entities → 一个潜在超边（latent hyperedge）：查询时通过 SQL join 动态生成，不预建、不全局维护
  • 原始证据始终是输出边界：选中的事件始终回溯到源 chunk，供生成和引用

快速安装

桌面应用（最简路径，无需编程）

下载对应平台的最新安装程序：https://github.com/Zleap-AI/SAG/releases

平台 安装包 注意
macOS 15+，Apple Silicon SAG-*-mac-arm64.dmg 签名并公证；应用内更新需手动下载确认
Windows 10/11, x64 SAG-Setup-*-win-x64.exe 暂无签名；Windows 会提示未知发布者

⚠️ 首次启动若检测到不兼容的旧版知识数据，SAG 会保留旧数据不动，等待用户确认备份和新工作区，不会自动迁移。

Docker 部署（推荐开发者路径）

依赖：Docker Desktop，或 Docker Engine + Compose v2。

git clone https://github.com/Zleap-AI/SAG.git
cd SAG
docker compose up -d --build

启动后访问： - Web 应用：http://localhost:3000 - API 文档：http://localhost:8000/docs

⚠️ 无需 API key、Python 运行时、Node 运行时或外部数据库即可启动应用。配置 LLM 和 embedding 模型后才可进行语义索引和生成。

初始配置（首次启动后）

  1. 输入名称创建本地身份
  2. 使用 302.AI 快速配置，或打开 Settings → Models 配置 OpenAI 兼容的 LLM 和 embedding 端点
  3. 创建 Source，上传文档，等待状态变为 Ready
  4. 开始搜索或对话

环境变量配置（Docker / .env）

变量 作用
SAG_LLM_* 初始 LLM 配置（模型、API key、端点）
SAG_LOCK_LLM_CONFIG=true 锁定配置，强制使用 env 中的值，Settings UI 中生成字段显示为锁定状态

配置保存后，API 容器重启自动使用持久化配置，无需手动重启。

核心用法

文档上传与索引

SAG 支持 Markdown、text、PDF、Office 等格式：

  • PDF：优先使用 MinerU，失败时回退到 MarkItDown
  • Office / text：默认使用 MarkItDown

上传后 SAG 自动执行： 1. 文档规范化到 Markdown 2. chunking（语义分块） 3. embedding（向量化） 4. 事件（event）抽取 5. 实体（entity）抽取 6. 关联存储（SQLite/LanceDB + 向量/全文索引）

搜索

两种检索模式： - Fast（向量）：语义相似性优先，速度快 - Precise（多路）：多路召回 + 重排序，精度高

支持全局搜索或限定 source 范围。搜索结果可一键展开原文块（original chunk），检索质量可审计。

知识图谱探索

切换 source 视图为 graph view，可视化事件、实体及其关联。每个 chunk 在图中生成一个 event node 和多个 entity nodes，hyperedge 连接关系在查询时动态生成。

Explore 模式可遍历整个知识库的事件-实体关系网络，无需离开当前视图即可打开任意事件的原始来源。

Agent 对话（带引用）

内置 Agent 默认绑定指定 source，回复流式输出，每条回复附可点击的引用（citations），点击跳转到对应原文块。⚠️ LLM 未配置时 Agent 功能不可用。

REST API / OpenAI 兼容端点

# OpenAI-compatible chat completions
curl -s http://localhost:8000/api/v1/openai/<AGENT_ID>/chat/completions \
  -H "Authorization: Bearer <SAG_JWT>" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"What is this material about?"}]}'

返回标准 chat.completion 格式，额外携带 sag.citations 字段供引用展示。标准客户端忽略未知字段。

MCP 接口（Agent 集成推荐路径）

# 安装 CLI（Node.js ≥ 20.19）
npm install --global @zleap-ai/sag-cli

# 验证 MCP 连通性
sag mcp test

# 连接到 Codex
sag agent connect codex

# 或 Claude Code
sag agent connect claude-code

# 查看连接状态
sag agent status

MCP 配置流程： 1. sag mcp test 验证 SAG MCP 可达 2. sag agent connect <client> 一键挂载 3. 若无 Node.js，在 SAG Web UI Settings → Integrations → Knowledge MCP 获取配置片段，手动粘贴到 Agent MCP 配置

⚠️ CLI 不将 JWT 写入 Agent 配置文件，token 存 OS keychain（可用时），只删除自己创建的 MCP 条目。--dry-run 可预览所有写操作。

Dify 集成

SAG 提供专用兼容端点，可连接 Dify 的「连接外部知识库」功能，无需修改 Dify 源码。详见 docs/dify-integration.en.md。

典型适用场景

  1. 个人知识管理：上传论文、笔记、文档，用自然语言提问并获取带引用的答案
  2. 团队知识库：Docker 部署在内部服务器，多人通过 Web 或 API 访问同一知识库
  3. AI Agent 的外部记忆：通过 MCP 或 REST API 给 Agent 提供可溯源的知识检索能力
  4. 多跳推理问答：基于 HotpotQA、2WikiMultiHopQA、MuSiQue 等多跳数据集验证，SAG 在这类场景显著优于 dense RAG 和 GraphRAG
  5. 复杂文档分析：PDF/Office 文档的深层挖掘，支持事件-实体图谱可视化

坑与注意

⚠️ v1.18.11 时格式迁移注意：检测到不兼容旧版知识数据时会停止，等待用户手动确认备份路径；新安装不携带旧数据，upload 文档后知识库为空，需重新上传。

⚠️ Embedding 模型必须配置：向量索引依赖 embedding 模型，未配置时上传文档无法完成索引，但 chunk 和原文仍然存储。

⚠️ LLM 必须配置：事件抽取、查询理解、生成回答依赖 LLM，未配置时 Agent 对话不可用。

⚠️ 增量更新是 SAG 优势：新增 chunk 时只追加自己的 event、entities 和 associations，不触发全局图重建——这是相对于 GraphRAG 的重要工程优势。

⚠️ 单用户本地优先设计：产品设计为单用户本地优先；多人共享需要通过 REST API 自建权限层（当前未内置）。

⚠️ PostgreSQL 需手动配置：默认使用 SQLite + LanceDB；生产级别高并发场景需要切换到 PostgreSQL + pgvector，详见 docker compose override 配置。

与同类对比

方案 索引方式 推理能力 增量更新 部署复杂度
SAG event-entity + 动态 hyperedge 语义 + 关系（原生） 原生增量 Docker 单容器
Dense RAG（BGE+向量检索） 向量 chunk 纯语义 需重建索引 简单
GraphRAG（Microsoft） 离线图（三元组） 关系强 图重建代价高 复杂（多组件）
HippoRAG 开放式知识图谱 关系推理 尚待验证 中等

SAG 在 HotpotQA / 2WikiMultiHopQA / MuSiQue 三个标准多跳数据集上 Recall@5 / F1 均优于最强基线 6.79 / 4.33 个百分点（平均）；MuSiQue 上领先 11.52 / 7.01 个百分点（最显著）。

⚠️ 注：以上基准数据来自论文，测试配置为 BGE-Large-EN-v1.5 embedding + Qwen3.6-Flash LLM；换用其他模型组合结果可能不同。

一句话推荐结论

如果你需要在一个系统里同时搞定语义检索和多跳关系推理，且希望增量更新自然、不维护两套系统，SAG 是当前开源方案里架构最干净、benchmark 表现最强的那一个——尤其是多跳问答场景，强烈建议试用 Docker 快速上手体验。