Python HDF5实战：h5py处理大规模传感器数据的核心技巧

1. 为什么值得花时间啃透HDF5这块硬骨头

做数据处理的同行大概都有过这种体验：手头一个几十GB的传感器采集文件，用pandas.read_csv一读，内存直接爆掉，机器风扇狂转，等了十分钟还没出结果。更让人头疼的是，这些数据往往不是规整的二维表，而是带层级结构的——比如一次实验有多个测点，每个测点有多个通道，每个通道又按时间片存储。用CSV或者JSON去装这种数据，要么拍平之后字段爆炸，要么嵌套太深查询起来像在迷宫里找路。

HDF5就是为这种场景生的。它的全称是Hierarchical Data Format version 5，翻译过来叫“层级数据格式”，你可以把它理解成一个专门为科学计算设计的“文件系统里的文件系统”。一个.h5文件内部可以像文件夹一样建组（group），组里再建组，也可以直接挂数据集（dataset），每个数据集是一块连续存储的多维数组。更关键的是，它支持分块存储、压缩、部分读取——你不需要把整个文件加载进内存，只读你关心的那一片就行。

我第一次在生产环境里用HDF5，是处理一批工业设备的振动信号。单个文件大概8GB，里面有128个通道，每个通道采样率25.6kHz，持续记录了40分钟。如果用传统方式存成CSV，光解析文本就要花掉几分钟，而且内存根本扛不住。换成HDF5之后，读取某个通道某10秒的数据，耗时不到200毫秒。这个差距不是优化出来的，是存储格式本身决定的。

这篇文章适合谁看？如果你正在处理以下任意一种场景，HDF5大概率能帮上忙：数据量超过内存容量、数据有天然的层级结构、需要频繁按切片读取而不是全量加载、需要在多个程序之间交换复杂数据结构。如果你只是处理几万行的表格数据，那pandas加Parquet可能更省事，不必为了用而用。

接下来我会从设计思路、核心概念、实操代码、性能调优、踩坑记录几个维度，把Python操作HDF5这件事讲透。代码基于h5py这个库，它是目前Python生态里操作HDF5最直接、最灵活的接口。全文的示例都可以直接复制运行，你只需要装好h5py和numpy。

2. HDF5的核心设计思路与Python生态选型

2.1 为什么是“层级”而不是“表格”

传统关系型数据库和CSV都假设数据是扁平的二维表，每一行是一条记录，每一列是一个字段。这个模型在处理业务数据时很好用，但遇到科学数据就捉襟见肘了。举个例子，一次风洞实验的数据可能是这样的结构：顶层是实验编号，下面挂着“压力数据”“温度数据”“位移数据”三个组，每个组里又有多个传感器通道，每个通道是一段随时间变化的数组。这种“组套组、组里挂数组”的结构，用表格表达要么得建很多张表然后join，要么得把数组序列化成二进制塞进一个字段里，两种做法都别扭。

HDF5的设计哲学是：数据本身就有结构，存储格式应该尊重这个结构。它用组来模拟目录树，用数据集来存数组，用属性（attribute）来存元数据。属性和数据集的区别在于，属性适合存小块的、描述性的信息，比如“采样率=25600”“单位=米”，而数据集适合存大块的、需要计算的数据。这个区分很实用，因为属性会被一次性读进内存，数据集可以按需读取。

2.2 h5py、PyTables、netCDF4怎么选

Python里操作HDF5的库不止一个，常见的有三个：h5py、PyTables、netCDF4。它们底层都调用同一个C库（HDF5官方库），但上层封装风格不同。

h5py的定位是“薄封装”，它尽量贴近HDF5的C API，给你最大的控制权。你可以直接操作数据空间（dataspace）、数据类型（datatype）、分块（chunking）、压缩（compression）这些底层概念。缺点是有些操作需要自己写循环，比如遍历组的时候得手动递归。

