mindspore.mindrecord

MindRecord是MindSpore开发的一种高效数据格式,此模块提供了一些方法帮助用户将不同数据集转换为MindRecord格式, 也提供了一些操作MindRecord数据文件的方法如读取、写入、检索等。 用户可以使用FileWriter API生成MindRecord格式数据集,并使用MindDataset API加载MindRecord格式数据集。

用户还可以通过相应的子模块将其他格式数据集转换为MindRecord格式数据集。

class mindspore.mindrecord.FileWriter(file_name, shard_num=1, overwrite=False)[源代码]

将用户自定义的数据转为MindRecord格式数据集的类。

说明

生成MindRecord文件后,如果修改文件名,可能会导致读取文件失败。

参数:
  • file_name (str) - 转换生成的MindRecord文件路径。

  • shard_num (int,可选) - 生成MindRecord的文件个数。取值范围为[1, 1000]。默认值: 1

  • overwrite (bool,可选) - 当指定目录存在同名文件时是否覆盖写。默认值: False

异常:
  • ParamValueError - file_nameshard_num 无效。

样例:

>>> from mindspore.mindrecord import FileWriter
>>>
>>> writer = FileWriter(file_name="test.mindrecord", shard_num=1, overwrite=True)
>>> schema_json = {"file_name": {"type": "string"}, "label": {"type": "int32"}, "data": {"type": "bytes"}}
>>> schema_id = writer.add_schema(schema_json, "test_schema")
>>> indexes = ["file_name", "label"]
>>> status = writer.add_index(indexes)
>>> for i in range(10):
...     data = [{"file_name": str(i) + ".jpg", "label": i,
...              "data": b"\x10c\xb3w\xa8\xee$o&<q\x8c\x8e(\xa2\x90\x90\x96\xbc\xb1\x1e\xd4QER\x13?\xff"}]
...     status = writer.write_raw_data(data)
>>> status = writer.commit()
add_index(index_fields)[源代码]

指定schema中的字段作为索引来加速MindRecord文件的读取。schema可以通过 add_schema 来添加。

说明

  • 索引字段应为Primitive类型,例如 intfloatstr

  • 如果不调用该函数,则默认将schema中所有的Primitive类型的字段设置为索引。 请参考 mindspore.mindrecord.FileWriter 类的样例代码。

参数:
  • index_fields (list[str]) - schema中的字段。

返回:

MSRStatus,SUCCESS或FAILED。

异常:
  • ParamTypeError - 索引字段无效。

  • MRMDefineIndexError - 索引字段不是Primitive类型。

  • MRMAddIndexError - 无法添加索引字段。

  • MRMGetMetaError - 未设置schema或无法获取schema。

add_schema(content, desc=None)[源代码]

增加描述用户自定义数据的schema。

说明

请参考 mindspore.mindrecord.FileWriter 类的样例代码。

MindRecord支持的数据类型

数据类型

数据维度

说明

int32

/

整数

int64

/

整数

float32

/

浮点数

float64

/

浮点数

string

/

字符串

bytes

/

二进制

int32

[-1] / [-1, 32, 32] / [3, 224, 224]

numpy.ndarray类型

int64

[-1] / [-1, 32, 32] / [3, 224, 224]

numpy.ndarray类型

float32

[-1] / [-1, 32, 32] / [3, 224, 224]

numpy.ndarray类型

float64

[-1] / [-1, 32, 32] / [3, 224, 224]

numpy.ndarray类型

参数:
  • content (dict) - schema内容的字典。

  • desc (str,可选) - schema的描述。默认值: None

返回:

int,schema ID。

异常:
  • MRMInvalidSchemaError - schema无效。

  • MRMBuildSchemaError - 构建schema失败。

  • MRMAddSchemaError - 添加schema失败。

样例:

>>> # Examples of available schemas
>>> schema1 = {"file_name": {"type": "string"}, "label": {"type": "int32"}, "data": {"type": "bytes"}}
>>> schema2 = {"input_ids": {"type": "int32", "shape": [-1]},
...            "input_masks": {"type": "int32", "shape": [-1]}}
commit()[源代码]

将内存中的数据同步到磁盘,并生成相应的数据库文件。

