HybRAG: Hybrid Retrieval-Augmented Generation

Official implementation of "Hybrid Retrieval-Augmented Generation: Semantic and Structural Integration for Large Language Model Reasoning" (Appl. Sci., 2026).

HybRAG integrates a semantic Node-level Retriever and a structural Path-level Retriever for knowledge-graph question answering (KGQA). Retrieved semantic triplets and multi-hop paths are merged, re-ranked, and consumed by a LoRA-tuned LLM via Retrieval-Augmented Fine-Tuning (RAFT).

📄 Paper: Applied Sciences 2026, 16(5), 2244

---

Project Structure

HybRAG/
├── datasets/               # RoG-{webqsp,cwq} parquet (git-ignored; scripts/00)
├── data/                   # Path-retriever inputs + retrieval outputs (git-ignored)
├── data_preprocess/        # KG graph construction + hybrid prompt generation
│   ├── model.py                   # S-BERT / BERT / RoBERTa / SimCSE / E5 / T5 encoder
│   ├── download_rog.py            # HuggingFace RoG downloader
│   ├── dic_extractor.py           # Per-split dictionary graph (Phase 0 for NR)
│   ├── inductive_extractor.py     # DGL heterograph + per-question subgraphs
│   └── hybrid_prompt_generation.py# Phases 3+4: merge + re-rank
├── node_retriever/         # §3.1 Node-level Retriever (dense_retriever.py)
├── path_retriever/         # §3.2 Path-level Retriever (ReaRev-based GNN)
├── raft_training/          # §3.5 RAFT fine-tuning with LoRA
├── raft_inference/         # Phase 6 — test-time generation
├── raft_evaluation/        # F1 / Hit@1 / Precision / Recall
├── templates/              # Prompt templates (alpaca, llama, mistral, qwen)
├── scripts/                # Numbered pipeline wrappers
├── models/                 # LoRA adapter checkpoints (git-ignored)
└── outputs/                # Predictions & eval results (git-ignored)

---

Quick Start

1. Environment

git clone https://github.com/2noweyh/HybRAG.git
cd HybRAG
conda create -n hybrag python=3.11 -y
conda activate hybrag
pip install -r requirements.txt

Tested with Python 3.11, PyTorch 2.3+cu121, DGL 2.4, Transformers 4.44, PEFT 0.11, NVIDIA H100 (80 GB).

2. Data

HybRAG uses the RoG-WebQSP and RoG-CWQ datasets from Luo et al. (ICLR 2024), hosted on HuggingFace Hub as rmanluo/RoG-webqsp and rmanluo/RoG-cwq.

# Downloads both datasets to ./datasets/RoG-{webqsp,cwq}/data/{trn,val,tst}/0000.parquet
bash scripts/00_download_data.sh

# Or choose subsets:
bash scripts/00_download_data.sh webqsp
bash scripts/00_download_data.sh cwq

Override the target location with DATASETS_ROOT:

DATASETS_ROOT=/scratch/data bash scripts/00_download_data.sh

Step (2) of the script materializes path_retriever inputs (train.json, dev.json, test.json, entities.txt, relations.txt, vocab.txt, word_emb.npy) under data/{webqsp,cwq}/.

3. Pipeline

The scripts/ mirror Algorithm 1 in the paper:

#	Script	Paper phase	Inputs → Outputs
00	00_download_data.sh	—	HF → datasets/RoG-*/data/{trn,val,tst}/*.parquet
01	01_build_graph.sh <ds> <ver>	Phase 0	parquet → data/{ds}/{ds}_dic_graph_{ver}.pt
02	02_node_retrieve.sh <ds> <split> <ver>	Phase 1 (§3.1)	dic_graph → data/{ds}/dense_retrieval_results_{split}_{ver}.json
03	03_path_retrieve.sh <ds>	Phase 2 (§3.2)	path-retriever json → ReaRev checkpoint + predictions_{split}.jsonl
04	04_hybrid_prompt.sh <ds> <split> <ver> <mode>	Phase 3+4 (§3.3–3.4)	merge + rerank → data/{ds}/rerank_{split}_{ver}_{mode}.json
05	05_raft_train.sh <epochs> <model> <ds> <ver> <mode>	Phase 5 (§3.5)	rerank json → LoRA adapter
06	06_inference.sh <model> <ds> <ver> <mode>	Phase 6	LoRA → outputs/{ds}/*_result_{mode}.jsonl
07	07_evaluate.sh <model> <ds> <ver> <mode>	§4.1.2	predictions → F1 / Hit@1

Example reproducing WebQSP with Llama-3-8B-Instruct (Table 4 main result):

bash scripts/00_download_data.sh webqsp

bash scripts/01_build_graph.sh   webqsp v1
for split in trn val tst; do
  bash scripts/02_node_retrieve.sh webqsp $split v1
done
bash scripts/03_path_retrieve.sh webqsp
for split in trn val tst; do
  bash scripts/04_hybrid_prompt.sh webqsp $split v1 both
done

bash scripts/05_raft_train.sh 2 Meta-Llama-3-8B-Instruct webqsp v1 both
bash scripts/06_inference.sh     Meta-Llama-3-8B-Instruct webqsp v1 both
bash scripts/07_evaluate.sh      Meta-Llama-3-8B-Instruct webqsp v1 both

Output / checkpoint locations are overridable by env vars: DATA_ROOT, MODEL_ROOT, OUTPUT_ROOT, DATASETS_ROOT.

---

Core Idea

HybRAG constructs a hybrid subgraph H(q) = H_sem(q) ∪ H_str(q, a) combining:

• Node Retriever (NR) — S-BERT cosine similarity + h-hop expansion with degree-weighted importance scoring (Eq. 4).
• Path Retriever (PR) — query-aware GNN (ReaRev backbone) with BFS-conditioned message passing (Eqs. 7–13); top-K shortest paths from the query entity to predicted answers.
• Hybrid Prompt + Re-Ranker — cosine-similarity re-ranking of candidate hybrid contexts (Eqs. 17–19).
• RAFT — LoRA fine-tuning conditioned on re-ranked hybrid prompts (Eq. 20).

Main results (Table 4): Hit@1 75.2 / 57.0 and F1 56.3 / 51.1 on WebQSP / CWQ.

---

Acknowledgements

• The Path-level Retriever builds on the GNN-RAG framework (Mavromatis & Karypis, ACL Findings 2024). The path_retriever/ module (ReaRev architecture, dataset loaders, GNN modules) is derived from their gnn/ codebase.
• The datasets are from RoG (Luo et al., ICLR 2024): rmanluo/RoG-webqsp, rmanluo/RoG-cwq.

Citation

@article{lee2026hybrag,
  title   = {Hybrid Retrieval-Augmented Generation: Semantic and Structural Integration for Large Language Model Reasoning},
  author  = {Lee, Hyewon and Lim, Sungsu},
  journal = {Applied Sciences},
  volume  = {16},
  number  = {5},
  pages   = {2244},
  year    = {2026},
  url     = {https://www.mdpi.com/2076-3417/16/5/2244}
}