PyTables的定位是“厚封装”，它在HDF5之上做了一层类似数据库的抽象，支持索引、查询、条件筛选。如果你习惯用SQL的思维操作数据，PyTables会更顺手。但它对HDF5原生特性的暴露不如h5py直接，某些高级压缩算法和自定义数据类型支持得不够灵活。

netCDF4是气象和海洋领域的标准格式，它本身也是基于HDF5的（netCDF4格式底层就是HDF5）。如果你做的是气候、遥感、地球科学相关的工作，用netCDF4库可能更合适，因为它的API和社区规范都是围绕这些领域设计的。

我个人的选择是：通用场景用h5py，需要复杂查询用PyTables，领域是气象海洋用netCDF4。这篇文章以h5py为主，因为它的概念最干净，学会了之后换其他库也就是API熟悉的问题。

2.3 分块存储与压缩：HDF5性能的两个命门

HDF5之所以能处理超大文件，核心在于两个机制：分块存储和压缩。

分块存储的意思是，一个数据集在磁盘上不是连续存放的，而是切成固定大小的块（chunk），每块单独存储。这样做的好处是，当你读取数据集的一个切片时，HDF5只需要读取包含这个切片的那些块，而不是整个数据集。举个例子，一个形状为(10000, 1000)的数组，如果按(100, 100)分块，那么读取[0:50, 0:50]这个切片时，只需要读第一个块。如果不用分块，就得把整个数组读出来再切片，内存和IO都浪费了。

分块的大小需要权衡。块太小，元数据开销大，读取时寻址次数多；块太大，部分读取的粒度就粗，可能读了很多不需要的数据。经验法则是：让每个块的大小在10KB到1MB之间，并且让块的形状匹配你最常用的切片方式。如果你经常按行读取，就把块的行数设小一点；如果经常按列读取，就把块的列数设小一点。

压缩是另一个利器。HDF5支持多种压缩算法，常用的有gzip、lzf、szip。gzip压缩率高但速度慢，lzf速度快但压缩率一般。对于浮点数组，gzip级别4到6通常能在压缩率和速度之间取得不错的平衡。压缩不仅能省磁盘空间，还能减少IO量——因为读的时候只需要读压缩后的数据，解压是在内存里做的，而磁盘IO往往是瓶颈。

注意：压缩和分块是绑定的。只有启用了分块存储，才能启用压缩。因为压缩后的块大小不固定，必须分块才能定位。

3. h5py核心API与实操要点拆解

3.1 文件、组、数据集：三件套的基本操作

用h5py操作HDF5，核心就是三个对象：File、Group、Dataset。File代表整个文件，Group代表组（类似文件夹），Dataset代表数据集（类似数组）。它们的关系是：File本身也是一个Group（根组），Group里可以包含子Group和Dataset。

创建文件的代码很直观：

import h5py import numpy as np # 创建文件，'w'表示覆盖写入 with h5py.File('demo.h5', 'w') as f: # 在根组下创建数据集 data = np.arange(1000).reshape(100, 10) dset = f.create_dataset('raw_data', data=data) # 创建子组 grp = f.create_group('experiment_1') grp.create_dataset('temperature', data=np.random.rand(100)) grp.create_dataset('pressure', data=np.random.rand(100))

这里有几个细节值得说。第一，with语句是必须的，它保证文件在代码块结束时正确关闭。如果不关闭，数据可能还在缓冲区里没刷到磁盘，文件可能损坏。第二，create_dataset的data参数可以直接传numpy数组，h5py会自动推断数据类型和形状。第三，组的创建和数据集类似，create_group返回一个Group对象，你可以继续在上面挂东西。

读取的时候，Dataset对象支持numpy风格的切片：

with h5py.File('demo.h5', 'r') as f: # 读取整个数据集 full = f['raw_data'][:] # 读取切片 partial = f['raw_data'][10:20, 3:7] # 读取单个元素 single = f['raw_data'][5, 5]

