EVIE-4.5B内置Demo实战：如何用文本查询精准定位8张文档页面中的目标信息

EVIE-4.5B内置Demo实战：如何用文本查询精准定位8张文档页面中的目标信息

EVIE-4.5B 是腾讯开源的视觉文档检索（Visual Document Retrieval）模型，仓库内置了一套8 页文档检索 Demo：无需自备任何数据，运行一条bash examples/demo/run.sh就能完成“文本查询 → 8 张文档页面排序”的完整流程，模型会自动为 “What was Q3 2024 revenue?” 这类问题精准选出含有答案的那一页。本文带你 3 步跑通这个 Demo。

🎯 看懂 8 页文档检索任务：文本查询如何对应到页面

Demo 模拟的是最典型的检索场景——你不知道答案在哪一页，只知道要查什么。

8 张示例文档页面位于 examples/demo/pages/，每一页都预配了一条自然语言查询，数据定义在 examples/demo/build.py 中：

先看两张最有“检索味”的页面：

查询 “What was Q3 2024 revenue?” 的正确页面就是这张 FY2024 Q3 earnings——页面上白纸黑字写着 “Q3 2024 revenue $12.4 million”。

组织架构图页面存的是 “CEO: Dana Ng / VP Sales: Priya Shah” 的汇报关系，查询 “Who is the VP of Sales under the CEO?” 要求模型读懂图中的层级结构，而不是简单关键词匹配。

⚡ 3 步跑通 EVIE-4.5B 内置 Demo

第 1 步：克隆仓库并安装依赖（一键配置环境）

git clone https://gitcode.com/tencent_hunyuan/EVIE-4.5B cd EVIE-4.5B pip install -r requirements.txt

这个仓库是自包含的模型仓库：根目录的 model.safetensors 就是 EVIE-4.5B 权重本体，克隆完成即模型就位，无需再下载额外的大文件。

第 2 步：一键运行内置 Demo

bash examples/demo/run.sh

examples/demo/run.sh 会依次自动完成三件事：

1. 准备数据：若 8 页数据集 test-00000-of-00001.parquet 不存在，先调用 examples/demo/build.py 生成页面图片与 parquet 文件（仓库已自带，一般直接跳过）；
2. 读取模型配置：从 config.json 读取 Prefix-MRL 最大投影维度（2048）作为评测头维度；
3. 分布式评测：使用全部可见 GPU 启动 code/shared/eval.py 评测框架，对 8 条查询逐一给 8 个页面打分，计算 Recall / nDCG / MRR / MAP 指标。

第 3 步：查看排序结果

评测结果写入runs/demo/eval/目录，核心文件：

• d2048/summary.json—— 2048 维投影下的完整评测汇总（每条查询、每个指标）；
• d2048/summary.md—— 人读版指标表格；
• summary_heads.json—— 跨维度聚合文件。

Demo 中每条查询只有 1 个正确页面，因此只要模型判断正确，8 条查询全部命中第 1 名，指标会非常接近 100%——这也是快速验证模型是否“装对了”的好办法。

👀 其余 6 张示例页面一览

剩下 6 张页面覆盖了发票、报错日志、专利等不同版式，考察模型“看图读数”的另一种能力：

发票页面：查询问 “invoice 4412 的到期日”，页面上的 “14 March 2026” 就是答案。

报错日志页面：查询问 “哪个文件哪一行抛出了 TypeError”，页面上 “app/ledger.py line 88” 即答案——从代码文本中定位关键信息是典型文档检索任务。

仓库卡片：查询 “Where is Warehouse B located?” 的答案是 “NORTH LOT”。

财务快照：查询 “How much cash is on hand?” 的答案是 “$80 million”。

人事统计页：查询 “What is the employee headcount?” 的答案是 “1,204”。

专利台账页：查询 “授权的专利号是什么？” 的答案是 “US-11,234,567”。

🔧 进阶用法：用 infer.py 对任意页面打分

内置 Demo 用的是固定 8 对查询，想换成“自己的页面”时，可以用仓库根目录的 infer.py：

python infer.py \ --query "What is the due date on invoice 4412?" \ --image examples/demo/pages/invoice_4412.png \ --image examples/demo/pages/q3_revenue.png \ --image examples/demo/pages/traceback.png

--query与--image都可重复传入任意多个；运行后终端会为每条查询输出一个排名列表：每行一张图片，按 MaxSim 相关性分数从高到低排序，第一行就是该查询最相关的页面。

两个实用参数：

• --head：选择 Matryoshka 投影维度 64 / 128 / 256 / 512 / 1024 / 2048（默认最宽的 2048）。维度越低，索引越轻量，分数略有下降；
• --device cpu：没有 GPU 也能跑（速度较慢，但流程完全一致）。

📊 理解打分原理：MaxSim 后交互是怎么算的

EVIE 的打分方式和“整页压成一个向量”的稠密检索不同：

查询文本 ──► ColQwen3.5（双向注意力）──► 多条文本向量 页面图片 ──► ColQwen3.5（视觉编码器）─► 多条视觉 patch 向量 │ MaxSim 后交互：每条查询向量取页内最大点积，再求和

查询被拆成多个 token 级向量，页面被拆成数百个视觉 patch 向量；每条查询向量都在页面里找匹配度最高的视觉向量（取最大点积），全部相加得到总分。正因如此，小字号文本、表格细节、版式结构都能参与匹配——这就是后交互（late-interaction）范式的核心，也是 EVIE-4.5B 在 ViDoRe 榜单上保持 SOTA 的关键。

❓ Demo 常见问题 FAQ

Q：每次运行都会重新生成 Demo 数据吗？

不会。examples/demo/build.py 只在 parquet 文件缺失时才被 examples/demo/run.sh 自动触发，第二次及以后运行直接进入评测。

Q：没有 GPU 的 CPU 机器能跑吗？

examples/demo/run.sh 会按可见 GPU 数量启动 torchrun 分布式评测，面向 GPU 环境。CPU 机器建议改用python infer.py --device cpu对少量页面打分，体验同样的检索流程。

Q：想把 Demo 扩展到更多页面怎么办？

参照 examples/demo/build.py 中PAGES列表的结构追加“页面内容 + 查询”即可，重新生成 parquet 后，评测框架会自动按“查询 ↔ 正确页面”配对计分。

📌 小结

EVIE-4.5B 的内置 Demo 用最小的 8 页语料演示了视觉文档检索最核心的一环——从自然语言查询到定位正确文档页面，一条bash examples/demo/run.sh即可完整跑通。跑通 Demo、看懂 Recall@1 / nDCG@10 这些指标之后，你可以继续用 infer.py 和 code/shared/eval.py 评测框架把自己的文档库接进来，从“玩具体验”走向真实业务数据。