HyperGraphRAG：超图结构知识表示的检索增强生成框架

想象一下，当你向一个医疗问答系统提问"老年体弱患者的收缩压控制目标是否应该定在 120-129 mmHg？这项建议的证据有多强？"——传统 RAG 只能从海量文档中捞出零散的段落，但HyperGraphRAG 却能构建一张由实体、关系和超关系交织而成的知识网络，精准地把问题映射到正确的知识子图，生成有理有据的完整答案。这就是 2025 年 NeurIPS 最新录用论文背后的核心框架。

一、背景：为什么传统 GraphRAG 遇到了瓶颈？

GraphRAG（基于知识图谱的检索增强生成）是近两年 RAG 赛道最热门的方向之一。微软的 GraphRAG 通过预先生成实体摘要图，显著提升了复杂问答的全面性；LightRAG 则引入了双向检索机制。但这些方案都面临一个根本性限制：它们基于传统二部图（节点-边）结构，表达能力有上限。

现实世界中的知识关系远比"实体 A —关系— 实体 B"复杂得多。例如，"药物 A 与药物 B 联合使用对癌症 C 患者的疗效"这个知识，需要横跨多个层级、多类实体的联合表示才能完整表达。在二部图中，跨文档的多跳推理容易产生信息碎片化，召回的上下文缺乏全局连通性，导致生成结果顾此失彼。

HyperGraphRAG 由北京邮电大学、华为诺亚方舟实验室、新加坡国立大学等机构联合提出，发表在 NeurIPS 2025（CCF-A）。它首次将超图（Hypergraph） 结构引入 RAG 领域，用超边（Hyper-edge）替代传统边，实现了对多元、高阶知识关系的高效建模。

二、核心原理：超图如何重塑知识表示

2.1 从二部图到超图

传统知识图谱中，一条边只能连接两个实体。但在 HyperGraphRAG 中，超边可以同时连接任意数量的节点，形成"知识胶囊"。打个比方：二部图像是乐高积木，每块只能和相邻两块拼接；超图则像是榫卯结构，一个榫头可以和多个卯眼咬合，表达更丰富的关系。

在知识抽取阶段，HyperGraphRAG 通过 LLM Prompt 引导，同时识别：

• 实体节点（Entity）：具有唯一标识的知识单元，附带类型和权重
• 超关系（Hyper-relation）：连接多个实体的语义关系，包含描述文本和置信权重
• 属性片段（Attribute）：实体的特征描述

2.2 三大查询模式

HyperGraphRAG 支持四种查询模式，通过 QueryParam 配置：

• Local Query（局部查询）：根据实体相似性召回相关节点，适合"某实体有哪些关联"类型的问题
• Global Query（全局查询）：基于社区检测算法（利用 graspologic 的 Leiden 社区检测），在大尺度知识超图中定位全局主题
• Hybrid Query（混合查询）：同时融合局部和全局检索结果，是最通用的模式
• Naive Query（朴素查询）：直接向量检索，不走图结构，作为对比基线

查询时，系统会根据模式动态分配 token 预算，将检索到的超图子结构压缩后填入 prompt，最大程度利用 LLM 的上下文窗口。

三、架构设计与代码实现

3.1 模块化存储层

HyperGraphRAG 的存储层设计高度解耦，定义了三个抽象基类：

存储类型	基类	默认实现	可扩展至
向量存储	BaseVectorStorage	NanoVectorDBStorage	Milvus、Chroma、TiDB Vector
KV 存储	BaseKVStorage	JsonKVStorage	MongoDB、Oracle KV、TiDB KV
图存储	BaseGraphStorage	NetworkXStorage	Neo4j（内置实现）

通过 lazy_external_import 机制，所有扩展存储都是按需加载，避免了不必要的依赖。例如，若用户配置 vector_storage="MilvusVectorDBStorge"，才会真正导入 pymilvus 模块。

3.2 异步 LLM 调用

llm.py 模块是整个框架的核心依赖层，设计上非常务实：

