XRAG完整入门:为什么这款RAG基准评测框架值得每个AI开发者关注

原创2026-11-15 10:13:051,630 阅读

XRAG完整入门:为什么这款RAG基准评测框架值得每个AI开发者关注

XRAG 是一款由 BUAA DocAILab 团队开源的 RAG 基准评测框架(Benchmarking Framework),论文已被 ICDE 2026 收录。它把检索增强生成(RAG)系统拆解为前置检索、检索器、后处理器、生成器等核心模块,用 40 多种指标逐层"体检",帮你快速定位:到底是检索不准、切分不当,还是 LLM 本身在"胡说八道"。无论你是做 RAG 应用的工程师,还是做检索系统研究的科研人员,这篇完整入门指南都会让你 10 分钟上手。

一、XRAG是什么?专为"黑盒"RAG打造的评测框架

做过 RAG 系统的人都有过这样的困惑:

  • 答案质量忽高忽低,到底是切分策略的问题,还是嵌入模型不行?
  • 换了重排模型后效果"感觉变好了",但到底好多少、哪个指标变好了,说不清楚。
  • 想对比 Self-RAG、Adaptive-RAG 等 Agentic RAG 方案,却没有统一的评测基准。

传统做法是"端到端黑盒测试",但 XRAG 的思路是组件级解剖:把 RAG 的每个基础模块单独拆出来基准化测试,让你看清每个配置选择对最终性能的真实影响。

XRAG RAG基准评测框架整体架构概览图

上图展示了 XRAG 的分层设计:顶层是三大类评测器(检索评测 ConR、生成评测 ConG、认知 LLM Agent 评测 CogL),中间是可插拔的进阶组件(Pre-retrieval、Retriever、Post-processor、Generator),底层由统一数据集预处理器、Config Hook 配置中心和 XRAG Board 支撑。所有模块都能像积木一样自由组合。

二、框架总览:一张图看懂RAG评测架构

XRAG RAG基准评测框架完整架构图

这张完整架构图中,信息量很大,我们自下而上快速过一遍:

层次 内容 说明
Config Hook API KEYS、RAG 参数、向量索引、RAG 策略、指标 一个 config.toml 管住全局
Unified Dataset Preprocessor 用户问题、检索上下文、Golden Context、预期答案 统一数据格式,支持 HotpotQA / Drop / NaturalQA
Advanced Components SBPT、HyDE、RRFusion、BGE-RRK、Jina-RRK 等 四个核心模块均可插拔替换
Orchestrators 顺序/条件/迭代/并行/混合 5 种编排 支撑 Agentic RAG 评测
Evaluators ConR / ConG / CogL 三类评测器 检索、生成、认知三层打分

核心入口是 src/xrag/launcher/launch.py:build_index 负责建向量索引,build_query_engine 组装"检索器 + 响应合成器 + 后处理器",最后逐题评测并累计指标。

三、Agentic RAG评测:5种编排模式一次看懂

XRAG 不只是测"经典 RAG",它内置了 5 种 Orchestrator 编排模式,覆盖当前主流的 Agentic RAG 方案:

XRAG Agentic RAG五种编排模式评测流程图

  • Sequential(顺序型):逐步执行 检索→后处理→生成,对应 Vanilla RAG;
  • Conditional(条件型):先由分类器判断问题类型再走不同检索分支,对应 Self-RAG、OPEN-RAG;
  • Iterative(迭代型):检索与生成循环迭代直到满足条件,对应 SIM-RAG、RFM-RAG;
  • Parallel(并行型):多路检索并行执行后融合,对应 RR-Fusion、SeaKR;
  • Hybrid(混合型):多种编排策略混合,对应 Adapt-RAG(Adaptive-RAG)。

这些 Agentic 模块都有独立源码目录,可以通过配置文件一键开关:

💡 想研究"Self-RAG 到底比朴素 RAG 强在哪",直接在配置里切换 self_rag.enabled = true 再跑一遍对比实验即可。

四、内置指标体系:传统检索、LLM、深度评测三层覆盖

XRAG 最大的卖点之一是指标丰富度。打开 src/xrag/eval/evaluate_rag.py 可以看到它内置的完整指标清单:

指标类别 代表指标 回答的问题
📐 传统检索指标 F1、EM、MRR、Hit@K、MAP、NDCG 检索回来的文档准不准、排得对不对
🤖 LLM 评测(LlamaIndex) Faithfulness、Relevancy、Correctness、Semantic Similarity、Answer Relevancy 答案忠实不忠实、相关不相关、正确不正确
🔬 深度评测(DeepEval) Contextual Precision/Recall/Relevancy、Hallucination、Bias、Toxicity 上下文有没有幻觉、偏见、毒性
📊 UpTrain 评测 Completeness、Conciseness、Factual Accuracy、Code Hallucination 回答完不完整、简洁不简洁、事实是否准确
✍️ NLG 文本指标 chrF、METEOR、WER/CER、Perplexity、ROUGE 生成的字面级文本质量
🧠 前沿指标 SePer(Semantic Perplexity,语义困惑度) 上下文对答案的信息增益

每个指标都支持独立开关,评测结果会自动汇总并支持导出到文件,方便写实验报告。传统检索指标(MRR、NDCG 等)的实现见 src/xrag/eval/evaluate_rag.py,SePer 语义困惑度评测见 src/xrag/eval/seper/。

五、检索策略:从BM25到混合检索,8种方式随便换

