超大h5ad文件分割与内存优化实战 | 单细胞数据处理

前两周处理一批公共数据时，我栽了一个大跟头：一批单细胞数据合并之后，落盘是个 h5ad 文件，30 GB 出头，六十万细胞，机器配了 64 GB 内存。我心想 64GB 总够了吧，结果 scanpy.read_h5ad() 一跑，内存直接冲到 58 GB，再往后所有分析流程全部卡死。后来我被迫认真做了一次“超大数据 h5ad 分割”，把文件拆成可独立加载的小块，才把整个项目救回来。这件事让我意识到，单细胞数据的“大”根本不是稀罕事，真正的问题是我们习惯性地把文件整个塞进内存再处理。

这篇我就围绕 h5ad 文件和超大数据分割，把整个踩坑和解决过程写出来。内容包括：h5ad 文件为什么动不动几十 GB、拿到 GEO 或其他来源的数据后怎么快速统一成可操作的 h5ad、真正适合大文件的分割姿势、以及我在实测中记录下来的内存和耗时表现。想直接把“大 h5ad”拆开用的人，这篇应该能帮你少走不少弯路。

1. 一套散装数据几十GB：先弄明白h5ad到底把空间吃在哪

很多人在分割文件之前，根本没搞懂手里的 h5ad 为什么这么大。于是最常见的做法就是盲目加内存、换服务器，最后发现文件大到连读取都成了问题。其实 h5ad 的体量来源是固定的几个部分，搞清了，分割方案自然就有了。

1.1 单细胞矩阵真实尺寸的测算与常见大文件来源

先做一个最朴素的估算。假设你的数据是 60 万细胞、3 万个基因（这个规模的现代单细胞项目很常见），如果表达矩阵用稠密 float32 存储，那理论体积是：

• 600,000 × 30,000 × 4 字节 = 72,000,000,000 字节，约 67 GB

这就是问题所在。只要矩阵是稠密形式，任何数据都很难真正处理。好在单细胞表达矩阵本质是稀疏的，绝大多数基因在绝大多数细胞里表达量是 0，因此实际存下来不会是 67 GB。h5ad 内部用 CSR/CSC 等稀疏格式保存 X，每个非零表达值大概占 8~12 字节（包含索引位和值），典型 10x 数据每个细胞中位表达基因数在两三千个左右，60 万细胞的非零元素大概在 15 亿量级，于是 X 本身能压到 15~18 GB，再加上索引、注释、坐标、底层 HDF5 的 chunk 开销，落到磁盘就是一个 30 GB 上下的文件。

但我在实际工作中发现，很多人忽略的另一大体积来源是 raw。假设你读入数据后做了 normalize、log1p，并把原始 counts 通过 adata.raw = adata.copy() 存了一份，那就等于同一套大矩阵又多存了一遍。文件里 raw/X 和 X 并存的时候，整体体积翻倍一点不奇怪。这种“为了后续恢复原始数据所以保留 raw”的习惯，在小文件上没问题，但对 30 GB 的超大 h5ad 来说，会直接拖累读写和分割。

另外 obs 和 var 表里的文本列也会占不少地方。尤其是从多个样本拼合的数据，obs 里常见的 sample_id、cell_type 等列，如果以纯字符串形式保存，HDF5 里会有大量重复字符串开销。uns 里通常还存着 UMAP 坐标、聚类树、PAGA 图等中间结果。这些跟“分割”本身没关系，却会实实在在地拖慢文件打开和写入。

1.2 先给文件做一个“内存体检”，再决定要不要分割

拿到一个巨大 h5ad，不要上来就 pd.read_h5ad() 直接加载，先用 backed 模式打开，做一次轻量级的检查：

python复制import anndata as ad
import scanpy as sc

file_path = "/mnt/data/big_scrna.h5ad"
adata = ad.read_h5ad(file_path, backed="r")

print(adata.shape)   # (600000, 30000)
print("cells:", adata.n_obs, "genes:", adata.n_vars)

# obs 和 var 里有哪些列，几乎决定文件里文本占比
print(adata.obs.columns.tolist())
print(adata.var.columns.tolist())

