SleepFM-Clinical睡眠分期微调教程:SleepEventLSTMClassifier与掩码加权交叉熵损失完全指南

原创2026-10-31 14:01:562,223 阅读

SleepFM-Clinical睡眠分期微调教程:SleepEventLSTMClassifier与掩码加权交叉熵损失完全指南

SleepFM-Clinical 是发表在 Nature Medicine 的多模态睡眠基础模型(Sleep Foundation Model)开源实现。本文带你从零完成 SleepFM-Clinical 睡眠分期微调:理解 SleepEventLSTMClassifier 的"空间+时序"双通路结构,吃透掩码加权交叉熵损失(masked weighted cross entropy loss)的设计动机,并跑通预处理→微调→评估的完整流水线。

项目速览:为什么需要睡眠基础模型

多导睡眠图(PSG)包含脑电、心电、呼吸、肌电等多通道信号,是睡眠分析的"金标准",但人工判读成本极高。SleepFM 在约 65,000 名受试者、超过 585,000 小时的 PSG 记录上用对比学习预训练,睡眠分期平均 F1 达到 0.70–0.78,与专用模型 U-Sleep、YASA 不相上下,还能预测 130 种疾病风险。

仓库自带三个可下载模型,本教程使用的睡眠分期模型就在其中:

模型 用途 路径
预训练基座 对比学习预训练产物 sleepfm/checkpoints/model_base
睡眠分期模型 本文主角 sleepfm/checkpoints/model_sleep_staging
疾病预测模型 CoxPH 生存分析 sleepfm/checkpoints/model_diagnosis

项目结构与核心文件导航

整个流水线只有 4 步,对应文件非常清晰:

  1. 预处理:sleepfm/preprocessing/preprocessing.py —— 把 .EDF 原始文件转成模型可读的 .hdf5
  2. 预训练:sleepfm/pipeline/pretrain.py(基座模型已提供,可跳过)
  3. 睡眠分期微调:sleepfm/pipeline/finetune_sleep_staging.py
  4. 测试集评估:sleepfm/pipeline/evaluate_sleep_staging.py

关键配置集中在 sleepfm/configs/ 目录:

环境安装与数据准备:3步跑通

项目推荐 Python 3.10 + CUDA 12.4,最小可用配置为 RTX 2080 Ti(需减小 batch size),8 核 CPU、32 GB 内存。

git clone https://gitcode.com/gh_mirrors/sl/sleepfm-clinical
cd sleepfm-clinical
conda env create -f env.yml
conda activate sleepfm_env

数据准备只需满足两点:

  1. 信号数据:PSG 文件经预处理后以 .hdf5 存放,目录结构按数据集名组织,如 <data>/mesa/xxx.hdf5
  2. 分期标注:每个研究对象一份 CSV,列格式为 Start,Stop,StageName,StageNumber,例如:
Start,Stop,StageName,StageNumber
0.0,5190.0,Wake,0
5190.0,6480.0,REM,4

其中 StageNumber 采用 5 类标准编码:0=Wake、1=N1、2=N2、3=N3、4=REM。示例标注可参考 notebooks/demo_data/demo_psg.csv。

💡 官方提供了 MESA 小数据集做端到端演示(参考 notebooks/demo.ipynb),在 A40 上微调一个 epoch 约 1 分钟,非常适合先跑通流程再替换为自己的数据。

微调实战:一条命令启动睡眠分期训练

修改 config_finetune_sleep_events.yaml 中的 data_path、model_path、labels_path 指向你的本地路径后:

cd sleepfm/pipeline
python finetune_sleep_staging.py --config_path ../configs/config_finetune_sleep_events.yaml

训练过程的核心逻辑在 finetune_sleep_staging.py:

  • 优化器为 AdamW(学习率 lr: 0.001),配合 ReduceLROnPlateau 在验证损失停滞 10 个 epoch 后把学习率降到 1/10
  • 每 save_iter 步保存断点 checkpoint.pth,可随时 --checkpoint_path 续训
  • 每当验证损失刷新最低,就自动保存 best.pth 并同步 config.json

常用超参数建议保持默认起步:

参数 默认值 含义
embed_dim 128 嵌入维度,需与基座模型一致
num_classes 5 睡眠分期类别数
max_seq_length 8196 单序列最大时间步
batch_size 16 显存不足时优先调小
channel_like BAS/RESP/EKG/EMG 参与分类的模态组
max_files 100 调试阶段限制样本数,快速验证

模型拆解:SleepEventLSTMClassifier 双通路设计

模型定义位于 models.py,前向流程可以概括为 "每个时间步先压缩空间维度,再沿时间轴建模" 两条通路:

