ov.fm — 基础模型模块

ov.fm — 基础模型模块#

ov.fm 提供了一个统一 API，用于发现、选择、验证、运行和解读单细胞基础模型。它通过一致的基于 AnnData 的接口封装了 17+ 个模型（scGPT、Geneformer、UCE、scFoundation、CellPLM 等），并具备自动数据分析和模型选择功能。

!!! note “何时使用 ov.fm”

当您希望将预训练基础模型应用于单细胞数据，同时无需手动配置每个模型的预处理流程时，请使用 `ov.fm`。它会自动为您处理基因 ID 转换、兼容性检查以及输出标准化。

快速开始#

import omicverse as ov

# 1. 查看可用模型
models = ov.fm.list_models(task="embed")

# 2. 分析您的数据
profile = ov.fm.profile_data("pbmc3k.h5ad")

# 3. 哪个模型最适合？
selection = ov.fm.select_model("pbmc3k.h5ad", task="embed")
print(selection["recommended"]["name"])

# 4. 数据是否准备就绪？
check = ov.fm.preprocess_validate("pbmc3k.h5ad", "scgpt", "embed")

# 5. 运行模型
result = ov.fm.run(task="embed", model_name="scgpt", adata_path="pbmc3k.h5ad",
                   output_path="pbmc3k_embedded.h5ad")

# 6. 可视化与评估
metrics = ov.fm.interpret_results("pbmc3k_embedded.h5ad", task="embed")

六步工作流程#

ov.fm 围绕六个可组合步骤设计。您可以单独使用任何步骤，也可以将它们全部串联起来。

发现 ──▸ 分析 ──▸ 选择 ──▸ 验证 ──▸ 运行 ──▸ 解读

步骤	函数	目的
发现	`list_models()`, `describe_model()`	浏览可用模型及其功能
分析	`profile_data()`	检测物种、基因方案、模态及每个模型的兼容性
选择	`select_model()`	对模型进行评分和排序，以适配您的数据和任务
验证	`preprocess_validate()`	检查数据兼容性，获取自动修复建议
运行	`run()`	执行模型推理（嵌入、注释、整合等）
解读	`interpret_results()`	计算指标（轮廓系数），生成 UMAP 可视化

API 参考#

`ov.fm.list_models`#

ov.fm.list_models(task=None, skill_ready_only=False) -> dict

列出可用的基础模型，支持可选过滤。

参数：

参数	类型	默认值	描述
`task`	str \| None	`None`	按任务过滤：`"embed"`、`"annotate"`、`"integrate"`、`"perturb"`、`"spatial"`、`"drug_response"`
`skill_ready_only`	bool	`False`	仅返回具有完整实现适配器的模型

返回值： 包含 count（整数）和 models（模型摘要列表）的字典。

result = ov.fm.list_models(task="embed")
for m in result["models"]:
    print(f"{m['name']:15s} status={m['status']:10s} tasks={m['tasks']}")

`ov.fm.describe_model`#

ov.fm.describe_model(model_name: str) -> dict

获取单个模型的完整规格，包括输入/输出约束、硬件要求和资源链接。

返回值： 包含 model、input_contract、output_contract、resources 键的字典。

spec = ov.fm.describe_model("scgpt")
print(spec["input_contract"]["gene_id_scheme"])   # "symbol"
print(spec["output_contract"]["embedding_key"])    # "X_scGPT"
print(spec["output_contract"]["embedding_dim"])    # 512

`ov.fm.profile_data`#

ov.fm.profile_data(adata_path: str) -> dict

分析 .h5ad 文件，返回包含自动物种/基因方案检测及每个模型兼容性评估的数据概况。

返回值： 包含 n_cells、n_genes、species、gene_scheme、modality、has_raw、layers、obs_columns、obsm_keys、batch_columns、celltype_columns、model_compatibility 的字典。

profile = ov.fm.profile_data("pbmc3k.h5ad")
print(f"物种：{profile['species']}")
print(f"基因 ID：{profile['gene_scheme']}")

# 查看哪些模型兼容
for name, compat in profile["model_compatibility"].items():
    status = "OK" if compat["compatible"] else "ISSUES"
    print(f"  {name}: {status}")

`ov.fm.select_model`#

ov.fm.select_model(
    adata_path: str,
    task: str,
    prefer_zero_shot: bool = True,
    max_vram_gb: int = None,
) -> dict

