如何看懂scFM-dataselection:微软Nature Methods单细胞基础模型预训练实验的完整入门指南

原创2026-10-18 14:20:471,677 阅读
文章标签:人工智能大模型基础模型预训练生物信息学科研

如何看懂scFM-dataselection:微软Nature Methods单细胞基础模型预训练实验的完整入门指南

scFM-dataselection 是微软为 Nature Methods 论文《Evaluating the role of pretraining dataset size and diversity on single-cell foundation model performance》公开的单细胞基础模型预训练检查点合集,共包含 455 个模型资产:125 个 Geneformer、125 个 scVI、125 个 SSL/MLP 神经网络检查点,以及 80 个 PCA 主成分矩阵。对做单细胞组学(single-cell foundation model)研究的新手来说,这份仓库最大的价值在于:它把"预训练数据量与多样性到底影响多大"这一问题的全部实验结果,以可下载、可加载的形式完整公开了,你不需要重跑任何训练,就能直接对比不同数据采样策略下的模型行为。

🧭 一分钟看懂这个项目在做什么

单细胞基础模型的"基础"来自海量预训练数据。微软团队系统性地回答了三个问题:

  1. 数据量:用 1%、10%、25%、50%、75%、100% 的预训练语料,模型能力如何变化?
  2. 数据多样性:随机抽样(random)、按细胞类型重加权(celltype_reweighted)、几何草图(geometric_sketching)三种采样策略各有什么影响?
  3. 干扰实验:在语料中掺入 10% / 50% 扰动 spike-in(spikein_10 / spikein_50),模型还能保持稳健吗?

每个条件都跑了 5 个随机种子(seed),保证结论不是偶然。完整背景可先读 README.md 前 45 行,论文引用信息在 CITATION.cff。

📦 455 个模型资产全景图

资产数量与规模一览(完整清单见 model-index.csv):

模型家族 数量 检查点格式 说明
Geneformer 125 model.safetensors + config.json BERT 架构,输入按表达量排序的基因序列
scVI 125 model.safetensors + config.json 深度生成模型,输入 AnnData
SSL/MLP 125 model.safetensors + config.json 自编码式无监督表示学习
PCA components 80 components.npy + config.json 经典降维基线

完整下载约 22.4 GB,仓库按 Python 3.10 + CPU 环境验证过所有加载示例,依赖版本锁死在 requirements.txt 中。

🗂️ 目录结构:按"模型家族 → 采样策略 → 数据量_种子"组织

所有权重统一放在 portable-checkpoints/ 下,目录命名规则非常规整:

portable-checkpoints/
├── geneformer/          # Geneformer 检查点(5 种采样策略)
├── scvi/                # scVI 检查点
├── ssl/                 # SSL/MLP 检查点
└── pca/                 # PCA 主成分矩阵(3 种采样策略)
    └── <采样策略>/
        └── idx_<数据比例>pct_seed<种子号>/
            ├── config.json
            └── model.safetensors  # 或 components.npy(PCA)

如何解读一个目录名——以 idx_10pct_seed5 为例:

片段 含义
10pct 使用了 10% 规模的预训练语料
seed5 第 5 号随机种子

而它上一级的目录名代表采样策略:

  • random/:纯随机抽样(唯一包含 idx_100pct_seed25~seed29 完整数据组的策略,作为全量基线)
  • celltype_reweighted/:按细胞类型重新加权,缓解类型不均衡
  • geometric_sketching/:几何草图采样,在降维空间保留数据几何结构
  • spikein_10/、spikein_50/:掺入 10% / 50% 扰动数据的稳健性实验

👉 想对比"同数据量、不同采样策略",只需横向对比同一 idx_* 下的四个目录;想对比"同策略、不同数据量",纵向看 1pct → 75pct 即可。

📋 model-index.csv:所有检查点的"总目录"

每个模型文件夹在 model-index.csv 中都有一行登记,字段含义如下(表头位于 model-index.csv):

  • family:模型家族(Geneformer / scVI / SSL / PCA)
  • sampling:采样策略(如 celltype_reweighted、random)
  • percentage / seed:数据比例与随机种子
  • experiment_type:main 为主实验,spike_in 为扰动实验
  • portable_directory:该检查点的确切目录路径

下载单个模型时,可以直接用这份索引配合 allow_patterns 只拉取需要的文件夹,避免 22.4 GB 全量下载。

🚀 最小示例:加载你的第一个检查点

加载逻辑全部封装在 tools/portable_models.py 的 load_model() 函数中(tools/portable_models.py),它会根据 config.json 自动识别家族类型。核心用法:

sys.path.insert(0, "tools")
from portable_models import load_model

geneformer = load_model(
    "portable-checkpoints/geneformer/random/idx_100pct_seed25"
)

不同家族的输入要求(详见 README.md 的 "Load a checkpoint" 一节):

家族 输入 备注
Geneformer 排序后的基因 ID 张量 需配合 public-resources/geneformer/ 下的 tokenizer 字典做归一化
SSL / PCA 19,331 基因矩阵(scTab 基因顺序) 基因顺序见 public-resources/sctab/adata_var.csv
scVI AnnData 对象(raw counts 在 X 中) 基因顺序必须与 config.json 的 gene_names 完全一致,否则直接报错

几个值得注意的工程细节:

  • SSL 模型通过 tools/_native_ssl.py 从 public-resources/ssl-source/ 的原始源码动态构建模型类,保证了与论文训练代码一致;
  • 所有加载都是严格校验模式——权重缺漏、基因顺序不符、PCA 矩阵形状不一致都会主动抛错,防止你拿着"错配"的权重得出错误结论。

⚠️ 新手常见坑位清单

  1. Python 版本:示例基于 Python 3.10 在 CPU 上测试通过,其他版本未验证;
  2. 只下需要的:全量 22.4 GB,按需使用 allow_patterns 下载单个 idx_* 目录,并记得带上 model-index.csv、tools/、public-resources/ 和 requirements.txt;
  3. scVI 的基因顺序陷阱:var_names 顺序与 config.json 不一致会直接抛 ValueError,这是保护性设计而非 bug;
  4. Geneformer ≠ 官方 Geneformer:这里的权重是本研究从零训练的模型,tokenizer 字典(Apache-2.0)来自上游 Geneformer 项目,但权重并非上游预训练权重(见 THIRD_PARTY_NOTICES.md);
  5. 许可:模型权重与加载代码为 MIT 许可,商用前建议通读 LICENSE 与 THIRD_PARTY_NOTICES.md。

📌 使用与引用

使用这批检查点时,请按 CITATION.cff 的要求引用原论文:

DenAdel, A., Hughes, M., Thoutam, A., et al. Evaluating the role of pretraining dataset size and diversity on single-cell foundation model performance. Nature Methods 23, 1447-1457 (2026).

如果你要克隆本仓库,仓库地址为 https://gitcode.com/hf_mirrors/microsoft/scFM-dataselection ;模型本体则推荐通过 Hugging Face 的 snapshot_download(repo_id="microsoft/scFM-dataselection")获取,具体命令见 README.md 的 "Download" 章节。

✅ 小结

scFM-dataselection 用统一的目录规范和一张 model-index.csv,把"预训练数据量 × 采样多样性 × 3 类基础模型 + PCA 基线"的 455 个实验结果整理成了一个可检索、可加载的资产库。新手只需记住三件事:按目录名读懂实验条件、用 model-index.csv 定位模型、用 load_model() 一键加载,就可以开始复现或对比 Nature Methods 论文中的任何结论了。

登录后查看全文
scFM-dataselection