scvi-tools

scvi-tools 技能概览

scvi-tools 适合做什么

scvi-tools 技能帮助你在面对单细胞组学时，使用 scVI 风格的概率模型，而不是停留在一个笼统的分析提示上。它尤其适合批次校正、潜在表示学习、跨运行或供体整合，以及带不确定性意识的差异表达分析。如果你的目标是高级单细胞建模，而不是常规预处理，那么这个 scvi-tools 技能非常合适。

适合谁安装

如果你处理的是 single-cell RNA-seq、multiome、CITE-seq、ATAC 或空间数据，并且希望采用模型驱动的工作流，就应该安装 scvi-tools。它尤其适合需要基于 PyTorch 的框架、而不只是静态方法概述的 Machine Learning 用户。如果你主要只需要基础 QC、聚类或可视化，标准的 Scanpy-first 工作流通常就已经足够。

采用前最重要的判断点

它的核心价值不只是 scvi-tools “存在”，而是它能把你从原始 counts 走到训练好的 latent model，并且把权衡关系说清楚。关键判断在于：你是否真的需要概率建模、迁移学习或多模态整合，足以抵消额外的配置和建模决策成本。只有当输出质量依赖于处理 batch effect，或者需要谨慎比较异质数据集时，这个技能才值得安装。

如何使用 scvi-tools 技能

安装该技能

使用目录安装流程安装 scvi-tools 技能：
npx skills add K-Dense-AI/claude-scientific-skills --skill scvi-tools

安装后，检查 scientific-skills/scvi-tools 下的技能路径，并直接打开源文件。对这个仓库来说，SKILL.md 是主要入口；没有可依赖的 rules/、resources/ 或 scripts/ 文件夹。

先读对文件

先看 SKILL.md，了解适用范围、模型家族，以及推荐的决策点。然后在发起 prompt 之前，扫一遍“何时使用该技能”“核心能力”和 single-cell RNA-seq 工作流相关部分。由于这个仓库很精简，最快减少猜测的方法是把文件从头到尾完整读一遍，而不是只挑模型名称看。

把粗略目标变成可用 prompt

像“分析我的 scRNA-seq 数据”这种模糊请求远远不够。更好的 scvi-tools 使用 prompt 应该说明 assay、数据形态，以及你真正需要做的决策：

• “使用 scVI 整合 6 个 scRNA-seq batch，比较 donor effect，并返回 latent space 和 batch-mixing 诊断结果。”
• “为配对的 RNA + ATAC 数据运行一个 MULTIVI 风格的工作流，并解释细胞更像是按生物学差异还是 batch 被分开。”
• “对两个细胞群做带不确定性的差异表达分析，并报告 effect size，而不只是 p-value。”

会明显影响输出质量的工作流建议

把技能真正需要的信息给全，才能让它选对模型家族：模态、batch 数量、数据是否配对，以及任务是整合、注释还是 DE。提前说明任何约束，比如 counts 很稀疏、样本量很小，或者需要保持与现有 scanpy 对象兼容。如果你想要 scvi-tools 的最佳指南结果，就一次性要求给出模型选择、设置步骤、预期输出和常见失败模式。

scvi-tools 技能常见问题

scvi-tools 只适用于 scRNA-seq 吗？

不是。scvi-tools 技能覆盖多种单细胞模态，包括 RNA-seq、ATAC、多模态检测和空间场景。话虽如此，RNA 整合通常是最常见的入口，所以在扩展到更复杂的数据之前，它往往也是最容易先验证是否匹配的地方。

如果我已经在用 Scanpy，还需要它吗？

两者都可以用，但分工不同。Scanpy 更适合标准预处理和探索性流程，而 scvi-tools 更适合你需要概率建模、latent embedding 或在 batch effect 下做整合的时候。如果你的分析问题并不需要学习式生成模型，那么 scvi-tools 可能就超出你的实际需求了。

它对新手友好吗？

只有在你已经理解 counts matrix、batch 和 annotation 这类基本单细胞概念时，它才算是对新手相对友好。这个技能最有帮助的前提，是你能清楚说明自己的数据和目标。如果你还不能判断自己需要整合、迁移学习还是差异表达，那最好先走更简单的分析路径。

什么时候不该用 scvi-tools？

不要为了简单归一化、快速画图或一次性的探索性检查就上 scvi-tools。如果你想要的是完全统计手册式、无需模型选择决策的方案，它也不算理想。对于极小数据集或高度定制的 pipeline，额外开销往往会超过收益。

如何改进 scvi-tools 技能

给出模型选择所需的上下文

提升质量最大的方式，是告诉技能你真正面对的 scvi-tools 问题类型。先描述数据，再说明你是否需要 scVI、TOTALVI、MultiVI 或其他家族。比如，“配对 CITE-seq 且 donor effect 很强”就比“用 MultiVI”有用得多。

说明数据结构和约束

更好的输入能减少最常见的失败模式：为错误的 assay 选错模型。请提供 matrix 类型、细胞数量、batch、协变量，以及 counts 是原始的还是已归一化的。如果你是在 scvi-tools for Machine Learning 工作流里使用它，也要说明你希望得到可复用的 latent space、下游分类器特征，还是与另一个模型相比的可解释对照。

请求能直接落地的输出

不要只问“分析”。要明确要求一个可交付成果，比如训练方案、模型选择理由、整合诊断，或者 notebook 风格的工作流。如果第一次结果太笼统，就补上缺失的信息继续迭代：细胞类型标签、batch 定义，或者你需要拿来和 scanpy 或其他 baseline 对照的内容。