youtu-graphrag
腾讯云 ADP 开源的 GraphRAG + Agent 统一推理框架，通过 Schema 约束和层
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
腾讯云 ADP 开源的 GraphRAG + Agent 统一推理框架，通过 Schema 约束和层
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
当你需要在一堆企业文档、私域知识库，甚至几千篇学术论文中回答一个需要跨多个知识点才能推导出来的复杂问题时，传统的 RAG（检索增强生成）往往会"顾此失彼"——要么检索不到足够的上下文，要么返回的片段之间缺乏逻辑连贯性，导致大模型给出的答案似是而非。
Youtu-GraphRAG（ICLR 2026 接收论文）正是为解决这一痛点而生。它由腾讯云智能体平台（ADP）团队研发，将"图"的结构化知识组织能力与"智能体"的多步推理能力深度融合，用图 Schema 引导知识抽取，用层次化社区检测压缩检索空间，用问题分解器将复杂查询拆解为可并行的子查询——最终在 Token 消耗降低 33.6% 的同时，精度提升 16.62%。
图1：Youtu-GraphRAG 框架概览 — 展示了从文档输入到答案输出的完整 Pipeline
传统 GraphRAG 的核心思路是：先从文档中提取实体和关系构建知识图谱，再通过社区检测将图谱划分为若干子图社区，查询时检索相关社区并生成答案。这一范式相比纯向量检索已经大幅提升了多跳问答的效果，但在实际落地中仍存在三个关键瓶颈：
第一，知识抽取缺乏约束。通用 GraphRAG 使用开放域抽取，不管什么类型的文档都用同一套实体关系体系，导致抽取质量参差不齐，图中噪声实体泛滥。
第二，社区检测过于粗糙。Leiden/Louvain 等经典社区算法只考虑图的拓扑结构，完全忽略社区内节点的语义相似性，导致语义相近的节点被拆分到不同社区，而语义相异的节点却被强行归并。
第三，问题检索缺乏规划。用户输入一个复杂问题后，系统直接在整个图上做向量相似度检索，没有先"理解问题要查什么"，也没有将问题分解为多个子查询并行执行。
Youtu-GraphRAG 正是针对这三个问题，给出了一套系统性的解决方案。
Youtu-GraphRAG 的整体架构分为知识构建和知识检索两大阶段，每一阶段内部又包含多个精心设计的子模块。
知识构建阶段的核心模块是 KTBuilder（Knowledge Tree Builder），负责将原始文档转化为结构化的层次化知识树。构建过程分四步：
文本分块（Chunking）：使用 tiktoken 的 cl100k_base 分词器按 Token 数量切分文本，默认块大小 5000 Token、重叠 200 Token。分块策略可通过 config/base_config.yaml 动态调整。
Schema 引导的知识抽取：这是 Youtu-GraphRAG 区别于通用 GraphRAG 的核心创新点。与开放抽取不同，系统引入了领域 Schema（预定义的实体类型、关系类型和属性类型集合），LLM 智能体在抽取时受到 Schema 约束，只提取符合 Schema 定义的节点和边。Schema 以 JSON 文件形式存放于 schemas/ 目录，内置了 demo、hotpotqa、2wiki、musique、graphrag-bench、anony_chs（中文匿名）、anony_eng（英文匿名）等多种数据集的 Schema。这种设计使得跨领域迁移时，只需准备目标领域的 Schema 文件，几乎不需要改代码。
三层索引：对抽取出的节点和文本块，分别构建：
tree_comm 模块）：基于 all-MiniLM-L6-v2 句子嵌入模型，为每个节点/块生成向量，存入 FAISS 索引，支持快速相似度检索。四层知识树结构：最终输出到 output/graphs/ 目录，包含：
图2：层次化社区检测 — 融合结构拓扑与语义相似性的社区划分，效果优于 Leiden/Louvain
检索阶段的核心是 agentic_decomposer（智能体问题分解器）和 enhanced_kt_retriever（增强知识树检索器）两个模块，协作流程如下：
问题分解（Decompose）：用户输入复杂问题后，GraphQ 类先读取当前数据集对应的 Schema，然后调用 LLM 将问题分解为 2-3 个子问题，每个子问题：
并行检索（Retrieve）：分解后的子问题并行执行检索：
迭代反思（Reflect）：若初步检索结果不足以回答某个子问题，触发二次检索循环：基于中间答案生成新的检索 query，再次在图中检索，直到结果收敛或达到最大迭代次数。
答案生成（Generate）：汇总所有子问题的检索结果，调用 LLM 生成最终答案，同时输出推理轨迹（sub_questions、retrieved_triples、reasoning_steps）供用户追溯。
图3：Agentic 问题分解 — 复杂问题被拆解为多个可独立并行处理的子问题
从代码结构看，Youtu-GraphRAG 的技术栈非常清晰：
| 层次 | 技术选型 |
|---|---|
| Web 框架 | FastAPI + uvicorn，支持 REST + WebSocket |
| LLM 调用 | OpenAI API 兼容接口（call_llm_api），可切换为 vLLM 等 |
| 嵌入模型 | sentence-transformers（默认 all-MiniLM-L6-v2） |
| 图结构 | NetworkX（MultiDiGraph），输出兼容 Neo4j 导入格式 |
| 向量检索 | FAISS-CPU |
| NLP 处理 | spaCy（en_core_web_lg）用于命名实体识别 |
| 文档解析 | Magic-PDF（layout detection）、python-docx、PyPDF、Tika（通用解析器） |
| 知识抽取 | 大模型 + JSON Schema 约束 + json-repair 纠错 |
代码组织：模块化程度较高，models/ 下分 constructor（知识构建）和 retriever（知识检索），utils/ 下包含日志、LLM 调用、文档解析、图处理等工具函数。配置层通过 config/base_config.yaml 集中管理所有参数。代码有基本的单元测试框架，整体风格偏向工程落地而非学术原型。
文档质量：极为优秀——提供了英文、中文、日文三种语言的 README，以及详细的 FULLGUIDE-CN.md 完整使用指南，涵盖从环境配置、数据准备到模型微调的每一步操作说明。
项目在 HuggingFace 上公开了匿名公平数据集 AnonyRAG（防范预训练数据泄露），包含 6 个跨领域多语言基准：
| 数据集 | 描述 | 特点 |
|---|---|---|
| HotpotQA | 多跳问答 | 2-hop 问答基准 |
| 2WikiMultiHopQA | 多跳问答 | 需要多步推理的复杂问题 |
| MuSiQue | 多跳问答 | 更深层次的多跳问题 |
| GraphRAG-Bench | GraphRAG 评测 | 专为本项目设计的评测集 |
| Anony-CHS | 中文匿名数据集 | 中文多跳问答 |
| Anony-ENG | 英文匿名数据集 | 英文多跳问答 |
在 Token 成本降低 33.6% 的同时精度提升 16.62%，且在 Pareto 前沿上实现了两者兼得，这说明通过 Schema 约束减少无效检索+结构化社区压缩搜索空间的组合策略是有效的。
图4：性能对比 — Youtu-GraphRAG 在精度和 Token 消耗上均优于主流方案
图5：Pareto 前沿分析 — 同时实现精度提升与成本降低
快速上手：提供了 Docker 支持，一条命令构建镜像并启动后端服务。内置 demo 数据集，无需额外准备数据即可体验完整流程。通过 backend.py 提供的 Web UI 支持文件上传（构建知识图谱）和问答交互（多跳推理），WebSocket 实时推送构建进度。
硬件需求：CPU 模式即可运行（嵌入模型 all-MiniLM-L6-v2 非常轻量），但处理大规模文档时建议 8GB+ 内存。生产环境建议 GPU 加速（torch 依赖已包含 CUDA 支持）。
主要依赖：Python 3.10+、Java（Apache Tika 解析 WPS/旧格式文档需要 JRE）、spaCy 英语模型（en_core_web_lg，约 700MB）。配置文件 .env.example 指导设置 API Key。
第一，Schema 工程是核心门槛。虽然文档宣称"最小化人工干预即可跨领域迁移"，但真正要将 Youtu-GraphRAG 部署到新领域，仍然需要领域专家精心设计 Schema——定义哪些实体类型、关系类型、属性类型。Schema 设计的质量直接决定了知识抽取和检索的效果，这一工作并不简单。
第二，LLM API 成本不可忽视。知识构建阶段需要对每个文本块调用 LLM 抽取实体关系，在大规模语料上成本可观。代码支持 max_workers=32 并行加速，但最终仍受 API Rate Limit 和成本约束。
第三，中文支持依赖高质量 Schema。内置的 anony_chs 数据集说明团队确实考虑了中文场景，但通用中文 NLP（实体识别、指代消解）的质量仍受限于 spaCy 对中文支持的不足。
第四，实时更新场景待优化。当前架构面向离线批量构建知识树（KTBuilder），对于需要实时增量更新的场景（图谱动态更新、增量索引），目前没有成熟方案。
GraphRAG 赛道从 2024 年兴起至今，经历了从"图谱辅助检索"到"智能体检索"的演进。Youtu-GraphRAG 代表了其中一个重要的技术方向：用 Schema 约束代替自由抽取，用结构感知代替纯向量相似度，用问题分解代替直接检索。它不只是一个开源工具，更是 ICLR 2026 论文的官方实现，其核心创新已在腾讯云 ADP 平台产品化落地。
对于企业知识库建设者而言，Youtu-GraphRAG 提供了一条在私有化部署环境下构建高质量多跳问答系统的可行路径，Schema 设计工作量虽不可省，但相比 Fine-tuning 一个专属模型，其成本和周期可控得多。对于AI 开发者而言，这套代码库是学习 GraphRAG 全链路实现的绝佳参考。