sentence-transformers调用EVIE-4.5B完整指南：MultiVectorEncoder三步实现多向量文档检索-育师

sentence-transformers调用EVIE-4.5B完整指南：MultiVectorEncoder三步实现多向量文档检索

EVIE-4.5B 是腾讯开源的多向量视觉文档检索模型，本指南带你用 sentence-transformers 的 MultiVectorEncoder 三步完成多向量文档检索：安装依赖、一行加载模型、三次调用算出相关性得分，并附赠 Prefix-MRL 弹性维度控制技巧，新手也能 10 分钟跑通 🚀

为什么选多向量检索：EVIE-4.5B 的 MaxSim 原理

传统单向量检索会把一整页文档"压"成一个点，复杂表格、图表、版式细节全部丢失。EVIE-4.5B 采用Late-Interaction 多向量范式：

查询文本→ 一组查询向量（每个 token 一个）
文档图片→ 一组文档向量（每个视觉 token 一个，约 750 个/页）
相关性得分= 对每个查询向量，找文档中最相似的那个向量，取内积后求和（即MaxSim）

S(Q, D) = Σᵢ maxⱼ (qᵢ · dⱼ)

这种"延迟交互"方式让文档中任意局部的证据都能被精确命中，ViDoRe V1 上 nDCG@5 达到92.07，稳居榜单前列。

此外，EVIE-4.5B 支持Prefix-MRL 弹性维度：单个 2048D 投影头，运行时可自由截断为 64 / 128 / 256 / 512 / 1024 / 2048 维，无需维护多套模型，见 config.json 中的head_dims字段。

第一步：30 秒安装 sentence-transformers 与 EVIE-4.5B

1. 克隆仓库（可选，需要本地权重与内置 demo 时使用）

git clone https://gitcode.com/tencent_hunyuan/EVIE-4.5B cd EVIE-4.5B

2. 安装依赖

pip install -U "sentence-transformers[image]"

仓库的基础依赖清单见 requirements.txt（torch ≥ 2.4、transformers、pillow 等）。若你有 NVIDIA GPU，强烈建议使用 GPU 推理，速度差异非常大。

💡 说明：仓库内已按 sentence-transformers 6.0 规范打包好模型（"model_type": "MultiVectorEncoder"），配置文件为 config_sentence_transformers.json。

第二步：一行代码用 MultiVectorEncoder 加载模型

from sentence_transformers import MultiVectorEncoder model = MultiVectorEncoder("tencent/EVIE-4.5B")

就这一行，背后会自动装配如下 4 级流水线（定义于 modules.json）：

模块	类型	作用
`0`	Transformer (ColQwen3.5)	多模态主干，双向注意力编码图文
`1_Dense`	Dense	2048D 线性投影（Prefix-MRL 头）
`2_Normalize`	Normalize	向量 L2 归一化
`3_MultiVectorMask`	MultiVectorMask	屏蔽 padding，保留多向量结构

同时，模型默认使用maxsim相似度函数（见 config_sentence_transformers.json 的similarity_fn_name），文档侧会自动套用专用的 sentence-transformers 对话模板（additional_chat_templates/sentence_transformers.jinja），无需你手动拼 prompt。

第三步：三次调用完成文档检索

encode_query、encode_document、similarity三个方法，即查即得：

queries = [ "What is the total quarterly revenue?", "How many employees does the company have?", ] documents = [ "examples/demo/pages/q3_revenue.png", "examples/demo/pages/headcount.png", "examples/demo/pages/invoice_4412.png", ] query_embeddings = model.encode_query(queries) document_embeddings = model.encode_document(documents) scores = model.similarity(query_embeddings, document_embeddings) print(scores) # tensor([[17.25, 4.53, 6.79], # [ 7.61, 12.78, 4.35]])

结果怎么读？

query_embeddings[0].shape为(23, 2048)：一条查询是 23 个 token 向量，每个 2048 维
document_embeddings[0].shape为(991, 2048)：一页文档约近千个向量
scores是「查询 × 文档」矩阵，值越大越相关；按行排序即得 Top-K 排名

文档输入非常灵活：本地图片路径、URL、PIL.Image对象都可以。比如仓库自带的 8 页示例文档中：

examples/demo/pages/headcount.png 员工人数页（headcount 1,204）
examples/demo/pages/patent.png 专利页（Patent US-11,234,567）

取 Top-1 只需一行：

top1 = scores.argmax(dim=-1) # 每条查询命中的文档下标

进阶：Prefix-MRL 弹性维度，64D–2048D 自由切换

完整 2048 维精度最高（ViDoRe V3 达 66.02），但索引体积大。如果显存或存储紧张，可对向量截断前缀 + 重新归一化：

from torch.nn.functional import normalize dimension = 128 query_embeddings = [normalize(e[..., :dimension], dim=-1) for e in query_embeddings] document_embeddings = [normalize(e[..., :dimension], dim=-1) for e in document_embeddings] scores = model.similarity(query_embeddings, document_embeddings)

各档位的精度参考（ViDoRe V3 Mean Task）：

维度	精度损失	适用场景
2048D	基准	离线精排、最高精度
1024D / 512D	≈ 0.04–0.12	均衡之选
128D / 64D	0.75–1.5	超大索引、CPU 在线检索

生产环境还可叠加仓库内置的HAC 无训练 token 压缩（code/compress/），把每页约 750 个向量聚类压缩到 32 个，百万页索引仅3.81 GiB。

一键跑通本地 8 页 Demo

不想写代码？仓库内置了 8 页演示文档与完整评测脚本：

bash examples/demo/run.sh

该脚本（examples/demo/run.sh）会自动构建 demo 页面、按最大 Matryoshka 维度加载模型并输出summary.json。若想更轻量地手动打分，也可以直接用独立的推理 CLI：

python infer.py --query "How many employees are there?" \ --image examples/demo/pages/headcount.png

infer.py 支持--head 128切换投影头、--device cpu回退 CPU。

常见坑与注意事项

问题	解决
CPU 上跑很慢	EVIE-4.5B 建议用 GPU + bfloat16，CPU 仅作调试
两次运行得分略有差异	不同 dtype 与 attention 后端会带来微小波动，属正常现象
想省显存/存储	用 Prefix-MRL 截断到 128D/64D（见进阶章节）
文档不是图片	`encode_document`接受 URL、本地路径或`PIL.Image`，先转图片即可