说明

请参考 mindspore.mindrecord.FileWriter 类的样例代码。

返回:

MSRStatus,SUCCESS或FAILED。

异常:
  • MRMOpenError - 打开MindRecord文件失败。

  • MRMSetHeaderError - 设置MindRecord文件的header失败。

  • MRMIndexGeneratorError - 创建索引Generator失败。

  • MRMGenerateIndexError - 写入数据库失败。

  • MRMCommitError - 数据同步到磁盘失败。

  • RuntimeError - 并行写失败。

classmethod open_for_append(file_name)[源代码]

打开MindRecord文件,准备追加数据。

参数:
  • file_name (str) - MindRecord格式的数据集文件的路径。

返回:

FileWriter,MindRecord文件的写对象。

异常:
  • ParamValueError - file_name 无效。

  • FileNameError - MindRecord文件路径中包含无效字符。

  • MRMOpenError - 打开MindRecord文件失败。

  • MRMOpenForAppendError - 打开MindRecord文件追加数据失败。

样例:

>>> from mindspore.mindrecord import FileWriter
>>>
>>> data = [{"file_name": "0.jpg", "label": 0,
...          "data": b"\x10c\xb3w\xa8\xee$o&<q\x8c\x8e(\xa2\x90\x90\x96\xbc\xb1\x1e\xd4QER\x13?\xff"}]
>>> writer = FileWriter(file_name="test.mindrecord", shard_num=1, overwrite=True)
>>> schema_json = {"file_name": {"type": "string"}, "label": {"type": "int32"}, "data": {"type": "bytes"}}
>>> schema_id = writer.add_schema(schema_json, "test_schema")
>>> status = writer.write_raw_data(data)
>>> status = writer.commit()
>>>
>>> write_append = FileWriter.open_for_append("test.mindrecord")
>>> for i in range(9):
...     data = [{"file_name": str(i+1) + ".jpg", "label": i,
...              "data": b"\x10c\xb3w\xa8\xee$o&<q\x8c\x8e(\xa2\x90\x90\x96\xbc\xb1\x1e\xd4QER\x13?\xff"}]
...     status = write_append.write_raw_data(data)
>>> status = write_append.commit()
set_header_size(header_size)[源代码]

设置MindRecord文件的header,其中包含shard信息、schema信息、page的元信息等。 header越大,MindRecord文件可以存储更多的元信息。如果header大于默认大小(16MB),需要调用本函数来设置合适的大小。

参数:
  • header_size (int) - header大小,可设置范围为16*1024(16KB)到128*1024*1024(128MB)。

返回:

MSRStatus,SUCCESS或FAILED。

异常:
  • MRMInvalidHeaderSizeError - 设置header大小失败。

样例:

>>> from mindspore.mindrecord import FileWriter
>>> writer = FileWriter(file_name="test.mindrecord", shard_num=1)
>>> status = writer.set_header_size(1 << 25) # 32MB
set_page_size(page_size)[源代码]

设置存储数据的page大小,page分为两种类型:raw page和blob page。 page越大,page可以存储更多的数据。如果单个样本大于默认大小(32MB),需要调用本函数来设置合适的大小。

参数:
  • page_size (int) - page大小,可设置范围为32*1024(32KB)到256*1024*1024(256MB)。

返回:

MSRStatus,SUCCESS或FAILED。

异常:
  • MRMInvalidPageSizeError - 设置page大小失败。

样例:

>>> from mindspore.mindrecord import FileWriter
>>> writer = FileWriter(file_name="test.mindrecord", shard_num=1)
>>> status = writer.set_page_size(1 << 26)  # 64MB
write_raw_data(raw_data, parallel_writer=False)[源代码]

根据schema校验用户自定义数据后,将数据转换为一系列连续的MindRecord格式的数据集文件。

说明

请参考 mindspore.mindrecord.FileWriter 类的样例代码。

参数:
  • raw_data (list[dict]) - 用户自定义数据的列表。

  • parallel_writer (bool,可选) - 如果为 True ,则并行写入用户自定义数据。默认值: False

返回:

MSRStatus,SUCCESS或FAILED。

