环境准备：conda环境创建、依赖包安装、GPU与内存配置

跑空间转录组Pipeline，环境准备是第一步，也是我见过翻车最多的地方。你可能觉得不就是装几个包吗？嗯，真不是这么简单。我记忆里至少有三个项目，因为环境冲突导致分析中断，最后不得不重头再来。这一章，咱们就把环境准备那些坑，一个一个填平。

3.1 conda环境创建——别在base里裸奔

我个人习惯，每个Pipeline单独一个conda环境。为什么？因为空间转录组涉及的依赖特别多，而且版本敏感。你想想看，Seurat v4和v5的API都变了，更别说Python那边Scanpy、Squidpy、STUtility互相打架的情况了。

创建环境的命令很简单，但我建议加上Python版本和频道指定：

conda create -n spatial_pipeline python=3.9 -c conda-forge -c bioconda
conda activate spatial_pipeline

3.2 依赖包安装——别一次性全装

很多人喜欢搞个requirements.txt然后pip install -r一把梭。我曾经也这么干过，结果运行时包冲突，日志里全是"ImportError: cannot import name 'xx' from 'yy'"，排查起来特别痛苦。

我建议分三步安装：先装核心分析库，再装可视化库，最后装GPU加速库。

pip install scanpy anndata pandas

pip install squidpy matplotlib

pip install cupy-cuda12x  # 根据cuda版本选择

安装过程中如果遇到冲突，别急着加`--ignore-installed`。先用`conda install`试试，conda的依赖解析比pip更严格。

3.3 GPU与内存配置——别让显存爆炸

空间转录组数据，一张10x Visium切片就有几千个spot，每个spot包含几万个基因表达。更别提Xenium或MERFISH这类高分辨率数据了，动不动几百万个细胞。内存和显存不够，Pipeline跑一半就给你OOM（Out of Memory）杀掉。

我整理了一份硬件配置建议表，你可以根据数据规模参考：

如果你显存有限，这里有几个实战技巧：

• 减少批次大小：GPU加速的模型（如SpaGCN、BayesSpace）可以调小batch_size，例如从128降到32。
• 使用混合精度：PyTorch或TensorFlow的混合精度训练，显存占用能减少40%。
• 内存映射：anndata支持backed模式，数据不全部加载到内存。我处理一个20GB的h5ad文件时，就用这个模式：

import anndata as ad
adata = ad.read_h5ad("large_dataset.h5ad", backed="r")
# 只读取需要的子集
subset = adata[:10000, :5000].copy()
subset.X = subset.X.toarray()  # 转换成密集矩阵后再操作

3.4 环境验证——装完了别急着跑

我见过不止一次，环境装完就开跑，结果跑了一小时报错，才发现cupy没装好。我的习惯是装完后跑一个快速验证脚本：

# validate_env.py
import scanpy as sc
import numpy as np
print("Scanpy version:", sc.__version__)

# 测试GPU可用性
try:
    import cupy as cp
    a = cp.array([1, 2, 3])
    print(f"CuPy available, device: {cp.cuda.runtime.getDeviceProperties(0)['name']}")
except ImportError:
    print("CuPy not installed, will use CPU")

# 测试anndata读写
import anndata as ad
import tempfile, os
tmp = tempfile.NamedTemporaryFile(suffix=".h5ad", delete=False)
adata = sc.datasets.pbmc3k()  # 小数据集
adata.write(tmp.name)
print("anndata I/O OK")
os.unlink(tmp.name)

如果这个脚本全部通过，环境基本就稳了。如果某个地方报错，直接定位，不要带着问题往下走。

3.5 中断恢复检查清单

当你从Pipeline中断中恢复时，环境准备阶段的检查清单如下：

1. 确认当前conda环境是否与之前一致（用conda list --export对比）
2. 检查GPU驱动和CUDA版本是否变动（重启或更新驱动后容易变）
3. 验证关键包版本（尤其是scanpy、anndata、cupy）是否与中断前一致
4. 确认磁盘空间足够（临时文件和h5ad缓存）
5. 用上面的验证脚本再跑一遍，确保环境健康

3.6 常见环境中断原因及恢复

我把几年前踩过的坑和团队遇到的情况汇总成一张表，你中断恢复时可以直接对照排查：