• 多 LLM Provider 支持：OpenAI（含 Azure 变体）、Ollama（本地模型）、HuggingFace Transformers
• 自动重试机制：通过 Tenacity 库实现指数退避重试，对 RateLimitError、APIConnectionError、Timeout 自动恢复
• Embedding 缓存：可选的语义缓存，相似度超过阈值时直接复用已有向量
• Base64 图片支持：支持 GPT-4o 的 vision 能力，可处理图片输入

3.3 知识抽取流程

知识抽取是整个 Pipeline 资源消耗最高的环节。operate.py 中的 chunking_by_token_size 函数使用 Tiktoken 按 token 分块，默认每块 1200 tokens、重叠 100 tokens。LLM 抽取后，结果通过 compute_mdhash_id 生成唯一哈希 ID，统一存入 KV 存储和向量存储。

3.4 评估模块

evaluation/ 目录包含完整的评估脚本，对标标准 RAG、HyDE、Query2Doc 等基线方法，通过 get_score.py 计算上下文召回、F1、实体覆盖等指标。

四、快速上手

4.1 安装

conda create -n hypergraphrag python=3.11
conda activate hypergraphrag
pip install -r requirements.txt

依赖包含 PyTorch 2.3.0（CUDA 支持）、transformers、ollama、neo4j、pymongo、pymilvus 等核心库。注意：不强制要求 GPU，但使用 LLM 推理时 GPU 能显著加速。

4.2 构建知识超图

import os, json
from hypergraphrag import HyperGraphRAG

os.environ["OPENAI_API_KEY"] = "your_openai_api_key"
rag = HyperGraphRAG(working_dir="expr/example")

with open("example_contexts.json") as f:
    contexts = json.load(f)

rag.insert(contexts)  # 构建知识超图

4.3 执行查询

from hypergraphrag import HyperGraphRAG

rag = HyperGraphRAG(working_dir="expr/example")
query = "老年体弱患者的收缩压目标 120-129 mmHg 证据充分吗？"
result = rag.query(query, mode="hybrid")
print(result)

4.4 自定义存储后端

如需切换到 Neo4j 图数据库：

rag = HyperGraphRAG(
    working_dir="expr/neo4j_example",
    graph_storage="Neo4JStorage",
    kv_storage="Neo4JStorage"
)
# 需配置 NEO4J_URI, NEO4J_USER, NEO4J_PASSWORD 环境变量

五、局限性与挑战

HyperGraphRAG 并非银弹，实际使用中有几个值得关注的限制：

1. 依赖 LLM 进行知识抽取：每个文档 chunk 都需要调用 LLM 抽取实体和超关系，成本不低。对于百万级文档集，建图时间可能达到小时级。

2. 存储空间随知识库规模线性增长：超图中的节点和超边会持久化为 JSON 文件，大型知识库的文件 I/O 可能成为瓶颈。虽然支持切换到 Neo4j、MongoDB 等外部数据库，但这增加了运维复杂度。

3. 查询模式选择依赖经验：Local/Global/Hybrid 三种模式各有适用场景，目前系统没有自动判断最佳模式的机制，需要用户对查询意图有预判。

4. 图片资源代理不可达：仓库中提供了 F1.png 等架构图用于说明超图结构，但在部分网络环境下无法正常加载，对文档可读性有一定影响。

六、行业意义与展望

HyperGraphRAG 的价值不仅在于算法本身，更在于它打开了一个新的研究方向——超图与 LLM 的深度融合。NeurIPS 2025 的录用证明了学术界对这一方向的认可。

从工程角度看，该项目有以下几点值得关注：

• 存储层抽象优秀：三个基类的设计让扩展新存储后端变得简单，有助于推动 HyperGraphRAG 在企业场景落地
• 异步设计完善：全链路 async/await，对高并发场景友好
• 依赖管理务实：虽然 requirements.txt 很长，但通过 lazy import 机制，不使用 Neo4j 就无需安装 neo4j 驱动

展望未来，随着知识图谱规模的持续膨胀，传统二部图结构将越来越难以承载复杂的多跳推理需求。HyperGraphRAG 提供了一种优雅的升级路径，值得 AI 研究者和工程师重点关注。