对给定数据集和任务的模型进行评分和排序。

参数：

参数	类型	默认值	描述
`adata_path`	str	—	`.h5ad` 文件路径
`task`	str	—	任务类型（必填）
`prefer_zero_shot`	bool	`True`	优先选择无需微调的模型
`max_vram_gb`	int \| None	`None`	最大显存限制

返回值： 包含 recommended（名称 + 理由）、fallbacks（列表）、preprocessing_notes、data_profile 的字典。

评分逻辑：

Skill-ready 适配器：+100（就绪），+50（部分），0（参考）
零样本匹配：+30
基因方案匹配：+20
支持 CPU 回退：+10
低显存：+5

result = ov.fm.select_model("pbmc3k.h5ad", task="embed", prefer_zero_shot=True)
print(f"推荐：{result['recommended']['name']}")
print(f"理由：{result['recommended']['rationale']}")
print(f"备选：{[f['name'] for f in result['fallbacks']]}")

`ov.fm.preprocess_validate`#

ov.fm.preprocess_validate(
    adata_path: str,
    model_name: str,
    task: str,
) -> dict

验证数据与特定模型和任务的兼容性。返回诊断信息和自动修复建议。

返回值： 包含 status（"ready" | "needs_preprocessing" | "incompatible"）、diagnostics、auto_fixes、data_summary 的字典。

result = ov.fm.preprocess_validate("pbmc3k.h5ad", "scgpt", "embed")
if result["status"] == "ready":
    print("数据已准备好用于 scGPT")
else:
    for diag in result["diagnostics"]:
        print(f"[{diag['severity']}] {diag['message']}")
    for fix in result["auto_fixes"]:
        print(f"建议修复：{fix['action']}")
        if "code" in fix:
            print(fix["code"])

`ov.fm.run`#

ov.fm.run(
    task: str,
    model_name: str,
    adata_path: str,
    output_path: str = None,
    batch_key: str = None,
    label_key: str = None,
    device: str = "auto",
    batch_size: int = None,
    checkpoint_dir: str = None,
) -> dict

在您的数据上执行基础模型。

参数：

参数	类型	默认值	描述
`task`	str	—	任务类型（必填）
`model_name`	str	—	模型名称（必填）
`adata_path`	str	—	输入 `.h5ad` 的路径（必填）
`output_path`	str \| None	`None`	输出路径（默认覆盖输入文件）
`batch_key`	str \| None	`None`	批次对应的 `.obs` 列（`integrate` 任务需要）
`label_key`	str \| None	`None`	细胞类型标签对应的 `.obs` 列
`device`	str	`"auto"`	`"auto"`、`"cuda"`、`"cpu"`、`"mps"`
`batch_size`	int \| None	`None`	覆盖模型默认批次大小
`checkpoint_dir`	str \| None	`None`	模型检查点目录路径

返回值： 成功时返回包含 output_path、output_keys、n_cells、status 的字典；失败时返回包含 error、status 的字典。

执行流程：

通过 preprocess_validate() 验证数据
尝试 conda 子进程执行（隔离环境）
若 conda 不可用，回退至进程内适配器
将结果和溯源元数据写入输出 AnnData

result = ov.fm.run(
    task="embed",
    model_name="scgpt",
    adata_path="pbmc3k.h5ad",
    output_path="pbmc3k_embedded.h5ad",
    device="cuda",
)
if "error" not in result:
    print(f"输出键：{result['output_keys']}")
    print(f"处理细胞数：{result['n_cells']}")

`ov.fm.interpret_results`#

ov.fm.interpret_results(
    adata_path: str,
    task: str,
    output_dir: str = None,
    generate_umap: bool = True,
    color_by: list = None,
) -> dict

为模型输出生成质量指标和可视化图表。

参数：

参数	类型	默认值	描述
`adata_path`	str	—	含模型结果的 `.h5ad` 路径
`task`	str	—	已执行的任务
`output_dir`	str \| None	`None`	可视化文件的输出目录
`generate_umap`	bool	`True`	是否生成 UMAP 图
`color_by`	list \| None	`None`	用于 UMAP 着色的 `.obs` 列

计算的指标：

嵌入维度和细胞数
轮廓系数（如有细胞类型标签且安装了 sklearn）
注释列检测
来自 adata.uns["fm"] 的溯源元数据

