Documentation Index Fetch the complete documentation index at: https://ultrarag.openbmb.cn/llms.txt
Use this file to discover all available pages before exploring further.
Evaluation Server 提供了一套完善的自动化评估工具，
用于对检索与生成任务的模型输出进行系统化、可复现的性能评测。
它支持多种主流指标，包括排序类、匹配类与摘要类评估，可直接嵌入 Pipeline 末尾，实现评估结果的自动计算与保存。
指标名 类型 说明 MRRfloat Mean Reciprocal Rank（平均倒数排名），衡量首个相关文档的平均排名位置。 MAPfloat Mean Average Precision（平均精确率），综合考虑检索的精确性与召回率。 Recallfloat 召回率，衡量检索系统能找回多少相关文档。 Precisionfloat 精确率，衡量检索结果中有多少是相关文档。 NDCGfloat Normalized Discounted Cumulative Gain（标准化折损累计增益），评估检索结果与理想排序的一致性。
指标名 类型 说明 EMfloat Exact Match，预测与任一参考完全相同。 Accfloat Answer 包含参考答案中的任一形式（宽松匹配）。 StringEMfloat 针对多组答案的软匹配比例（常用于多选/嵌套 QA）。 CoverEMfloat 参考答案是否完全被预测文本覆盖。 F1float Token 级别 F1 得分。 Rouge_1float 1-gram ROUGE-F1。 Rouge_2float 2-gram ROUGE-F1。 Rouge_Lfloat Longest Common Subsequence (LCS) based ROUGE。
使用示例 Trec文件评估 在信息检索中，TREC 格式文件 是标准化的评测接口，用于衡量模型在排序、召回等方面的性能。
TREC 评估通常由两类文件组成：qrel（人工标注的真实相关性）与 run（系统检索输出结果）。
一、qrel 文件（“ground truth”，人工标注的相关性） qrel 文件用于存储“哪些文档与哪个查询是相关的”这类人工标注的真实相关性判断。
格式（4列，空格分隔）：
<query_id> <iter> <doc_id> <relevance>
query_id：查询编号iter：通常写 0（历史遗留字段，可忽略）doc_id：文档编号relevance：相关性标注（通常 0 表示不相关，1 或更高表示相关）
示例：
1 0 DOC123 1 1 0 DOC456 0 2 0 DOC321 1 2 0 DOC654 1
二、run 文件（系统输出的检索结果） run 文件保存检索系统的输出结果，用于与 qrel 文件对比评估性能。
格式（6列，空格分隔）：
<query_id> Q0 <doc_id> <rank> <score> <run_name>
query_id：查询编号Q0：固定写 Q0（TREC 标准要求）doc_id：文档编号rank：排序名次（1 表示最相关）score：系统打分run_name：系统名称（例如 bm25、dense_retriever）
示例：
1 Q0 DOC123 1 12.34 bm25 1 Q0 DOC456 2 11.21 bm25 2 Q0 DOC654 1 13.89 bm25 2 Q0 DOC321 2 12.01 bm25
examples/eval_trec.yaml # MCP Server servers : evaluation : servers/evaluation # MCP Client Pipeline pipeline : - evaluation.evaluate_trec
运行以下命令编译 Pipeline：
ultrarag build examples/eval_trec.yaml
examples/parameters/eval_trec_parameter.yaml evaluation : ir_metrics : - mrr - map - recall - ndcg - precision ks : - 1 - 5 - 10 - 20 - 50 - 100 qrels_path : data/qrels.txt run_path : data/run_a.txt qrels_path : data/qrels.test run_path : data/results.test save_path : output/evaluate_results.json
运行以下命令执行该 Pipeline：
ultrarag run examples/eval_trec.yaml
显著性分析 显著性分析（Significance Testing）用于判断两个检索系统之间的性能差异是否“真实存在”，而不是由随机波动造成。
在检索任务中，系统的性能通常通过多个查询的平均指标（如 MAP、NDCG、Recall 等）衡量。
常见的显著性分析方法包括：
置换检验（Permutation Test） ：通过随机交换系统 A 和系统 B 的查询结果多次（如 10000 次），构建差异的随机分布。若实际差异超过 95% 的随机情况（p < 0.05），则认为提升显著。t 检验（Paired t-test） ：假设两个系统的查询得分服从正态分布，计算两者均值差异的显著性。
UltraRAG 内置 双侧置换检验（Two-sided Permutation Test），在自动评估过程中输出以下关键统计信息：
A_mean / B_mean 表示新旧系统的平均指标；Diff(A-B) 表示改进幅度；p_value 为显著性检验的概率；significant 为显著性判断（p < 0.05 时为 True）。
examples/eval_trec_pvalue.yaml # MCP Server servers : evaluation : servers/evaluation # MCP Client Pipeline pipeline : - evaluation.evaluate_trec_pvalue
运行以下命令编译 Pipeline：
ultrarag build examples/eval_trec_pvalue.yaml
examples/parameters/eval_trec_pvalue_parameter.yaml evaluation : ir_metrics : - mrr - map - recall - ndcg - precision ks : - 1 - 5 - 10 - 20 - 50 - 100 n_resamples : 10000 qrels_path : data/qrels.txt run_new_path : data/run_a.txt run_old_path : data/run_b.txt save_path : output/evaluate_results.json
运行以下命令执行该 Pipeline：
ultrarag run examples/eval_trec_pvalue.yaml
基本用法 examples/rag_full.yaml servers : benchmark : servers/benchmark retriever : servers/retriever prompt : servers/prompt generation : servers/generation evaluation : servers/evaluation custom : servers/custom pipeline : - benchmark.get_data - retriever.retriever_init - retriever.retriever_embed - retriever.retriever_index - retriever.retriever_search - generation.generation_init - prompt.qa_rag_boxed - generation.generate - custom.output_extract_from_boxed - evaluation.evaluate 只需在 Pipeline 的末尾添加 evaluation.evaluate 工具，即可在任务执行完成后自动计算所有指定评测指标，并输出结果到配置文件中设定的路径。
评估已有结果 如果你已经拥有模型生成的结果文件，并希望直接对其进行评估，可以将结果整理为标准化的 JSONL 格式。文件中应至少包含代表答案标签与生成结果的字段，例如：
{ "id" : 0 , "question" : "when was the last time anyone was on the moon" , "golden_answers" : [ "14 December 1972 UTC" , "December 1972" ], "pred_answer" : "December 14, 1973" } { "id" : 1 , "question" : "who wrote he ain't heavy he's my brother lyrics" , "golden_answers" : [ "Bobby Scott" , "Bob Russell" ], "pred_answer" : "The documents do not provide information about the author of the lyrics to \" He Ain't Heavy, He's My Brother. \" " }
examples/evaluate_results.yaml # MCP Server servers : benchmark : servers/benchmark evaluation : servers/evaluation # MCP Client Pipeline pipeline : - benchmark.get_data - evaluation.evaluate
为了让 Benchmark Server 读取生成结果，需要在 get_data 函数中增加 pred_ls 字段：
servers/prompt/src/benchmark.py
@app.tool ( output = "benchmark->q_ls,gt_ls" ) @app.tool ( output = "benchmark->q_ls,gt_ls,pred_ls" ) def get_data ( benchmark : Dict[ str , Any], ) -> Dict[ str , List[Any]]:
然后，运行以下命令编译 Pipeline：
ultrarag build examples/evaluate_results.yaml
在生成的参数文件中，新增字段 pred_ls 并指定其在原始数据中的对应键名，同时修改数据路径和名称以指向新的评估文件：
examples/parameters/evaluate_results_parameter.yaml benchmark : benchmark : key_map : gt_ls : golden_answers q_ls : question pred_ls : pred_answer limit : -1 name : nq path : data/sample_nq_10.jsonl name : evaluate path : data/test_evaluate.jsonl seed : 42 shuffle : false evaluation : metrics : - acc - f1 - em - coverem - stringem - rouge-1 - rouge-2 - rouge-l save_path : output/evaluate_results.json
运行以下命令执行该 Pipeline：
ultrarag run examples/evaluate_results.yaml
examples/eval_trec.yaml