LaBraM源码深度阅读:从PatchEmbed到lm_head的EEG大模型代码实现原理

原创2026-11-02 09:39:381,741 阅读

LaBraM源码深度阅读:从PatchEmbed到lm_head的EEG大模型代码实现原理

LaBraM(Large Brain Model)是 ICLR 2024 spotlight 的 EEG 大模型,借鉴了大语言模型(LLM)的范式:先用向量量化的"神经 tokenizer"把原始脑电信号压缩成离散 token,再通过 12 层 Transformer 做掩码预测预训练,最终用 lm_head 输出词表中的神经代码。本文带你逐行读懂它的关键源码:从 modeling_finetune.py 的 PatchEmbed、modeling_pretrain.py 的 Transformer 主干,到 norm_ema_quantizer.py 的 8192 项码本,完整还原"EEG 版 GPT"的代码实现原理。

LaBraM EEG大模型架构:上半部分为神经tokenizer训练的VQ-NSP流程,下半部分为LaBraM掩码预训练流程

上图即 LaBraM 的整体架构:上半部分是神经 Tokenizer 的训练(VQ-NSP,预测傅里叶谱),下半部分是 LaBraM 的掩码预训练(Temporal Encoder → Transformer Block × L → Token Prediction Head)。

🧠 先建立全局观:两个阶段、三个核心类

LaBraM 的训练分为两步,源码与论文一一对应:

阶段 入口脚本 模型定义 核心类
1️⃣ 训练神经 Tokenizer run_vqnsp_training.py modeling_vqnsp.py VQNSP
2️⃣ 掩码预训练 LaBraM run_labram_pretraining.py modeling_pretrain.py NeuralTransformerForMaskedEEGModeling
3️⃣ 下游微调 run_class_finetuning.py modeling_finetune.py NeuralTransformer

数据在代码中统一表示为 B, N, A, T 四维张量:批次 × 通道数 N × 时间片 A × 采样点 T。以 base 配置为例:A=8、T=200,即 8 个 1 秒的时间片(200 Hz 采样率,共 8 秒),整个序列被切成 N×8 个长度为 200 的 EEG patch——这就是模型眼中的"词"。

📦 EEG 信号如何变成 token:PatchEmbed 与 TemporalConv 的双重身份

打开 modeling_finetune.py,会看到两个做"patch 嵌入"的模块,它们由 in_chans 参数自动切换(见 NeuralTransformer.init 第 276 行的三目判断):

  • TemporalConv(in_chans=1 时启用):用于处理原始 EEG 波形。它把每个 200 点的时间片看作一维信号,串联 3 个一维卷积(核大小 15/3/3、步长 8/1/1)加 GELU 与 GroupNorm,把 B N A T 重排后压缩成 B (N·A) (T·C),其中输出通道 out_chans=8,最终每个 patch 得到 1600 维特征再投影。这是模型"看波形"的眼睛。
  • PatchEmbed(in_chans≠1 时启用):一个 kernel=(1, patch_size)、stride=(1, patch_size) 的 nn.Conv2d,等价于逐 patch 的线性投影。注释写得很直白:当输入已经是量化后的神经代码(in_chans=codebook_dim=64)时,比如 VQ-NSP 的 decoder 就靠它把码本维度投影到隐层维度。

也就是说,"切 patch"这个动作本身是免费的(时间维本来按 200 点切好了),真正有参数的是每个 patch 内部的时序编码。

🔤 神经 Tokenizer:VQ-NSP 把波形压成 8192 种"脑电字"

modeling_vqnsp.py 中的 VQNSP 由四部分组成:

  1. Encoder:一个 NeuralTransformer(12 层、embed_dim=200),以 return_patch_tokens=True 输出每个 patch 的特征;
  2. 量化器 NormEMAVectorQuantizer:8192 个码字(n_embed)、维度 64(embed_dim)。在 norm_ema_quantizer.py 的 forward 中,输入先做 L2 归一化,再用"平方差展开式"(第 157-159 行)向量化地计算每个特征到 8192 个码字的距离,argmin 即得到神经代码索引 encoding_indices。码本不用梯度下降,而是 EMA(指数移动平均,decay=0.99)更新,支持 k-means 初始化(--quantize_kmeans_init)和多卡 all_reduce 统计;
  3. Decoder:3 层 NeuralTransformer,输入通道就是 64 维码字,经 PatchEmbed 线性投影恢复特征;
  4. 谱预测头:两个 MLP(decode_task_layer 与 decode_task_layer_angle),分别重建幅度谱与相位。

损失函数在 forward 中:对每个 200 点时间片做 FFT,分别标准化幅度谱和相位,与 decoder 输出算 MSE,再加量化损失 emb_loss,三项之和即总损失。训练收敛后,get_codebook_indices(第 134-136 行)就能把任意 EEG 变成一串 0~8191 的整数索引——这串整数就是后面预训练任务的"词"。

🏗️ 12 层 Transformer 主干:mask_token、pos_embed 与 time_embed 的协作

