SleepFM-Clinical睡眠分期微调教程:SleepEventLSTMClassifier与掩码加权交叉熵损失完全指南
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 步,对应文件非常清晰:
- 预处理:sleepfm/preprocessing/preprocessing.py —— 把
.EDF原始文件转成模型可读的.hdf5 - 预训练:sleepfm/pipeline/pretrain.py(基座模型已提供,可跳过)
- 睡眠分期微调:sleepfm/pipeline/finetune_sleep_staging.py
- 测试集评估:sleepfm/pipeline/evaluate_sleep_staging.py
关键配置集中在 sleepfm/configs/ 目录:
- config_finetune_sleep_events.yaml:微调超参数
- channel_groups.json:通道分组定义
- dataset_split.json:train/valid/test 划分
环境安装与数据准备: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
数据准备只需满足两点:
- 信号数据:PSG 文件经预处理后以
.hdf5存放,目录结构按数据集名组织,如<data>/mesa/xxx.hdf5 - 分期标注:每个研究对象一份 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 会:
- 加载
best.pth,在指定 split(默认test)上推理 - 对输出做
softmax并连同logits、targets、mask、文件路径一起存成 5 个 pickle - 后续可基于
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 的端到端演示继续探索。