这里的关键是：切片操作只读取需要的数据。如果你写f['raw_data'][10:20, 3:7]，h5py会根据分块信息，只读取覆盖这个切片的块。这就是为什么分块策略如此重要——它直接决定了切片读取的效率。

3.2 数据类型与形状的显式控制

虽然h5py能自动推断数据类型，但在生产环境里，显式指定类型是更好的习惯。原因有两个：一是避免平台差异（比如Windows上默认整数是32位，Linux上可能是64位），二是可以精确控制存储大小。

# 显式指定数据类型和形状 dset = f.create_dataset( 'sensor_data', shape=(10000, 128), dtype='float32', chunks=(100, 128), compression='gzip', compression_opts=4 )

这段代码创建了一个形状为(10000, 128)的数据集，但并没有立即写入数据。shape参数指定了数据集的维度，dtype指定了每个元素占4字节（float32）。chunks=(100, 128)表示按100行一块来分块，compression='gzip'启用gzip压缩，级别为4。

这种“先建骨架、后填数据”的方式在处理流式数据时特别有用。比如你从传感器实时读取数据，每读一批就写入对应的切片：

# 模拟分批写入 for i in range(0, 10000, 100): batch = np.random.rand(100, 128).astype('float32') dset[i:i+100, :] = batch

注意写入的切片形状必须和chunks对齐，否则h5py会报错。这是因为分块存储要求每个块的大小固定，如果你写入的切片跨越了块边界，h5py需要做额外的处理。对齐之后，每次写入正好落在一个块内，效率最高。

3.3 属性：给数据贴上标签

属性是HDF5里容易被忽视但非常有用的特性。它适合存那些“描述数据的数据”，比如单位、采样率、实验条件、创建时间。属性和数据集的区别在于：属性会被一次性全部读入内存，所以只适合存小数据；数据集可以按需读取，适合存大数据。

# 给数据集添加属性 dset.attrs['unit'] = 'm/s' dset.attrs['sampling_rate'] = 25600 dset.attrs['description'] = '振动速度信号' # 给组添加属性 grp.attrs['experiment_date'] = '2024-01-15' grp.attrs['operator'] = 'A同学' # 读取属性 print(dset.attrs['unit']) # 输出: m/s print(list(dset.attrs.keys())) # 输出: ['unit', 'sampling_rate', 'description']

属性的一个实用场景是版本管理。你可以在根组上挂一个version属性，记录数据的格式版本。当格式升级时，读取程序可以根据版本号决定用哪种解析逻辑。这比在文件名里加版本号要可靠得多，因为文件名可能被重命名，属性是跟着数据走的。

实操心得：属性名不要用中文，虽然HDF5规范允许，但某些工具链对非ASCII字符支持不好，容易出乱码。用英文加下划线是最稳妥的。

3.4 遍历与查询：怎么在层级结构里找东西

当文件结构复杂时，你需要遍历组来找到特定的数据集。h5py提供了visit和visititems两个方法。visit只访问组，visititems同时访问组和数据集。

def print_name(name): print(name) def print_name_and_type(name, obj): if isinstance(obj, h5py.Dataset): print(f"Dataset: {name}, shape={obj.shape}, dtype={obj.dtype}") elif isinstance(obj, h5py.Group): print(f"Group: {name}") with h5py.File('demo.h5', 'r') as f: f.visit(print_name) f.visititems(print_name_and_type)

visititems的回调函数接收两个参数：名字和对象。名字是相对于当前组的路径，比如experiment_1/temperature。对象是Dataset或Group实例，你可以直接检查它的类型和属性。

如果你知道路径，直接用字典风格的索引就行：f['experiment_1/temperature']。如果路径里有特殊字符（比如空格），可以用f['path with space']，h5py会正确处理。但为了避免麻烦，建议命名时只用字母、数字、下划线和斜杠。

