ImageNet100 Parquet 数据集转换指南

1. 背景与需求1.1 问题描述Hugging Face 下载的 ImageNet100 数据集通常以 Parquet 格式存储包含多个分片文件train-00000-of-00017.parquet~train-00016-of-00017.parquet训练集17个分片validation-00000-of-00001.parquet验证集但深度学习框架如 PyTorch通常需要 ImageFolder 格式的数据集即dataset/ ├── train/ │ ├── class_000/ │ │ ├── img_00000.jpg │ │ └── ... │ ├── class_001/ │ └── ... └── test/ ├── class_000/ └── ...2. 数据集结构分析2.1 Parquet 文件结构Parquet 文件包含两个核心列image: 图片数据bytes 格式label: 类别标签int 格式2.2 转换脚本开发创建了convert_parquet_simple.py脚本关键功能import pyarrow.parquet as pq import cv2 import numpy as np def convert_parquet_to_imagenet_folder(parquet_dir, output_dir, ...): # 1. 读取 Parquet 文件 table pq.read_table(train_path) # 2. 自动检测列名 image_col image label_col label # 3. 提取图片字节数据并解码 image_data images[idx].as_py() # bytes image_np cv2.imdecode( np.frombuffer(image_bytes, dtypenp.uint8), cv2.IMREAD_COLOR ) # 4. 按类别保存为 JPG cv2.imwrite(f{class_dir}/{img_count:05d}.jpg, image_np)2.3 完整转换脚本import os import cv2 import numpy as np import pyarrow.parquet as pq from tqdm import tqdm import json def convert_parquet_to_imagenet_folder( parquet_dir, output_dir, train_start0, train_end16, val_filevalidation-00000-of-00001.parquet ): 将 ImageNet100 的 Parquet 文件转换为 ImageFolder 格式 Args: parquet_dir: Parquet 文件所在目录 output_dir: 输出目录 train_start: 训练文件起始编号 train_end: 训练文件结束编号 val_file: 验证文件名 train_dir os.path.join(output_dir, train) test_dir os.path.join(output_dir, test) os.makedirs(train_dir, exist_okTrue) os.makedirs(test_dir, exist_okTrue) class_counts {train: {}, test: {}} class_names {} # 处理训练数据 for i in tqdm(range(train_start, train_end 1)): train_file ftrain-{i:05d}-of-00017.parquet train_path os.path.join(parquet_dir, train_file) table pq.read_table(train_path) images table[image] labels table[label] for idx in range(table.num_rows): image_data images[idx].as_py()[bytes] label int(labels[idx].as_py()) image_np cv2.imdecode( np.frombuffer(image_data, dtypenp.uint8), cv2.IMREAD_COLOR ) class_name fclass_{label:03d} class_dir os.path.join(train_dir, class_name) os.makedirs(class_dir, exist_okTrue) img_count class_counts[train].get(label, 0) cv2.imwrite( os.path.join(class_dir, fimg_{img_count:05d}.jpg), image_np ) class_counts[train][label] img_count 1 # 处理验证数据类似逻辑 # ... # 保存元数据 metadata { total_train_samples: sum(class_counts[train].values()), total_test_samples: sum(class_counts[test].values()), num_classes: len(class_names), class_counts: class_counts } with open(os.path.join(output_dir, metadata.json), w) as f: json.dump(metadata, f, indent2) if __name__ __main__: import argparse parser argparse.ArgumentParser() parser.add_argument(--parquet_dir, requiredTrue) parser.add_argument(--output_dir, requiredTrue) args parser.parse_args() convert_parquet_to_imagenet_folder( parquet_dirargs.parquet_dir, output_dirargs.output_dir )3. 环境配置与问题解决3.1 环境依赖依赖包版本要求说明pyarrow 14.0读取 Parquet 文件numpy 2.0与 pyarrow 兼容opencv-python最新图片解码3.2 环境冲突问题问题描述AttributeError: _ARRAY_API not found numpy.core.multiarray failed to import原因系统默认 Python 环境的 numpy 版本2.2.6与已编译的 pyarrow 不兼容。解决方案使用独立的 conda 环境# 检查可用环境 conda env list conda activate XXXXX # 验证环境 python -c import numpy; print(numpy.__version__) # 输出: 2.2.6 python -c import pyarrow; print(pyarrow.__version__) # 输出: 22.0.04. 转换执行过程4.1 完整命令conda activate XXXXX # 首次转换包含 17 个训练分片 python convert_parquet_simple.py \ --parquet_dir /imagenet100 \ --output_dir /data/imagenet100 \ --train_start 0 \ --train_end 16 # 补充缺失数据如有需要 python convert_parquet_simple.py \ --parquet_dir /imagenet100 \ --output_dir /data/imagenet100 \ --train_start 0 \ --train_end 04.2 转换结果统计指标数值训练样本总数126,342测试样本总数5,000类别数量100样本/类训练集~1,263样本/类测试集504.3 生成的文件结构/data/imagenet100/ ├── train/ # 100 个类别文件夹 │ ├── class_000/ # 1,300 张图片 │ ├── class_001/ # 1,300 张图片 │ ├── ... │ └── class_099/ # 1,300 张图片 ├── test/ # 100 个类别文件夹 │ ├── class_000/ # 50 张图片 │ ├── ... │ └── class_099/ # 50 张图片 └── metadata.json # 数据集元信息5. 数据验证5.1 验证命令# 检查类别数量 ls /data/imagenet100/train/ | wc -l # 输出: 100 # 检查测试集类别 ls /data/imagenet100/test/ | wc -l # 输出: 100 # 检查图片数量 find /data/imagenet100/train -name *.jpg | wc -l # 输出: 126342 # 检查特定类别样本数 ls /data/imagenet100/train/class_000/ | wc -l # 输出: 13007. 常见问题Q1: Parquet 文件读取失败检查import pyarrow.parquet as pq table pq.read_table(path/to/file.parquet) print(table.column_names) # 确认列名Q2: 图片解码失败原因图片数据可能存储在嵌套结构中解决image_data images[idx].as_py() if isinstance(image_data, dict): image_bytes image_data[bytes] else: image_bytes image_dataQ3: 缺少训练分片检查确保所有 17 个分片文件都存在ls imagenet100/train-*.parquet | wc -l # 应输出: 17