企业官网建设流程全解析

• 人工智能
• 大模型
• Embedding
• RAG
• 计算机视觉

EVIE-4.5B 是腾讯开源的轻量级视觉文档检索模型（ViDoRe 榜单 SOTA）。本文手把手带你用自有数据，通过LoRA 微调打造只认"你的文档"的检索模型：从环境配置、数据格式、一键训练脚本到效果验证，全流程讲解。

1. EVIE-4.5B 是做什么的？

一句话：输入一句自然语言问题，从一堆文档页面图片里找出答案所在的那一页。它基于 Qwen3.5 多模态底座，用 late-interaction 多向量方式对每一页文档做细粒度匹配，因此能看懂复杂表格、图表和小字号排版。

比如你问"Q3 的季度营收是多少？"，模型就能把下面这张财务页面排到最前面：

官方权重在通用数据上已经很强，但如果你要检索的是公司内部制度、私有合同、行业垂类报告，用自有数据微调一轮，效果会明显更贴合业务。

2. 为什么选择 LoRA 微调？

EVIE 官方训练管线本身就是LoRA（PEFT）方案，好处非常实际：

• 显存友好：只更新文本塔的注意力/MLP 投影层（见 code/student/scripts/train.py 中的TARGET_MODULES）加上 Prefix-MRL 投影头，视觉塔完全冻结；
• 产物轻量：训练完得到一个 LoRA 适配器（adapter_model.safetensors），想部署完整模型再合并即可；
• 默认超参已调好：lora_r=32、lora_alpha=128、学习率1.5e-5、bf16 训练，开箱即用。

3. 环境准备：一次性配置

先克隆仓库并安装依赖：

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

然后复制环境模板 env.sh.example 为自己的env.sh，只需关注几个关键变量：

cp env.sh.example env.sh source env.sh

💡 仓库内置了一套 6 页的 toy 数据（examples/toy/），可以先用它跑通全流程，再换成真实数据。

4. 准备你的自有训练数据

EVIE 训练需要两种数据，格式都有现成 toy 样例可以参考：

4.1 训练对：part_*.parquet

放在DATA_ROOT下的 parquet 文件，每行一条query + 正样本文档页（图片以字节形式存在image列），可选source列用于"同任务组批"（code/shared/data_loader.py）。toy 样例见 examples/toy/part_000.parquet。

4.2 困难负样本：HuggingFace datasets 目录

放在HARDNEG_ROOT下，是一个可被load_from_disk读取的数据集目录，核心列为query、positive_doc_id、negative_doc_ids。仓库提供两个 shard 可直接试用：

• examples/toy/hardneg/judged：经人工/模型判定的负样本
• examples/toy/hardneg/allpos：全部正样本版（带sample_weight、query_group_id列）

所谓"困难负样本"就是长得像但不是答案的页面。以发票检索为例，下面这张发票页对"3 月有哪些高管？"这类 query 来说就是典型困难负样本——内容相关、答案却不对：

小技巧：用现成的检索模型先对全库召回 top-k，把"排序靠前但不相关"的页面标注为负样本，是最快的冷启动方式。

5. 开始训练：官方三步脚本

训练入口在 code/ 下，官方配方分三步（README 训练章节）：

# 第 1 步：训练 EVIE-8B 教师（两臂 + 权重合并；已有检查点可跳过） bash code/teacher/run.sh # 第 2 步：用 ARD 蒸馏训练 EVIE-4.5B 学生 export TEACHER_DIR=/path/to/Evie-8B bash code/student/run.sh # 第 3 步：138 任务评测（换成你自己的评测集亦可） MODEL_DIR=. RUN_NAME=evie-4.5b bash code/shared/eval_run.sh

第 2 步内部发生的事值得了解（见 code/student/run.sh）：

1. 两臂训练：a臂用allpos负样本 shard、b臂用judgedshard，其余配方相同；
2. 平均合并（soup）：两臂的 LoRA 适配器在 code/shared/merge_seeds.py 中做均值合并，得到更稳的权重；
3. 自动评测：训练完自动跑 code/shared/eval_run.sh，Prefix-MRL 各维度头（64/128/256/512/1024/2048）分别出分。

关键参数速查

都可以通过环境变量覆盖（code/student/scripts/launch.sh）：

📌 如果没有 EVIE-8B 教师检查点，train.py也支持无教师模式：留空--teacher-dir且不配--head-dims时退化为纯检索训练（ColbertLoss/ColbertNegativeCELoss），适合纯自有数据场景。

6. 验证你的微调成果

方式一：8 页玩具检索（最快见效）

仓库内置 examples/demo/ 的 8 页文档和查询，跑 examples/demo/run.sh 即可得到 nDCG/Recall 汇总：

RUN_NAME=my-evie bash examples/demo/run.sh

方式二：命令行单条打分

用 infer.py 对任意 query 和文档页图片打分排序，肉眼验收：

python infer.py \ --query "发票 4412 的付款截止日期是几号？" \ --image examples/demo/pages/invoice_4412.png \ --image examples/demo/pages/org_chart.png

输出按相关性从高到低排列，分数越高表示该页越匹配查询。

方式三：完整评测

把自有测试集接入 code/shared/eval.py，跑bash code/shared/eval_run.sh，与官方 138 任务协议对齐（nDCG、Recall、MAP、MRR）。

7. 常见问题

Q1：训练必须从教师模型开始吗？不必。官方两阶段（教师训练 → ARD 蒸馏）是复现 SOTA 配方的路径；只想在自己的数据上微调，直接指向已有 EVIE-8B 检查点或启用无教师模式即可。

Q2：显存要求？4.5B 模型 + LoRA + bf16，单张 80GB 显卡即可起步；默认脚本用torchrun自动探测 GPU 数量做多卡并行，显存不够可打开GRAD_CHECKPOINTING=on或调小MVT。

Q3：换了数据格式要改代码吗？不用。只要符合第 4 节的 parquet / datasets 目录结构，改DATA_ROOT、HARDNEG_ROOT两个环境变量即可，数据加载逻辑都在 code/shared/data_loader.py。

Q4：训完的模型索引太大？部署时可用仓库内置的HAC token 压缩（code/compress/），免训练地把每页向量从约 750 个压到 32 个，百万页索引仅需 3.81 GiB。

8. 总结

跟着上面四步，你就能看到用自有数据微调后的 EVIE-4.5B在自己的文档库上跑起来。

• 人工智能
• 大模型
• Embedding
• RAG
• 计算机视觉