# 看看是否有 raw，这两个矩阵同时存在是最占空间的
if adata.raw is not None:
    print("raw shape:", adata.raw.shape)
else:
    print("no raw")

# 常见冗余：uns 里的聚类/坐标/图结构
print(list(adata.uns.keys()))

backed 模式的意思是，文件不会整体读进内存，只是打开 HDF5 句柄，真正调用 .X 或 adata[...] 时才去底层读取对应 block。这个模式对超大文件非常关键，它让我可以只查看元数据和结构，而不用立刻面对 30 GB 的加载压力。

通过这些体检信息，基本就能判断手里的文件该走哪条路线：

• 如果 X 和 raw.X 同时存在，文件体积几乎翻倍，优先考虑裁剪；
• 如果 obs 里大量字符串列是非重复系数低的 ID 字段，转成 category 收益不大，但如果是重复率高的注释标签，转 category 收益明显；
• 如果 uns 里塞了几十 MB 的中间结果，而下游根本不需要，清理后文件能小一截；
• 如果文件去掉冗余后依然很大，这时候才真正需要做切片分割。

2. 拿到GEO或其他公开来源数据后，怎么统一成可操作的h5ad

很多人手上不是现成的 h5ad，而是从 GEO 或各种公共数据库下载的原始矩阵。此时候面临的第一步不是切割，而是把来源五花八门的数据先转换成一个干净的 h5ad。很多人问“如何用 Python 读取 GEO 单细胞数据”，其实这个问题的本质不是不知道函数名，而是进了误区：GEO 上发布的单细胞数据通常有三种形态，形态不同，读取路径也不同。

2.1 三种常见数据形态与正确读入方式

我在实际项目中遇到最多的三类数据来源，对应的读法大概是这样：

一种是最常见的 10x Cell Ranger 三件套：

text复制matrix.mtx.gz
barcodes.tsv.gz
features.tsv.gz（旧版本叫 genes.tsv.gz）

这种用 scanpy.read_10x_mtx() 直接读一个目录就行：

python复制import scanpy as sc

adata = sc.read_10x_mtx("./GSE_xxx/", var_names="gene_symbols", make_unique=True, gex_only=True)
adata.X = adata.X.astype("float32")
print(adata.shape)

这里有个细节容易翻车：gex_only=True 的意思是把 10x 多组学数据里非 Gene Expression 的部分过滤掉。很多公共数据下载之后，features.tsv.gz 里不仅有 Gene Expression，还有 Antibody Capture 或 CRISPR Guide Capture 的 feature。如果不加这个参数，后面做基因表达分析时，矩阵里会混进来大量非基因行，而且这些行往往比普通基因短很多，在处理时很容易出 bug。如果文件是 v2/v1 老版本，目录里可能没有 features.tsv 而是 genes.tsv，scanpy 也能自动识别，但我建议先 ls 看一下目录真实内容再跑。

第二种是 Cell Ranger 直接导出的 filtered_feature_bc_matrix.h5：

python复制adata = sc.read_10x_h5("filtered_feature_bc_matrix.h5")
print(adata)

GEO 的 supplementary 文件里经常能下到这种 .h5，它本质就是按 10x 的规则存好的 HDF5。读取之后同样注意 var_names_make_unique()，因为不同 feature 类型前缀可能重合，直接使用容易出现变量名重复。

第三种是已经整理成 adata.h5ad 或 .loom 的成品数据：

如果下载到的是 .h5ad，直接用 sc.read_h5ad() 就行；如果是 .loom，用 sc.read_loom() 读入。这类数据一般已经做了部分质控，甚至已经有细胞类型注释，读入后可以省很多事，但也要分清注释列是真实注释还是上游的聚类标签，千万别把 leiden 当细胞类型直接用。

2.2 读入后先做索引清洗，避免后续分割出现幽灵细胞

