如何恢复损坏的超大型HDF5文件及解读h5debug输出？

问题背景 #

有一个存储耗时数小时计算得到的logits集合的HDF5文件，从Mac通过SMB写入Windows 11的16TB NTFS磁盘（剩余13TB）。写入到接近4TB时失败，macOS Finder显示文件大小为4.04TB，但实际文件大小仅3.7TB，文件无法正常访问，需要恢复数据或排查问题根源。

h5debug输出结果 #

h5debug /Volumes/MacBackup-1/gguf/baseline_logits.hdf5

Reading signature at address 0 (rel)
File Super Block...
File name (as opened):                             /Volumes/MacBackup-1/gguf/baseline_logits.hdf5
File name (after resolving symlinks):              /Volumes/MacBackup-1/gguf/baseline_logits.hdf5
File access flags                                  0x00000000
File open reference count:                         1
Address of super block:                            0 (abs)
Size of userblock:                                 0 bytes
Superblock version number:                         0
Free list version number:                          0
Root group symbol table entry version number:      0
Shared header version number:                      0
Size of file offsets (haddr_t type):               8 bytes
Size of file lengths (hsize_t type):               8 bytes
Symbol table leaf node 1/2 rank:                   4
Symbol table internal node 1/2 rank:               16
Indexed storage internal node 1/2 rank:            32
File status flags:                                 0x00
Superblock extension address:                      18446744073709551615 (rel)
Shared object header message table address:        18446744073709551615 (rel)
Shared object header message version number:       0
Number of shared object header message indexes:    0
Address of driver information block:               18446744073709551615 (rel)
Root group symbol table entry:
   Name offset into private heap:                  0
   Object header address:                          96
   Cache info type:                                Symbol Table
   Cached entry information:
      B-tree address:                              136
      Heap address:                                680
Error in closing file!
HDF5: infinite loop closing library
      L,T_top,F,P,P,Z,FD,VL,VL,PL,E,SL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL,FL

文件实际大小 #

ls -la  /Volumes/MacBackup-1/gguf/baseline_logits.hdf5
-rwx------@ 1 macdev  staff   3.7T Nov 12 12:21 /Volumes/MacBackup-1/gguf/baseline_logits.hdf5

脚本失败日志 #

[471] 114207.41 ms [472] 24712.48 ms [473] 120010.91 ms [474] 134073.39 ms
INFO - Processed 4 chunks
INFO - Final file size: 3832472.77 MB
Running from 475 to 478
INFO - generate_logits starting (version 0.5.3)
INFO - Loaded precomputed tokens from /Users/Shared/Public/huggingface/salamandra-2b-instruct/imatrix/oscar/calibration-dataset.txt.tokens.npy
INFO - Processing chunks from 475 to 478
INFO - Estimated runtime: 6.11 minutes for 3 remaining chunks
[475] 122266.14 ms [476] 27550.59 ms ERROR - Unexpected error occurred: Can't decrement id ref count (unable to close file, errno = 9, error message = 'Bad file descriptor')
Error occurred. Exiting.

环境信息 #

• 写入目标：Windows 11 NTFS磁盘（16TB，剩余13TB）
• SMB版本：smb_3.1.1，且LARGE_FILE_SUPPORTED TRUE

排查与恢复方案 #

1. 修复文件系统层面问题 #

在Windows端对目标NTFS磁盘运行磁盘检查，修复可能存在的文件系统元数据错误：

chkdsk /f X:

（将X替换为磁盘对应的盘符）

2. 尝试修复HDF5文件 #

• 使用h5repack工具提取可恢复的数据并重新打包：

  h5repack -v /Volumes/MacBackup-1/gguf/baseline_logits.hdf5 repaired_logits.hdf5
  

  该工具会跳过损坏的块，尽可能保留可读取的数据集。
• 如果h5repack失败，用h5dump导出可读取的内容：

  # 导出整个文件的结构和数据（大文件可能耗时久）
  h5dump /Volumes/MacBackup-1/gguf/baseline_logits.hdf5 > logits_dump.txt
  # 或指定已知的数据集导出
  h5dump -d /logits_dataset /Volumes/MacBackup-1/gguf/baseline_logits.hdf5 > dataset_recovered.h5
  

3. h5debug输出解读 #

• Error in closing file! HDF5: infinite loop closing library：说明HDF5库在关闭文件时无法正常释放资源，核心原因是文件元数据（如根组符号表、对象头）未完成写入，导致结构不完整。
• 超块中多个字段显示为18446744073709551615：这是64位无符号整数的最大值，代表无效地址，说明文件写入中断时，超块的扩展部分未被正确初始化。
• 根组符号表的B-tree和堆地址正常，但文件关闭流程失败，证明数据块可能部分完整，但元数据损坏导致文件无法正常被HDF5库识别。

4. 后续预防措施 #

• 拆分大文件：将logits按批次存储为多个小HDF5文件，避免单文件接近4TB临界值，降低写入失败风险。
• 强化HDF5写入配置：在代码中设置fapl_set_fclose_degree(H5F_CLOSE_STRONG)，确保文件关闭时强制刷新所有元数据到磁盘。
• 优化SMB传输：挂载NTFS磁盘时添加参数rsize=65536,wsize=65536提升传输稳定性，优先使用有线网络避免无线波动。

内容的提问来源于stack exchange，提问作者roberto tomás