• 这是论文《HiRAG：基于层次化知识的检索增强生成》（https://arxiv.org/abs/2503.10150）的代码仓库。
• 已被 EMNLP 2025 接收！🎉

模型流程

安装

# 请先克隆本仓库
cd HiRAG
pip install -e .

快速入门

您只需使用以下代码即可通过 HiRAG 执行查询。

graph_func = HiRAG(
    working_dir="./your_work_dir",
    enable_llm_cache=True,
    enable_hierachical_mode=True, 
    embedding_batch_num=6,
    embedding_func_max_async=8, # 根据您的机器配置调整
    enable_naive_rag=True
    )
# 索引构建
with open("path_to_your_context.txt", "r") as f:
    graph_func.insert(f.read())
# 检索与生成
print("执行 hi 搜索：")
print(graph_func.query("您想提出的问题？", param=QueryParam(mode="hi")))

如果您希望将 HiRAG 与 DeepSeek、ChatGLM 或其他第三方检索 API 集成，可在 ./hi_Search_deepseek.py、./hi_Search_glm.py 和 ./hi_Search_openai.py 中找到示例。API 密钥和 LLM 配置可设置在 ./config.yaml 文件中。

评估

我们以 Mix 数据集中的流程为例。

cd ./HiRAG/eval

1. 从原始 QA 数据集中提取上下文。

python extract_context.py -i ./datasets/mix -o ./datasets/mix

2. 将上下文插入图数据库。

python insert_context_deepseek.py

请注意，insert_context_deepseek.py 脚本适用于使用 DeepSeek-v3 API 进行生成的场景，您可以将其替换为 insert_context_openai.py 或 insert_context_glm.py。

3. 使用不同版本的 HiRAG 进行测试。

# 存在不同的检索选项
# 如果您想采用 HiRAG 方法，只需运行：
python test_deepseek.py -d mix -m hi
# 如果您想采用朴素 RAG 方法，只需运行：
python test_deepseek.py -d mix -m naive
# 如果您想采用不使用桥接的 HiRAG 方法，只需运行：
python test_deepseek.py -d mix -m hi_nobridge
# 如果您想采用仅检索本地知识的 HiRAG 方法，只需运行：
python test_deepseek.py -d mix -m hi_local
# 如果您想采用仅检索全局知识的 HiRAG 方法，只需运行：
python test_deepseek.py -d mix -m hi_global
# 如果您想采用仅检索桥接知识的 HiRAG 方法，只需运行：
python test_deepseek.py -d mix -m hi_bridge

请注意，数据集 mix 可替换为 Hugging Face 链接 中的任何其他数据集。此外，test_deepseek.py 脚本适用于使用 DeepSeek-v3 API 进行生成的场景，您可以将其替换为 test_openai.py 或 test_glm.py。

4. 对生成的答案进行评估。

第一步，请求评估。

python batch_eval.py -m request -api openai
python batch_eval.py -m request -api deepseek

第二步，获取结果。

python batch_eval.py -m result -api openai
python batch_eval.py -m result -api deepseek

结果

与朴素 RAG 对比：

将配置 output_file 设置为 f"./datasets/{DATASET}/{DATASET}_eval_hi_naive.jsonl" 后，运行以下命令：

python batch_eval.py -m result -api openai

数据集	维度	朴素RAG %	HiRAG %
Mix
	全面性	16.6	83.4
	赋能性	11.6	88.4
	多样性	12.7	87.3
	整体	12.4	87.6
CS
	全面性	30.0	70.0
	赋能性	29.0	71.0
	多样性	14.5	85.5
	整体	26.5	73.5
法律
	全面性	32.5	67.5
	赋能性	25.0	75.0
	多样性	22.0	78.0
	整体	22.5	74.5
农业
	全面性	34.0	66.0
	赋能性	31.0	69.0
	多样性	21.0	79.0
	整体	28.5	71.5

与 GraphRAG 对比：

将配置 output_file 设置为 f"./datasets/{DATASET}/{DATASET}_eval_hi_graphrag.jsonl" 后，运行以下命令：

python batch_eval.py -m result -api openai

数据集	维度	GraphRAG %	HiRAG %
Mix
	全面性	42.1	57.9
	赋能性	35.1	64.9
	多样性	40.5	59.5
	整体	35.9	64.1
CS
	全面性	40.5	59.5
	赋能性	38.5	61.5
	多样性	30.5	69.5
	整体	36.0	64.0
法律
	全面性	48.5	51.5
	赋能性	43.5	56.5
	多样性	47.0	53.0
	整体	45.5	54.5
农业
	全面性	49.0	51.0
	赋能性	48.5	51.5
	多样性	45.5	54.5
	整体	46.0	54.0

与 LightRAG 对比：

将配置 output_file 设置为 f"./datasets/{DATASET}/{DATASET}_eval_hi_lightrag.jsonl"，然后运行以下命令：

python batch_eval.py -m result -api openai

数据集	维度	LightRAG %	HiRAG %
Mix
	全面性	36.8	63.2
	赋能性	34.9	65.1
	多样性	34.1	65.9
	总体	34.1	65.9
CS
	全面性	44.5	55.5
	赋能性	41.5	58.5
	多样性	33.0	67.0
	总体	41.0	59.0
