如何科学评估检索模型？EVIE-4.5B 138任务四指标评测体系实战指南
EVIE-4.5B 是腾讯开源的高精度视觉文档检索模型（Visual Document Retrieval）。它把整页文档图像编码为多向量表示，用 MaxSim 延迟交互打分。要验证一个检索模型是否真的好用，只看一个榜单分数远远不够——EVIE 官方提供了一套完整的评测体系：138 个多语言评测任务、4 大榜单（ViDoRe V1/V2/V3、JinaVDR）、4 个指标族（nDCG、Recall、MAP、MRR）× 3 个截断位（@1/@5/@10），一条命令即可跑完全量评测并自动生成汇总报告。本文带你读懂这套体系，并上手运行。
为什么"单一指标"不足以评估检索模型
新手常犯的错误是：只盯住 nDCG@10 一个数字。但真实业务里，"Top1 命中率"、"Top10 覆盖率"、"多页结果的整体排序质量"关注的维度完全不同。EVIE 的评测框架（code/shared/eval.py）对每个任务强制计算 4 族 × 3 位 =12 个指标，缺一个都不算任务完成。
| 指标族 | 回答的问题 | 典型用途 |
|---|---|---|
| nDCG | 排序质量好不好？相关文档是否排在前面？ | 榜单主流指标，综合评估 |
| Recall | 相关文档找到了多少？Top-K 有没有漏掉答案？ | 高召回场景（如 RAG 召回层） |
| MAP | 面对多个相关页，整体精确率如何？ | 一个查询对应多份正确文档时 |
| MRR | 第一个正确结果出现在第几位？ | 用户只看第一条结果的场景 |
截断位@1 / @5 / @10则分别刻画"首位命中"、"小结果集"、"大结果集"三种粒度。这样一张 4×3 的指标矩阵，比任何单一分数都更能暴露模型的短板。
138 个评测任务是怎么组织的
EVIE 的评测集覆盖 4 个榜单目录：eval（ViDoRe V1）、eval_v2、eval_v3、JinaVDR，共138 个任务子集。其中 ViDoRe V3 还支持多语言（同一页面语料被 6 种语言的查询分别检索），JinaVDR 按语言拆分子集。任务发现逻辑见 code/shared/eval.py 的discover_tasks：它自动识别三种数据格式——
- BEIR 多语言（
*-corpus目录，V3 六语言共享英文语料只编码一次） - BEIR 单语言（
corpus/ + queries/ + qrels/，V2） - Paired 配对格式（
data/test-*.parquet，V1 与 JinaVDR）
这些任务的"文档"就是带版面、表格、小字号的真实页面图像，例如官方 demo 语料（examples/demo/pages/）中的页面：
评测协议固定为paired-all-pages-dedup+process_queries+ndcg2r-20260827（定义于 code/shared/eval.py），保证全量页面、去重、查询统一预处理，让不同模型的结果严格可比。
一条命令运行 138 任务全量评测
评测入口是 code/shared/eval_run.sh，训练产物（LoRA adapter 或全量模型）放好后直接运行：
MODEL_DIR=. RUN_NAME=evie-4.5b bash code/shared/eval_run.sh几个值得新手了解的机制：
- 断点续跑：默认
--resume，每个任务成功后写入tasks/*.json缓存，中断后重跑只补缺失任务；想全量重算设EVAL_OVERWRITE=1。 - 多卡并行：自动按可见 GPU 数启动
torch.distributed.run，任务按语料体积贪心均衡分配到各 rank。 - 关键参数：
EVAL_BATCH（批大小，默认 8）、EVAL_K（截断位，默认1,5,10）、EVAL_MAX_QUERIES/EVAL_MAX_DOCS（抽样快速验证）、EVAL_DATASETS（只跑部分榜单）。 - Prefix-MRL 多头评测：EVIE-4.5B 是弹性维度模型，脚本会读取
head_dims自动对 64/128/…/2048 各维度依次评测，最后由 code/shared/aggregate_heads.py 聚合成summary_heads.json横向对比。
没有大语料环境？仓库自带 8 页 mini demo（examples/demo/run.sh），把EVAL_ROOT指向 demo 即可快速走通全流程：
如何读懂评测报告
评测结束后，结果目录 code/shared/ 输出三类产物：
summary.json：机器可读的总报告，含status、completed_tasks/expected_tasks、headline（四榜 nDCG@10）与avg4均分；summary.md：人类可读版，含指标矩阵与完整 Config（见 code/shared/eval.py 的write_summary_md）；tasks/*.json：逐任务明细，可按子集定位弱项。
EVIE-4.5B 官方 138 任务评测结果（2048D 全维度）如下，"4-Board Macro Avg" 即 138 任务宏平均：
| 指标 | ViDoRe V1 | ViDoRe V2 | ViDoRe V3 | JinaVDR | 4-Board 宏平均 |
|---|---|---|---|---|---|
| nDCG@1 | 88.35 | 72.76 | 61.16 | 74.26 | 74.13 |
| nDCG@5 | 92.07 | 73.38 | 63.39 | 81.57 | 77.60 |
| nDCG@10 | 92.53 | 74.91 | 66.02 | 82.48 | 78.98 |
| Recall@1 | 88.35 | 36.73 | 30.14 | 74.26 | 57.37 |
| Recall@5 | 94.95 | 65.59 | 58.06 | 87.39 | 76.50 |
| Recall@10 | 96.36 | 76.56 | 69.67 | 90.17 | 83.19 |
| MAP@10 | 91.29 | 66.25 | 55.50 | 79.99 | 73.25 |
| MRR@10 | 91.29 | 82.11 | 75.43 | 79.99 | 82.20 |
（完整 12 行数据见 README.md 的 Complete 138-Task Evaluation Matrix 一节。）
解读示例：一眼看出模型性格
- V3 的 Recall@1 = 30.14：V3 语料库更大更难，首位命中率天然低——如果你的业务强依赖 Top1，要重点看这一格而非 nDCG@10；
- JinaVDR 各项普遍更高：说明模型在该分布上更容易，横向比模型时不能跨榜单直接比分数；
- nDCG 与 MAP 的差距：V3 上 nDCG@10=66.02 而 MAP@10=55.50，提示多相关页场景下排序仍有优化空间。
维度取舍：Prefix-MRL 的"质量-成本"曲线
EVIE-4.5B 单投影头支持运行时截断到任意维度，官方也给出了各维度的完整评测对比：
| 维度 | 字节/向量 | ViDoRe V1 | ViDoRe V2 | ViDoRe V3 | JinaVDR | 138任务 Avg4 |
|---|---|---|---|---|---|---|
| 64 | 128 B | 92.16 | 73.18 | 64.51 | 81.00 | 77.71 |
| 128 | 256 B | 92.28 | 73.37 | 65.27 | 81.83 | 78.18 |
| 512 | 1 KiB | 92.38 | 74.53 | 65.90 | 82.27 | 78.77 |
| 2048 | 4 KiB | 92.53 | 74.91 | 66.02 | 82.48 | 78.98 |
可以看到从 64D 到 2048D，Avg4 只从 77.71 升到 78.98——小维度已经保留了近 99% 的精度，这是选型时最实用的一张表。
实操清单：新手 5 步上手
- 先跑 demo 冒烟测试：用 examples/demo/run.sh 验证环境与流程（8 页数据，几分钟出结果）；
- 抽样试跑：
EVAL_MAX_QUERIES=50限定查询量，快速确认指标计算无误； - 全量评测：
MODEL_DIR=. RUN_NAME=evie-4.5b bash code/shared/eval_run.sh，多卡自动并行； - 看报告：先读
summary.md的 Headline（四榜 nDCG@10 + Avg4），再用tasks/*.json定位掉分任务； - 失败修复：中断后直接重跑同一命令即可续跑；个别坏任务删除对应
tasks/下文件后再--resume。
💡 小提示：评测结果与
eval_contract_id（模型结构 + 数据 + 超参的哈希）绑定，跨模型对比时务必确认双方协议版本一致（code/shared/eval.py），否则分数不可比。
总结
- 138 任务 × 4 榜单：覆盖 ViDoRe V1/V2/V3 与 JinaVDR，多语言、多领域、多难度；
- 4 指标族 × 3 截断位：nDCG、Recall、MAP、MRR 组合出 12 个指标，全方位刻画排序质量；
- 工程友好：断点续跑、多卡均衡、协议哈希防串版、Prefix-MRL 多头自动聚合；
- 选型可落地：维度对比表直接告诉你 64D 与 2048D 的精度差距不到 1.3 分。
掌握这套评测方法后，无论是复现 EVIE 还是训练自己的检索模型，你都能用同样的标尺科学地回答那个关键问题：我的检索模型，到底比昨天好了多少？
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考