RManLuo/gfm-rag

GFM‑RAG：用于检索增强生成的图基础模型

它是什么 – GFM‑RAG 是一个 Python 库，可让你构建基于 图结构 的检索流水线，用于大语言模型（LLM）生成。它首先将一组文档（或现有的知识图谱）转换为一个 图索引（节点、关系、边）。随后，一个预训练的 图基础模型（GFM）——一种在数百个知识图谱上训练过的图神经网络——对这个索引进行推理，以获取与用户查询最相关的文档。检索到的段落将被输入任意 LLM 以生成答案。

为何重要 – 传统的 RAG 系统通过关键词或密集向量相似性来检索文档，这在多跳推理和结构化知识方面表现不佳。GFM‑RAG 引入了一个图神经网络检索器，能够单步追踪关系（例如 总统 → 国家 → 首都），使检索更准确且更具可解释性。

主要特性（在仓库中列出）

图基础模型（GFM） – 基于 GNN 的检索器，可对图索引进行推理。
通用图索引 – 支持知识图谱、文档图谱、层次图谱，全部通过三个 CSV 文件（nodes.csv、relations.csv、edges.csv）表达。
高效性 – 多跳推理仅需一次检索调用即可完成。
泛化能力 – 预训练的 GFM 可开箱即用地处理未见过的数据集；无需微调。
可迁移性 – 你可以在自己的数据上微调检索器，以提升特定领域的性能。
代理友好 – 与任何期望包含检索步骤的代理框架兼容。
可解释性 – 检索到的图路径可可视化，以展示文档被选中的原因。

快速入门概览

安装（Python 3.12，CUDA 12+）：

conda create -n gfmrag python=3.12
conda activate gfmrag
conda install cuda-toolkit -c nvidia/label/cuda-12.6.3
pip install gfmrag

两个入口点：
- 路径 A – 原始文档 – 提供 documents.json（键值对），并让 GFMRetriever.from_index 自动构建图。
- 路径 B – 预构建图 – 将 nodes.csv、relations.csv、edges.csv（以及可选的 test.json）放在 processed/stage1/ 目录下；库将直接加载它们。

检索：

from gfmrag import GFMRetriever
retriever = GFMRetriever.from_index(
    data_dir="./data",
    data_name="toy_raw",
    model_path="rmanluo/G-reasoner-34M",
)
results = retriever.retrieve("Who is the president of France?", top_k=5)
print(results["document"])

该调用返回一个包含文档 ID 和相关性得分的列表。

微调

准备一个 train.json，包含查询-文档对，以及可选的起始/目标节点标注（参见 README 示例）。
编辑提供的 Hydra 配置文件（gfm_reasoner/sft_training.yaml）。

在一个或多个 GPU 上运行训练：

torchrun --nproc_per_node=4 -m gfmrag.workflow.sft_training --config-path config/gfm_reasoner

代码将自动从 Hugging Face 下载预训练检查点（GFM‑RAG‑8M 或 G‑reasoner‑34M）。

何时使用 GFM‑RAG？

场景	为何 GFM‑RAG 有帮助
知识密集型问答（例如企业文档、科学文献）	基于图的检索能捕捉纯向量搜索所遗漏的实体关系。
多步推理（例如“谁创立了收购 X 的公司？”）	单步 GNN 检索可遍历图中的多个跳数。
可解释人工智能	检索到的图路径可可视化，以展示推理链。
低资源领域	预训练的 GFM 无需微调即可工作，节省数据收集成本。
自定义知识图谱	使用你自己的 `nodes/relations/edges` CSV 文件，跳过索引步骤。

生态系统与资源

项目页面：https://rmanluo.github.io/gfm-rag/
论文：GFM‑RAG（NeurIPS 2025）和 G‑reasoner（ICLR 2026）。
Hugging Face 上的模型：rmanluo/GFM-RAG-8M，rmanluo/G-reasoner-34M。
相关开源工作：ULTRA（基础 GNN），HippoRAG（知识图谱构建），Microsoft GraphRAG（设计灵感）。

总结

GFM‑RAG 允许你将任意文档集合转换为图结构，然后使用预训练的图神经网络检索器，为 LLM 生成获取最相关的片段。它速度快，开箱即用，且可针对特定领域进行微调。