TGS-RAG

TGS-RAG（Text-Graph Synergy RAG）是一个面向多跳问答的文本-图谱协同检索增强生成框架。项目对应论文 Text-Graph Synergy: A Bidirectional Verification and Completion Framework for RAG，当前已被 IJCAI 2026 接收。

传统文本 RAG 容易召回语义相近但逻辑无关的伪证据；图谱 RAG 虽然具备结构化推理能力，但搜索剪枝可能丢失有效路径。TGS-RAG 通过双向协同机制缓解这个“信息孤岛”问题：

• Graph-to-Text：利用语义束搜索中访问过的图节点进行全局投票，对文本 chunk 进行结构引导重排。
• Text-to-Graph：利用初始文本证据中的实体线索，从 visited memory 中恢复被剪枝但可能有效的 orphan entity 路径。
• 统一向量数据库：文本块、实体和关系均存入 PostgreSQL + pgvector，并维护 chunk/entity/relation 的来源映射。

主要成果

论文在 MuSiQue 和 HotpotQA 多跳问答基准上评估了 TGS-RAG。检索指标采用 provenance mapping，生成质量采用 DeepSeek-V3.2 作为 LLM judge。

Dataset	Method	Strict Hit Rate	Recall	Precision	Support F1	LLM Judge Acc
MuSiQue	TGS-RAG	34.84	62.01	24.85	20.60	41.37
HotpotQA	TGS-RAG	62.00	77.55	27.41	26.06	79.99

论文中的消融结果显示：

• 移除 Graph-to-Text 重排后，HotpotQA Strict Hit Rate 从 62.00 降至 52.65。
• 移除 Text-to-Graph bridging 后，HotpotQA Strict Hit Rate 从 62.00 降至 47.82。

这些结果表明，TGS-RAG 的性能提升来自文本证据和图谱路径之间的双向验证，而不是简单拼接两类证据。

代码结构

文件	作用
TGSRAG.py	离线知识库构建入口：读取文档、分块、embedding、实体关系抽取、融合入库
retriever_db.py	在线检索核心：query entity extraction、seed entity retrieval、semantic beam search、chunk reranking、orphan bridging、answer generation
fusion.py	增量知识融合：实体/关系去重、摘要、embedding 更新、chunk 映射写入
db_utils.py	PostgreSQL + pgvector schema 初始化和表读写
chunks.py	fixed/semantic chunking
extraction.py	LLM 实体与关系抽取
embedding.py	chunk/entity/relation embedding 生成
app.py	Streamlit 可视化检索界面
search_kb.py	命令行知识库检索和文档删除工具
manage_db.py	数据库和知识库 schema 管理
config.yaml	数据库、模型、分块、图检索和打分参数配置

环境要求

• Python 3.10+
• PostgreSQL
• PostgreSQL 扩展：pgvector
• 可访问的 LLM API 和 embedding API

数据库需要启用 pgvector 扩展：

CREATE EXTENSION IF NOT EXISTS vector;

db_utils.py 会在 config.yaml 指定的数据库中自动创建当前 rag_space 对应的 schema，并创建：

• chunks
• entities
• relationships

安装依赖

pip install -r requirements.txt

如果需要处理 PDF，可安装 Docling 的 PDF 支持并下载模型：

pip install "docling[pdf]"
docling-tools models download -o <your-docling-model-dir>

配置

编辑 config.yaml：

• Database：填写 PostgreSQL 连接信息。
• General.rag_space：当前知识库名称，会被转换成数据库 schema 名。
• Embedding：填写 embedding API、模型名和向量维度。
• LLM：填写实体抽取和答案生成使用的 LLM API。
• Chunking：选择 fixed 或 semantic 分块策略。
• GraphRetrieval 和 Scoring：当前已与论文 Appendix C 的主要超参数对齐。

当前核心检索参数包括：

GraphRetrieval:
  top_p_per_entity: 3
  bfs_depth: 3
  top_k_orphans_to_bridge: 3
  beam_width: 20
  max_neighbors: 30

Scoring:
  chunk_score_alpha: 0.5
  text_confirmation_bonus: 0.4
  strong_chunk_recommendation_bonus: 0.3
  weak_chunk_recommendation_bonus: 0.15
  seed_density_bonus: 0.4
  entity_degree_weight: 0.01
  relation_degree_weight: 0.01
  top_rec_k_for_similarity: 4

构建知识库

初始化数据库：

python manage_db.py init

运行离线构建流程：

python TGSRAG.py

注意：TGSRAG.py 中的 input_dir 和 output_dir_base 目前是脚本内路径，需要按本机数据目录修改。

在线检索与问答

启动 Streamlit 应用：

streamlit run app.py

应用会加载 PathSBERetriever，执行以下流程：

1. 从 query 中抽取核心实体。
2. 在实体表中向量检索 seed entities。
3. 从 seed entities 出发执行 semantic beam search，并记录 visited memory。
4. 文本通道向量检索初始 chunks。
5. 用 visited graph nodes 对 chunks 进行全局投票和重排。
6. 从文本证据中识别 orphan entities，并从 visited memory 中恢复 bridge paths。
7. 将 Top-K graph paths 和 Top-K text chunks 送入 LLM 生成回答。

知识库搜索与管理

查看已有知识库：

python search_kb.py list

搜索全部表：

python search_kb.py search "刘备"

只搜索实体：

python search_kb.py search "刘备" --scope entities

搜索关系和文本块：

python search_kb.py search "刘备" --scope relations,chunks

删除某个文档及其关联数据：

python search_kb.py delete_doc "document_name.md"

删除某个知识库 schema：

python manage_db.py delete my_kb

该命令会执行 DROP SCHEMA ... CASCADE，会删除该知识库下的 chunks、entities 和 relationships。

Citation

如果本项目对你的研究有帮助，请引用（arXiv）：

@misc{zhong2026textgraphsynergybidirectionalverification,
      title={Text-Graph Synergy: A Bidirectional Verification and Completion Framework for RAG}, 
      author={Jiarui Zhong and Hong Cai Chen},
      year={2026},
      eprint={2605.05643},
      archivePrefix={arXiv},
      primaryClass={cs.AI},
      url={https://arxiv.org/abs/2605.05643}, 
}