4. 完整实操：从零搭建一个传感器数据存储方案

4.1 场景定义与数据结构设计

假设我们要处理一个模拟的工业监测场景：一台设备上有8个传感器，每个传感器以1000Hz的频率采集振动信号，持续记录1小时。总数据量是8通道 × 1000Hz × 3600秒 × 4字节 ≈ 115MB。这个量级不算大，但足以演示HDF5的核心优势。

数据结构设计如下：

• 根组下建一个metadata组，存设备编号、采集开始时间、采样率等全局信息。
• 根组下建一个sensors组，里面按传感器编号建8个子组。
• 每个传感器子组里建一个vibration数据集，形状为(3600000,)，即1小时的总采样点数。
• 每个vibration数据集按(10000,)分块，启用gzip压缩级别4。
• 每个数据集挂属性：unit、sensor_id、calibration_factor。

这个设计的好处是：读取某个传感器的某段时间数据时，只需要定位到对应的数据集，然后按切片读取。分块大小10000意味着每块覆盖10秒的数据，读取10秒切片正好读一个块，效率最高。

4.2 写入流程与参数计算

先算一下分块参数。采样率1000Hz，10秒就是10000个点。每个点float32占4字节，所以一个块是10000 × 4 = 40000字节，约40KB。这个大小在推荐范围（10KB到1MB）内，合适。

压缩级别选4。gzip级别1最快但压缩率低，级别9最慢但压缩率高。对于振动信号这种有一定周期性的数据，级别4通常能压到原始大小的60%到70%，而压缩耗时在可接受范围内。你可以根据实际数据做基准测试，但级别4是个稳妥的起点。

import h5py import numpy as np from datetime import datetime def create_sensor_file(filename, num_sensors=8, duration_sec=3600, fs=1000): total_samples = duration_sec * fs chunk_size = 10000 # 10秒一个块 with h5py.File(filename, 'w') as f: # 全局元数据 meta = f.create_group('metadata') meta.attrs['device_id'] = 'SIM-001' meta.attrs['start_time'] = datetime.now().isoformat() meta.attrs['sampling_rate'] = fs meta.attrs['duration_sec'] = duration_sec # 传感器组 sensors = f.create_group('sensors') for i in range(num_sensors): sensor_grp = sensors.create_group(f'sensor_{i:02d}') # 创建数据集骨架 dset = sensor_grp.create_dataset( 'vibration', shape=(total_samples,), dtype='float32', chunks=(chunk_size,), compression='gzip', compression_opts=4 ) # 挂属性 dset.attrs['unit'] = 'm/s^2' dset.attrs['sensor_id'] = f'ACC-{i:02d}' dset.attrs['calibration_factor'] = 1.0 + i * 0.01 # 模拟分批写入 for start in range(0, total_samples, chunk_size): end = min(start + chunk_size, total_samples) # 生成模拟振动信号：正弦波加噪声 t = np.arange(start, end) / fs signal = np.sin(2 * np.pi * 50 * t) + 0.1 * np.random.randn(end - start) dset[start:end] = signal.astype('float32') print(f"文件 {filename} 创建完成") create_sensor_file('sensor_data.h5')

这段代码有几个值得注意的地方。第一，shape参数指定了数据集的总大小，但数据是分批写入的。这利用了HDF5的“可扩展数据集”特性——虽然这里没有用maxshape，但分块存储本身就允许部分写入。第二，每次写入的切片[start:end]正好对齐到块边界，因为chunk_size和循环步长一致。第三，信号生成用了正弦波加高斯噪声，模拟真实振动信号的特征。

4.3 读取验证与性能对比

写完数据后，我们需要验证读取的正确性和性能。下面这段代码读取第一个传感器的前10秒数据，并和直接读取整个数据集做对比。