result = ov.fm.interpret_results(
    "pbmc3k_embedded.h5ad",
    task="embed",
    generate_umap=True,
    color_by=["louvain"],
)
for key, info in result["metrics"]["embeddings"].items():
    print(f"{key}: dim={info['dim']}, silhouette={info.get('silhouette', 'N/A')}")

支持的任务#

任务	描述	示例模型
`embed`	生成细胞嵌入用于下游分析	scGPT, Geneformer, UCE, CellPLM
`annotate`	预测细胞类型标签	scGPT（微调版）, sccello, ChatCell
`integrate`	跨数据集的批次整合	scGPT, Geneformer, UCE
`perturb`	扰动响应预测	scFoundation, Tabula
`spatial`	空间转录组学分析	Nicheformer
`drug_response`	药物响应建模	scFoundation

模型目录#

Skill-Ready 模型（完整适配器）#

这些模型具有完整实现的适配器，可直接通过 ov.fm.run() 执行。

模型	版本	任务	物种	基因 ID	GPU	最低显存
scGPT	whole-human-2024	embed, integrate	human, mouse	symbol	是	8 GB
Geneformer	v2-106M	embed, integrate	human	ensembl	否（支持 CPU）	4 GB
UCE	4-layer	embed, integrate	7 种物种	symbol	是	16 GB

部分规格模型#

这些模型具有部分规格。可用于模型选择和数据分析；执行能力取决于适配器可用性。

模型	任务	模态	核心特点
scFoundation	embed, integrate	RNA	19K 基因词表，扰动预训练
scBERT	embed, integrate	RNA	BERT 风格掩码语言建模
GeneCompass	embed, integrate	RNA	1.2 亿细胞预训练语料
CellPLM	embed, integrate	RNA	以细胞为中心（非基因），高吞吐量
Nicheformer	embed, integrate, spatial	RNA, Spatial	感知微环境的空间建模
scMulan	embed, integrate	RNA, ATAC, Protein, Multi-omics	原生多组学
Tabula	embed, annotate, integrate, perturb	RNA	联邦学习 + FlashAttention
tGPT	embed, integrate	RNA	自回归下一 token 预测
CellFM	embed, integrate	RNA	MLP 架构，1.26 亿细胞
sccello	embed, integrate, annotate	RNA	通过细胞本体论进行零样本注释
scPRINT	embed, integrate	RNA	去噪 + 蛋白质编码基因专注
ATACformer	embed, integrate	ATAC	原生 ATAC-seq（基于 Peak）
scPlantLLM	embed, integrate	RNA	植物专用（拟南芥、水稻、玉米）
LangCell	embed, integrate	RNA	文本+细胞对齐，自然语言查询

!!! tip “模型选择速查表”

- **默认（RNA，人类）：** scGPT
- **Ensembl ID / 纯 CPU：** Geneformer
- **跨物种：** UCE（支持 7 种物种）
- **多组学（RNA+ATAC+蛋白质）：** scMulan
- **空间转录组学：** Nicheformer
- **仅 ATAC-seq：** ATACformer
- **植物数据：** scPlantLLM
- **大规模（100 万+ 细胞）：** CellPLM

数据类型与枚举#

from omicverse.fm import TaskType, Modality, GeneIDScheme, SkillReadyStatus

=== “TaskType”

```python
TaskType.EMBED          # "embed"
TaskType.ANNOTATE       # "annotate"
TaskType.INTEGRATE      # "integrate"
TaskType.PERTURB        # "perturb"
TaskType.SPATIAL        # "spatial"
TaskType.DRUG_RESPONSE  # "drug_response"
```

=== “Modality”

```python
Modality.RNA         # "RNA"
Modality.ATAC        # "ATAC"
Modality.SPATIAL     # "Spatial"
Modality.PROTEIN     # "Protein"
Modality.MULTIOMICS  # "Multi-omics"
```

=== “GeneIDScheme”

```python
GeneIDScheme.SYMBOL   # "symbol"  — HGNC 符号（如 TP53）
GeneIDScheme.ENSEMBL  # "ensembl" — Ensembl ID（如 ENSG00000141510）
GeneIDScheme.CUSTOM   # "custom"  — 模型特定词表
```

=== “SkillReadyStatus”

