RGE源码逐行剖析:encode_and_generate与ar_encode双编码路径全解析
RGE源码逐行剖析:encode_and_generate与ar_encode双编码路径全解析
🎯 RGE(Reasoning Guided Embeddings,推理引导嵌入) 是一个面向多模态检索的开源模型,基于 Qwen2.5-VL-3B-Instruct 微调而来。本文带你逐行剖析 README 中两条核心编码路径 encode_and_generate 与 ar_encode 的源码,用最通俗的方式讲清楚:为什么一个多模态向量模型需要"两条路",以及每条路的关键代码分别在做什么。读完你能快速上手 RGE 向量嵌入(Embedding)提取,不再被源码劝退。
一、RGE 是什么?一句话理解核心思想
传统的多模态向量模型(Embedding 模型)通常是"图片进去,向量出来",一步到位。而 RGE 的思路是:
让多模态大模型(MLLM)先"推理",再生成向量。
具体做法是:对查询侧(比如一张图片),先让模型生成一段结构化的描述(rationale,即"推理文本"),再基于这段生成内容提取最终向量。由于向量"看过"了模型的推理结果,它对上下文的理解更充分,检索准确率也随之提升。
这正对应了仓库 README.md 中那句核心摘要(TL;DR):用生成式推理(generated rationales)+ 对比学习(contrastive training)来产出更上下文感知的表示,从而提升嵌入质量。
在 MMEB-eval 多模态检索基准上,RGE 取得了显著优于同类 3B 级模型的检索效果。
二、快速上手:环境准备与模型加载
如果你只是想复现效果,按下面三步走即可:
git clone https://gitcode.com/MCG-NJU/RGE
cd RGE
模型加载部分(摘自 README 示例):
model = Qwen2_5_VLForConditionalGeneration.from_pretrained(
model_name, config=config,
torch_dtype=torch.bfloat16,
attn_implementation='flash_attention_2',
).to("cuda")
从 config.json 可以看到关键架构参数:
| 配置项 | 值 | 含义 |
|---|---|---|
architectures |
Qwen2_5_VLForConditionalGeneration |
底层是 Qwen2.5-VL 多模态模型 |
hidden_size |
2048 |
隐层维度,也就是最终向量长度 |
num_hidden_layers |
36 |
Transformer 层数 |
vocab_size |
151666 |
词表大小(比原版 Qwen 多了 1 个 token,后面讲) |
torch_dtype |
bfloat16 |
推荐用 bf16 精度加载 |
权重文件分为两个分片(model-00001-of-00002.safetensors 和 model-00002-of-00002.safetensors),总大小约 8.1 GB,映射关系见 model.safetensors.index.json。
三、双编码路径总览:为什么要两条路?
这是理解 RGE 最核心的部分。两条路径的分工如下:
| 路径 | 适用场景 | 是否生成文本 | 向量取自哪里 |
|---|---|---|---|
encode_and_generate |
查询侧(图片 / 视频 + 问题) | ✅ 先生成 128 token 内的描述 | 生成结束后最后一个位置的隐状态 |
ar_encode |
目标侧(纯文本,如检索目标) | ❌ 不生成,前向一次 | 文本中 <emb> 特殊 token 处的隐状态 |
💡 简单记忆:"看图走生成路,对文本走直连路"。
- 查询往往带图片,需要模型充分"看懂"再向量化 →
encode_and_generate - 目标(document side)通常是纯文本,追求速度,一个前向就拿到向量 →
ar_encode
两侧的向量都经过 F.normalize(L2 归一化)后做余弦相似度匹配,这就是检索的本质。
四、逐行剖析 encode_and_generate:边生成边取向量
完整示例见 README.md 的 Usage 部分,这里拆解四个关键步骤。
步骤 1:先跑一次自回归生成(生成推理文本)
generation_output = model.generate(
**inputs,
return_dict_in_generate=True,
output_hidden_states=True,
max_new_tokens=128,
eos_token_id=processor.tokenizer.convert_tokens_to_ids("<emb>"),
use_cache=True,
)
max_new_tokens=128:最多生成 128 个 token 的描述,防止无限生成eos_token_id被设为<emb>的 ID:意思是"生成到模型自己吐出<emb>就停"。这是 RGE 训练出来的行为——模型学会了"说完该说的,就用<emb>收尾"use_cache=True:开启 KV Cache,为下一步"省钱"做铺垫
步骤 2:把生成出来的文本解码出来看看
prompt_len = inputs['input_ids'].shape[1]
generated_ids = generation_output.sequences[0][prompt_len:]
generated_text = processor.tokenizer.decode(generated_ids, skip_special_tokens=False)
prompt_len 是输入提示的长度,从它之后切出来的就是模型新生成的部分。打印 generated_text 你能直观看到模型对图片的"推理输出"——这正是 RGE 相对传统 Embedding 模型的差异点。
步骤 3:复用 KV Cache,只对最后一个 token 做前向
past_seen = generation_output.past_key_values.get_seq_length()
new_inputs = {
'input_ids': generation_output.sequences[:, -1:], # 只喂最后 1 个 token
'past_key_values': generation_output.past_key_values, # 复用之前的缓存
'cache_position': torch.arange(past_seen, past_seen + 1, ...),
}
outputs = model(**new_inputs, output_hidden_states=True, use_cache=True)
这一步是性能的精髓:生成时 KV Cache 已经存好了整段序列的注意力缓存,所以只需要把最后一个 token 送进模型做一次轻量前向,就能拿到它对应的隐状态,而不用把整个序列重新算一遍。
步骤 4:取最后一个位置的隐状态作为向量
pooled_output = outputs.hidden_states[-1][:, -1, :]
return pooled_output, generated_text
hidden_states[-1]:取最后一层(第 36 层)的隐状态,而非 embedding 层[:, -1, :]:取序列中最后一个位置、维度为 2048 的向量
这就是"生成引导嵌入"的落地方式:向量 = 看过推理全文后,模型在收尾处的内部表示。
五、逐行剖析 ar_encode:用 <emb> 锚点一步到位
目标侧不需要生成(README 中目标本来就是纯文本),所以路径更短。核心是一个内部函数 _ar_pooling:
def _ar_pooling(input_ids, hidden_states):
emb_id = processor.tokenizer.convert_tokens_to_ids("<emb>")
embed_indices = torch.argmax((input_ids == emb_id).int(), dim=1)
embed_features = hidden_states[torch.arange(len(embed_indices)), embed_indices]
return embed_features
逐行翻译:
emb_id:查出<emb>这个特殊 token 的数字 IDtorch.argmax((input_ids == emb_id).int(), dim=1):构造一个布尔掩码,找出每个样本中<emb>出现在第几个位置。argmax在这里的技巧用法是"第一个 1 的位置"hidden_states[arange, embed_indices]:用"行号 + 列号"的批量索引,精准抠出每个样本在<emb>位置上的隐状态作为该样本的向量
外层逻辑非常简单:
outputs = model(**inputs, output_hidden_states=True)
pooled_output = _ar_pooling(inputs['input_ids'], outputs.hidden_states[-1])
也就是说:输入是 apply_chat_template(...) 后手动拼接上 <emb> 的文本(见 README.md:instruction = ... + "<emb>"),一次前向,取 <emb> 处的隐状态,完事。没有生成、没有循环,速度远快于查询侧——这也是检索系统里"目标侧要处理海量文档"时的工程必然。
⚠️ 新手易错点:
ar_encode的输入必须在文本末尾带<emb>标记,否则_ar_pooling找不到锚点。而encode_and_generate的输入不能预置<emb>,它是生成过程中模型自己吐出来的停止信号。
六、<emb> 从哪来?——词表里的"第 151666 个 token"
<emb> 不是 Qwen2.5-VL 原生 token,而是 RGE 训练时新增的。证据在 added_tokens.json 中:
"<emb>": 151665
- ID
151665恰好是 config.json 中vocab_size: 151666的最后一个可用下标——词表被扩了一格 - tokenizer_config.json 的
added_tokens_decoder里也登记了它 - 对应地,
model.embed_tokens.weight(嵌入矩阵)最后一行就是为<emb>学出来的新向量
所以 <emb> 一身三职:
| 用途 | 位置 |
|---|---|
| 生成侧的停止信号(eos) | encode_and_generate 的 eos_token_id |
| 目标侧的向量锚点(pooling 位置) | ar_encode 的 _ar_pooling |
| 训练时的嵌入对齐目标 | 论文中的对比训练 |
一个 token 把两条路径统一起来,设计上非常优雅。
七、选路速查表:我的任务该用哪条路径?
| 你的任务 | 输入形态 | 调用 | 备注 |
|---|---|---|---|
| 以图搜文 / 图搜图查询 | 图片 + 指令 | encode_and_generate |
会先打印 generated_text |
| 检索目标(文档/标题向量化) | 纯文本 + <emb> |
ar_encode |
记得拼 <emb> |
| 视频查询 | 视频帧 + 指令 | encode_and_generate |
与图片同理 |
无论哪条路,拿到向量后都要 F.normalize(x, p=2, dim=-1) 再算相似度;相似度计算就是简单的矩阵乘法 q @ p.T(见 README.md)。
八、生成行为小细节(选读)
geneRATION_config.json 中 temperature: 1e-06、do_sample: true 这种"接近贪心"的配置,配合 repetition_penalty: 1.05,说明 RGE 官方推理追求确定性输出(温度极低时采样几乎退化为 argmax),保证同一个查询的向量稳定可复现——对检索系统至关重要。
另外 chat_template.json 定义了对话模板:没有 system 消息时会自动补一句 You are a helpful assistant.,并在末尾加上 assistant\n,两条编码路径的输入都走这套模板。
九、总结
🧠 全文一张图式总结:
- RGE = Qwen2.5-VL-3B + 词表新增的
<emb>token + 推理引导式嵌入训练 - 查询侧
encode_and_generate:先生成 ≤128 token 的推理描述(<emb>为停止信号)→ 复用 KV Cache 前向最后 1 个 token → 取末位隐状态为向量 - 目标侧
ar_encode:文本末尾手动拼<emb>→ 单次前向 → 定位<emb>位置抠出隐状态为向量 - 两边 L2 归一化后余弦相似度即检索分数;官方在 MMEB-eval 上展示了相对同类模型的检索精度优势
理解这两条路径后,你就可以基于本仓库的权重(配合 transformers 4.51.3+ 与 FlashAttention-2)搭建自己的多模态检索系统了。
相关文件速览:README.md · config.json · added_tokens.json · tokenizer_config.json · generation_config.json · chat_template.json · preprocessor_config.json · model.safetensors.index.json