RManLuo/gfm-rag

GFM‑RAG: Graph Foundation Model for Retrieval‑Augmented Generation

What it is – GFM‑RAG is a Python library that lets you build a graph‑based retrieval pipeline for large‑language‑model (LLM) generation. It first turns a collection of documents (or an existing knowledge graph) into a graph index (nodes, relations, edges). A pre‑trained Graph Foundation Model (GFM) – a graph neural network trained on hundreds of knowledge graphs – then reasons over that index to fetch the most relevant documents for a user query. The retrieved passages are fed to any LLM for answer generation.

Why it matters – Traditional RAG systems retrieve documents by keyword or dense vector similarity, which struggles with multi‑hop reasoning and structural knowledge. GFM‑RAG adds a graph‑neural‑network retriever that can follow relationships (e.g., president → country → capital) in a single step, making retrieval more accurate and interpretable.

Key Features (as listed in the repo)

Graph Foundation Model (GFM) – a GNN‑based retriever that can reason over a graph‑index.
Universal Graph Index – supports knowledge graphs, document graphs, hierarchical graphs, all expressed with three CSV files (nodes.csv, relations.csv, edges.csv).
Efficiency – multi‑hop reasoning is performed with a single retrieval call.
Generalizability – the pre‑trained GFM works out‑of‑the‑box on unseen datasets; no fine‑tuning required.
Transferability – you can fine‑tune the retriever on your own data to improve domain performance.
Agent‑friendly – compatible with any agent framework that expects a retrieval step.
Interpretability – the retrieved graph paths can be visualised to show why a document was selected.

Quick‑Start Overview

Install (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

Two entry points:
- Path A – raw documents – give a documents.json (key/value pairs) and let GFMRetriever.from_index build the graph automatically.
- Path B – pre‑built graph – place nodes.csv, relations.csv, edges.csv (and optional test.json) under processed/stage1/; the library will load them directly.

Retrieve:

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"])

The call returns a list of document IDs with relevance scores.

Fine‑tuning

Prepare a train.json with query‑document pairs and optional start/target node annotations (see README example).
Edit the provided Hydra config (gfm_reasoner/sft_training.yaml).

Run training on one or many GPUs:

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

The code will download the pre‑trained checkpoints (GFM‑RAG‑8M or G‑reasoner‑34M) from Hugging Face automatically.

When to use GFM‑RAG?

Scenario	Why GFM‑RAG helps
Knowledge‑intensive QA (e.g., corporate docs, scientific literature)	Graph‑based retrieval captures entity relationships that plain vector search misses.
Multi‑step reasoning (e.g., “Who founded the company that acquired X?”)	Single‑step GNN retrieval can traverse multiple hops in the graph.
Explainable AI	Retrieved graph paths can be visualised to show the reasoning chain.
Low‑resource domains	The pre‑trained GFM works without fine‑tuning, saving data‑collection effort.
Custom knowledge graphs	Bring your own `nodes/relations/edges` CSVs and skip the indexing step.

Ecosystem & Resources

Project page: https://rmanluo.github.io/gfm-rag/
Paper: GFM‑RAG (NeurIPS 2025) and G‑reasoner (ICLR 2026).
Models on Hugging Face: rmanluo/GFM-RAG-8M, rmanluo/G-reasoner-34M.
Related open‑source work: ULTRA (base GNN), HippoRAG (KG construction), Microsoft GraphRAG (design inspiration).

TL;DR

GFM‑RAG lets you turn any document collection into a graph, then uses a pre‑trained graph neural retriever to fetch the most relevant pieces for LLM generation. It’s fast, works out‑of‑the‑box on new data, and can be fine‑tuned for domain‑specific performance.