import time with h5py.File('sensor_data.h5', 'r') as f: dset = f['sensors/sensor_00/vibration'] # 方式一：读取前10秒（一个块） t0 = time.time() chunk = dset[:10000] t1 = time.time() print(f"读取一个块耗时: {(t1-t0)*1000:.2f} ms") # 方式二：读取前100秒（十个块） t0 = time.time() chunk = dset[:100000] t1 = time.time() print(f"读取十个块耗时: {(t1-t0)*1000:.2f} ms") # 方式三：读取整个数据集 t0 = time.time() full = dset[:] t1 = time.time() print(f"读取整个数据集耗时: {(t1-t0)*1000:.2f} ms") # 验证数据 print(f"数据集形状: {dset.shape}") print(f"数据类型: {dset.dtype}") print(f"压缩方式: {dset.compression}") print(f"分块大小: {dset.chunks}") print(f"属性: {dict(dset.attrs)}")

在我的测试环境里（普通SSD，16GB内存），读取一个块大约2到5毫秒，读取十个块大约20到30毫秒，读取整个数据集（360万个点，约14MB压缩后）大约200到400毫秒。这个性能对于交互式分析来说完全够用。

如果你把同样的数据存成CSV，文件大小会膨胀到约50MB（文本格式），读取前10秒需要解析整个文件的前面部分，耗时可能超过100毫秒。而且CSV不支持部分读取，你没法只读第100万到第101万个点而不读前面的内容。

注意：上面的耗时数据是示意性的，实际性能取决于磁盘类型、CPU、压缩级别、数据特征。建议你在自己的环境里跑一遍基准测试，得到真实的数字。

4.4 数据追加与动态扩展

实际场景中，数据往往是持续产生的，你不可能等所有数据都收集完再写文件。HDF5支持动态扩展数据集，只需要在创建时指定maxshape。

with h5py.File('streaming.h5', 'w') as f: # 创建可扩展数据集，初始大小为0，最大无限 dset = f.create_dataset( 'stream', shape=(0, 128), maxshape=(None, 128), dtype='float32', chunks=(1000, 128), compression='gzip' ) # 模拟流式追加 for i in range(10): batch = np.random.rand(1000, 128).astype('float32') old_size = dset.shape[0] new_size = old_size + 1000 dset.resize(new_size, axis=0) dset[old_size:new_size, :] = batch print(f"最终形状: {dset.shape}")

maxshape=(None, 128)表示第一个维度可以无限扩展，第二个维度固定为128。resize方法用于改变数据集大小。每次追加时，先扩展形状，再写入数据。这种模式适合日志记录、实时监测等场景。

但要注意，频繁resize会有性能开销，因为HDF5需要更新元数据。如果追加频率很高，建议攒一批再写，比如每1000行写一次，而不是每行都写。

5. 常见问题与排查技巧实录

5.1 文件打不开或数据损坏

最常见的问题是程序异常退出导致文件没有正确关闭。HDF5文件在写入时，元数据更新不是原子的，如果进程被kill，文件可能处于不一致状态。症状是打开时抛出OSError: Unable to open file或者读取时得到乱码。

排查思路：首先检查文件大小是否正常。如果文件大小是0或者远小于预期，说明写入根本没完成。如果大小正常但打不开，可以用h5py.File(filename, 'r')尝试只读模式打开，看报错信息。如果只读也打不开，可能需要用HDF5官方工具h5check来检查文件结构。

预防措施：始终用with语句管理文件句柄。如果代码逻辑复杂，确保在finally块里关闭文件。对于关键数据，写入完成后立即用f.flush()强制刷盘，然后再关闭。

5.2 内存溢出：为什么我只读了一个切片却爆了内存

这个问题通常是因为切片方式不对。如果你写dset[:]，那就是读整个数据集，当然会爆内存。但有时候你写的是dset[0]，以为只读第一行，结果也爆了——这是因为dset[0]返回的是一个numpy数组，如果数据集是二维的，dset[0]返回第一行，形状是(128,)，这个不大。但如果数据集是三维的，dset[0]返回的是一个二维切片，可能很大。