我在分割数据时曾经被一个隐蔽问题坑过：从几个数据集拼合的大 h5ad，表面看每个样本的 barcode 都正常，但当我按某个样本条件切出子集后再拼接回去，却发现比原来的总细胞数少了几个。最后排查下来的原因是不同平台的 barcode 有重复，导致部分细胞在索引对齐时被吞掉了。

所以，不管数据是从哪来，读完第一步先做索引唯一化：

python复制adata.obs_names_make_unique()
adata.var_names_make_unique()

obs_names_make_unique() 会在重复的 barcode 后面自动追加后缀。这一步在“超大数据分割”里尤其重要，因为分割后你常常要把多份子集再合并，索引不唯一会导致合并时无法正确区分来自不同样本的相同 barcode。

另外，我还习惯在 obs 里加一列原始 barcode 的存档。因为某些注释方法会修改 obs_names 的内容，比如加前缀当作样本标签，一旦修改后想回到原始 barcode，就会很痛苦：

python复制if "orig_barcode" not in adata.obs.columns:
    adata.obs["orig_barcode"] = adata.obs_names.astype(str)

读入所有来源数据后，先统一成 h5ad 并保存一份。这一步很重要，之后无论是做子集筛选、按批次切分，还是把数据喂给深度学习模型，你都只需要面对同一个接口，不用再回到各个来源格式里去重新折腾。

3. 分片前的“瘦身”往往比分割本身更值钱

很多人一听到超大 h5ad，第一反应就是切成更小的文件。但我在处理很多大文件后发现，一个 30 GB 的文件真正必要的数据可能只有 18 GB。与其费劲分割，不如先把冗余清掉，很多时候清完就直接能整载了。

3.1 raw、uns、obsm 里的冗余先处理掉

先讲最常见的三种冗余。

第一种是 raw。如果你已经做了标准化、log1p，后续分析也不需要回到原始 RNA 计数，那么 raw 可以直接丢掉：

python复制adata.raw = None

如果你的下游确实需要原始 counts（很多差异表达工具需要），也应该把 raw 单独存成一个文件，而不是始终和大矩阵绑定在一起。这个操作能把文件瘦身一半，非常可观。

第二种是 uns 里的中间产物。许多上游流程会把 UMAP 坐标、leiden 图、PAGA 图都塞进 uns。这些结果对最终可视化有用，但对后续子集分析或模型训练基本没有意义。如果你打算按分期处理大文件，可以保留 obsm 里的 UMAP 坐标用于画图，清理掉 uns 里的图结构：

python复制for key in ["neighbors", "paga", "draw_graph", "diffmap_evals"]:
    adata.uns.pop(key, None)

这里不用害怕丢失信息，真正有价值的 UMAP 坐标在 adata.obsm["X_umap"] 里，而 uns["neighbors"] 这类对象只对再次运行依赖邻居图的算法有用，切完片之后通常需要重新算。

第三种是 obsm 里的大量坐标矩阵。每个坐标矩阵大概是细胞数×2 的浮点数，某些文件里可能有 10 个以上的不同降维结果，几十 MB 上百 MB 也很常见。如果确定不需要这些投影，就按需删掉。

这里特别提醒一个容易操作失误的地方：backed 模式（backed="r"）打开的文件是只读句柄，不能直接对 .raw 或 .uns 赋值。需要先一次性 to_memory() 加载，再做瘦身处理，最后写回新文件：

python复制adata = ad.read_h5ad(file_path, backed="r")
adata = adata.to_memory()

adata.raw = None
for key in ["neighbors", "paga"]:
    adata.uns.pop(key, None)

adata.write_h5ad("slim.h5ad")

如果你的机器内存连 to_memory() 都撑不住，那就需要先做分片，每片瘦身后再考虑合并。

3.2 把该转的字符串列转成category，别一股脑全转

h5ad 在保存 obs 和 var 表时，对字符串的处理比较特殊。HDF5 本身没有字符串数组这种高效结构，anndata 在底层会为 category 类型列建立整数映射存储。这个机制对于高重复率的类别字段（比如细胞类型、样本名）效果十分显著；但并不是所有字符串列转 category 都好。

我总结的实际经验是：

具体代码很直接：

