Python 如何读写HDF5文件:使用h5py库

HDF5（Hierarchical Data Format version 5）是一种设计用于存储和管理大规模、复杂数据的高性能文件格式。在 Python 中，h5py 是最主流的 HDF5 操作库，它提供了类似 Python 字典（Dict）和 NumPy 数组（ndarray）的高级接口，能够无缝地与科学计算生态集成。

HDF5 核心概念

HDF5 文件的内部结构非常类似于操作系统中的文件系统。它主要由以下四种核心逻辑概念组成：

‍1. File（文件）：
HDF5 文件的物理载体，同时也是逻辑结构的根目录（通常用 / 表示）。

‍2. Group（组）：
类似于操作系统中的文件夹。一个 Group 可以包含 Dataset（数据集）或者其他的 Group，用于对数据进行层次化组织。

‍3. Dataset（数据集）：
类似于操作系统中的文件，是实际存储数据的地方。Dataset 内部通常是同质的、多维度的数值型数组（类似于 NumPy 数组）。

‍4. Attribute（属性）：
附加在 Group 或 Dataset 上的元数据（Key-Value 对）。常用于保存辅助信息，例如数据的单位、采样率、创建时间或作者信息等。

h5py 包介绍

h5py 提供了对 HDF5 C 语言库的 Python 包装。它的核心设计理念是：

‍✦ 将 Group 映射为 Python 的字典（dict）：通过键值对的方式访问子组和数据集，如 f['/group_name/dataset_name']。

‍✦ 将 Dataset 映射为 NumPy 数组（ndarray）：支持切片操作，仅在需要时才将数据读入内存，非常适合超大文件的延迟加载。

信息整理

‍✦ GitHub：https://github.com/h5py/h5py

‍✦ 官网：https://www.h5py.org/

安装方法

可以使用 pip 或 conda 进行安装：

pip install h5py
# 或者使用 conda
conda install h5py

写入 HDF5 文件

写入 HDF5 时，推荐使用 Python 的 with 语句来管理文件生命周期，这样可以确保即使程序出错，文件也能被正确关闭并写入磁盘。

创建 Dataset

Dataset是HDF5中存储实际数据的基本单元。可以创建Dataset，然后再写入数据；也可以创建Dataset的同时写入数据，可以直接写入 NumPy 数组，h5py 会根据 NumPy 的数据类型自动选择对应的 HDF5 存储类型。

import h5py
import numpy as np

# 'w' 模式：写模式（如果文件存在则覆盖，不存在则创建）
with h5py.File("data_example.h5", "w") as f:
# 模拟一些数据
    matrix_data = np.random.randn(100, 100)

# 方式 A：显式指定数据集名称和数据
    f.create_dataset("matrix", data=matrix_data)

# 方式 B：显式指定 shape 和 dtype，随后写入数据
    ds = f.create_dataset("empty_matrix", shape=(10, 10), dtype="float32")
    ds[...] = 1.0# 填充数据

创建 Group

可以通过 create_group 构建多层级目录结构。

with h5py.File("data_example.h5", "w") as f:
# 创建一级子组
    group_sensor = f.create_group("sensor_data")

# 在一级子组下创建二级子组
    group_gps = group_sensor.create_group("gps")

# 写入数据到特定的组路径下
    gps_coords = np.array([[39.9, 116.4], [31.2, 121.5]])
    group_gps.create_dataset("coordinates", data=gps_coords)

# 也可以直接通过路径方式隐式创建层级（h5py 会自动生成缺失的组）
    f.create_dataset("sensor_data/temperature/reading", data=np.array([22.5, 23.0, 22.8]))

写入 Attribute

属性可以绑定在任何 Group 或 Dataset 上，用于存储描述性信息。

with h5py.File("data_example.h5", "w") as f:
# 创建数据集
    ds = f.create_dataset("temperature", data=[22.5, 23.0, 22.8])

# 写入属性（通过 .attrs 字典）
    ds.attrs["unit"] = "Celsius"
    ds.attrs["sensor_model"] = "DHT22"
    ds.attrs["calibration_factor"] = 1.02

# 给根目录（File）写属性
    f.attrs["author"] = "Antigravity AI"

可扩展数据集

在实际应用中，数据可能是流式产生并不断追加的。通过设置 maxshape 参数，可以创建能够动态扩容的 Dataset。

import h5py
import numpy as np