更隐蔽的情况是：你用了dset.value或者dset[...]，这两个都会读取整个数据集。正确的做法是明确指定切片范围，比如dset[0:100, :]。

另一个内存陷阱是数据类型转换。如果数据集是float64，你读出来之后做了astype('float32')，numpy会先创建float64数组再转换，峰值内存是两倍。如果数据量很大，这个峰值可能撑爆内存。解决办法是直接用dset.astype('float32')[:]，h5py会在读取时直接转换，不经过中间数组。

5.3 压缩率不理想怎么办

压缩率取决于数据本身的特征。如果数据是随机噪声，gzip几乎压不动，因为随机数据没有冗余。如果数据是平滑信号或者有周期性，压缩率会好很多。

提升压缩率的几个方向：第一，换压缩算法。gzip对浮点数据的压缩率一般，可以试试szip或者lzf。szip在某些科学数据上表现更好，但兼容性不如gzip。第二，调整数据布局。如果数据在内存里是行优先的，但你的切片经常按列读，可以考虑转置后再存，让相邻数据在磁盘上也相邻。第三，用“缩放+偏移”预处理。如果数据范围很小（比如0到1之间的浮点数），可以先转成整数再存，读取时再转回来。比如int16能表示-32768到32767，对于精度要求不高的场景，可以把float32转成int16，数据量直接减半。

5.4 并发读写冲突

HDF5文件默认不支持多进程同时写入。如果两个进程同时打开同一个文件写，后打开的会失败或者数据损坏。多线程也不行，因为h5py不是线程安全的。

解决方案有几种。如果只是读多写少，可以用“单写多读”模式：一个进程负责写，其他进程只读。HDF5支持多个读者同时打开文件，只要没有写操作。如果必须多进程写，可以用mpi4py配合HDF5的MPI版本，但这需要重新编译HDF5库，配置复杂。更简单的做法是每个进程写自己的文件，最后合并。或者用消息队列把写请求集中到一个进程。

实操心得：我在一个项目里遇到过这个问题，当时是多个采集进程往同一个H5文件写数据。后来改成每个进程写独立的临时文件，采集结束后用一个合并脚本统一整理到一个文件里。虽然多了一步，但稳定性大大提升，而且合并过程可以并行化。

5.5 常见问题速查表

6. 性能调优与进阶技巧

6.1 分块策略的量化分析方法

分块策略没有万能公式，但有一个量化分析方法：统计你的典型读取模式，然后选择让“读取块数/总块数”最小的分块形状。

假设你的数据集形状是(10000, 1000)，你经常读取[i:i+100, :]这样的行切片。如果分块是(100, 1000)，那么每次读取正好覆盖一个块，读取块数为1。如果分块是(1000, 100)，那么读取[i:i+100, :]需要读取10个块（因为每个块只覆盖100列，而你要读1000列）。所以对于行切片，分块的行数应该匹配切片行数，列数应该等于总列数。

你可以写一个简单的模拟脚本，统计不同分块方案下的读取块数：

def simulate_chunk_reads(shape, chunk_shape, slice_shape): rows, cols = shape chunk_rows, chunk_cols = chunk_shape slice_rows, slice_cols = slice_shape # 计算切片覆盖的块范围 row_chunks = (slice_rows + chunk_rows - 1) // chunk_rows col_chunks = (slice_cols + chunk_cols - 1) // chunk_cols return row_chunks * col_chunks # 示例 print(simulate_chunk_reads((10000, 1000), (100, 1000), (100, 1000))) # 1 print(simulate_chunk_reads((10000, 1000), (1000, 100), (100, 1000))) # 10

这个计算假设切片从块边界开始。如果切片不对齐，块数会更多。所以除了选择合适的分块形状，还要尽量让读取切片对齐到块边界。

6.2 用内存映射加速重复读取