Legal
	全面性	49.0	51.0
	赋能性	43.5	56.5
	多样性	63.0	37.0
	总体	48.0	52.0
Agriculture
	全面性	38.5	61.5
	赋能性	36.5	63.5
	多样性	37.5	62.5
	总体	38.5	61.5

与 FastGraphRAG 对比：

将配置 output_file 设置为 f"./datasets/{DATASET}/{DATASET}_eval_hi_fastgraphrag.jsonl"，然后运行以下命令：

python batch_eval.py -m result -api openai

数据集	维度	FastGraphRAG %	HiRAG %
Mix
	全面性	0.8	99.2
	赋能性	0.8	99.2
	多样性	0.8	99.2
	总体	0.8	99.2
CS
	全面性	0.0	100.0
	赋能性	0.0	100.0
	多样性	0.5	99.5
	总体	0.0	100.0
Legal
	全面性	1.0	99.0
	赋能性	0.0	100.0
	多样性	1.5	98.5
	总体	0.0	100.0
Agriculture
	全面性	0.0	100.0
	赋能性	0.0	100.0
	多样性	0.0	100.0
	总体	0.0	100.0

与 KAG 对比：

将配置 output_file 设置为 f"./datasets/{DATASET}/{DATASET}_eval_hi_kag.jsonl"，然后运行以下命令：

python batch_eval.py -m result -api openai

数据集	维度	KAG %	HiRAG %
Mix
	全面性	2.3	97.7
	赋能性	3.5	96.5
	多样性	3.8	96.2
	总体	2.3	97.7
CS
	全面性	1.0	99.0
	赋能性	4.5	95.5
	多样性	5.0	95.0
	总体	1.5	98.5
Legal
	全面性	16.5	83.5
	赋能性	9.0	91.0
	多样性	11.0	89.0
	总体	8.5	91.5
Agriculture
	全面性	5.0	95.0
	赋能性	5.0	95.0
	多样性	3.5	96.5
	总体	0.0	100.0

致谢

我们衷心感谢在本工作中使用了以下开源项目：

• nano-graphrag：一个简单易用的 GraphRAG 实现

• RAPTOR：一种通过从文档中构建递归树结构来增强检索型语言模型的新方法。

💡 引用我们

@article{huang2025retrieval,
  title={具有层次化知识的检索增强生成},
  author={Huang, Haoyu and Huang, Yongfeng and Yang, Junjie and Pan, Zhenyu and Chen, Yongqiang and Ma, Kaili and Chen, Hongzhi and Cheng, James},
  journal={arXiv 预印本 arXiv:2503.10150},
  year={2025}
}

🌟 星标历史

HiRAG 快速上手指南

HiRAG 是一个基于分层知识（Hierarchical Knowledge）的检索增强生成（RAG）框架，旨在通过构建层级化的知识图谱来提升大模型在复杂问答任务中的表现。该模型已被 EMNLP 2025 Findings 接收。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux 或 macOS（Windows 用户建议使用 WSL2）
• Python 版本：推荐 Python 3.8 及以上版本
• 依赖管理：已安装 pip
• API 密钥：如需使用 DeepSeek、ChatGLM 或 OpenAI 等第三方模型，请提前准备好对应的 API Key，并在项目根目录的 config.yaml 中进行配置。

安装步骤

1. 克隆仓库 首先将代码库克隆到本地：

   git clone https://github.com/hhy-huang/HiRAG.git
   cd HiRAG
   

2. 安装依赖 以可编辑模式安装项目及其依赖：

   pip install -e .
   

   提示：国内用户若遇到下载缓慢问题，可使用清华源加速安装： pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

安装完成后，您可以通过简单的 Python 代码快速体验 HiRAG 的核心功能（索引构建与查询）。

1. 初始化与索引构建

创建一个 Python 脚本（例如 demo.py），写入以下代码。该示例将启用分层模式并构建本地缓存。

from hirag import HiRAG, QueryParam # 假设导入路径，具体以实际包结构为准

# 初始化 HiRAG 实例
graph_func = HiRAG(
    working_dir="./your_work_dir",       # 工作目录，用于存储图谱数据
    enable_llm_cache=True,               # 启用 LLM 缓存以节省 Token
    enable_hierachical_mode=True,        # 开启核心的分层模式
    embedding_batch_num=6,               # 嵌入批处理数量
    embedding_func_max_async=8,          # 最大异步并发数（根据机器性能调整）
    enable_naive_rag=True                # 同时启用基础 RAG 作为对比或补充
)

# 插入上下文数据
with open("path_to_your_context.txt", "r") as f:
    graph_func.insert(f.read())

2. 执行查询

数据索引完成后，即可进行分层检索与生成：

print("Perform hi search:")
# mode="hi" 表示使用 HiRAG 的分层检索策略
response = graph_func.query("The question you want to ask?", param=QueryParam(mode="hi"))
print(response)

进阶配置

如果您希望使用 DeepSeek、ChatGLM 或其他第三方 API 进行推理，可以参考项目自带的示例脚本：

• DeepSeek: ./hi_Search_deepseek.py
• ChatGLM: ./hi_Search_glm.py
• OpenAI: ./hi_Search_openai.py

所有模型的 API Key 及具体配置参数请在根目录下的 config.yaml 文件中统一设置。