企业知识库系列（04）：HyperGraphRAG 实测——超图结构的多跳推理

这篇的任务

系列走到第四篇，前三篇已经跑完了四个框架：

• QAnything v2（向量 RAG，文章 02）
• LightRAG 1.5.6（图+向量混合，文章 02）
• GraphRAG 3.1.1（LLM 驱动的知识图谱，文章 03）
• HippoRAG 2.0（海马体启发的 PPR 图扩散，文章 03）

这篇测最后一个：HyperGraphRAG 1.0.6（NeurIPS 2025）。

---

HyperGraphRAG 的核心思路

传统知识图谱的边是二元的：实体 A → 实体 B。这意味着"A、B、C 三者同时参与了某件事"这种关系，必须拆成多条二元边才能表达，而拆分过程会丢失语义。

HyperGraphRAG 用**超边（hyperedge）**解决这个问题：一条超边可以直接连接任意数量的实体。

传统图：    A → B, B → C, A → C（拆成3条边，各自独立）
超图：      {A, B, C} 被同一条超边连接（一次性保留三者关系）

从文档到超图的流程：

文档 → LLM 提取实体集合（每次提取一组相关实体，而非两两配对）
     → 构建超图（每个实体集合 = 一条超边）
     → BGE 向量化实体
     → 查询时：向量召回种子实体 → 超图扩散 → 提取相关段落 → LLM 生成答案

理论预期：在"多个实体共同参与的关系"上，超图结构应该比二元图提取更多信号。

---

部署过程

依赖安装

HyperGraphRAG 没有发布到 PyPI，只有 GitHub 源码。不能 pip install hypergraphrag，也不能 pip install -e .（没有 setup.py 或 pyproject.toml）。

实际可行方案：把源码目录加入 PYTHONPATH，然后按 README 安装依赖：

# 进入 HyperGraphRAG 源码目录
pip install -r requirements.txt   # graspologic, nano-vectordb 等

# 运行时
PYTHONPATH=/path/to/HyperGraphRAG python run_eval.py

SiliconFlow API 的两个隐藏限制

问题 1：文档内容触发内容过滤（HTTP 400，code 20015）

测试文档里有大量 .env 示例片段，类似：

EMBEDDING_MODEL=jina-embeddings-v4
EMBEDDING_BINDING=jina
EMBEDDING_ASYMMETRIC=true

这些 ALLCAPS=value 格式的行触发了 SiliconFlow 的内容安全过滤。解决：在发 embedding 请求前，用正则把含敏感格式的行替换为 [REDACTED]。

问题 2：bge-large-en-v1.5 的字符长度限制约为 512 tokens

测试发现超过约 1000 字符就 400。密集 markdown 表格（每个 | 和 % 都占一个 token）在 900 字符时同样超限。

最终设定：每条文本截断到 700 字符（按词截断），并留 10% 余量应对高密度内容。

建库过程的网络稳定性问题

GLM-4-flash 和 SiliconFlow 在长时间运行中偶发 ConnectTimeout 和 HTTP 500。

两个必要改动：

1. 把 LLM 客户端超时设为 180s，加 6 次重试（间隔 10/20/30/40/50/60s）
2. 建库改为逐文档 insert：每成功 insert 一个文档，立即写进度文件；崩溃重启后自动从断点续跑，不重复已完成的文档

没有这两个改动，443 分钟的建库很难一次跑完。

---

评测结果

数字

指标	HyperGraphRAG 1.0.6
建库时间	443.2 min
边界拒答率	26.3%
P90 延迟	49.3 s
平均延迟	29.6 s
单跳匹配	0.081
多跳匹配	0.171
边界匹配	0.021

答案匹配使用 Jaccard 关键词重叠，不是 LLM judge；LLM 全程 GLM-4-flash

多跳：0.171，和 LightRAG 几乎持平

超图结构的理论优势并没有在这次评测里体现。0.171 vs LightRAG 的 0.178，差距在误差范围内。

几个可能的原因：

• 本次测试文档是技术文档（配置手册、API 说明），文档内关系主要是单一实体的描述，真正的"多实体共同参与"关系不多------这是超边最能发挥优势的场景，但在这类文档里出现频率低
• 超边提取依赖 LLM，GLM-4-flash 的提取质量影响图结构质量
• BGE 截断到 700 字符可能损失了部分语义信息

建库时间：443 分钟，是系列最慢

GraphRAG 建库 31 分钟，HippoRAG 36 分钟，HyperGraphRAG 443 分钟------约 7.4 小时。

原因：HyperGraphRAG 对每个文档块做了多轮 LLM 调用 来提取实体集合，且 llm_model_max_async=1（GLM 限流）。提取 124 个块，每块约 4 次 LLM 调用，在测试期间还遇到多次超时和重试，累计时间大幅拉长。

对生产环境来说：如果用 GPT-4o 等并发能力强的 LLM，建库时间可能降到 30-60 分钟；GLM 低并发放大了这个问题。

边界拒答率：26.3%，高于预期