如果你需要反复读取同一个数据集的相同部分，可以考虑用内存映射（memory mapping）。h5py支持driver='core'或driver='family'等驱动，但更简单的方法是用操作系统的页缓存。当你第一次读取一个块后，操作系统会把这块数据缓存在内存里，第二次读取就直接从内存拿，不走磁盘。

要利用页缓存，关键是保持文件打开状态，并且重复读取相同的块。如果你每次读取都重新打开文件，页缓存可能还在，但文件句柄的打开关闭有开销。对于交互式分析，建议在一个会话里保持文件打开。

另一个技巧是用f['dataset'][:]一次性读取整个数据集到内存，然后后续操作都在内存里做。这适合数据集能装进内存的情况。如果装不下，就得分块处理。

6.3 数据压缩与IO的权衡

压缩不是免费的。压缩和解压都需要CPU时间。如果CPU是瓶颈，压缩可能反而降低整体吞吐量。判断标准是：压缩节省的IO时间是否大于压缩消耗的CPU时间。

对于机械硬盘，IO速度慢，压缩通常划算。对于NVMe SSD，IO速度快，压缩可能不划算。你可以做一个简单测试：写入同样的数据，一次不压缩，一次压缩，比较总耗时。

import time data = np.random.rand(1000000).astype('float32') # 不压缩 t0 = time.time() with h5py.File('no_compress.h5', 'w') as f: f.create_dataset('data', data=data, chunks=(10000,)) t1 = time.time() print(f"不压缩写入耗时: {t1-t0:.3f}s") # 压缩 t0 = time.time() with h5py.File('compress.h5', 'w') as f: f.create_dataset('data', data=data, chunks=(10000,), compression='gzip', compression_opts=4) t1 = time.time() print(f"压缩写入耗时: {t1-t0:.3f}s")

在我的测试里，不压缩写入约0.05秒，压缩写入约0.15秒。但压缩后的文件大小是不压缩的60%左右。如果后续要多次读取这个文件，压缩节省的IO时间会逐渐抵消写入时的额外开销。

6.4 与pandas的配合使用

虽然HDF5不是为表格数据设计的，但你可以把二维数据集当成表格来用。pandas提供了read_hdf和to_hdf方法，底层用的就是PyTables。如果你已经有一个DataFrame，想存成HDF5，可以这样：

import pandas as pd df = pd.DataFrame({ 'timestamp': pd.date_range('2024-01-01', periods=10000, freq='1s'), 'value': np.random.randn(10000) }) # 存成HDF5 df.to_hdf('table.h5', key='data', mode='w', format='table') # 读取 df2 = pd.read_hdf('table.h5', key='data')

format='table'会创建一个可查询的表格结构，支持条件筛选。但要注意，pandas的HDF5存储和h5py的存储格式不完全兼容。pandas用的是PyTables的格式，h5py读的时候需要按PyTables的约定来解析。如果你需要在两个库之间交换数据，建议用h5py直接操作，避免格式转换的麻烦。

7. 从单文件到数据管道：HDF5在真实项目中的位置

7.1 什么时候该用HDF5，什么时候不该用

HDF5不是银弹。它适合的场景是：数据有层级结构、数据量大到内存装不下、需要按切片读取、需要在不同程序之间交换复杂数据。它不适合的场景是：数据是简单的二维表且能装进内存（用Parquet或CSV更简单）、需要频繁的行级更新（HDF5不支持原地更新，只能重写整个数据集）、需要事务支持（HDF5没有事务概念）。

我见过一些项目把HDF5当数据库用，结果在并发写入和查询上踩了很多坑。HDF5的定位是“科学数据容器”，不是“数据库”。如果你需要数据库的功能，应该用SQLite、DuckDB或者真正的数据库。

7.2 数据管道的典型架构

