源码逐行解析(下):text_encoder.py的Transformer文本塔、正弦位置编码与掩码池化
源码逐行解析(下):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)做三件事:
- 定长填充:预分配
(B, 64)的零矩阵,每条句子只填前min(len(ids), 64)个位置,超长的直接截断; - 返回填充掩码:
is_padding = (tokens == 0),即“哪些位置是补的 0”; - 词表中 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)逐行看:
mask = (paddings == 0).float():把“填充掩码”翻转成“有效掩码”(1=真实 token),并转置成[L, B]以匹配内部的 LND 布局;x = self.token_embedding(ids):查词嵌入表得到[B, 64, 384];x = x * (384 ** 0.5):√d 缩放(scale_sqrt_depth控制),CLIP 系列的经典技巧,让嵌入初值与后续残差加法的量级匹配,稳定训练;x = x + self.pos_embedder(seq_length):加上上一节解析的正弦位置编码,[1, 64, 384]广播到整个 batch;- 两次
permute完成NLD → LND → NLD的布局切换(内部残差块按“序列优先”布局工作); - 12 层 Transformer 提纯上下文表示;
ln_final:出口 LayerNorm,平滑各方向尺度;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 中完成另一半的故事。