异常:
  • ParamTypeError - 索引字段无效。

  • MRMOpenError - 打开MindRecord文件失败。

  • MRMValidateDataError - 数据校验失败。

  • MRMSetHeaderError - 设置MindRecord文件的header失败。

  • MRMWriteDatasetError - 写入MindRecord格式的数据集失败。

  • TypeError - 参数 parallel_writer 不是bool类型。

class mindspore.mindrecord.FileReader(file_name, num_consumer=4, columns=None, operator=None)[源代码]

读取MindRecord格式数据集。

说明

  • 如果 file_name 是文件路径的字符串,则会尝试加载同一批转换生成的所有MindRecord文件,如果缺少其中某个MindRecord文件,则会引发异常。

  • 如果 file_name 是文件路径组成的列表,则只加载列表中指定的MindRecord文件。

  • 参数 operator 未发挥任何作用,会逐步废弃。

参数:
  • file_name (str, list[str]) - MindRecord格式的数据集文件路径或文件路径组成的列表。

  • num_consumer (int,可选) - 加载数据的并发数。默认值: 4 。不应小于1或大于处理器的核数。

  • columns (list[str],可选) - MindRecord中待读取数据列的列表。默认值: None ,读取所有的数据列。

  • operator (int,可选) - 保留参数。默认值: None

异常:
  • ParamValueError - file_namenum_consumercolumns 无效。

样例:

>>> from mindspore.mindrecord import FileReader
>>>
>>> mindrecord_file = "/path/to/mindrecord/file"
>>> reader = FileReader(file_name=mindrecord_file)
>>>
>>> # create iterator for mindrecord and get saved data
>>> for _, item in enumerate(reader.get_next()):
...     ori_data = item
>>> reader.close()
close()[源代码]

停止数据集加载并且关闭文件句柄。

说明

请参考 mindspore.mindrecord.FileReader 类的样例代码。

get_next()[源代码]

按列名一次返回下一批的数据。

说明

请参考 mindspore.mindrecord.FileReader 类的样例代码。

返回:

dict,下一批数据,键值与数据列名相同。

异常:
  • MRMUnsupportedSchemaError - 当schema无效。

len()[源代码]

返回当前MindRecord文件的样本个数。

返回:

int,样本个数。

样例:

>>> from mindspore.mindrecord import FileReader
>>>
>>> mindrecord_file = "/path/to/mindrecord/file"
>>> reader = FileReader(file_name=mindrecord_file)
>>> length = reader.len()
>>> reader.close()
schema()[源代码]

返回当前MindRecord文件的Schema信息。

返回:

dict,Schema信息。

样例:

>>> from mindspore.mindrecord import FileReader
>>>
>>> mindrecord_file = "/path/to/mindrecord/file"
>>> reader = FileReader(file_name=mindrecord_file)
>>> schema = reader.schema()
>>> reader.close()
class mindspore.mindrecord.MindPage(file_name, num_consumer=4)[源代码]

以分页方式读取MindRecord文件的类。

参数:
  • file_name (Union[str, list[str]]) - MindRecord格式的数据集文件或文件列表。

  • num_consumer (int,可选) - 加载数据的并发数。默认值: 4 。不应小于1或大于处理器的核数。

异常:
  • ParamValueError - file_namenum_consumercolumns 无效。

  • MRMInitSegmentError - 初始化ShardSegment失败。

样例:

>>> from mindspore.mindrecord import MindPage
>>>
>>> mindrecord_file = "/path/to/mindrecord/file"
>>> mind_page = MindPage(mindrecord_file)
>>>
>>> # get all the index fields
>>> fields = mind_page.candidate_fields
>>>
>>> # set the field to be retrieved
>>> mind_page.category_field = "file_name"
>>>
>>> # get all the group info
>>> info = mind_page.read_category_info()
>>>
>>> # get the row by id which is from category info
>>> row_by_id = mind_page.read_at_page_by_id(0, 0, 1)
>>>
>>> # get the row by name which is from category info
>>> row_by_name = mind_page.read_at_page_by_name("8.jpg", 0, 1)
property candidate_fields

返回用于数据分组的候选category字段。

说明

请参考 mindspore.mindrecord.MindPage 类的样例代码。

返回:

list[str],候选category 字段。

property category_field

返回用于数据分组的category字段。

说明

请参考 mindspore.mindrecord.MindPage 类的样例代码。

返回:

list[str],category字段。

read_at_page_by_id(category_id, page, num_row)[源代码]

以分页方式按category ID进行查询。

说明

请参考 mindspore.mindrecord.MindPage 类的样例代码。

参数:
  • category_id (int) - category ID,参考 read_category_info 函数的返回值。

  • page (int) - 分页的索引。

  • num_row (int) - 每个分页的行数。

返回:

list[dict],根据category ID查询的数据。

异常:
  • ParamValueError - 参数无效。

  • MRMFetchDataError - 无法按category ID获取数据。

  • MRMUnsupportedSchemaError - schema无效。

read_at_page_by_name(category_name, page, num_row)[源代码]

以分页方式按category字段进行查询。

说明

请参考 mindspore.mindrecord.MindPage 类的样例代码。

参数:
  • category_name (str) - category字段对应的字符,参考 read_category_info 函数的返回值。

  • page (int) - 分页的索引。

  • num_row (int) - 每个分页的行数。

返回:

list[dict],根据category字段查询的数据。

read_category_info()[源代码]

当数据按指定的category字段进行分组时,返回category信息。

说明

请参考 mindspore.mindrecord.MindPage 类的样例代码。

返回:

str,分组信息的描述。

异常:
  • MRMReadCategoryInfoError - 读取category信息失败。

class mindspore.mindrecord.Cifar10ToMR(source, destination)[源代码]

将CIFAR-10数据集(需要是Python版本的,名字类似:cifar-10-python.tar.gz)转换为MindRecord格式数据集。

参数:
  • source (str) - 待转换的CIFAR-10数据集文件所在目录的路径。

  • destination (str) - 转换生成的MindRecord文件路径,需提前创建目录并且目录下不能存在同名文件。

异常:
  • ValueError - sourcedestination 无效。

样例:

>>> from mindspore.mindrecord import Cifar10ToMR
>>>
>>> cifar10_dir = "/path/to/cifar10"
>>> mindrecord_file = "/path/to/mindrecord/file"
>>> cifar10_to_mr = Cifar10ToMR(cifar10_dir, mindrecord_file)
>>> status = cifar10_to_mr.transform()
transform(fields=None)[源代码]

执行从CIFAR-10数据集到MindRecord格式数据集的转换。

说明

请参考 mindspore.mindrecord.Cifar10ToMR 类的样例代码。

参数:
返回:

MSRStatus,SUCCESS或FAILED。

异常:
  • ParamTypeError - 设置MindRecord索引字段失败。

  • MRMOpenError - 新建MindRecord文件失败。

  • MRMValidateDataError - 原始数据集数据异常。

  • MRMSetHeaderError - 设置MindRecord文件头失败。

  • MRMWriteDatasetError - 创建MindRecord索引失败。

  • TypeError - 参数 parallel_writer 不是bool类型。

  • ValueError - 参数 fields 不合法。

class mindspore.mindrecord.Cifar100ToMR(source, destination)[源代码]

将CIFAR-100数据集(需要是Python版本的,名字类似:cifar-100-python.tar.gz)转换为MindRecord格式数据集。

参数:
  • source (str) - 待转换的CIFAR-100数据集文件所在目录的路径。

  • destination (str) - 转换生成的MindRecord文件路径,需提前创建目录并且目录下不能存在同名文件。

异常:
  • ValueError - 参数 sourcedestination 无效。

样例:

>>> from mindspore.mindrecord import Cifar100ToMR
>>>
>>> cifar100_dir = "/path/to/cifar100"
>>> mindrecord_file = "/path/to/mindrecord/file"
>>> cifar100_to_mr = Cifar100ToMR(cifar100_dir, mindrecord_file)
>>> status = cifar100_to_mr.transform()
transform(fields=None)[源代码]

执行从CIFAR-100数据集到MindRecord格式数据集的转换。

说明

请参考 mindspore.mindrecord.Cifar100ToMR 类的样例代码。

参数:
返回:

MSRStatus,SUCCESS或FAILED。