预训练模型 NeuralTransformerForMaskedEEGModeling 定义在 modeling_pretrain.py,关键组件一目了然:

  • cls_token 与 mask_token:两个可学习向量。前向时(forward_features 第 137-138 行),被掩码的 patch 特征用一行插值 x*(1-w) + mask_token*w 整体替换成 mask_token;
  • pos_embed:形状 (1, 129, embed_dim)。第 0 位对应 cls,后 128 位对应电极位置。不同数据集通道数不同,所以用 get_input_chans(utils.py)把通道名映射到标准 10-20 系统的下标,再按 input_chans 索引取出对应位置嵌入——这是 LaBraM 跨数据集统一电极位置的关键设计;
  • time_embed:形状 (1, 16, embed_dim),编码 patch 在时间轴上的第几片,同一通道不同时刻的 patch 因此可区分;
  • Block:复用 modeling_finetune.py 的 Block。注意两个大模型技巧:QK-Norm(对 Q/K 每头做 LayerNorm,qk_norm=partial(nn.LayerNorm, eps=1e-6))保证训练稳定,以及 LayerScale(init_values=0.1 时引入 gamma_1/gamma_2 缩放残差分支)。base 模型 12 层、embed_dim=200、10 头,参数量约 50M 级。

random_masking(engine_for_pretraining.py)则完全照搬 BEiT 的做法:对每个样本生成随机噪声、argsort 后保留前 (1-mask_ratio) 的位置,掩码率默认 0.5——一半 patch 被抹掉,模型要猜回来。

🎯 最后一公里:lm_head 与"对称掩码"损失

lm_head 在 modeling_pretrain.py 只有一行:

self.lm_head = nn.Linear(embed_dim, vocab_size)  # vocab_size = 8192

它把每个 patch 的隐层表示投影到 8192 维词表上,与 BERT/LLM 的预测头完全同构——区别只是"词表"是 8192 个神经代码而非英文词。

真正有趣的是预训练入口 NeuralTransformerForMEM(modeling_pretrain.py):它在同一次前向中对同一个掩码的互补集合各跑一遍 student(bool_masked_pos 和 ~bool_masked_pos),分别用同一个 lm_head 预测被掩掉的代码,两个交叉熵相加(engine_for_pretraining.py 第 104-106 行)。即掩码部分和未掩码部分互为监督,等效于每个样本做了两次 MLE,这就是图中"Symmetric Mask"的由来。

另外,tokenizer 在预训练阶段是冻结的(with torch.no_grad() 下调用 get_codebook_indices,见 engine_for_pretraining.py),标签直接来自码本索引,训练只更新 Transformer 主干与 lm_head。

🚀 预训练完成之后:微调阶段的"瘦身"

预训练结束后,仓库直接提供 checkpoints/labram-base.pth。下游微调时换用 modeling_finetune.py 的 NeuralTransformer:去掉 mask_token 与 lm_head,末端改为

self.head = nn.Linear(embed_dim, num_classes)

特征提取时(forward_features)默认对全部 patch token 做均值池化(use_mean_pooling=True)再过 fc_norm 与分类头。以 TUAB 异常检测为例(run_class_finetuning.py),典型启动参数为 --model labram_base_patch200_200 --finetune ./checkpoints/labram-base.pth,并配合 --abs_pos_emb、--disable_rel_pos_bias、--layer_decay 0.65 等;数据预处理脚本为 dataset_maker/make_TUAB.py 与 dataset_maker/make_TUEV.py。

三个规模的模型在两个文件中对称注册,方便按需选用:

注册名(预训练 / 微调) 层数 embed_dim 头数
labram_base_patch200_1600_8k_vocab / labram_base_patch200_200 12 200 10
labram_large_patch200_1600_8k_vocab / labram_large_patch200_200 24 400 16
labram_huge_patch200_1600_8k_vocab / labram_huge_patch200_200 48 800 16

(分别见 modeling_pretrain.py 与 modeling_finetune.py。)

📚 核心源码地图与小结

把关键文件串起来,LaBraM 的数据流就是一条清晰的流水线:

  1. dataset_maker/ 与 data_processor/dataset.py:原始 EEG → HDF5 → B N A T 张量;
  2. modeling_vqnsp.py:波形 → 8192 词表的神经代码(VQ-NSP);
  3. modeling_pretrain.py:掩码 + TemporalConv + 12 层 Transformer + lm_head,交叉熵预测被掩码的代码;
  4. modeling_finetune.py:加载预训练权重,均值池化 + 分类头,适配 TUAB/TUEV 等下游任务。

可以看到,LaBraM 在代码层面几乎是"EEG 版的 BEiT/LLM":TemporalConv/PatchEmbed 对应图像里的 Patch Embedding,VQNSP 对应 VQ 离散化,lm_head 对应语言模型头,而电极位置嵌入 pos_embed、对称掩码损失则是面向 EEG 数据的独有设计。读懂这条从 patch 到 lm_head 的路径,也就掌握了 EEG 大模型预训练的通用范式。

登录后查看全文
LaBraM