EVIE-8B评测框架实战指南：如何一键复现138个任务的ViDoRe与JinaVDR基准

EVIE-8B 是腾讯开源的视觉文档检索模型（ViDoRe 榜单 SOTA），本仓库自带一套完整的EVIE-8B 评测框架：一条命令即可在 ViDoRe V1/V2/V3 与 JinaVDR 共138 个任务上复现官方基准成绩，支持断点续跑与多卡并行。本文手把手带你完成环境搭建、数据准备到一键评测的全流程，零基础也能跑通。

🎯 EVIE-8B 是什么？

EVIE-8B（Evidence-Vector-Informed Embedding）是一个8.4B 参数的多向量视觉文档检索模型：

• 🧠4096 维 per-token 表示：文档图像不按"单向量"压缩，而是保留每个 token 的精细语义，配合MaxSim 延迟交互打分（见 colpali_engine/utils/maxsim.py）
• 📄ViDoRe V3 榜单第 1：nDCG@10 达 66.75，覆盖图表、表格、版式等复杂文档
• 🏗️双向注意力 + FlashAttention：视觉 patch 与文本提示充分交互

本仓库既是模型权重（model.safetensors、config.json），也是评测框架 + 推理引擎 + 演示数据的一体化工程。

📦 138 个评测任务全景图

评测框架内置对 4 大基准数据集的自动发现（任务发现逻辑见 code/shared/eval.py）：

官方成绩基准线（4 板块宏平均，MVT=1024、双向注意力）：

复现时只要最终summary.json中的 nDCG@10 与上表基本一致，就说明你的评测环境配置正确 ✅

🗂️ 评测框架核心组成

💡 评测协议常量paired-all-pages-dedup+process_queries+ndcg2r-20260827（定义于 code/shared/eval.py）锁定了编码与打分规则，任何规则变动都会使旧缓存自动失效，保证结果可复现。

⚡ 第 1 步：安装环境，5 分钟搭好

git clone https://gitcode.com/tencent_hunyuan/EVIE-8B cd EVIE-8B pip install -r requirements.txt export PYTHONPATH="$(pwd)/colpali${PYTHONPATH:+:$PYTHONPATH}"

仓库自带模型权重（约 8.4B 参数、bfloat16），MODEL_DIR直接指向仓库根目录即可，无需额外下载。

🚀 第 2 步：先跑 8 页 Demo，验证链路通不通

仓库内置了 8 张演示文档页（财务报表、发票、专利、组织架构图等），用 examples/demo/run.sh 一键执行迷你评测：

bash examples/demo/run.sh

运行结束后会打印结果摘要路径runs/demo/eval/summary.json。以下是其中两张演示文档页：

Demo 走的就是与完整评测完全相同的eval_run.sh链路，只是数据集换成了demo。跑通 Demo，就代表 138 任务评测没有任何环境障碍。

🔍 单文档快速打分：infer.py

想快速感受"文本查询 → 文档图片"的检索效果？infer.py 是最轻量的入口：

python infer.py \ --query "What is the total quarterly revenue?" \ --image examples/demo/pages/q3_revenue.png \ --image examples/demo/pages/invoice_4412.png

输出为每张文档图的相关度分数排序，最高分即为检索命中结果。

🏆 第 3 步：准备 138 任务评测数据

1️⃣ViDoRe V1/V2/V3：从 Hugging Face 的vidore/vidore_benchmark、vidore/vidore_benchmark_v2、vidore/vidore_benchmark_v3数据集下载，解压到$EVAL_ROOT下的eval/、eval_v2/、eval_v3/目录（V3 为多语言 BEIR 结构，每种语言一个xxx-corpus子目录）。

2️⃣JinaVDR：仓库提供专用下载脚本，自动拉取全部 76 个公开子集：

python code/shared/download_jinavdr.py

下载脚本（code/shared/download_jinavdr.py）会写入$EVAL_ROOT/JinaVDR（可用JINAVDR_ROOT覆盖）。

3️⃣设置环境变量：参考 env.sh.example：

cp env.sh.example env.sh # 按需修改 EVAL_ROOT（评测数据根目录） source env.sh

🛠️ 第 4 步：一键运行 138 任务评测

export RUN_NAME="EVIE-8B" # 运行名，结果归档到 runs/EVIE-8B/eval/ export EVAL_BATCH=8 # 图像编码 batch，按显存调整 bash code/shared/eval_run.sh

脚本自动完成：检测 GPU 数量 → 启动torch.distributed多进程 → 均衡切分 138 个任务到各卡 → 逐任务编码 + MaxSim 打分 → 由 rank 0 汇总生成报告。

📊 结果解读

评测完成后，查看runs/$RUN_NAME/eval/目录：

summary.json中status: "complete"且 138/138 任务齐全即表示完整复现成功。

🧩 框架进阶特性（复现顺利的关键）

• 任务完整性校验：不指定--datasets时，框架强制要求任务数为10 + 4 + 48 + 76 = 138，数据缺一个子集就直接报错拒绝启动，避免"假装复现"
• 断点续跑：默认--resume模式，已成功的任务从tasks/缓存直接读取；某任务失败后删除对应 JSON 重跑即可
• 防污染契约指纹：每次运行会对模型文件、评测数据、超参数做 SHA256 指纹（eval_contract_id），换模型或改数据后旧缓存自动失效
• 语料编码复用：ViDoRe V3 的 6 种语言共享同一页语料，框架只编码一次、复用 6 次（见 code/shared/eval.py 的 corpus cache）
• 多节点并行：通过NNODES/MASTER_ADDR/MASTER_PORT环境变量即可横向扩展，共享语料的任务会被固定分配到同一张卡
• Matryoshka 多头：若 checkpoint 训练了多个head_dims，eval_run.sh会自动逐个 head 评测并调用 aggregate_heads.py 聚合
• 快速冒烟：EVAL_MAX_QUERIES=20 EVAL_MAX_DOCS=50 bash code/shared/eval_run.sh可在几分钟内验证小规模流程

❓ 常见问题

✅ 写在最后

整套评测框架的设计哲学是"可复现优先"：协议常量、契约指纹、任务级缓存、完整性校验层层兜底。跟着本文四步走——装环境 → 跑 Demo → 备数据 → 一键评测——你就能在runs/目录下得到与官方一致的 138 任务完整评测报告。想进一步训练与蒸馏 EVIE-4.5B，可参考技术报告 arXiv:2610.11553 与项目 README.md。

祝评测顺利，跑出属于你的 SOTA 基线 🚀