RGE源码逐行剖析:encode_and_generate与ar_encode双编码路径全解析

原创2026-10-22 17:58:381,610 阅读
文章标签:人工智能大模型多模态Embedding

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

逐行翻译:

  1. emb_id:查出 <emb> 这个特殊 token 的数字 ID
  2. torch.argmax((input_ids == emb_id).int(), dim=1):构造一个布尔掩码,找出每个样本中 <emb> 出现在第几个位置。argmax 在这里的技巧用法是"第一个 1 的位置"
  3. 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

登录后查看全文
RGE