异常:
  • ParamTypeError - 设置MindRecord索引字段失败。

  • MRMOpenError - 新建MindRecord文件失败。

  • MRMValidateDataError - 原始数据集数据异常。

  • MRMSetHeaderError - 设置MindRecord文件头失败。

  • MRMWriteDatasetError - 创建MindRecord索引失败。

  • TypeError - 参数 parallel_writer 不是bool类型。

  • ValueError - 参数 fields 不合法。

class mindspore.mindrecord.CsvToMR(source, destination, columns_list=None, partition_number=1)[源代码]

将CSV格式数据集转换为MindRecord格式数据集。

参数:
  • source (str) - 待转换的CSV文件路径。

  • destination (str) - 转换生成的MindRecord文件路径,需提前创建目录并且目录下不能存在同名文件。

  • columns_list (list[str],可选) - CSV中待读取数据列的列表。默认值: None ,读取所有的数据列。

  • partition_number (int,可选) - 生成MindRecord的文件个数。默认值: 1

异常:
  • ValueError - 参数 sourcedestinationpartition_number 无效。

  • RuntimeError - 参数 columns_list 无效。

样例:

>>> from mindspore.mindrecord import CsvToMR
>>>
>>> csv_file = "/path/to/csv/file"
>>> mindrecord_file = "/path/to/mindrecord/file"
>>> csv_to_mr = CsvToMR(csv_file, mindrecord_file)
>>> status = csv_to_mr.transform()
transform()[源代码]

执行从CSV格式数据集到MindRecord格式数据集的转换。

说明

请参考 mindspore.mindrecord.CsvToMR 类的样例代码。

返回:

MSRStatus,SUCCESS或FAILED。

异常:
  • ParamTypeError - 设置MindRecord索引字段失败。

  • MRMOpenError - 新建MindRecord文件失败。

  • MRMValidateDataError - 原始数据集数据异常。

  • MRMSetHeaderError - 设置MindRecord文件头失败。

  • MRMWriteDatasetError - 创建MindRecord索引失败。

  • TypeError - 参数 parallel_writer 不是bool类型。

  • IOError - 参数 source 不存在。

  • ValueError - CSV文件首行为列名,每个字段不能以数字开头。

class mindspore.mindrecord.ImageNetToMR(map_file, image_dir, destination, partition_number=1)[源代码]

将ImageNet数据集转换为MindRecord格式数据集。

参数:
  • map_file (str) - 标签映射文件的路径。该文件可通过命令: ls -l [image_dir] | grep -vE "总用量|total|\." | awk -F " " '{print $9, NR-1;}' > [file_path] 生成,其中 image_dir 为ImageNet数据集的目录路径, file_path 为生成的 map_file 文件 。 map_file 文件内容示例如下:

    n01440764 0
    n01443537 1
    n01484850 2
    n01491361 3
    ...
    n15075141 999
    
  • image_dir (str) - ImageNet数据集的目录路径,目录中包含类似n01440764、n01443537、n01484850和n15075141的子目录。

  • destination (str) - 转换生成的MindRecord文件路径,需提前创建目录并且目录下不能存在同名文件。

  • partition_number (int,可选) - 生成MindRecord的文件个数。默认值: 1

异常:
  • ValueError - 参数 map_fileimage_dirdestination 无效。

样例:

>>> from mindspore.mindrecord import ImageNetToMR
>>>
>>> map_file = "/path/to/imagenet/map_file"
>>> imagenet_dir = "/path/to/imagenet/train"
>>> mindrecord_file = "/path/to/mindrecord/file"
>>> imagenet_to_mr = ImageNetToMR(map_file, imagenet_dir, mindrecord_file, 8)
>>> status = imagenet_to_mr.transform()
transform()[源代码]

执行从ImageNet数据集到MindRecord格式数据集的转换。

说明

请参考 mindspore.mindrecord.ImageNetToMR 类的样例代码。

返回:

MSRStatus,SUCCESS或FAILED。

异常:
  • ParamTypeError - 设置MindRecord索引字段失败。

  • MRMOpenError - 新建MindRecord文件失败。

  • MRMValidateDataError - 原始数据集数据异常。

  • MRMSetHeaderError - 设置MindRecord文件头失败。

  • MRMWriteDatasetError - 创建MindRecord索引失败。

  • TypeError - 参数 parallel_writer 不是bool类型。