XRAG 在 src/xrag/retrievers/retriever.py 中提供了丰富的可插拔检索器:

  • BM25:经典词频检索
  • Vector:向量语义检索
  • Hybrid:BM25 + 向量 + 关键词混合(支持 AND 模式融合)
  • Tree(Auto Merging):树状分层索引 + 自动合并检索
  • Keyword / Document Summary / Sentence Window:关键词表、文档摘要、句子窗口检索
  • Query Fusion(RR-Fusion):多路查询融合
  • Recursive:多粒度递归检索(128/256/512 子块)

除了"检索器本身",XRAG 还覆盖了 RAG 流水线前后两端:

  • 前置检索(Pre-retrieval):src/xrag/process/query_transform.py 支持 HyDE(假设性文档嵌入)、StepBack(抽离本质提问)、Subquery(子查询分解),均支持 zero-shot 和 few-shot;
  • 后置重排(Post-processing):src/xrag/process/postprocessor.py 提供相似度截断、关键词过滤、长上下文重排、LLM 重排,以及业界热门的 BGE-RRK、Jina-RRK 重排模型。

这种"三端皆可插拔"的设计,正是它作为基准框架的价值所在——你可以系统地回答"重排到底值不值""HyDE 对哪类问题有效"这类问题。

六、WebUI六步指南:零代码完成RAG评测

不想碰配置文件?XRAG 2026 年 10 月新增了 WebUI 交互界面(源码在 src/xrag/webui/),一条命令即可启动:

xrag-cli webui

浏览器打开后,跟着 6 步向导走:Build Dataset → Build Vector Database → Configure LLM → Configure Retrieval → Set Evaluation Metrics → View Test Results。

第 1 步:选择数据集。 内置 HotpotQA(多跳问答)、DropQA(数值推理)、NaturalQA 三个基准数据集,也支持上传自己的文档文件夹(PDF/TXT/DOCX)或自定义 JSON 数据集:

XRAG RAG评测WebUI数据集配置界面

第 5 步:勾选评测指标。 界面把 NLG、Llama、DeepEval、UpTrain 四大类指标做成复选框,勾选哪些就评哪些,完全不用记指标名:

XRAG RAG评测WebUI指标选择界面

中间几步分别用于配置嵌入模型与切分参数、填写 LLM API Key、选择检索器类型与提示词模板,全程有可视化步骤指示器,新手也不会迷路。

七、快速上手:3条命令完成第一次RAG评测

1. 安装(建议 Python 3.11 + conda 虚拟环境)

conda create -n xrag python=3.11
conda activate xrag

# 安装 XRAG(PyPI 包名 examinationrag)
pip install examinationrag
# 避免依赖冲突的补充安装
pip install jury --no-deps
pip install requests==2.27.1
pip install urllib3==1.25.11
pip install "jiwer<4.0.0"

2. 准备配置文件

首次运行会基于内置的 src/xrag/default_config.toml 自动生成 config.toml,只需改两处:填入你的 LLM API 信息(api_key、api_base、api_name),以及确认评测设置(llm、embeddings、dataset、n 等)。

3. 运行评测

# 完整基准评测
xrag-cli run

# 不重跑实验,只改个别参数(例如换嵌入模型)
xrag-cli run --override embeddings="new-embedding-model"

# 从文档文件夹生成自己的 QA 对
xrag-cli generate -i <输入文件夹> -o <输出文件> -n <每文件问题数>

# 把 XRAG 当后端服务用
xrag-cli api --port 8000 --dataset_folder <文档目录>

CLI 的全部子命令定义在 src/xrag/cli.py,包括 run、webui、version、generate、api、help。评测结果默认写入日志并逐条打印累计指标,persist_dir 下会自动按"数据集 + 嵌入 + 切分方式"隔离缓存索引,切换配置不会互相污染。

八、常用配置参数速查表

参数 默认值 作用
llm openai LLM 后端:openai / huggingface / ollama
embeddings BAAI/bge-large-en-v1.5 嵌入模型
split_type / chunk_size sentence / 128 文档切分方式与块大小
dataset hotpot_qa 评测数据集(hotpot_qa / drop / natural_questions)
retriever BM25 检索器类型
postprocess_rerank long_context_reorder 后置重排策略
query_transform none 前置查询改写(hyde / stepback / subquery)
n 100 评测样本数
persist_dir storage 索引缓存目录

完整配置说明见 src/xrag/default_config.toml,参数加载逻辑在 src/xrag/config.py。

九、常见问题排查(Troubleshooting)

  • 依赖冲突:务必在独立虚拟环境安装,并按 README 固定 requests、urllib3、jiwer 版本(依赖清单见 requirements.txt);
  • --override 不生效:确认键名与 config.toml 完全一致,且值类型正确(如布尔值写 true 而非字符串);
  • 数据集/模型下载慢:XRAG 在 src/xrag/launcher/launch.py 已默认配置国内 HuggingFace 镜像端点,如遇网络问题可优先检查代理设置;
  • LLM 评测偶发失败:内置评测框架对 LLM 调用有重试与容错逻辑,个别样本失败会被标记为无效计数(valid number),不影响整体结果。

十、总结:XRAG适合谁?

你的角色 XRAG 能帮到你
RAG 应用工程师 用统一指标验证"换嵌入/换检索器/加重排"是否真的有效
算法研究者 复现并对比 Self-RAG、Adaptive-RAG 等 Agentic RAG 方案
学生/新手 通过 WebUI 零代码跑通完整 RAG 评测流程

一句话概括:当别人还在问"我的 RAG 效果怎么样"时,用 XRAG 的开发者已经能回答"是哪个组件、在哪个指标上、差了多少"。 现在就可以 pip install examinationrag,跑起你的第一次 RAG 基准评测 🚀

登录后查看全文
XRAG