用途:当需要比 PCA 结构更丰富的 transformer 式逐细胞表示时使用,包括细胞嵌入、零样本或微调后的细胞类型注释、在基础模型隐空间上的批次整合,以及在模型允许时的扰动预测。它不覆盖基于 marker 规则的注释器(CellTypist/SCSA/gpt4celltype)或参考映射注释器(popV/scmap/SingleR),那些属于 single-cell-annotation 技能;基础模型嵌入常作为下游注释/整合的输入空间。
主要能力与后端选择:五个后端中,scGPT 支持嵌入、整合、微调后注释,人/鼠,gene symbol,最低 8GB 显存,可用 CPU;Geneformer 支持嵌入、整合、微调后注释,人,ENSEMBL ID,4GB,可用 CPU;scFoundation 支持嵌入、整合,人,symbol,16GB,不可 CPU;UCE 支持嵌入、整合,7 物种跨物种,symbol,16GB,不可 CPU;CellPLM 支持嵌入、整合、零样本注释,人,symbol,8GB,可用 CPU,推理最快。
用法:使用 import omicverse as ov,创建 ov.llm.SCLLMManager(model_type=..., model_path=..., device=...),然后调用 get_embeddings(adata) 得到嵌入写入 obsm["X_<backend>"];annotate_cells(adata) 得到 obs["cell_type_<backend>"];integrate(adata, batch_key="batch") 写入 X_<backend>_integrated;必要时用 fine_tune(train_adata, valid_adata, task="annotation") 微调注释头。可用 ov.utils.registry_lookup("scgpt") 或 registry_lookup("foundation model embedding") 发现入口。
限制与注意:scGPT 预训练权重只输出嵌入,做注释前需先 fine_tune(task='annotation');Geneformer 需先通过 ov.utils.geneid_to_ensembl(...) 将 symbol 转为 ENSEMBL;不要在 scGPT/Geneformer/UCE/CellPLM 上尝试 predict_perturbation,该路径属于 scFoundation 或特定领域,需要扰动时优先使用 single-cell-perturbation 技能。结果约定:obsm 存嵌入,uns["neighbors"] 存基于嵌入的 kNN 图,obs 注释列带后端标识。2026 起旧的 ov.fm.run 已移除,SCLLMManager 是唯一受支持入口。各方法签名、返回形状与后端细节见 reference.md。