(B, C, S, E) 多通道token序列
      │
 ① AttentionPooling 空间池化 ── 对每个时间步的 C 个通道做注意力加权平均
      │                          (通道缺失时用 mask 排除)
 ② PositionalEncoding + LayerNorm ── 注入时间位置信息
      │
 ③ TransformerEncoder ── 时间维度上下文建模(key_padding_mask 屏蔽padding)
      │
 ④ 双向 LSTM ── 捕捉睡眠状态转换的长程依赖(如 Wake→N1→N2 的周期)
      │
 ⑤ 全连接层 fc ── 输出 (B, S, 5),即每个时间步的 5 类分期 logits

几个值得注意的设计点:

  • 通道级掩码:不同 PSG montage 记录的电极数量不同,spatial_pooling 用 key_padding_mask 只对真实存在的通道做注意力平均(AttentionPooling),这就是模型"适配任意 montage"的关键
  • 逐时间步输出:与其他分类头输出单一向量不同,该模型对序列中每一帧都给出分期预测,天然匹配按分钟标注的睡眠分期任务
  • 双向 LSTM:睡眠分期允许使用未来上下文(如回看 REM 眼动特征),双向结构对此更友好

数据侧由 SleepEventClassificationDataset 加载 .hdf5 信号与分期标注,collate 函数 负责把变长序列 padding 到同一长度并生成掩码(0=真实数据,1=填充)。

损失函数深潜:掩码加权交叉熵为什么这么设计

损失函数实现仅 20 行,位于 finetune_sleep_staging.py,由三个机制叠加而成:

① 加权(weighted)——对抗类别不平衡

一夜睡眠中 N3 深睡与 REM 占比天然低于 Wake/N2,且标注质量差异大。代码为 5 个类别赋予不同权重:

类别 Wake N1 N2 N3 REM
权重 1 4 2 4 3

少数类(N1、N3)的误判代价被放大,防止模型"躺平"只预测多数类。

② 掩码(masked)——padding 不参与计算

batch 内各夜睡眠时长不同,collate 后短序列被 padding。损失先 reshape 成 (B*S, 5),再乘以 (mask == 0) 并把总和除以真实时间步数:

loss = F.cross_entropy(outputs, y_data, weight=weights_tensor, reduction='none')
loss = loss * (mask == 0).float()
loss = loss.sum() / (mask == 0).float().sum()

这样填充帧不产生梯度,且损失按"有效时间步"归一化,不受 batch 内序列长短影响——这是长变长 PSG 序列训练的必备技巧。

③ 交叉熵(cross entropy):标准的 5 类逐帧分类目标,与 AUC/F1 指标方向一致。

评估流程:从 best.pth 到分期指标

微调完成后,best.pth 与 config.json 会保存在输出目录(默认按 模型名_数据集_标注前缀_通道 自动命名)。评估脚本 evaluate_sleep_staging.py 会:

  1. 加载 best.pth,在指定 split(默认 test)上推理
  2. 对输出做 softmax 并连同 logits、targets、mask、文件路径一起存成 5 个 pickle
  3. 后续可基于 mask 剔除 padding 帧,自行计算逐类 F1、混淆矩阵等指标

配套的运行脚本 evaluate_sleep_staging.sh 已写好参数模板,只需把 model_path 改成你的训练输出目录:

cd sleepfm/pipeline
bash evaluate_sleep_staging.sh

评估不需要 GPU,几秒即可完成(MESA 规模)。

常见问题排查清单

  • labels_path 格式报错:确认 CSV 含 StageNumber 列,且文件名(不含 .csv)与 .hdf5 文件名一致
  • 验证损失不降:先检查 dataset 参数是否与数据目录名一致;小数据集可把 max_files 调小快速过拟合验证
  • 显存不足:依次调小 batch_size → max_seq_length → num_workers
  • 想续训:传入 --checkpoint_path 训练输出目录,脚本会读取其中的 checkpoint.pth 从断点恢复
  • 结果与论文不一致:官方提示小数据集(如 MESA)的指标仅作流程验证,不代表论文中的完整数据表现

结语

到这里,你已经掌握了 SleepFM-Clinical 睡眠分期微调的全部要点:SleepEventLSTMClassifier 用"注意力空间池化 + Transformer + 双向 LSTM"兼顾多模态通道与时间动态,掩码加权交叉熵则让 padding 无干扰、少数类不缺席。完成本任务后,同一框架只需换模型类与损失函数即可扩展到 疾病预测(CoxPH) 等其他临床下游任务,建议配合 notebooks/demo.ipynb 的端到端演示继续探索。

登录后查看全文
sleepfm-clinical