with h5py.File('resizable.h5', 'w') as f:
# 创建可扩展数据集，初始形状为(100,)，最大可扩展到无限
    dset = f.create_dataset('expandable', 
                           shape=(100,), 
                           maxshape=(None,),  # None表示该维度可无限扩展
                           dtype='float64')
    dset[:] = np.arange(100)

# 扩展数据集
    dset.resize((200,))
    dset[100:] = np.arange(100, 200)

# 创建二维可扩展数据集
    dset2 = f.create_dataset('expandable_2d',
                            shape=(10, 20),
                            maxshape=(None, 20),  # 只有第一维可扩展
                            dtype='int32')
    dset2[:] = np.arange(200).reshape(10, 20)

# 追加新的行
    dset2.resize((15, 20))
    dset2[10:] = np.arange(200, 300).reshape(5, 20)

压缩存储

针对大规模数据，HDF5 提供了内置的数据压缩机制。这通常配合分块（chunks）使用，能够极大地减少磁盘空间消耗，且在读取时可以自动解压。

with h5py.File("compressed_example.h5", "w") as f:
    large_data = np.random.randn(1000, 1000)

# 启用 gzip 压缩，设置压缩级别为 4（范围 1-9，数值越大压缩率越高，但越耗时）
    f.create_dataset(
"compressed_matrix", 
        data=large_data, 
        compression="gzip", 
        compression_opts=4, 
        chunks=(100, 100) # 指定分块形状
    )

此外还可以使用第三方库 hdf5plugin 可以使用更高性能的压缩算法（如 Zstd、LZ4 等），具体见Python 如何压缩HDF5文件

保存字符串

HDF5 原生不支持 Python 3 的可变长度 Unicode 字符串。在 h5py 中，推荐使用特定的数据类型来处理字符串。

with h5py.File("strings_example.h5", "w") as f:
# 1. 单个/少量变长 UTF-8 字符串
    utf8_type = h5py.string_dtype(encoding="utf-8")

# 2. 写入字符串数组
    words = np.array(["你好", "HDF5", "Python 数据科学"], dtype=object)
    ds = f.create_dataset("chinese_words", (3,), dtype=utf8_type)
    ds[:] = words

# 3. 简写方式（通常可以直接传入字节串 bytes，或者使用 asstr() 进行读写）
    f.create_dataset("ascii_bytes", data=[b"hello", b"world"])

读取 HDF5 文件

递归遍历文件结构

由于 HDF5 具有树状结构，我们可以使用 visit 或 visititems 方法对文件中的所有节点（Group 和 Dataset）进行深度优先遍历。

import h5py

defprint_structure(name, obj):
"""
    回调函数：
    name: 节点的相对路径 (如 '/sensor_data/temperature')
    obj: HDF5 Group 或 Dataset 对象
    """
    indent = "  " * name.count("/")
ifisinstance(obj, h5py.Dataset):
print(f"{indent}📄 Dataset: {name} (shape={obj.shape}, dtype={obj.dtype})")
# 打印属性
iflen(obj.attrs) > 0:
for k, v in obj.attrs.items():
print(f"{indent}    🏷️ {k}: {v}")
elifisinstance(obj, h5py.Group):
print(f"{indent}📁 Group: {name}")

# 以只读模式 'r' 打开文件
with h5py.File("data_example.h5", "r") as f:
print("--- 文件树形结构 ---")
    f.visititems(print_structure)

读取全部数据

当我们确定数据集较小，可以直接一次性读入内存转换为标准的 NumPy 数组。

with h5py.File("data_example.h5", "r") as f:
# 检查键是否存在
if"matrix"in f:
# 使用切片 [:] 读取全部数据到内存中，得到一个 NumPy ndarray
        data = f["matrix"][:]
print("数据类型:", type(data))
print("数据形状:", data.shape)

读取部分数据（切片/延迟加载）

这是 HDF5 最核心的优势之一。如果文件大小为数吉字节（GB），你只需读取其中的某一小块数据，而无需将其全部加载至内存。

with h5py.File("data_example.h5", "r") as f:
    dataset = f["matrix"] # 此时只是获取了数据集的引用，并未真正读取数据

# 仅读取前 10 行的前 5 列数据到内存
    sub_data = dataset[0:10, 0:5]
print("局部数据形状:", sub_data.shape)

小结

常用操作对照表

下面是 h5py 中最常用操作的方法整理，便于在实际开发中快速检索：

相关笔记

‍✦ 大文件存储格式丨HDF5

‍✦ 如何预览HDF5文件：使用HDFView

‍