19 道边界问题里有 5 道（26.3%）被正确拒答，高于 GraphRAG 的 15.8% 和 HippoRAG 的 5.3%。

原因可能是 HyperGraphRAG 的 hybrid 模式（本地+全局）在找不到相关实体时，比纯局部搜索更容易判断为"知识库里没有"。

---

五框架完整横评

结合前三篇的数据，完整对比：

框架	类型	建库时间	拒答率	P90 延迟	单跳	多跳
QAnything v2	向量 RAG	~5 min	26.3%	52.2 s	0.111	0.162
LightRAG 1.5.6	图+向量	~8 min	10.5%	19.4 s	0.082	0.178
GraphRAG 3.1.1	图 RAG	31 min	15.8%	32.4 s	0.107	0.211
HippoRAG 2.0	图 RAG	36 min	5.3%	84.0 s	0.122	0.163
HyperGraphRAG 1.0.6	超图 RAG	443 min	26.3%	49.3 s	0.081	0.171

规律：

1. 建库成本和多跳性能不成正比：GraphRAG 31 分钟拿到最高多跳分 0.211；HyperGraphRAG 花了 443 分钟只得到 0.171。超图结构的理论优势在这次评测里没有转化为性能优势。

2. LightRAG 的性价比最高：建库 8 分钟，多跳 0.178（系列第二），P90 延迟最低（19.4s）。唯一短板是拒答率偏低（10.5%），图结构让它容易"硬答"。

3. 拒答能力是设计出来的，不是自然涌现的：QAnything 有置信度阈值机制，拒答率 26.3%；图 RAG 框架普遍不内置拒答逻辑，容易对超范围问题"硬答"。

4. 单跳性能：向量 RAG > 图 RAG：HippoRAG 0.122 是图 RAG 里最好的，但 QAnything 0.111 和 GraphRAG 0.107 都在一档。图结构对简单事实检索没有加分。

---

选型建议

根据这 5 个框架的数据：

优先 LightRAG（1.5.6），覆盖大多数场景：建库快、多跳表现好、延迟最低，8 分钟可以出图。需要加一层置信度过滤来提升拒答能力。

选 GraphRAG，如果：

• 多跳推理是核心需求（策略交叉分析、因果链推理）
• 有足够的 LLM 预算
• 能接受 30+ 分钟建库时间
• 使用 GPT-4o 等结构化输出稳定的模型（GLM 的结构化输出问题会禁用 community reports，削弱 global search）

选 QAnything，如果：

• 需要开箱即用的强拒答能力（置信度过滤 + 52% 拒答率）
• 不想自己维护图结构

暂时观望 HyperGraphRAG：超图结构的理论很吸引人，但当前版本（1.0.6）：

• 没有 PyPI 包，只能用源码
• 建库时间极长（7 小时），生产不友好
• 在这次技术文档场景下，多跳性能没有超过 LightRAG
• 等生产化程度更高的版本

---

代码要点

完整代码在 llm-in-action/kb-04-hypergraphrag-eval/。

关键：文本截断 + 脱敏

import re

_SENSITIVE_LINE_RE = re.compile(
    r'[^\n]*(?:'
    r'api[_\-]?key|secret|token|password|Authorization'
    r'|sk-[A-Za-z0-9]{10,}'
    r'|[A-Z][A-Z0-9_]{3,}=[^\s\n]+'  # ENV_VAR=value
    r')[^\n]*',
    re.IGNORECASE,
)
_MAX_CHARS = 700  # bge-large-en-v1.5 via SiliconFlow 约 512 tokens

def _truncate(text: str) -> str:
    text = _SENSITIVE_LINE_RE.sub("[REDACTED]", text)
    if len(text) <= _MAX_CHARS:
        return text
    truncated = text[:_MAX_CHARS]
    last_space = truncated.rfind(" ")
    return truncated[:last_space] if last_space > 0 else truncated

关键：逐文档 insert + 断点续跑

def build_index(rag, doc_files: list[Path]) -> float:
    progress = load_progress()  # 读已完成列表
    for fpath in doc_files:
        if fpath.name in progress["indexed"]:
            continue  # 跳过已完成
        content = fpath.read_text().strip()
        rag.insert([content])          # 逐文档 insert
        progress["indexed"].append(fpath.name)
        save_progress(progress)        # 立即持久化

---

系列总结

五个框架，五篇实测，同一套 89 道题：

• 单跳检索：向量 RAG 并没有输，图结构不带来加成
• 多跳推理：GraphRAG 最强（0.211），LightRAG 紧随（0.178），超图没有突破
• 拒答能力：需要主动设计，不能依赖框架默认行为
• 工程可用性：建库时间、部署难度、API 兼容性------在 GLM + SiliconFlow 这套国产模型栈下，都有不同程度的坑

下一篇会做一次系列复盘：方法论的局限性、这套测试集的偏差、以及如果真要上生产，评测框架本身应该怎么设计。

---

在 PrimeSkills 可以找到已在真实企业场景验证过的 AI Agent 技能和工作流，不是演示级的，是用在实际项目里的。

更多内容见我的个人主页