源码逐行解析(下):text_encoder.py的Transformer文本塔、正弦位置编码与掩码池化

原创2026-10-21 18:39:32816 阅读

源码逐行解析(下):text_encoder.py的Transformer文本塔、正弦位置编码与掩码池化

TIPSv1-s14 是谷歌发布的 TIPS 系列中空间感知的对比式视觉-语言模型(ICLR 2025),把图像和文本映射到同一个 384 维空间,支持零样本图像分类。它的文本侧完全由 text_encoder.py 一个文件完成:先用 SentencePiece 把句子切成最长 64 个 token,再送入 12 层 Transformer 文本塔,其中正弦位置编码赋予每个位置独一无二的“坐标指纹”,最后的掩码池化只对真实 token 求平均,输出一条与图像特征对齐的文本向量。这篇文章逐块拆解这份源码,帮新手看懂每一条向量的来历。

text_encoder.py 在项目中的位置 🏗️

先建立全局视角。TIPSv1-s14 由两大塔组成:

模块 文件 职责
视觉塔(ViT-S/14,22M 参数) image_encoder.py 输出 CLS 全局特征 + 1024 个 patch 空间特征
文本塔(12 层 Transformer,34M 参数) text_encoder.py 把句子编码为 384 维向量
总装与推理入口 modeling_tips.py 提供 encode_image / encode_text
文本塔超参数 config.json text_config 段定义宽度、层数、词表等

调用链非常清晰:modeling_tips.py 中的 encode_text 先懒加载 Tokenizer,把字符串变成 ids 和 paddings 两个张量,再一次性喂给 TextEncoder。整条流水线的形状变化如下:

"a photo of a dog"
   → ids (B, 64) + paddings (B, 64)      # Tokenizer
   → token embedding (B, 64, 384)        # 查表 + 缩放
   → + 正弦位置编码 (64, 384)            # PositionalEmbedding
   → 12 层 Transformer (B, 64, 384)      # 注意力 + MLP
   → LayerNorm + 掩码平均池化 (B, 384)   # 一条句子的向量

下文就按这个顺序,逐块解析源码。

第一站:Tokenizer 把句子变成 64 长数字序列 🔤

