XRAG完整入门:为什么这款RAG基准评测框架值得每个AI开发者关注
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 的分层设计:顶层是三大类评测器(检索评测 ConR、生成评测 ConG、认知 LLM Agent 评测 CogL),中间是可插拔的进阶组件(Pre-retrieval、Retriever、Post-processor、Generator),底层由统一数据集预处理器、Config Hook 配置中心和 XRAG Board 支撑。所有模块都能像积木一样自由组合。
二、框架总览:一张图看懂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 方案:
- 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 实现:src/xrag/self_rag/
- SIM-RAG 实现:src/xrag/sim_rag/
- Adaptive-RAG 实现:src/xrag/adaptive_rag/
- OPEN-RAG 实现:src/xrag/open_rag/
💡 想研究"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 数据集:
第 5 步:勾选评测指标。 界面把 NLG、Llama、DeepEval、UpTrain 四大类指标做成复选框,勾选哪些就评哪些,完全不用记指标名:
中间几步分别用于配置嵌入模型与切分参数、填写 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 基准评测 🚀




