如何快速下载scFM-dataselection:22.4GB、455个单细胞基础模型检查点的全量与按需下载教程

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

如何快速下载scFM-dataselection:22.4GB、455个单细胞基础模型检查点的全量与按需下载教程

scFM-dataselection 是微软团队发布的单细胞基础模型检查点集合,共包含 455 个模型(Geneformer 125 个、scVI 125 个、SSL 125 个、PCA 成分矩阵 80 组),完整体积约 22.4 GB。这份 README.md 说明它是《Nature Methods》论文"Evaluating the role of pretraining dataset size and diversity on single-cell foundation model performance"的配套资源。本文将手把手教你:如何全量下载 22.4GB 数据,以及如何只按需下载你真正需要的那几个检查点,避免浪费磁盘空间。

📦 仓库内容一览:455 个检查点都有什么

下载前先了解目录结构,下载时心里才有数。所有模型都放在 portable-checkpoints/ 下,按四大类分组:

模型族 数量 说明 文件形式
Geneformer 125 基因序列基础模型(BERT 架构) model.safetensors
scVI 125 单细胞变分推断模型 model.safetensors
SSL/MLP 125 自监督学习模型 model.safetensors
PCA 80 降维成分矩阵 components.npy
合计 455 约 22.4 GB —

每个检查点目录的命名规则为:<模型族>/<采样策略>/idx_<比例>pct_seed<种子号>,例如:

采样比例覆盖预训练语料的 1%、10%、25%、50%、75%、100%,另有 spikein_10、spikein_50 扰动实验。完整的模型清单和训练配置见 model-index.csv,按需下载时它就是你的"目录索引"。

⚡ 全量下载:几行命令下完 22.4GB

适合需要完整复现论文、或有足够磁盘空间的场景。官方推荐使用 Python 3.10(示例已在 CPU 环境验证)。

方法一:Python 的 snapshot_download(推荐)

from huggingface_hub import snapshot_download

root = snapshot_download(
    repo_id="microsoft/scFM-dataselection",
    local_dir="scFM-dataselection",
)

方法二:命令行 huggingface-cli

huggingface-cli download microsoft/scFM-dataselection --local-dir scFM-dataselection

💡 提示:大文件下载建议放在稳定的 Wi-Fi 或有线网络环境下执行,snapshot_download 支持断点续传,中断后重新运行即可接着下。

🎯 按需下载:只拿你需要的模型

22.4 GB 不小,如果你的任务只涉及某一个模型(比如只复现 100% 随机采样的 Geneformer),用 allow_patterns 过滤即可只拉取指定目录。

from huggingface_hub import snapshot_download

snapshot_download(
    repo_id="microsoft/scFM-dataselection",
    local_dir="scFM-dataselection",
    allow_patterns=[
        "portable-checkpoints/geneformer/random/idx_100pct_seed25/*",
        "model-index.csv",
        "tools/*",
        "public-resources/*",
        "requirements.txt",
    ],
)

⚠️ 注意:按需下载时,README 明确要求一并包含 model-index.csv、tools/*、public-resources/* 和 requirements.txt,否则加载代码会缺少共享的 tokenizer 字典等依赖。

如何确定要下载哪些目录?打开 model-index.csv,每行都包含 family(模型族)、sampling(采样策略)、percentage(采样比例)、seed(随机种子)和 portable_directory(模型文件夹路径)字段,直接按条件筛选后填入 allow_patterns 即可。

🌐 备用方案:git 克隆镜像仓库

如果你的环境不方便使用 Hugging Face,也可以直接克隆 gitcode 上的镜像仓库:

git clone https://gitcode.com/hf_mirrors/microsoft/scFM-dataselection

克隆下来后目录结构与上文完全一致,同样包含 portable-checkpoints/、tools/、public-resources/ 等内容。

🚀 下载完成后的验证与加载

下载完成后,先安装官方验证过的 CPU 依赖栈(版本清单见 requirements.txt,包含 torch==2.0.1、transformers==4.48.0、safetensors 等):

python -m pip install -r requirements.txt

然后用仓库自带的统一加载入口 tools/portable_models.py 验证模型能否正常加载。它以 load_model 函数同时支持四类检查点:

  • Geneformer:按 BERT 严格加载 config.json + model.safetensors
  • SSL:原生 PyTorch 结构加载
  • scVI:需要传入基因顺序与 config.json 中 gene_names 一致的 AnnData 对象
  • PCA:返回 numpy 成分数组,并校验 shape 与 dtype

README 中给出了加载示例(Geneformer 前向推理、SSL 重构、PCA 投影),可复制到你的数据上运行前,先按论文完成预处理:Geneformer 需要排序后的基因输入并使用 public-resources/geneformer/ 中的 tokenizer 字典归一化;SSL 和 PCA 使用论文中 19,331 基因的 scTab 基因顺序(见 public-resources/sctab/adata_var.csv)。

📝 许可与引用

  • 许可协议:模型权重、PCA 成分和加载代码均为 MIT 协议;Geneformer tokenizer 文件为 Apache-2.0,详见 LICENSE 与 THIRD_PARTY_NOTICES.md
  • 引用要求:在研究中使用这些检查点时,请引用 CITATION.cff 中指定的论文:DenAdel 等,《Nature Methods》23, 1447–1457 (2026)

✅ 小结

  • 全量下载:snapshot_download 或 huggingface-cli,一次拿全 455 个检查点(约 22.4 GB)
  • 按需下载:用 model-index.csv 定位目标目录,allow_patterns 精准过滤,记得带上 tools/*、public-resources/* 等公共文件
  • 备用通道:git clone 镜像仓库,适合无法访问 Hugging Face 的环境
  • 下载后运行 pip install -r requirements.txt,即可用 tools/portable_models.py 验证并加载任意检查点
登录后查看全文
scFM-dataselection