在一个典型的数据管道里，HDF5通常出现在中间层。上游是数据采集，可能产生CSV、二进制流或者消息队列。中间层用HDF5做标准化存储，把不同来源的数据统一成层级结构。下游是分析程序，从HDF5里按需读取切片，做计算或可视化。

这个架构的好处是解耦。采集程序不需要知道分析程序怎么读数据，只需要按约定写入HDF5。分析程序不需要知道数据从哪来，只需要按路径读取。中间的HDF5文件就是契约。

一个实际的做法是：每天生成一个HDF5文件，文件名包含日期。文件内部按数据源分组，每个数据源下面按通道分组。分析程序根据日期和数据源路径定位数据。这样既方便管理，也方便归档。

7.3 数据版本管理与迁移

HDF5文件一旦生成，格式就固定了。如果后续需要修改结构（比如增加一个通道、改变数据类型），旧文件和新文件就不兼容了。解决办法是在根组上挂一个format_version属性，读取程序根据版本号决定用哪种解析逻辑。

with h5py.File('data.h5', 'r') as f: version = f.attrs.get('format_version', 1) if version == 1: # 旧格式解析逻辑 pass elif version == 2: # 新格式解析逻辑 pass

迁移旧文件时，可以写一个转换脚本，读旧格式、写新格式。因为HDF5支持流式读取，转换过程不需要把整个文件加载进内存。

实操心得：我在一个项目里遇到过格式升级的问题。当时有几千个旧文件需要迁移，每个文件几GB。我的做法是写一个并行转换脚本，用多进程池同时处理多个文件。每个进程读一个旧文件，写一个新文件，互不干扰。转换完成后，用校验脚本对比新旧文件的关键数据集，确保数据没有丢失。

7.4 与其他格式的对比

选择格式时，先问自己三个问题：数据有层级结构吗？数据量超过内存吗？需要按切片读取吗？如果三个都是“是”，HDF5是首选。如果只有第一个是“是”，可以考虑JSON或自定义二进制格式。如果只有第二个是“是”，Parquet可能更合适。

8. 一些踩过的坑和最后的建议

先说一个我踩过的坑：早期用h5py的时候，我习惯用f['dataset'][:]读取整个数据集，然后做切片。后来数据量涨到几十GB，内存直接爆了。排查了半天才发现，问题不在切片逻辑，而在读取方式。改成f['dataset'][start:end]之后，内存占用从几十GB降到几百MB。这个教训是：永远不要读你不确定大小的数据集。在读取之前，先打印dset.shape，算一下需要多少内存。

第二个坑是压缩级别。我曾经为了追求压缩率，把gzip级别设到9。结果写入速度慢得离谱，一个1GB的文件写了将近10分钟。后来降到4，写入时间降到2分钟，压缩率只差了5个百分点。这个教训是：压缩级别不是越高越好，要在压缩率和速度之间找平衡。对于大多数场景，级别4到6足够了。

第三个坑是属性命名。我曾经用中文属性名，结果在另一个工具里打开时全是乱码。后来统一改成英文加下划线，再也没出过问题。这个教训是：跨工具交换的数据，命名要保守。字母、数字、下划线是最安全的字符集。

如果你刚开始用HDF5，我的建议是从小项目开始。先拿一个几MB的数据集练手，熟悉文件、组、数据集、属性的操作。然后逐步增加数据量，观察内存和耗时的变化。最后再上生产环境。不要一上来就处理几十GB的文件，那样出了问题很难定位。

另外，养成写元数据的习惯。每个数据集至少挂三个属性：unit（单位）、description（描述）、created_at（创建时间）。这些信息在几个月后你回头看的时候，会救命。我见过太多项目，数据文件还在，但没人知道里面的数字是什么意思。

最后，HDF5的官方文档和h5py的文档都写得不错，遇到问题先查文档。如果文档解决不了，可以在科学计算社区提问，那里有很多有经验的用户。但提问之前，先写一个最小可复现的例子，这样别人更容易帮你定位问题。