如何快速下载scFM-dataselection:22.4GB、455个单细胞基础模型检查点的全量与按需下载教程
如何快速下载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<种子号>,例如:
- portable-checkpoints/geneformer/random/ — 随机采样
- portable-checkpoints/scvi/celltype_reweighted/ — 细胞类型重加权
- portable-checkpoints/ssl/geometric_sketching/ — 几何草图采样
- portable-checkpoints/pca/ — PCA 成分(如 idx_100pct_seed25/config.json 中为 19331×50 的 float64 矩阵)
采样比例覆盖预训练语料的 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 验证并加载任意检查点