class mindspore.mindrecord.MnistToMR(source, destination, partition_number=1)[源代码]

将MNIST数据集转换为MindRecord格式数据集。

参数:
  • source (str) - 数据集目录路径,其包含t10k-images-idx3-ubyte.gz、train-images-idx3-ubyte.gz、t10k-labels-idx1-ubyte.gz和train-labels-idx1-ubyte.gz数据集文件。

  • destination (str) - 转换生成的MindRecord文件路径,需提前创建目录并且目录下不能存在同名文件。

  • partition_number (int,可选) - 生成MindRecord的文件个数。默认值: 1

异常:
  • ValueError - 参数 sourcedestinationpartition_number 无效。

样例:

>>> from mindspore.mindrecord import MnistToMR
>>>
>>> mnist_dir = "/path/to/mnist"
>>> mindrecord_file = "/path/to/mindrecord/file"
>>> mnist_to_mr = MnistToMR(mnist_dir, mindrecord_file)
>>> status = mnist_to_mr.transform()
transform()[源代码]

执行从MNIST数据集到MindRecord格式数据集的转换。

说明

请参考 mindspore.mindrecord.MnistToMR 类的样例代码。

返回:

MSRStatus,SUCCESS或FAILED。

异常:
  • ParamTypeError - 设置MindRecord索引字段失败。

  • MRMOpenError - 新建MindRecord文件失败。

  • MRMValidateDataError - 原始数据集数据异常。

  • MRMSetHeaderError - 设置MindRecord文件头失败。

  • MRMWriteDatasetError - 创建MindRecord索引失败。

  • TypeError - 参数 parallel_writer 不是bool类型。

class mindspore.mindrecord.TFRecordToMR(source, destination, feature_dict, bytes_fields=None)[源代码]

将TFRecord格式数据集转换为MindRecord格式数据集。

参数:
  • source (str) - 待转换的TFRecord文件路径。

  • destination (str) - 转换生成的MindRecord文件路径,需提前创建目录并且目录下不能存在同名文件。

  • feature_dict (dict[str, FixedLenFeature]) - TFRecord的feature类别的字典,当前支持 FixedLenFeature 类型。

  • bytes_fields (list[str],可选) - feature_dict 中的字节字段,可以为字节类型的图像字段。默认值: None ,表示没有诸如图像的二进制字段。

异常:
  • ValueError - 无效参数。

  • Exception - 找不到TensorFlow模块或其版本不正确。

样例:

>>> from mindspore.mindrecord import TFRecordToMR
>>> import tensorflow as tf
>>>
>>> tfrecord_file = "/path/to/tfrecord/file"
>>> mindrecord_file = "/path/to/mindrecord/file"
>>> feature_dict = {"file_name": tf.io.FixedLenFeature([], tf.string),
...                 "image_bytes": tf.io.FixedLenFeature([], tf.string),
...                 "int64_scalar": tf.io.FixedLenFeature([], tf.int64),
...                 "float_scalar": tf.io.FixedLenFeature([], tf.float32),
...                 "int64_list": tf.io.FixedLenFeature([6], tf.int64),
...                 "float_list": tf.io.FixedLenFeature([7], tf.float32)}
>>> tfrecord_to_mr = TFRecordToMR(tfrecord_file, mindrecord_file, feature_dict, ["image_bytes"])
>>> status = tfrecord_to_mr.transform()
transform()[源代码]

执行从TFRecord格式数据集到MindRecord格式数据集的转换。

说明

请参考 mindspore.mindrecord.TFRecordToMR 类的样例代码。

返回:

MSRStatus,SUCCESS或FAILED。

异常:
  • ParamTypeError - 设置MindRecord索引字段失败。

  • MRMOpenError - 新建MindRecord文件失败。

  • MRMValidateDataError - 原始数据集数据异常。

  • MRMSetHeaderError - 设置MindRecord文件头失败。

  • MRMWriteDatasetError - 创建MindRecord索引失败。

  • TypeError - 参数 parallel_writer 不是bool类型。