python复制for col in ["sample", "cell_type", "batch"]:
    if col in adata.obs.columns:
        adata.obs[col] = adata.obs[col].astype("category")

很多初学者喜欢用 adata.obs[col].astype("category") 直接把所有列都转一遍，这是不推荐的。对于唯一性很高的列，category 映射表本身不会省空间，反而在读入写出时需要多一次解码，白白增加耗时。

3.3 写回压缩参数怎么选

瘦身式处理完文件，写回的时候也要注意 compression 参数。scanpy/anndata 的 write_h5ad() 支持 compression="gzip" 或 compression="lzf"。gzip 压缩率高但写入较慢，lzf 更快但体积相对略大。

我的经验是：

• 文件要长期归档、很少反复切分，用 gzip；
• 文件还需要频繁做子集读取或多次迭代，用 lzf 甚至不压缩，避免每次读文件都解压半天；
• gzip 压缩等级不要盲目拉满，compression_opts=6 是比较实用的档位。

写回时我还习惯先写临时文件再 os.replace()，避免中途磁盘占满导致文件写坏：

python复制import os

tmp = "slim_tmp.h5ad"
adata.write_h5ad(tmp, compression="gzip", compression_opts=6)
os.replace(tmp, "slim.h5ad")

这一步看似多余，但对几十 GB 级别的文件非常保险。毕竟写坏一个 20 GB 文件之后，重新生成的成本高到让人崩溃。

4. 两种真正的分割姿势：按子集筛选和按顺序切块

清理完冗余之后，如果文件仍然大到无法整个加载，那就只剩分割这条路。分割大体分两类：一类是“按生物学分组想提取关心的亚群”，另一类是“纯粹为了适配批量处理对文件进行物理切块”。这两种需求对应不同的实现思路，很多教程混为一谈，导致代码改来改去总不对味。

4.1 场景A：按注释标签筛选出目标细胞群

这类需求的典型场景是：从一个大局中抽取出某个细胞类型，或者某个样本组，然后单独做分析或可视化。

操作核心其实就三步：条件筛选、取子集、把子集写回 h5ad。

python复制import scanpy as sc
import numpy as np

adata = sc.read_h5ad("/data/big_slim.h5ad", backed="r")

# 在 backed 模式上做布尔条件筛选
boolean_mask = adata.obs["cell_type"].isin(["CD8_T", "NK"]).values

# 重要：直接取子集再 to_memory，一次性落成可写的内存 AnnData
subset = adata[boolean_mask].to_memory()
print("subset shape:", subset.shape)

subset.write_h5ad("/data/cd8_nk.h5ad", compression="gzip")

这里有个会被反复踩到的点：adata[boolean_mask] 拿到的是一个 View 对象，而不是真正独立的 AnnData。如果直接对它 write_h5ad()，anndata 会报错或者写出一个不完整的文件。所以必须加 .to_memory()，这个操作会把 backing 文件里对应区块的数据真正读进内存，付出这一步内存开销，换来的是后续可以随便写、随便改。

内存够不够是很多人担心的问题。这里给个量级感受：如果原始文件 30 GB，目标细胞群大约占全量 1/3，那么 subset.to_memory() 过程中暂时需要的峰值内存大约是子集本身的大小加上一些索引开销，也就是 10~12 GB 左右。对多数 32 GB 或 64 GB 机器是可行的。真正危险的是在子集写回后，自己不手动释放旧的大对象。

一个常见的错误是写成这样：

python复制# 不要这么做，backed 模式不是这么玩的
adata = sc.read_h5ad("/data/big_slim.h5ad")  # 直接加载全量
subset = adata[adata.obs["cell_type"].isin(["CD8_T", "NK"])]

这一版在 30 GB 文件上大概率直接 OOM。backed 模式的精髓就在于你不读取全量数据，只是通过查询条件在 HDF5 上做切片。

4.2 场景B：按顺序切块生成多个分片，供批量训练或并行处理

另一种更常见的需求，是把大文件切成 N 个大致等大的 h5ad 分片，例如为了平行跑 10 个下游任务，或者为了把数据分块喂给深度模型。

