VeriRAG-Agent

可验证推理 + GraphRAG 的企业级检索智能体

🎯 项目概述

VeriRAG-Agent 是一个融合向量检索 + GraphRAG + 结构化检索的三重检索策略，并使用 Self-RAG 风格的自反思 gating 决定何时/如何检索的企业级 RAG 系统。下游通过 过程奖励模型（PRM）/Verifier 对推理与引用逐步校验，实现可追溯、可验证、抗注入的问答智能体。

✨ 核心特性

1. 三重检索融合 (MoE-Retriever)

• Dense 检索: FAISS/ColBERT 向量检索
• GraphRAG: 社区摘要 + 知识图谱检索
• Structured 检索: Elasticsearch BM25 / PostgreSQL FTS

2. 自反思 Gating (Self-RAG)

• 动态决定检索策略和权重
• 基于查询特征自适应调整
• 支持启发式和学习型策略

3. 可验证推理 (Verifier/PRM)

• 原子事实提取和验证
• Best-of-N with verification
• 证据覆盖率和一致性检查

4. 安全与可审计

• Llama Guard 3 内容安全检查
• OWASP LLM Top-10 场景防护
• JSON Schema 强制校验
• 完整的 trace 可追溯

5. 评测体系

• RAGAS (Faithfulness, Context Precision/Recall)
• Citation Coverage
• QAFactEval / FActScore (可选)

🏗️ 系统架构

┌─────────────────────────────────────────────────────────────┐
│                      用户查询                                │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│              安全检查 (Llama Guard 3 + OWASP)               │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│          自反思 Gating (检索策略决策)                        │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│              三重检索融合                                    │
│  ┌──────────┐  ┌──────────┐  ┌──────────────┐             │
│  │  Dense   │  │  Graph   │  │  Structured  │             │
│  │  (FAISS) │  │ (GraphRAG)│  │    (BM25)    │             │
│  └──────────┘  └──────────┘  └──────────────┘             │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│                    LLM 生成                                  │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│              Verifier 验证 (事实一致性)                      │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│          安全检查 + Schema 验证                              │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│                  结构化输出                                  │
└─────────────────────────────────────────────────────────────┘

🚀 快速开始

方法 1: 一键安装 (推荐)

cd verirag-agent

# 运行快速开始脚本
bash scripts/quickstart.sh

脚本会自动完成:

• ✓ 检查 Python 环境
• ✓ 安装依赖
• ✓ 下载模型 (可选择轻量级或高性能)
• ✓ 创建目录结构
• ✓ 配置环境变量
• ✓ 测试安装

方法 2: 手动安装

1. 安装依赖

cd verirag-agent

# 使用安装脚本
bash scripts/install.sh

# 或手动安装
pip install -r requirements.txt

2. 下载模型

使用 HF Mirror 加速 (中国大陆推荐):

# 下载所有推荐模型到 models/ 目录
bash scripts/download_models.sh

模型对比:

方案	Embedding	Reranker	大小	性能	推荐场景
轻量级	bge-base-zh-v1.5	bge-reranker-v2-m3	~2.6GB	⭐⭐⭐	资源受限
高性能	Qwen3-Embedding-8B	Qwen3-Reranker-8B	~32GB	⭐⭐⭐⭐⭐	生产环境 (Qwen3最新)

详见 模型配置指南

3. 配置

编辑 configs/app.yaml 配置文件，设置模型、检索器等参数。

4. 构建知识图谱

# 准备数据到 data/raw/
# 运行 GraphRAG 索引
bash scripts/ingest_graph.sh data/raw/ data/processed/graphrag

5. 启动服务

# 开发模式
bash scripts/run_api.sh dev

# 生产模式
bash scripts/run_api.sh prod

# Docker 模式
bash scripts/run_api.sh docker

5. 测试 API

curl -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "什么是 GraphRAG？"
  }'

📊 评测

运行评测套件:

bash scripts/eval_all.sh configs/eval.yaml data/eval/results --report

📁 项目结构

verirag-agent/
├── apps/
│   └── rag_api/              # FastAPI 服务
├── packages/
│   ├── retrievers/           # 三重检索器
│   ├── gating/               # 自反思 Gating
│   ├── verifier/             # Verifier/PRM
│   ├── security/             # 安全模块
│   ├── orchestrator/         # LangGraph 编排
│   └── evalsuite/            # 评测套件
├── pipelines/
│   └── graphrag/             # GraphRAG 管道
├── data/
│   ├── raw/                  # 原始数据
│   └── processed/            # 处理后数据
├── configs/
│   ├── app.yaml              # 主配置
│   ├── schema.output.json    # 输出 Schema
│   └── eval.yaml             # 评测配置
├── deploy/
│   ├── docker-compose.yml    # Docker 编排
│   └── Dockerfile            # Docker 镜像
└── scripts/
    ├── ingest_graph.sh       # 图谱构建
    ├── run_api.sh            # 启动服务
    └── eval_all.sh           # 运行评测

🔧 配置说明

检索器配置

retrieval:
  dense:
    engine: "faiss"           # 或 "colbert"
    topk: 8
  graph:
    enabled: true
    topk: 6
  structured:
    engine: "elasticsearch"   # 或 "postgres-fts"
    topk: 8

Gating 配置

gating:
  enabled: true
  policy_model: "heuristic"   # 或 "learned"
  default_weights:
    dense: 0.4
    graph: 0.35
    structured: 0.25

验证配置

verification:
  enabled: true
  candidate_n: 3              # Best-of-N
  min_verifier_score: 0.62
  max_iterations: 2

📈 性能指标

基于内部测试数据集:

指标	Naive RAG	Hybrid Search	VeriRAG (本方案)
Faithfulness	0.65	0.72	0.85
Citation Coverage	0.58	0.68	0.82
Context Precision	0.70	0.75	0.88

🛡️ 安全特性

• ✅ Llama Guard 3 内容安全分类
• ✅ OWASP LLM Top-10 场景检测
• ✅ Prompt Injection 防护
• ✅ 敏感信息泄露检测
• ✅ JSON Schema 强制校验

📚 参考文献

• GraphRAG (Microsoft)
• Self-RAG (ICLR'24)
• LangGraph
• RAGAS
• Llama Guard 3

📄 License

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request!