{"id":50718199,"url":"https://github.com/Zleap-AI/SAG","last_synced_at":"2026-06-26T22:00:41.645Z","repository":{"id":324690522,"uuid":"1091563845","full_name":"Zleap-AI/SAG","owner":"Zleap-AI","description":"An document retrieval project built on SAG","archived":false,"fork":false,"pushed_at":"2026-06-26T10:28:55.000Z","size":39007,"stargazers_count":1674,"open_issues_count":2,"forks_count":68,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-26T12:12:47.340Z","etag":null,"topics":["agent","ai","data-engineering","graphrag","knowledge-base","knowledge-graph","knowledge-graphs","llm","rag","sag","vector-search"],"latest_commit_sha":null,"homepage":"https://zleap.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Zleap-AI.png","metadata":{"files":{"readme":"README-CN.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-07T07:33:35.000Z","updated_at":"2026-06-26T12:01:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Zleap-AI/SAG","commit_stats":null,"previous_names":["zleap-ai/sag"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Zleap-AI/SAG","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zleap-AI%2FSAG","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zleap-AI%2FSAG/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zleap-AI%2FSAG/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zleap-AI%2FSAG/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Zleap-AI","download_url":"https://codeload.github.com/Zleap-AI/SAG/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zleap-AI%2FSAG/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34834415,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-26T02:00:06.560Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","ai","data-engineering","graphrag","knowledge-base","knowledge-graph","knowledge-graphs","llm","rag","sag","vector-search"],"created_at":"2026-06-09T21:00:25.964Z","updated_at":"2026-06-26T22:00:41.635Z","avatar_url":"https://github.com/Zleap-AI.png","language":"TypeScript","funding_links":[],"categories":["Model Serving \u0026 Inference","*Ops for AI"],"sub_categories":["Vector Databases \u0026 Retrieval Infrastructure","Model Serving \u0026 Inference"],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/logo.svg\" alt=\"Zleap AI\" width=\"220\" /\u003e\n\u003c/p\u003e\n\n# SAG\n\n**语言**：简体中文 | [English](README.md)\n\n\u003e **SAG:** 可以在大规模动态数据上运行的图谱检索技术\n\u003e \n\u003e **Paper:** [https://arxiv.org/abs/2606.15971](https://arxiv.org/abs/2606.15971)\n\n本项目是基于 SAG 制作的开箱即用的文档检索工作台：上传 Markdown / TXT 文档后，系统会自动完成切片、向量化、事项提取、实体提取和关系整理。你可以像使用 ChatGPT 一样围绕项目资料连续提问，也可以查看每个文档的切片、事项、实体、Embedding、搜索过程、原始模型日志和知识图谱。\n\n![SAG 对话工作台](docs/assets/sag-chat.png)\n\n## RAG 领域新 SOTA\n\n论文复现代码：[Zleap-AI/SAG-Benchmark](https://github.com/Zleap-AI/SAG-Benchmark)\n\nSAG 是面向 Agent 的新一代 RAG 技术路线。它不靠给模型塞更多 chunk，而是用更轻量的结构重新组织文档知识：\n\n```text\nchunk -\u003e event\nchunk -\u003e entities\nevent \u003c-\u003e entities\n```\n\n每个 chunk 提取一个完整事项 event 和多个 entities。event 保留完整语义，entities 负责索引和关系扩展，让检索可以从命中事项出发继续多跳召回，同时避免重型知识图谱的全局重建成本。\n\n![SAG 架构图](docs/assets/paper-sag-architecture.jpeg)\n\n在 HotpotQA / 2WikiMultiHop / MuSiQue 上，使用相同配置：\n\n```text\nEmbedding = bge-large-en-v1.5\nLLM = qwen3.6-flash\nDatasets = HotpotQA / 2WikiMultiHop / MuSiQue\n```\n\nSAG 对比 HippoRAG 2 在多跳问答召回上取得了明显提升：**平均 Recall@2 从 68.14% 提升到 79.30%，提升 11.16 个百分点，相对提升约 16.4%**。Recall@2 更高意味着 Agent 可以用更少上下文更早命中关键证据，减少 token 成本、延迟和多轮任务里的干扰。\n\n![SAG Benchmark 简图](docs/assets/sag-benchmark-simple.png)\n\n在 MuSiQue Recall@5 上，SAG 从 HippoRAG 2 的 65.13% 提升到 80.04%；换用 NV-Embed-v2 后进一步达到 81.71%，说明收益主要来自结构设计，而不只是更强的 embedding 模型。\n\n## SAG 能做什么\n\n这个项目把 SAG 技术做成了一个可以直接运行的本地工作台，适合：\n\n- 项目文档问答\n- 个人知识库检索\n- RAG / Agent 原型验证\n- 文档事项和实体分析\n- MCP 工具接入测试\n- 检索链路调试和模型调用观察\n\n核心功能：\n\n- **项目管理**：每个项目拥有自己的文档、对话、图谱和 MCP 配置。\n- **多文档上传**：支持一次上传多个 Markdown / TXT 文档，展示处理阶段和进度。\n- **文档处理结果**：查看切片、事项、实体、Embedding 数据，支持标题关键字搜索和分页浏览。\n- **对话式检索**：围绕当前项目资料多轮提问，支持流式输出和停止生成。\n- **引用原文**：回答里可以显示引用序号，点击查看对应原文块。\n- **搜索过程可视化**：右侧面板实时展示 SAG 内部检索链路和耗时。\n- **原始日志**：浏览器缓存中可查看 LLM / Embedding / Rerank 原始请求和返回。\n- **知识图谱**：以实体和事项为节点查看项目关系，可拖动、缩放、展开和查看详情。\n- **MCP 接入**：每个项目都有自己的 MCP 配置，外部 Agent 可直接调用当前项目资料。\n\n## 技术栈\n\nSAG 使用 TypeScript 贯穿前后端。前端是 React + Vite + Tailwind CSS 的 WebUI；后端是 Fastify HTTP API、MCP TypeScript SDK 和分层服务模块；数据层使用 PostgreSQL、pgvector、全文检索和 SQL 多跳查询；模型侧兼容 OpenAI-compatible 的 LLM、Embedding 和 Rerank 接口。\n\n## 工作台预览\n\n### 文档处理\n\n在「文档」页可以上传文档，查看处理状态、切片、事项、实体和 Embedding。\n\n![SAG 文档视图](docs/assets/sag-documents.png)\n\n### 图谱浏览\n\n在「图谱」页可以查看项目内实体和事项关系。节点可以拖动、缩放，点击展开，双击打开详情。\n\n![SAG 图谱视图](docs/assets/sag-graph.png)\n\n### 对话检索\n\n在「对话」页可以围绕当前项目资料连续提问。每次检索都会刷新右侧搜索过程，方便调试本轮调用链路。\n\n## 检索模式\n\nSAG 提供两种模式：\n\n- **极速模式**：直接用 query 在实体库做全文 / BM25 匹配，结合 SAG 多跳扩展，最后用 `qwen3-rerank` 选择 top-k。这个模式不需要 LLM 抽 query 实体，也不需要 LLM 过滤候选，速度更快。\n- **标准模式**：用 LLM 抽取 query 实体，再走 SAG 多路召回和 LLM 精排，适合对比更高精度链路。\n\n两种模式都不是普通向量搜索，因为它们都使用 SAG 的 event/entity 索引和 SQL 多跳扩展。\n\n## 快速开始\n\n### 1. 准备环境\n\n你需要：\n\n- Node.js 20 或更高版本\n- npm\n- PostgreSQL\n- pgvector\n\n如果你只是想最快跑起来，推荐用 Docker 启动 PostgreSQL。\n\n### 2. 克隆项目\n\n```bash\ngit clone https://github.com/Zleap-AI/SAG.git\ncd SAG\n```\n\n### 3. 创建配置文件\n\n```bash\ncp .env.example .env\n```\n\n`.env.example` 已经包含默认配置。真实使用时，请填入自己的 LLM 和 Embedding API Key。\n\n### 4. 启动 PostgreSQL\n\n使用 Docker：\n\n```bash\ndocker compose up -d\n```\n\n不想用 Docker，也可以在 macOS 上用 Homebrew：\n\n```bash\nbrew install postgresql@17 pgvector\nbrew services start postgresql@17\n\n/opt/homebrew/opt/postgresql@17/bin/createdb sag_lite\n/opt/homebrew/opt/postgresql@17/bin/psql -d sag_lite -c 'create extension if not exists vector;'\n```\n\n如果你使用本机 PostgreSQL，请把 `.env` 里的 `DATABASE_URL` 改成自己的连接地址，例如：\n\n```env\nDATABASE_URL=postgres://你的用户名@localhost:5432/sag_lite\n```\n\n### 5. 安装依赖并初始化数据库\n\n```bash\nnpm install\nnpm run db:setup\n```\n\n### 6. 启动开发服务\n\n```bash\nnpm run dev\n```\n\n开发模式默认地址：\n\n```text\nWebUI: http://localhost:5173\nAPI:   http://localhost:4173\n```\n\n### 7. 构建并启动生产服务\n\n```bash\nnpm run build\nnpm start\n```\n\n生产模式默认地址：\n\n```text\nhttp://localhost:4173\n```\n\n## 第一次怎么用\n\n1. 打开 WebUI。\n2. 在左侧项目列表顶部点击「新建项目」。\n3. 进入「文档」页，点击「添加文档」。\n4. 上传 `.md` 或 `.txt` 文件。\n5. 等待处理队列完成。\n6. 查看切片、事项、实体和 Embedding 状态。\n7. 回到「对话」页，围绕当前项目资料提问。\n8. 需要调试时，查看右侧「搜索过程」和「原始日志」。\n9. 需要看关系时，进入「图谱」页。\n10. 需要给外部 Agent 使用时，进入「MCP」页复制当前项目的配置。\n\n## 配置 LLM 和 Embedding\n\nSAG 支持 OpenAI-compatible 接口。默认示例：\n\n```env\nEMBEDDING_BASE_URL=https://api.302ai.cn/v1\nEMBEDDING_MODEL=text-embedding-3-large\nEMBEDDING_DIMENSIONS=1024\n\nLLM_BASE_URL=https://api.302ai.cn/v1\nLLM_MODEL=qwen3.6-flash\n\nRERANK_MODEL=qwen3-rerank\nDEFAULT_SEARCH_MODE=fast\n```\n\n你可以通过两种方式配置：\n\n### 方式一：WebUI 全局设置\n\n点击左侧顶部的设置图标，进入全局设置页，填写 provider、模型名和 API Key。\n\nAPI Key 只会显示“已配置 / 未配置”，不会在界面和接口响应里明文回显。\n\n### 方式二：`.env`\n\n```env\nEMBEDDING_API_KEY=你的_embedding_key\nLLM_API_KEY=你的_llm_key\nRERANK_BASE_URL=https://api.your-provider.com/v1/rerank\n```\n\n默认情况下，重排序请求会基于 `LLM_BASE_URL` 追加 `/reranks`，例如 `https://api.302ai.cn/v1/reranks`。只有当平台需要 `/v1/rerank` 等不同完整 endpoint 时，才配置 `RERANK_BASE_URL`。\n\n如果没有配置 API Key，系统会使用本地 deterministic fallback，方便跑测试和看界面；真实检索效果请配置远程模型。\n\n## MCP 接入\n\nSAG 可以作为 MCP Server 提供给外部 Agent 使用。每个项目的 MCP 都会绑定当前项目 ID，工具调用时不需要再传 `projectId`。\n\n在 WebUI 里进入「MCP」页，可以看到当前项目自动生成的 `mcpServers` JSON。格式类似：\n\n```json\n{\n  \"mcpServers\": {\n    \"sag\": {\n      \"command\": \"npm\",\n      \"args\": [\"run\", \"mcp\"],\n      \"env\": {\n        \"SAG_MCP_SOURCE_ID\": \"当前项目ID\"\n      }\n    }\n  }\n}\n```\n\n当前提供的 MCP 工具：\n\n- `sag_ingest_document`：导入文档并执行切片、事项抽取、实体抽取和向量化。\n- `sag_search`：对当前项目执行 SAG 多路检索，并返回内部检索 trace。\n- `sag_explain_search`：返回当前项目的检索链路说明和 trace。\n- `sag_get_event`：按事件 ID 查询事件详情。\n\n## HTTP API 示例\n\n健康检查：\n\n```bash\ncurl http://localhost:4173/health\n```\n\n创建项目：\n\n```bash\ncurl -X POST http://localhost:4173/api/projects \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"name\":\"Demo 项目\"}'\n```\n\n写入文档：\n\n```bash\ncurl -X POST http://localhost:4173/ingest \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"sourceId\":\"项目ID\",\"title\":\"Demo\",\"content\":\"# Demo\\n\\nSAG 可以检索项目文档。\",\"extract\":true}'\n```\n\n执行检索：\n\n```bash\ncurl -X POST http://localhost:4173/api/search \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"query\":\"SAG 为什么适合多跳检索？\",\"sourceIds\":[\"项目ID\"],\"strategy\":\"multi\",\"searchMode\":\"fast\",\"topK\":5,\"returnTrace\":true}'\n```\n\n流式检索过程：\n\n```bash\ncurl -N -X POST http://localhost:4173/api/search/stream \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"query\":\"解释 SAG 的 event/entity 索引\",\"sourceIds\":[\"项目ID\"],\"strategy\":\"multi\",\"returnTrace\":true}'\n```\n\n## 常用命令\n\n```bash\n# 类型检查\nnpm run typecheck\n\n# 运行测试\nnpm test\n\n# 构建生产版本\nnpm run build\n\n# 启动生产服务\nnpm start\n\n# 启动 MCP stdio server\nnpm run mcp\n```\n\n## 项目结构\n\n```text\nsrc/\n  ai/                 LLM、Embedding、Rerank 客户端\n  api/                HTTP API\n  config/             环境配置\n  db/                 数据库连接、迁移、Repository、向量工具\n  ingestion/          文档切片和事项提取\n  mcp/                MCP Server\n  observability/      日志和模型调用记录\n  services/           文档处理、搜索、图谱、WebUI 服务\n\nweb/\n  src/                React WebUI\n\nmigrations/           PostgreSQL schema\ntest/                 单元测试\ndocs/assets/          README 截图和图示资源\n```\n\n## 常见问题\n\n### PostgreSQL 连接失败怎么办？\n\n先确认数据库已经启动：\n\n```bash\ndocker compose ps\n```\n\n再确认 `.env` 里的 `DATABASE_URL` 是否正确。\n\n### 提示 pgvector 不存在怎么办？\n\n请确认数据库安装了 pgvector，并执行过：\n\n```sql\ncreate extension if not exists vector;\n```\n\n如果使用 `docker compose up -d`，镜像已经包含 pgvector。\n\n### 为什么没有真实模型效果？\n\n如果没有配置 `LLM_API_KEY` 和 `EMBEDDING_API_KEY`，系统会进入本地 fallback 模式。这个模式适合测试，不适合判断真实检索质量。\n\n### 上传后处理很慢怎么办？\n\n文档处理会调用 Embedding 和 LLM。速度主要取决于文档数量、切片数量、模型接口速度和并发配置。可以通过 `.env` 调整：\n\n```env\nINGEST_CONCURRENCY=5\n```\n\n### 端口被占用了怎么办？\n\n开发模式可以调整 `.env`：\n\n```env\nHTTP_PORT=4173\n```\n\nVite WebUI 默认会使用 `5173`，如果端口被占用会自动提示新的地址。\n\n## License\n\nMIT License. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FZleap-AI%2FSAG","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FZleap-AI%2FSAG","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FZleap-AI%2FSAG/lists"}