这时要注意的核心是：切分不能破坏数据本身的分布。如果你的数据是有批次效应的项目，每个分片里最好是混合了各个样本的细胞，而不是一个分片全是样本 A，另一个分片全是样本 B。否则切片本身会引入新的偏差。

一个稳妥的做法是使用分层切分，按样本列做 StratifiedKFold，这样可以保证每个分片里的样本比例大致相当：

python复制import scanpy as sc
import numpy as np
from sklearn.model_selection import StratifiedKFold

adata = sc.read_h5ad("/data/big_slim.h5ad", backed="r")
n_splits = 10
y = adata.obs["sample"].astype(str).values

skf = StratifiedKFold(n_splits=n_splits, shuffle=True, random_state=42)

# 分片后每个文件都独立保存
for fold, (_, test_idx) in enumerate(skf.split(np.zeros(adata.n_obs), y)):
    shard = adata[test_idx].to_memory()
    shard.write_h5ad(f"/data/shard_{fold:02d}.h5ad", compression="lzf")
    # 写完后及时释放
    del shard

代码里有两个细节值得解释。

第一，skf.split() 返回的 test_idx 是整数索引数组，adata[test_idx] 用位置索引来取子集，在 backed 模式下会触发 HDF5 读取对应行区块，这正是我们想要的操作。整数数组的随机索引在某些实现里会比连续切片慢，但比先载入全量再抽样快得多。

第二，每写完一个分片就用 del 删除对象，并且最好配合 gc.collect()。如果你在一个循环里不断构造 shard 对象而不释放，Python 的垃圾回收机制不会在对象离开作用域后立刻把内存还给操作系统，内存峰值会逐步上涨，最后可能所有分片写完了，机器也假死了。

如果不是很在意样本分布，而是希望把文件按行号切成连续 block，也可以直接用 np.array_split：

python复制chunk_size = 50000
n_chunks = int(np.ceil(adata.n_obs / chunk_size))

for i in range(n_chunks):
    start = i * chunk_size
    end = min((i + 1) * chunk_size, adata.n_obs)
    shard = adata[start:end].to_memory()
    shard.write_h5ad(f"/data/range_{i:02d}.h5ad", compression="lzf")

这种方式的好处是连续切片对底层磁盘 I/O 更友好，速度通常比随机分层切块快。如果下游任务对分布不敏感，只是需要把数据拆开分批处理，这个方案最简单直接。

4.3 分片后某一些工具要求重新初始化注释列

切出来的分片虽然形状和原数据一致，但 obs 和 var 里可能保留了许多来自大文件的中间列。有些列在切块后已经失去意义，例如原本的全量聚类标签。更麻烦的是，许多单细胞分析工具在跑 normalization、PCA、UMAP 时会检查 obs 里的特定列是否存在，如果存在旧的重建列，后面容易出现奇怪冲突。

我自己一般会在切块后做一步清理，重置关键信息：

python复制shard.obs = shard.obs[["sample", "cell_type"]]  # 只保留需要的列
shard.uns = {}
shard.obsm = {}

这个步骤虽然会丢掉部分注释，但能避免很多隐患。尤其在分片准备用来跑深度学习模型时，轻装上阵带来的收益远比保留一团 metadata 大。

5. 实测记录：内存占用、耗时以及我反复踩过的坑

理论讲了一堆，真实的数字可能更能说明问题。我拿手头真实的一个 22 GB slim 文件做了一次完整的分割测试，环境是 64 GB 内存、普通 SATA SSD，文件大约是 48 万细胞、31,000 基因。结果如表格所示：

从表格能看出来，直接全量加载是全场最失败的方式。backed 模式加瘦身处理后，即使是在 64 GB 内存上完成同样任务，也能有非常大的冗余，不会动不动死机。

5.1 最容易翻车：backed模式下对对象误赋值

我见过最多的问题就是有人读完 backed 模式后就正常写分析代码，比如直接：

python复制adata = sc.read_h5ad("big.h5ad", backed="r")
adata.obs["new_col"] = some_list  # 这一行在 backed='r' 下不报错，但并没有实际写入文件