```python
SkillReadyStatus.READY      # 完整适配器已实现
SkillReadyStatus.PARTIAL    # 部分规格，需要验证
SkillReadyStatus.REFERENCE  # 仅参考文档
```

插件系统#

您可以通过编写插件来注册自定义基础模型。

入口点插件（pip 安装）#

在您的 pyproject.toml 中：

[project.entry-points."omicverse.fm"]
my_model = "my_package.fm_plugin:register"

本地插件（开发用）#

在 ~/.omicverse/plugins/fm/my_model.py 创建文件：

from omicverse.fm import ModelSpec, SkillReadyStatus, TaskType, Modality, GeneIDScheme
from omicverse.fm.adapters import BaseAdapter

MY_SPEC = ModelSpec(
    name="my_model",
    version="v1.0",
    skill_ready=SkillReadyStatus.PARTIAL,
    tasks=[TaskType.EMBED],
    modalities=[Modality.RNA],
    species=["human"],
    gene_id_scheme=GeneIDScheme.SYMBOL,
    zero_shot_embedding=True,
    embedding_dim=256,
)

class MyAdapter(BaseAdapter):
    def run(self, task, adata_path, output_path, **kwargs):
        ...  # 您的实现

    def _load_model(self, device):
        ...

    def _preprocess(self, adata, task):
        ...

    def _postprocess(self, adata, embeddings, task):
        ...

def register():
    """返回 (spec, adapter_class) 元组。"""
    return (MY_SPEC, MyAdapter)

!!! note

插件不能覆盖内置模型。若发生名称冲突，插件将被跳过并发出警告。

注册表 API#

对于高级用法，您可以直接查询模型注册表：

from omicverse.fm import get_registry

registry = get_registry()

# 获取特定模型的规格
spec = registry.get("scgpt")
print(spec.embedding_dim)       # 512
print(spec.supports_task("embed"))  # True

# 查找符合条件的模型
matches = registry.find_models(
    task="embed",
    species="human",
    gene_scheme="symbol",
    zero_shot=True,
    max_vram_gb=16,
)
for m in matches:
    print(m.name, m.version)

环境变量#

变量	描述
`OV_FM_CHECKPOINT_DIR`	模型检查点的基础目录（`<base>/<model_name>/`）
`OV_FM_CHECKPOINT_DIR_SCGPT`	模型专用检查点目录（适用于任何大写模型名）
`OV_FM_DISABLE_CONDA_SUBPROCESS`	禁用 conda 子进程执行，仅使用进程内适配器

检查点解析顺序：

ov.fm.run() 中的 checkpoint_dir 参数
OV_FM_CHECKPOINT_DIR_<MODEL> 环境变量
OV_FM_CHECKPOINT_DIR/<model_name>/
默认缓存：~/.omicverse/models/<model_name>/

错误处理#

所有函数均通过结果字典返回错误信息，而非抛出异常：

result = ov.fm.run(task="embed", model_name="scgpt", adata_path="data.h5ad")
if "error" in result:
    print(f"错误：{result['error']}")
    print(f"状态：{result['status']}")  # "not_implemented"、"incompatible" 等

常见错误信息：

错误	原因
`Model 'xxx' not found`	模型名称不在注册表中
`File not found: xxx`	文件路径无效
`Expected .h5ad file`	文件格式错误
`No compatible models found`	没有模型满足任务/数据约束
`No adapter implemented for model 'xxx'`	模型仅为参考文档，无适配器

动手教程#

如需使用真实数据（PBMC 3K + scGPT）的逐步演练，请参阅基础模型教程笔记本。

ov.fm — 基础模型模块

目录

ov.fm — 基础模型模块#

快速开始#

六步工作流程#

API 参考#

ov.fm.list_models#

ov.fm.describe_model#

ov.fm.profile_data#

ov.fm.select_model#

ov.fm.preprocess_validate#

ov.fm.run#

ov.fm.interpret_results#

支持的任务#

模型目录#

Skill-Ready 模型（完整适配器）#

部分规格模型#

数据类型与枚举#

插件系统#

入口点插件（pip 安装）#

本地插件（开发用）#

注册表 API#

环境变量#

错误处理#

动手教程#

`ov.fm.list_models`#

`ov.fm.describe_model`#

`ov.fm.profile_data`#

`ov.fm.select_model`#

`ov.fm.preprocess_validate`#

`ov.fm.run`#

`ov.fm.interpret_results`#