scvi-tools（单细胞变分推断工具）是一个基于 PyTorch 和 AnnData 构建的用于单细胞组学数据概率建模与分析的软件包。

单细胞组学数据分析

scvi-tools 包含多种模型，能够处理单细胞、多组学及空间组学数据中的各类分析任务：

• 降维
• 数据整合
• 自动注释
• 因子分析
• 双重细胞检测
• 空间去卷积
• 以及其他更多功能！

在 [用户指南] 中，我们对每个模型进行了概述。所有模型实现都提供了与 Scanpy 兼容的高级 API，并包含标准的保存/加载功能、GPU 加速等特性。

快速开发新型概率模型

scvi-tools 提供了构建和部署新型概率模型的基础组件。这些组件依托于流行的概率编程框架和机器学习框架，如 PyTorch Lightning 和 Pyro。有关 scvi-tools 软件包结构的详细信息，请参阅 [代码库概览] 页面。

我们建议从 [模板仓库] 开始，利用 scvi-tools 开发并部署新模型。

基本安装

使用 conda 安装：

conda install scvi-tools -c conda-forge

使用 pip 安装：

pip install scvi-tools

请确保安装与您的 GPU 兼容的 PyTorch 版本（如果适用）。

资源

• 教程、API 参考和安装指南可在 [文档] 中找到。
• 如需讨论使用方法，请访问我们的 [论坛]。
• 请通过 issues 提交错误报告。
• 如果您希望贡献代码，请参阅我们的 [贡献指南]。
• 如果您发现某个模型对您的研究有帮助，请考虑引用相应的论文。

参考文献

如果您在工作中使用 scvi-tools，请引用以下文献：

一种用于单细胞组学数据概率分析的 Python 库

Adam Gayoso, Romain Lopez, Galen Xing, Pierre Boyeau, Valeh Valiollah Pour Amiri, Justin Hong, Katherine Wu, Michael Jayasuriya, Edouard Mehlman, Maxime Langevin, Yining Liu, Jules Samaran, Gabriel Misrachi, Achille Nazaret, Oscar Clivio, Chenling Xu, Tal Ashuach, Mariano Gabitto, Mohammad Lotfollahi, Valentine Svensson, Eduardo da Veiga Beltrame, Vitalii Kleshchevnikov, Carlos Talavera-López, Lior Pachter, Fabian J. Theis, Aaron Streets, Michael I. Jordan, Jeffrey Regier & Nir Yosef

Nature Biotechnology 2022 年 2 月 7 日。doi: 10.1038/s41587-021-01206-w。

同时，请一并引用描述所用模型的论文。

您也可以引用 scverse 的相关论文如下：

scverse 项目为单细胞组学数据分析提供了一个计算生态系统

Isaac Virshup, Danila Bredikhin, Lukas Heumos, Giovanni Palla, Gregor Sturm, Adam Gayoso, Ilia Kats, Mikaela Koutrouli, Scverse 社区, Bonnie Berger, Dana Pe’er, Aviv Regev, Sarah A. Teichmann, Francesca Finotello, F. Alexander Wolf, Nir Yosef, Oliver Stegle & Fabian J. Theis

Nature Biotechnology 2023 年 4 月 10 日。doi: 10.1038/s41587-023-01733-8。

scvi-tools 是 scverse® 项目的一部分（官网, 治理结构），并由 NumFOCUS 提供财务支持。

如果您喜欢 scverse® 并希望支持我们的使命，请考虑向 [NumFOCUS] 进行可抵税捐赠 (捐赠链接)，以帮助项目支付开发人员工时、专业服务、差旅、研讨会及其他各项开支。

版权所有 © 2026，Yosef 实验室，魏茨曼科学研究所

scvi-tools 快速上手指南

scvi-tools 是一个基于 PyTorch 和 AnnData 构建的 Python 库，专为单细胞多组学数据的概率建模与分析而设计。它提供了降维、数据整合、自动注释、空间反卷积等多种高级分析功能，并与 Scanpy 生态无缝集成。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows (推荐 Linux 以获得最佳 GPU 支持)
• Python 版本：3.9 及以上
• 核心依赖：
  • PyTorch：需安装与您的硬件（特别是 GPU）兼容的版本。
  • AnnData：用于处理单细胞数据标准格式。
  • Scanpy：推荐的单细胞数据分析流程工具。

提示：如果您需要使用 GPU 加速，请务必先根据 PyTorch 官网 指引安装正确的 CUDA 版本 PyTorch，然后再安装 scvi-tools。

安装步骤

您可以选择通过 conda 或 pip 进行安装。国内用户若遇到下载速度慢的问题，可配置清华或中科大镜像源。

方式一：使用 Conda (推荐)

conda install scvi-tools -c conda-forge

国内加速方案（使用清华镜像）：

conda install scvi-tools -c https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge

方式二：使用 Pip

pip install scvi-tools

国内加速方案（使用清华镜像）：

pip install scvi-tools -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

scvi-tools 的设计哲学是与 Scanpy 紧密协作。以下是一个最简化的工作流程示例，展示如何加载数据、训练模型并进行降维可视化。

1. 导入库并加载数据

import scanpy as sc
from scvi.model import SCVI

# 加载示例数据集 (10x Genomics PBMC 数据)
adata = sc.datasets.pbmc68k_reduced()

# 预处理：识别高变基因 (scvi-tools 通常只需要高变基因作为输入)
sc.pp.highly_variable_genes(adata)

# 注册数据到 scvi-tools 模型
# 这一步会设置必要的元数据列，为训练做准备
SCVI.setup_anndata(
    adata,
    layer=None,          # 如果使用原始计数矩阵，设为 None
    batch_key="batch",   # 如果有批次效应，指定批次列名，否则可省略
)

2. 初始化并训练模型

# 初始化模型
model = SCVI(adata)

# 训练模型
# max_epochs 可根据数据量调整，默认通常为 400
model.train(max_epochs=200)

3. 提取结果并可视化

训练完成后，可以提取潜在表示（latent representation）用于下游分析，如聚类或 UMAP 可视化。

# 获取降维后的潜在空间表示
adata.obsm["X_scVI"] = model.get_latent_representation()

# 使用 Scanpy 进行邻域计算和 UMAP 降维
sc.pp.neighbors(adata, use_rep="X_scVI")
sc.tl.umap(adata)

# 绘制 UMAP 图
sc.pl.umap(adata, color=["cell_type"]) # 假设有 cell_type 注释列

通过以上步骤，您已完成从数据准备到模型训练及可视化的完整闭环。更多高级功能（如数据整合、差异表达分析、空间转录组分析等）请参考官方 文档。