Tokenizer 类(text_encoder.py#L27-L48)只有 3 行核心逻辑,值得逐行品味:

self.sp = spm.SentencePieceProcessor(model_file=tokenizer_path)
self._add_bos = False
self._add_eos = False
  • SentencePiece 是谷歌的子词分词器,词表文件就是仓库里的 tokenizer.model。它不依赖空格,可以把 "dogs" 切成 "do" + "gs" 这样的子词,对没见过的词也不至于完全失语。
  • 显式关闭 BOS/EOS:注释写明这是为了与参考实现保持一致——不追加句首/句尾特殊符。这一点和 tokenizer_config.json 中 bos_token: null、eos_token: null 相互印证。
  • 编码前统一 小写化(t.lower()),因为训练时文本就是小写输入。

接下来 tokenize 方法(L36-L48)做三件事:

  1. 定长填充:预分配 (B, 64) 的零矩阵,每条句子只填前 min(len(ids), 64) 个位置,超长的直接截断;
  2. 返回填充掩码:is_padding = (tokens == 0),即“哪些位置是补的 0”;
  3. 词表中 0 号位恰好就是 <pad>(见 tokenizer_config.json 的 pad_token),所以用 0 填充天然就是合法的 pad token,掩码和 token 序列可以一一对应。

💡 为什么是 64?config.json 的 max_position_embeddings: 64 限定了句子最长 64 个 token,足够覆盖零样本分类的短句查询(如 "a photo of a cat")。

正弦位置编码:一个公式生成的“坐标指纹” 📍

Transformer 的注意力本身是置换不变的——打乱 token 顺序,结果不变。所以必须额外告诉模型“谁在第几位”。PositionalEmbedding 类(text_encoder.py#L51-L104)选择的是经典的正弦位置编码:不查表、不学习,纯粹用三角函数算出来。

核心代码只有五行(L89-L100):

num_timescales = self.embedding_dim // 2          # 384 // 2 = 192
log_timescale_increment = torch.log(10000.0 / 1.0) / (num_timescales - 1)
inv_timescales = 1.0 * torch.exp(torch.arange(192) * -log_timescale_increment)
scaled_time = position[:, :, None] * inv_timescales[None, None, :]
signal = torch.cat((torch.sin(scaled_time), torch.cos(scaled_time)), dim=2)

拆开来看,这套数学其实非常优雅:

行 在做什么 直觉理解
min_timescale=1、max_timescale=10000 频率区间取 [1, 10000] 从“很慢”到“很快”的 192 档频率
log + exp 相乘 频率按几何级数排布:1, 10^(i/191)×10000⁻¹ 的倒数 相邻频率比恒定,像钢琴键一样“等程”
position * inv_timescales 每个位置 × 每个频率 = 相位 位置 0、1、2… 各自拨动 192 根“弦”
sin / cos 拼接 192 对正弦余弦 → 384 维 奇数维补 sin、偶数维补 cos
F.pad(..., (0, dim % 2, ...)) 若维度为奇数补一维 0 384 是偶数,这里实际是空操作

为什么新手要记住这张图:每个位置得到一个独一无二的 384 维向量,低频分量变化缓慢(捕捉“大概在哪段”),高频分量变化剧烈(区分相邻位置)。更重要的是两个性质:

  • 零可学习参数:不像可学习位置表需要为训练长度逐位训练,公式天然能外推到更长的序列;
  • 相对位移可线性表达:位置 p+k 的向量可以由位置 p 的向量线性变换得到,这对注意力学习“谁在谁后面”非常友好。

__call__ 还留了一个 position 参数(L70-L87):默认用 arange(seq_length) 生成 0…63 的位置行(形状 [1, 64]);若传入显式 position [B, L],则支持“打包序列”场景——多条句子拼在一行里各自带位置。返回形状为 [1, 64, 384],广播加到整个 batch 上。

Transformer 文本塔:带掩码的残差注意力块 🧱

MLP 块:为什么掩码要乘两次?

MlpBlockWithMask(text_encoder.py#L107-L148)是标准的两层前馈网络:384 → 1536 → 384(intermediate_size: 1536 来自 config.json),激活函数在 ResidualAttentionBlock 里被指定为 ReLU。

关键在这两行(L143-L147):

x = x * mlp_mask[..., None]   # First masking.
x = self.c_proj(x)
x = x * mlp_mask[..., None]   # Second masking.

注意力层自带掩码机制,但 FFN 是每个位置独立算的——只要 pad 位置的行被清零,理论上信息不会“串”过来。但 pad 位置在残差路径中仍然可能携带 LayerNorm 产生的非零值,两次显式置零(进 FFN 前一次、出 FFN 后一次)是双保险,确保 pad 位置的表示在任何情况下都是纯零,不污染后续池化和注意力。

注意力块:一个块如何同时管理两种掩码

ResidualAttentionBlock(text_encoder.py#L151-L191)每层包含四件套:nn.MultiheadAttention(384 维、6 头)+ 两个 LayerNorm + 上面的 MLP 块,且都是 pre-LN 结构(先归一化再算注意力/FFN,见 L188-L191):

x = x + self.attention(self.ln_1(x), mask.permute(1, 0))
x = x = x + self.mlp(self.ln_2(x), mask)

注意这里出现了两种形状不同的掩码,是初读最容易困惑的点:

  • 传给 attention 的是 mask.permute(1, 0),即 [B, L],0=pad、1=有效;
  • 传给 mlp 的仍是 [L, B],与主张量 x [L, B, D] 维度对齐,直接逐元素相乘。

attention 方法内部(L178-L186)把布尔掩码“翻译”成 PyTorch 需要的加性掩码:

attn_mask = mask[:, None, None, :].repeat(1, self.n_head, x.shape[0], 1)
attn_mask[attn_mask == 0] = float('-inf')
attn_mask[attn_mask == 1] = 0
  • mask[:, None, None, :] 先把 [B, L] 广播成 [B, 1, 1, L],意思是“每个 query 都按 key 的 pad 状态过滤”;
  • 再 repeat 到每个注意力头,flatten(0,1) 合批,得到 [B*H, L, L] 加性掩码;
  • 0 → -inf:softmax 后得分归零,即“永远不许看 pad”;1 → 0:对有效位置不加偏移。

一句话总结:注意力用 -inf 加法掩码屏蔽 pad 的 key,MLP 用 乘 0 掩码清零 pad 的行,二者配合让 padding 在整个 12 层网络中彻底“隐身”。

胶水层:SequentialMultiInput 与 Transformer

  • SequentialMultiInput(text_encoder.py#L194-L203)解决一个工程痛点:标准 nn.Sequential 只能传单个张量,而这里每个残差块都要同时接收 x 和 mask(每层块的签名是 forward(x, mask) -> (x, mask))。它按顺序把元组解包透传即可;
  • Transformer(text_encoder.py#L206-L230)则只是把 12 个 ResidualAttentionBlock 装进上述容器,forward 返回 (x, mask)[0] 丢掉掩码。

掩码池化:只给“真实 token”算平均 🎯

文本塔输出的 64 个位置里,大部分可能是 pad。若直接对全部 64 个位置求平均,句子向量会被一堆零向量稀释——"a cat" 和 "a cat"(后面补 40 个 pad)将得到强度不同的向量。掩码池化(GlobalAvgPooling,text_encoder.py#L233-L285)就是为了解决这个问题。

核心逻辑等价于一个“分子分母都看掩码”的除法:

inputs = torch.where(compatible_paddings > 0, padded_value, inputs)  # pad 位置置 0
valid_inputs = torch.sum(1.0 - compatible_paddings, pooling_dims, keepdims=True) + epsilon
outputs = torch.divide(torch.sum(inputs, pooling_dims, keepdims=True), valid_inputs)
  • 分子:先 torch.where 把 pad 位置的表示清零,再求和——sum 只累计有效 token;
  • 分母:sum(1 - paddings) 数出有效 token 个数,+ 1e-8 的 epsilon 防止极端情况下除零;
  • 最后 squeeze 掉池化维度,[B, L, D] → [B, D]。

顺带一提 L270-L271 有个看似冗余的写法:

padded_value = torch.zeros_like(inputs)
padded_value = torch.ones_like(inputs) * padded_value

先建零矩阵再乘一,纯属从 JAX/追踪(trace)代码迁移 PyTorch 时留下的“静态值”习惯(L101-L102 的注释也佐证了这一点),功能上就是一个零张量。读懂这一点,就明白“逐行解析”为何必要——很多行是历史包袱,而非设计。

总装:TextEncoder 的完整前向 ⚙️

TextEncoder 类(text_encoder.py#L288-L342)把前面所有零件拧在一起。构造时它从配置读取文本塔超参(configuration_tips.py#L39-L44 负责把 config.json 的 text_config 转成字段):

超参 值 含义
hidden_size 384 文本向量维度,与图像塔输出对齐
intermediate_size 1536 FFN 中间层宽度(4 倍)
num_attention_heads 6 每头 64 维
num_hidden_layers 12 Transformer 层数
vocab_size 32000 SentencePiece 词表大小

前向 __call__(L324-L342)逐行看:

  1. mask = (paddings == 0).float():把“填充掩码”翻转成“有效掩码”(1=真实 token),并转置成 [L, B] 以匹配内部的 LND 布局;
  2. x = self.token_embedding(ids):查词嵌入表得到 [B, 64, 384];
  3. x = x * (384 ** 0.5):√d 缩放(scale_sqrt_depth 控制),CLIP 系列的经典技巧,让嵌入初值与后续残差加法的量级匹配,稳定训练;
  4. x = x + self.pos_embedder(seq_length):加上上一节解析的正弦位置编码,[1, 64, 384] 广播到整个 batch;
  5. 两次 permute 完成 NLD → LND → NLD 的布局切换(内部残差块按“序列优先”布局工作);
  6. 12 层 Transformer 提纯上下文表示;
  7. ln_final:出口 LayerNorm,平滑各方向尺度;
  8. self.pooling(x, paddings[:, :, None]):掩码平均池化,产出最终 [B, 384]。

输出就是一条 384 维句子向量,与视觉塔的 CLS token 处于同一对比学习空间——README 中零样本分类的相似度计算(cls @ text_emb.T)正是建立在它之上,温度系数 temperature_init_value 同样来自 config.json。

小结:一张表带走全文 ✅

模块 位置 一句话职责
Tokenizer text_encoder.py#L27-L48 SentencePiece 小写分词,定长 64,零填充并产出 pad 掩码
PositionalEmbedding text_encoder.py#L51-L104 几何级数频率 + sin/cos,零参数正弦位置编码
MlpBlockWithMask text_encoder.py#L107-L148 384→1536→384 FFN,双次掩码置零 pad
ResidualAttentionBlock text_encoder.py#L151-L191 pre-LN 残差块,-inf 注意力掩码 + 乘 0 FFN 掩码
Transformer text_encoder.py#L206-L230 12 层残差块堆叠,SequentialMultiInput 透传掩码
GlobalAvgPooling text_encoder.py#L233-L285 分子分母都看掩码,只对真实 token 求平均
TextEncoder text_encoder.py#L288-L342 嵌入 × √d + 正弦位置 → Transformer → LN → 掩码池化

至此,TIPSv1-s14 文本侧的 3400 万参数已全部交代清楚:它并不追求花哨结构,而是用 √d 缩放、正弦位置编码、双重掩码、掩码池化 这四个朴素而可靠的技巧,把任意短句稳稳压缩进 384 维对比空间。想继续深入视觉塔 ViT-S/14 的两个 CLS token 与 patch 空间特征,可以结合 image_encoder.py 与 modeling_tips.py 继续阅读,两者在 encode_image 中完成另一半的故事。

登录后查看全文
tipsv1-s14