由于 read-only 模式没有明显报错，很多人以为修改成功了，实际只是在内存里临时改了一份局部表。等到保存时才发现要么无法保存，要么会以错误的方式写回。我的建议是：backed 模式只用于读取和切片，切出来的数据一旦调用 .to_memory() 就立刻切到内存态，之后再做一切修改操作。

另外，如果要以 backed="r+" 模式原位修改大型 h5ad，对文件的操作限制更多，通常也更危险。实际工作中我更推荐“读出并另存”的方式，不带原地修改，原因很简单：出错后原文件还能保住。

5.2 索引重复与索引错位问题

另一个高频坑是子集写好后，局部索引已经不是全量原始索引。部分分片写回后，如果再拼接回去会出现重复 barcode。这里我建议在写分片时，额外把原始 barcode 保留为一个普通列，这样就算后续 obs_names 被修改，也不会丢失原始标识：

python复制shard.obs["orig_barcode"] = shard.obs_names.astype(str)

如果你想确保切片和全量文件能精确对应，也可以直接把原始 obs_names 留作索引，不重置，这样后续需要 merge 时能准确地定位回原文件。

5.3 字符串编码与旧版本anndata的读写兼容

h5ad 格式虽然规范，但不同 anndata 版本之间出现过编码兼容问题。特别是老版本的 scanpy/anndata 在读取新版写入的 categorical 列时，会报一些奇怪的错误，比如 Unknown categorical encoding type 之类。解决办法通常是把环境升级到当前主版本，或确保同一项目组都用统一版本的 anndata。跨版本传播超大 h5ad 时，最好先在原环境里做一次简单的“写出再读入”验证。

我在新版 h5ad 写入时发现一个比较实用的习惯：用 pandas 的 CategoricalDtype 之前，先确认 adata.obs[col].cat.categories 没有包含 NaN。当分类列里有缺失值时，切分后的某些分片可能完全不包含某个 category，而 category 本身会在背后保留完整 levels。这不会直接影响数据，但如果你后续做 pd.concat 时，会发现每个分片里的同一列 category levels 不同，导致合并时出现意外的 NaN或性能下降。

5.4 分割后其实经常需要重新走一步过滤

分片后的数据不是拿到就能直接用。很多流程在前一步整合大文件时已经过滤了低质量细胞和低表达基因，但按子集切出来的分片往往会漏掉某些只在其他亚群表达的基因。如果你准备跑差异表达分析，你需要保留所有基因，否则统计检验会在基因子集上做，结果会出现偏差；如果你只是想把数据喂给分类模型，则可以选择性地过滤掉那些在所有分片里零表达的基因，能再省一点磁盘。

我个人的偏好是：只有在每个分片都要做相同流程，并且流程本身包含过滤步骤的时候，才会在分片文件上重新执行过滤；如果分片是为了保留一个可供全量数据回溯的切片，那就不做任何额外修剪，保证行数、列数和原文件对齐。

分片完成之后的一点额外建议

当把所有分片都写好之后，最好对每个分片做一次快速完整性验证，避免某个分片在写盘时损坏或缺失：

python复制import scanpy as sc

for i in range(10):
    f = f"/data/shard_{i:02d}.h5ad"
    tmp = sc.read_h5ad(f)
    print(i, tmp.shape, tmp.obs["sample"].value_counts().head(2).to_dict())
    del tmp

这个验证虽然会花掉一些时间，但能提前暴露很多问题。比如漏掉 gex_only 导致某些分片 shape 不对，或者某些分片因为抽样方式不对导致 sample 分布极端失衡。

超大数据 h5ad 的分割，说到底考验的并不是什么高深技巧，而是两条原则：一是不该留在内存里的东西坚决不提前载进来，二是文件在落盘前先尽量瘦身。操作上真正要紧的就是 backed 模式加 .to_memory() 加分层切块这三板斧。用熟这三板斧之后，我后来处理超过 80 GB 的 h5ad 文件时，也没有再出现过 OOM 到整个分析流程崩溃的情况。