Datasets

一、基本概念

  1. Datasets 是一个用于轻松地访问和共享数据集的库,这些数据集是关于音频、计算机视觉、以及自然语言处理等领域。

    Datasets 可以通过一行来加载一个数据集,并且可以使用 Hugging Face 强大的数据处理方法来快速准备好你的数据集。在 Apache Arrow 格式的支持下,通过 zero-copy read 来处理大型数据集,而没有任何内存限制,从而实现最佳速度和效率。

  2. Arrow 是一种特定的数据格式,以列式的 memory layout 存储数据。这提供了几个显著的优势:

    • Arrow 的标准格式允许 zero-copy read,这实际上是消除了所有的序列化开销。
    • Arrow 是语言无关的,它支持不同的编程语言。
    • Arrow 是面向列的,因此在查询和处理数据切片或列时,它的速度更快。
    • Arrow 允许 copy-free 地移交给标准的机器学习工具,如 Numpy, Pandas, PyTorch, TensorFlow
    • Arrow 支持多种列类型(可能是嵌套类型)。
  3. Datasets 使用 Arrow 作为它的局部缓存系统,这允许 datasetson-disk cache 来支持,这是用于 fast lookup 的内存映射。这种架构允许在设备内存相对较小的机器上使用大型数据集。

    Arrow 数据实际上是从磁盘进行内存映射的,而不是加载到内存中。内存映射允许访问磁盘上的数据,并利用虚拟内存功能进行 fast lookup

    在使用 Arrow 的内存映射数据集上进行迭代,速度很快。

  4. 安装:

    如果希望安装 Audio 特性,执行命令:

    如果希望安装 Image 特性,执行命令:

  5. 音频数据集就像文本数据集一样被加载。然而,音频数据集的预处理略有不同。你需要一个 feature extractor ,而不是一个 tokenizer 。音频输入也可能需要重新采样其采样率,从而匹配你正在使用的预训练模型的采样率。

    例如:

  6. 同样地,图像数据集就像文本数据集一样被加载。图像数据集也需要一个 feature extractor ,而不是一个 tokenizer 。对图像进行数据增强在计算机视觉中很常见,你可以随意使用任何数据增强的库。

    例如:

  7. 文本数据集需要一个 tokenizer

    例如:

  8. Hugging Face Hub 包含了很多数据集,我们可以从 Hub 上下载和上传数据集。

    • 下载数据集:

    • 上传数据集:

      首先安装必要的库:

      然后再命令行中登录 Hugging Face 账户:

      最后在代码中上传数据集:

  9. Datasets 会存储以前下载和处理的数据集,因此当你需要再次使用它们时,可以直接从 cache 中重新加载它们。这避免了重新下载数据集或重新应用处理函数。

    Datasetscache 文件分配一个指纹 fingerprint 。指纹跟踪数据集的当前状态。初始指纹是使用来自Arrow table 的哈希、或 Arrow files 的哈希 (如果数据集在磁盘上)来计算的。通过组合前一状态的指纹、以及哈希最近应用的变换,从而计算随后的指纹。

    注意,需要确保所有的 transform 是可以 pickle 序列化或 dill 序列化的,否则 Datasets 使用一个随机的指纹并且抛出一个警告(此时 transformer 是不可哈希的)。

    当禁用缓存时,Datasets 会重新计算所有的内容。此时,每次都会生成缓存文件并将它们写入临时目录。Python session 结束时,临时目录中的缓存文件将被删除。

  10. Features 定义为数据集的内部结构,它用于指定底层的序列化格式。Features 包含了从列名和类型到ClassLabel 的所有高级信息,因此可以视为是数据集的 backbone

    Features 的格式很简单:dict[column_name, column_type] 。它是列名和列类型的字典。

    其中:

    • Value 特征表明 idx 数据类型为 int32sentence1/sentence2 数据类型为 string

    • label 特征表明 label 包含两个类别:'not_equivalent', 'equivalent' 。我们可以通过 ClassLabel.int2str() 以及 ClassLabel.str2int()label 执行整数和字符串之间的转换。

    另外还有一些有用的特征类型:

    • Sequence:包含多个特征。

    • Array2D/Array3D/... :包含可变长度的数据。

    • Audio:包含音频类型的数据,该特征具有三个重要的字段:

      • array:存放解码的音频数据,以一维的 array 来表示。
      • path:所下载的音频文件的路径。
      • sampling_rate:音频文件的采样率。
  11. Batch mapping:以 batch mode 来执行 Dataset.map() 是非常强大的,可以加速数据预处理过程,并自由地控制生成的数据集的规模。

    但是,注意 batch 中每一列的行数应该相同:

二、load_dataset() 原理

  1. 一个 dataset 是包含如下内容的目录:

    • 一些通用格式的数据文件,如 JSON, CSV, Parquet, text 等等格式。
    • 一个可选的 dataset script ,如果它需要一些代码来读取数据文件。这用于加载所有格式和结构的文件。

    load_dataset() 函数从本地或 Hugging Face Hub 获取 datasetHub 是一个 central repository ,它存储了 Hugging Face 的数据集和模型。

    • 如果数据集仅包含数据文件,那么 load_dataset() 会根据数据文件的扩展名(如 json, csv, parquet,text 等等)来自动推断如何加载数据文件。

    • 如果数据集有一个 dataset script ,那么 load_dataset()Hugging Face Hub 下载并导入 dataset scriptdataset script 中的代码定义数据集信息(描述、Features 、原始文件的 URL 等等),并讲述 Datasets 如何从 dataset script 生成和展示样本。

      dataset script 从原始文件的 URL 下载数据集文件,生成数据集并将其缓存在磁盘上的 Arrow table 中。 如果你以前下载过该数据集,那么 Datasets 将从缓存中重新加载它,从而避免重复下载。

  2. 构建一个数据集:首次加载数据集时,Datasets 获取原始数据文件,并将其构建为一个 table,这个 table 由行组成并且包含带类型的列。有两个主要的类负责构建数据集:BuilderConfigDatasetsBuilder

  3. BuilderConfigBuilderConfigDatasetsBuilder 的配置类,包含以下基本属性:

    • name:数据集的简称。
    • version:数据集的版本 id
    • data_dir:包含数据文件的本地目录的路径。
    • data_files:本地数据文件的文件名。
    • description:数据集的描述。

    如果你想向你的数据集添加额外的属性,如 class label,你可以创建 base BuilderConfig class 的子类。有两种方法可以填充 BuilderConfig 类及其子类的属性:

    • 在数据集的 DatasetsBuilder.BUILDER_CONFIGS() 属性中,提供一组预定义的 BuilderConfig 类(或子类)的实例。
    • 当你调用 load_dataset() 时,任何不是特定于该方法的关键字参数都将用于设置 BuilderConfig 类的关联属性(如果属性已经设置过,那么这里将覆盖它)。

    你还可以设置 DatasetBuilder.BUILDER_CONFIG_CLASSBuilderConfig 的任意自定义子类。

  4. DatasetsBuilderDatasetBuilder 访问 BuilderConfig 中的所有属性来构建实际的数据集。DatasetBuilder 有三个主要的方法:

    • DatasetBuilder._info():负责定义数据集属性。当你调用 dataset.info 时,Datasets 返回存储在这里的信息。同样地,这里也指定了 FeaturesFeatures 提供了每一列的名称和类型)。

    • DatasetBuilder._split_generator():下载或检索数据文件,将它们组织为 splits(即,训练集、验证集、测试集的拆分)。

      该方法有一个 DownloadManager ,可以从本地文件系统下载或获取文件。在 DownloadManager 中,有一个 DownloadManager.download_and_extract() 方法,它接受 URL 到原始数据文件的字典,并下载所请求的文件。可接受的输入包括:单个 URL 或路径、URL 或路径的列表/字典。任何压缩文件类型(如 TAR, GZIP, ZIP)都将被自动解压。

      文件下载完成之后,SplitGenerator 会将它们组织成 splitsSplitGenerator 包含 split 的名称,以及任何关键字参数(这些关键字参数用于提供给 DatasetBuilder._generate_examples() 方法)。这些关键字参数可以特定于每个 split,并且通常至少包括每个 split 的数据文件的本地路径。

    • DatasetBuilder._generate_examples() :为一个 split 读取并解析数据文件。然而,它根据来自 DatasetBuilder._info()features 指定的格式来生成样本。DatasetBuilder._generate_examples() 的输入实际上是 DatasetBuilder._split_generator() 的关键字参数中所提供的路径。

      数据集是使用 Python generator 生成的,该生成器不会将所有数据加载到内存中。因此,生成器可以处理大型数据集。但是,在将生成的样本刷新到磁盘上的数据集文件之前,它们存储在一个 ArrowWriter buffer 中。这意味着被生成的样本是以 batch 的方式写入的。如果数据集样本消耗大量的内存(如图像、视频),请确保在 DatasetBuilder 中为 DEFAULT_WRITER_BATCH_SIZE 属性指定一个较低的值。我们建议不要超过 200 MB 的大小。

  5. 没有 loading script:有时候我们希望能够快速使用一个数据集。实现一个 dataset loading script 有时会碍事。Datasets 消除了这个障碍,它使从 Hug 加载任何数据集成为可能,而无需 dataset loading script 。用户只需要将数据文件上传到 Hug 上的 dataset repository 中。

    loading script-free 方法使用 huggingface_hub library 来列出 dataset repository 中的文件。你也可以提供本地目录的路径,而不是 repository name。根据可用的数据文件格式,Datasets 自动选择一个 data file builder 来为你创建数据集。

  6. 维持完整性:为了确保数据集是完整的,load_dataset() 将对下载的文件执行一系列的测试,确保所有内容都在那里。以下数据将被验证:下载文件的列表、下载文件的字节数量、下载文件的 SHA256 checksum 、生成的 DatasetDictsplit 数量、生成的 DatasetDict 的每个 split 中的样本数。

    如果数据集没有通过验证,很可能数据集的原始 host 在数据文件中做了一些更改。在这种情况下,会引发一个错误,警告数据集已更改。要忽略错误,需要在 load_dataset() 中指定 ignore_verifications=True 。每当看到验证错误时,请随时在相应的数据集 "Community" 选项卡中发起一个 discussionpull request ,以便更新该数据集的完整性检查。

  7. Datasets 将每个数据集看作一个内存映射文件,这个内存映射文件提供了 RAM 和文件系统存储之间的映射,从而允许 Datasets 访问和操作数据集的元素而无需将数据集完全加载到内存中。内存映射文件也在多个进程之间共享,这使得像 Dataset.map()之类的方法可以并行化,而无需移动或者拷贝数据集。在底层,些功能都是由 apache Arrow 内存格式和 pyarrow 库提供的支持,使得数据加载和处理速度非常快速。Datasets 通常能以 GB/s 级别的速度迭代数据集。

    通过上述的方法就已经能够解决大多数大数据集加载的限制,但是有时候我们不得不使用一个很大的数据集, 该数据集甚至无法存储在笔记本电脑的硬盘上。例如,如果我们尝试下载整个 Pile 数据集,我们需要 825GB 的可用磁盘空间。为了处理这种情况,Datasets 提供了一个流式功能,这个功能允许我们动态下载和访问数据集元素而不需要下载整个数据集。

三、API

3.1 DatasetInfo

  1. DatasetInfo:包含数据集的信息。

    参数:

    • description:一个字符串,指定数据集的描述。
    • citation:一个字符串,指定数据集的 BibTeX citation
    • homepage:一个字符串,指定数据集的官方 URL
    • license:一个字符串,指定数据集的 licence
    • features:一个 Features 对象,指定数据集的特征。
    • post_processed:一个 PostProcessedInfo 对象,指定数据集的后处理信息。
    • supervised_keys:一个 SupervisedKeysData 对象,指定用于监督学习的 input featurelabel (如果该数据集有的话)。
    • builder_name:一个字符串,指定创建数据集的 GeneratorBasedBuilder 子类的名称。通常与相应的 script name 相匹配。它也是 dataset builder class namesnake_case 版本。
    • config_name :一个字符串,指定从 BuilderConfig 派生的配置的名称。
    • version:一个字符串,指定数据集的版本。
    • splits:一个字典,指定 split namemetadata 之间的映射。
    • download_checksums:一个字典,指定 URL 到被下载的数据集 checksum 和对应 metadata 之间的映射。
    • download_size:一个整数,指定为生成数据集而下载的文件的大小(单位字节)。
    • post_processing_size:一个整数,指定后处理之后数据集的大小(单位字节)。
    • dataset_size:一个整数,指定所有 splitArrow table 的组合后的大小(单位字节)。
    • size_in_bytes:一个整数,指定数据集关联的所有文件的总大小(包括下载的文件和 Arrow 文件,单位字节)。
    • task_templatesTaskTemplate 的一个列表,指定训练和评估期间预处理数据集的 task template 。每个模板都将数据集的 Features 转换为标准化的列名和类型。
    • config_kwargs:额外的关键字参数,传递给 BuilderConfig 并在 DatasetBuilder 中使用。

    注意:这些属性在 DatasetInfo 创建时被赋值,并可能在随后被更新。

    方法:

    • from_directory(dataset_info_dir: str, fs = None) :从dataset_info_dir 中的 JSON 文件中创建 DatasetInfo 。它将重写所有的 DatasetInfometadata

      参数:

      • dataset_info_dir:一个字符串,指定存放 metadata file 的目录。
      • fs:一个 fsspec.spec.AbstractFileSystem,指定从哪里下载文件。
    • write_to_directory(dataset_info_dir, pretty_print = False, fs = None):将 DatasetInfolicense 写入 dataset_info_dir 中的 JSON 文件。

      参数:

      • pretty_print:一个布尔值,指定 JSON 是否是 pretty-printed 的。
      • 其它参数参考 from_directory()

3.2 Dataset

  1. Dataset:数据集的基类,基于 Apache Arrow table 来实现。

    参数:文档未指定,源码也没有。

    属性:

    • info:返回一个 DatasetInfo 对象,包含数据集中的所有 metadata
    • split:返回一个 NamedSplit 对象,对应于 named dataset split
    • builder_name/citation/config_name/dataset_size/description/download_checksums/download_size/features/homepage/license/size_in_bytes/supervised_keys/version:参考 DatasetInfo 的属性。
    • format:返回一个字典,表示数据集的格式。
    • shape:返回一个 Tuple[int, int],表示数据集的形状(列数,行`数)。
    • column_names:返回一个字符串列表,表示数据集的列名。
    • num_rows:返回一个整数,表示数据集的行数。
    • num_columns:返回一个整数,表示数据集的列数。
    • cache_files:返回一个字典的列表,表示数据集背后的、包含 Apache Arrow table 的缓存文件。
    • data:返回一个 Tabe 对象,表示数据集背后的 Apache Arrow table

    方法:

    • add_column(name: str, column: Union[list, np.array], new_fingerprint: str) -> Dataset :向数据集中添加列。

      参数:

      • name:一个字符串,指定列名。
      • column:一个列表或 np.array,指定列数据。
      • new_fingerprint:一个字符串,指定新的指纹。

      返回一个 Dataset

    • add_item(item: dict, new_fingerprint: str) -> Dataset:向数据集中添加一行。

      参数:

      • item:一个字典,指定行数据。字典的 key 就是列名,需要提供全部列名。
      • 其它参数参考 add_column

      返回一个 Dataset

    • from_file():从 Arrow table 的文件中初始化一个数据集。

      参数:

      • filename:一个字符串,指定数据集的文件名。
      • info:一个 DatasetInfo 对象,指定数据集的信息。
      • split:一个 NamedSplit 对象,指定数据集的 split
      • indices_filename:一个字符串,指定索引的文件名。
      • in_memory:一个布尔值,指定是否将数据拷贝到内存。

      返回一个 Dataset

    • from_buffer():从 Arrow buffer 中初始化一个数据集。

      参数:

      • buffer:一个 pyarrow.Buffer ,指定 Arrow buffer
      • indices_buffer:一个 pyarrow.Buffer ,指定索引的 Arrow buffer
      • 其它参数参考 from_file()

      返回一个 Dataset

    • from_pandas():从 pandas.DataFrame 转换为一个 pyarrow.Table 进而创建一个数据集。

      Arrow Table 中的列类型是从 DataFrame 中的 pandas.Series 中推断而来。在 non-object Series 的情况下,Numpy dtype 被直接转换为对应的 Arrow 类型。在 object Series 的情况下,我们需要查看 Series 中的 Python object 来猜测数据类型。

      注意:object Series 可能没有包含足够的信息来推断 Arrow 类型,例如 DataFrame 的长度为零、或者 Series 仅包含 None/nan 对象,此时 Arrow type 被设为 null 。可以通过构造显式的 features 来避免。

      参数:

      • df:一个 pandas.DataFrame 对象,指定数据集的数据内容。

      • features:一个 Features 对象,指定数据集的特征。

      • preserve_index:一个布尔值,指定是否将 pandas 索引存储为数据集中的额外的列。

        默认值为 None,表示将索引存储为额外的列(RangeIndex 除外,它仅被存储为 metadata)。使用 True,则强制将索引存储为列(包括 RangeIndex)。

      • 其它参数参考 from_file()

      返回一个 Dataset

    • from_dict():从字典转换为一个 pyarrow.Table 进而创建一个数据集。

      参数:

      • mapping:一个字典对象,指定数据集的数据内容,它将字符串映射到 ArrayPython 列表。
      • 其它参数参考 from_pandas()

      返回一个 Dataset

    • from_list():从字典的列表转换为一个 pyarrow.Table 进而创建一个数据集。

      参数:

      • mapping:一个字典的列表,其中每个字典代表一行数据,字典的 key 就是列名,需要提供全部列名。
      • 其它参数参考 from_dict()

      返回一个 Dataset

    • from_csv():从 CSV 文件中创建数据集。

      参数:

      • path_or_paths:一个 path-like 对象或者 path-like 对象的列表,指定 CSV 文件的路径。
      • split:一个 NamedSplit 对象,指定被赋予到数据集上的 split name
      • features:一个 Features 对象,指定数据集特征。
      • cache_dir:一个字符串,指定缓存数据的目录。默认为 "~/.cache/huggingface/datasets"
      • keep_in_memory:一个布尔值,指定是否拷贝数据到内存。
      • **kwargs:关键字参数,传递给 padans.read_csv()

      返回一个 Dataset

    • from_generator():从迭代器中创建一个数据集。

      参数:

      • generator:一个可调用对象,表示一个 generator function,它可以 yield 样本。
      • gen_kwargs:一个字典,它作为关键字参数被传递给 generator 。你可以定义一个分片的数据集,其中在 gen_kwargs 中传递分片列表。
      • kwargs:额外的关键字参数,用于传递给 GeneratorConfig
      • 其它参数参考 from_csv()

      返回一个 Dataset

      示例(分片数据集):

    • from_json():从 JSON 文件中创建数据集。

      参数:

      • field:一个字符串,指定数据集被包含在JSON 文件的哪个字段,所对应的 field name
      • kwargs:关键字参数,传递给 JsonConfig
      • 其它参数参考 from_csv()

      返回一个 Dataset

    • from_parquet():从 Parquet 文件中创建数据集。

      参数:

      • columns:一个字符串的列表,如果不是 None,那么仅从文件中读取这些列。可以进行嵌套,如 a.b, a.d.e
      • kwargs:关键字参数,传递给 ParquetConfig
      • 其它参数参考 from_csv()

      返回一个 Dataset

    • from_text():从文本文件中创建数据集。

      返回一个新的 Dataset

      参数:

      • kwargs:关键字参数,传递给 TextConfig
      • 其它参数参考 from_csv()

      返回一个 Dataset

    • from_sql():从 SQL querydatabase table 中创建数据集。

      参数:

      • sql:一个字符串或者 sqlalchemy.sql.Selectable 对象,指定一个 table name 或者待执行的 sql query
      • con:一个字符串或者 sqlalchemy.engine.Connection 或者 sqlalchemy.engine.Engine 或者 sqlite3.Connection ,用于初始化一个 database connection
      • **kwargs:关键字参数,用于 SqlConfig
      • 其它参数参考 from_csv()

      返回一个 Dataset

    • unique( column: str ) -> list:返回指定列的 unique element 的列表。

      参数:column:一个字符串,指定列名。

      返回值:该列 unique 元素组成的列表。

    • flatten(new_fingerprint: Optional[str] = None, max_depth=16) -> Dataset:对数据集的所有列进行展平,返回当前数据集的、列被展平了的 copy 。每个 struct type 列被展平为:每个 struct filed 一个列。非 struct type 列被保留。

      参数:

      • new_fingerprint:一个字符串,指定数据集经过变换之后的新的指纹。如果为 None,那么这个新的指纹是基于一个哈希来计算得到,这个哈希考虑了前一个指纹、以及 transform argument
      • max_depth:一个整数,指定最多展平多少层。

      返回一个 Dataset (拷贝后的新数据集)。

    • cast():对数据集的列进行类型强制转换,返回当前数据集的被类型转换的 copy

      参数:

      • features:一个 Features 对象,指定数据集要强制转换的新的 featuresfeatures 的字段名必须匹配当前的列名。并且底层的数据能够支持转换到目标类型。对于困难的转换,如 string <-> ClassLabel,你必须使用 map 来进行转换。
      • batch_size:一个整数,指定强制类型转换的每个 batch 的样本数。如果 batch_size <= 0 或者 batch_size == None,那么将整个数据集作为单个 batch 来强制类型转换。
      • keep_in_memory:一个布尔值,是否拷贝数据到内存中。
      • load_from_cache_file:一个布尔值,如果一个缓存文件已经存储了当前的计算,那么使用这个缓存文件而不是重新计算。
      • cache_file_name:一个字符串,指定缓存文件的路径名。如果未指定,则自动生成缓存文件名。
      • writer_batch_size:一个整数,指定 cache file writer 每次写操作时写入多少行。该值是内存占用和处理速度之间的 trade-off:取值越大则处理速度更快(因为查找次数更少),取值越小则内存占用更少。
      • num_proc:一个整数,指定多进程处理时的进程数。默认不使用多进程。

      返回一个 Dataset (拷贝后的新数据集)。

    • cast_column(column: str, feature: FeatureType, new_fingerprint: Optional[str] = None) -> Dataset:强制类型转换指定的列。

      参数:

      • column:一个字符串,指定列名。
      • feature:一个 FeatureType 对象,表示目标的类型。
      • new_fingerprint:参考 cast()

      返回一个 Dataset

    • remove_columns(column_names: Union[str, List[str]], new_fingerprint: Optional[str] = None) -> Dataset:返回数据集的一个 copy 版本,该版本移除数据集中的某些列及其关联的内容。

      参数:

      • column_names:一个字符串或者字符串列表,指定要被移除的列。
      • new_fingerprint:参考 cast()

      返回一个 Dataset (拷贝后的新数据集)。

      你也可以通过带 remove_columnsDataset.map() 方法来移除列,但是 map() 方法是原地修改(而不会拷贝一个新的数据集),因此速度更快。

    • rename_column( original_column_name: str, new_column_name: str, new_fingerprint: Optional[str] = None) -> Dataset:返回数据集的一个 copy 版本,该版本重命名了数据集的指定列。

      参数:

      • original_column_name:一个字符串,指定旧的列名。
      • new_column_name:一个字符串,指定新的列名。
      • new_fingerprint:参考 cast()

      返回一个 Dataset (拷贝后的新数据集)。

    • rename_columns(column_mapping: Dict[str, str], new_fingerprint: Optional[str] = None) -> Dataset:返回数据集的一个 copy 版本,该版本重命名了数据集的一些列。

      参数:

      • column_mapping:一个字典,键为旧的列名、值为新的列名。
      • new_fingerprint:参考 cast()

      返回一个 Dataset (拷贝后的新数据集)。

    • class_encode_column(column: str, include_nulls: bool = False) -> Dataset:将指定的列强制类型转换为 datasets.features.ClassLabel ,并更新数据集。

      参数:

      • column:一个字符串,指定被强制类型转换的列名。
      • include_nulls:一个布尔值,指定 class label 中是否包含 null value 。如果为 True,则 null value 被编码为 None

      返回一个 Dataset

    • __len__() -> int:返回数据集的行数。

    • __iter__() :迭代从而每次迭代产生样本。如果已经通过 Dataset.set_format() 来设置了格式,那么迭代返回的 row 将具有指定的格式。

    • formatted_as():用于在 with 表达式中使用,它设置了 __getitem__ 所返回的格式。

      参数:

      • type:一个字符串,指定输出类型,可以为 None, 'numpy', 'torch', 'tensorflow', 'pandas', 'arrow'None 意味着 __getitem__ 返回 Python 对象。
      • columns:一个字符串列表,指定输出中哪些列需要被格式化。None 意味着 __getitem__ 返回所有的列。
      • output_all_columns:一个布尔值,指定是否在输出中保留 un-formatted 列(作为 python 对象)。
      • **format_kwargs:关键字参数,被传递给一些转换函数,如 np.array, torch.tensor, tensorflow.ragged.constant

      可以通过 Dataset.format 来查看数据集的格式。

    • set_format():设置 getitem 所返回的格式。数据格式化是 on-the-fly 应用的。

      参数:参考 formatted_as()

      也可以通过 Dataset.set_transform() 来使用自定义的变换从而用于格式化。

      如果你在调用 Dataset.set_format() 之后再调用 Dataset.map() 从而创建一个新的列,那么这个新的列也会被格式化。

    • set_transform():利用 transform 来转换 getitem 所返回的内容。 transformon-the-fly 应用到 batch 上的。

      参数:

      • transform:一个可调用对象,给出了用户自定义的转换。它的输入是一个 batch (以字典的形式,键位列名、值为该列在 batch 内的值)作为输入并返回一个 batch 作为输出。这个可调用对象再 getitem 返回之前的时刻被调用。
      • columns:一个字符串列表,如果指定,则表示转换仅发生在这些列上,此时 transform 的输入仅包含这些列作为 key 的字典。
      • output_all_columns:一个布尔值,指定是否输出所有的列。如果为 True,则未包含在 transform 中的列也被输出。
    • reset_format():恢复 getitem 的格式为,对所有的列返回 python 对象。

    • with_format():设置 getitem 所返回的格式。几乎类似于 set_format()

      参数:参考 set_format()

      Dataset.set_format() 是原地修改操作,而 Dataset.with_format() 返回一个新的Dataset

    • with_transform():利用 transform 来转换 getitem 所返回的内容。几乎类似于 set_transform()

      参数:参考 set_transform()

      Dataset.set_transform() 是原地修改操作,而 Dataset.with_transform() 返回一个新的Dataset

    • __getitem__(key):用于对列索引(key 为列名字符串)或行索引(key 为整数索引、或者索引集合、或布尔值集合)。返回指定索引的值。

    • cleanup_cache_files() -> int:清理数据集缓存目录中的所有缓存文件,当前使用的缓存文件(如果有的话)除外。

      返回被清除的文件的数量。

      运行此命令时要小心,确保当前没有其他进程正在使用其他缓存文件。

    • map():对数据集中每个样本执行一个函数(以单个样本的形式或 batch 的形式),并更新数据集。如果函数返回的列在数据集中已存在,则覆盖该列。

      参数:

      • function:一个可调用对象,它被应用到样本上。它的签名为:

        • 如果 batched=Falsewith_indices=Falsewith_rank=False ,那么函数签名为 function(example: Dict[str, Any]) -> Dict[str, Any]

        • 如果 batched=Falsewith_indices=True 且/或 with_rank=True ,那么函数签名为 function(example: Dict[str, Any], extra_args) -> Dict[str, Any]

          其中 extra_args 包含一个或两个参数,对应于 with_indices=True 且/或 with_rank=True

        • 如果 batched=Truewith_indices=Falsewith_rank=False ,那么函数签名为 function(batch: Dict[str, List]) -> Dict[str, List]

        • 如果 batched=Truewith_indices=True 且/或 with_rank=True ,那么函数签名为 function(batch: Dict[str, List], extra_args) -> Dict[str, List]

        对于更高级的用法,function 也可以返回一个 pyarrow.Table。此外,如果 function 返回 None,那么 map 将执行该 function 并保留数据集不变。如果没有提供 function,则默认为恒等映射:lambda x : x

      • with_indices:一个布尔值,指定是否提供样本索引作为 function 的输入。此时,function 的签名应该是 function(example, idx[, rank])

      • with_rank:一个布尔值,指定是否将 rank 作为 function 的输入。此时,function 的签名应该是 function(example[, idx], rank)

        rank 是用于分布式环境。

      • input_columns:一个字符串或字符串列表,指定哪些列传递给 function (作为关键字参数)。如果为 None,则一个映射到所有格式化列的字典将被作为一个参数传递给 function

      • batched:一个布尔值,指定是否 batch 执行。如果为 True,那么传递给 function 的是一个 batch 的样本;否则传递给 function 的是单个样本。

      • batch_size:一个整数,指定 batch size 。当 batched = True 时才生效。如果 batched = Truebatch size <= 0batch size = None,则整个数据集作为一个 batch

      • drop_last_batch:一个布尔值,当最后一个 batch 的大小小于 batch_size 时,是否丢弃掉这个小的 batch 。当 batched = True 时才生效。

      • remove_columns:一个字符串或字符串列表,指定哪些列要被移除。这些列将在 function 执行之后、数据集样本更新之前被移除。例如,假设数据集的列为 ['a','b','c']function 根据 'c' 创建了一个新的列 'new_c',如果要移除列 ['b', 'c'],那么最终的数据集包含两列 ['a', 'new_c'](而不是仅有一列 ['a'])。

      • keep_in_memory:一个布尔值,指定是否保存数据集到内存中(而不是写入一个缓存文件)。`

      • load_from_cache_file:一个布尔值,当为 True 时,如果已经有一个缓存文件存储了 function 的计算,那么使用这个缓存文件而不是重新计算。当为 False 时,始终重新计算。

      • cache_file_name:一个字符串,指定缓存文件的路径名。用于 load_from_cache_file

      • writer_batch_size:一个整数,指定 cache file writer 每次写操作时写入多少行。

      • features:一个 Features 对象,指定一个特定的 Features 来存储缓存文件,而不是自动生成一个 Features

      • disable_nullable:一个布尔值,指定是否在数据集中不允许 null 值。

      • fn_kwargs:一个字典,用于为 function 提供关键字参数。

      • num_proc:一个整数,指定用于生成缓存的最大进程数量。

      • suffix_template:一个字符串,如果指定了 cache_file_name,那么 suffix_template 用于指定 cache_file_name 的后缀。默认的模板为 "_{rank:05d}_of_{num_proc:05d}"

        例如,假设 cache_file_nameABC.arrow,而 rank=1, num_proc=4,那么最终的缓存文件名为 ABC_000001_of_000004.arrow

      • new_fingerprint :一个字符串,指定新的指纹。如果为 None,则新的指纹根据一个哈希值来计算,这个哈希值来自于前一个指纹、以及 transform 参数。

      • desc:一个字符串,表示有意义的描述,用于进度条的展示。

      返回一个 Dataset

    • filter():应用一个 filter function 到数据集中所有的样本(以单个样本的形式或 batch 的形式),并更新数据集,使得数据集仅包含 filter function 返回为 True 的样本。

      参数:

      • function:一个可调用对象,它的签名类似于 map() 中的 function,但是这里的 function 必须返回一个布尔值(表示是否保留该样本)。
      • 其它参数参考 map()

      返回一个 Dataset

    • select():创建一个新的数据集,这个新的数据集的row 是根据索引(以列表或 array 来提供)从原始数据集检索得到。

      参数:

      • indices:一个可迭代对象,表示一组索引。

        • 如果 indices 对应于一个连续的区间,那么 Arrow table 仅仅是简单的切片。
        • 如果 indices 对应于多个连续的区间,那么会创建索引映射 indices mapping
        • 否则,会创建一个新的 Arrow table
      • 其它参数参考 map()

      返回一个新的 Dataset(样本粒度的拷贝)。

    • sort():创建一个新的数据集,该数据集根据指定的列来排序。

      目前使用 pandas 排序算法,因此该列必须是 pandas 兼容的类型(尤其不是嵌套类型)。这也意味着用于排序的列能够完全加载到内存中。

      参数:

      • column:一个字符串,指定根据哪一列来排序。
      • reverse:一个布尔值,指定是否降序排列。如果为 True 则降序排列,否则升序排列。
      • kind:一个字符串,指定 pandas 排序算法,可以为 {'quicksort', 'mergesort', 'heapsort', 'stable'} ,默认为 'quicksort' 。注意,'stable''mergesort' 都在幕后使用 timsort ,一般而言,实际的实现会因为数据类型而异。
      • null_placement:一个字符串,指定 None 值应该排在头部 ('first')还是尾部 ('last')。
      • indices_cache_file_name:一个字符串,指定用于排序的索引的缓存文件名(而不是自动生成)。
      • 其它参数参考 map()

      返回一个新的 Dataset(拷贝后的新数据集)。

    • shuffle():创建一个新的数据集,该数据集随机混洗了 row

      目前混洗使用 numpy 随机数生成器。

      参数:

      • seed:一个整数,当 generator = None 时指定随机数种子来初始化默认的 BitGenerator 。如果为 None,那么从操作系统中抽取新的、不可预测的 entropy
      • generator:一个 numpy.random.Generator ,指定随机数生成器。如果为 None,则默认为 BitGenerator(PCG64)
      • 其它参数参考 sort()

      返回一个新的 Dataset(拷贝后的新数据集)。

    • train_test_split():返回一个 datasets.DatasetDict,它具有两个随机拆分的子集(traintestDataset splits)。

      该方法类似于 scikit-learntrain_test_split()

      参数:

      • test_size:一个整数或浮点数,表示测试集大小。如果是整数,则表示测试集的绝对大小;如果是浮点数,则必须是 0.01.0 之间,表示测试集相对于整个数据集的比例。

        如果为 None,则测试集就自动设为训练集的补集;如果 test_size = None, train_size = None,那么默认为 test_size = 0.25, train_size = 0.75

      • train_size:一个整数或浮点数,表示训练集大小。参考 test_size

      • shuffle:一个布尔值,指定是否在拆分之前首先混洗数据集。

      • stratify_by_column:一个字符串,指定 label 列的列名,用于执行分层拆分(使得拆分之后,训练集/验证集中的 label 分布和整体数据集保持一致)。

      • 其它参数参考 shuffle()

      返回一个 datasets.DatasetDict

    • shard():执行数据集分片,并返回第 index 个分片。

      确保在使用任何随机操作(如 shuffle())之前执行分片。最好在 dataset pipeline 的早期使用分片操作。

      参数:

      • num_shards:一个整数,指定将数据集拆分为多少个分片。
      • index:一个整数,指定选择和返回第几个分片。
      • contiguous:一个布尔值,指定是否为分片选择连续的索引 block
      • 其它参数参考 shuffle()

      返回一个 Dataset

      分片算法是确定性的:

      • 如果 contiguous=False,那么dataset.shard(n, i) 将包含满足这种条件的样本:样本索引除以 n 的余数为 i
      • 如果 contiguous=True,那么dataset.shard(n, i) 将连续地分片,并且满足:datasets.concatenate([dataset.shard(n, i, contiguous=True) for i in range(n)]) 仍然等于 dataset 的样本及其原始顺序。
    • to_tf_dataset():根据底层的 Dataset 创建一个 tf.data.Dataset。这个 tf.data.Dataset 将从数据集中加载和 collate batch 数据,并适用于传递给 model.fit()model.predict() 等方法。

      如果数据集同时包含 inputslabels,那么这个数据集的 yield 将产生一个字典,该字典包含 inputslabels 的键;如果没有 labels,那么 yield 仅包含一个原始的 tf.Tensor

      参数:

      • batch_size:一个整数,指定 batch size
      • columns:一个字符串或字符串列表,指定 tf.data.Dataset 中包含当前数据集的哪些列。可以使用 collate_fn 创建的、但是不在 dataset 原始列中的列名。
      • shuffle:一个布尔值,指定是否在加载时混洗数据集。推荐在训练期间设置为 True,在验证和评估期间设置为 False
      • drop_remainder:一个布尔值,指定是否在加载时丢弃最后一个 incomplete batch
      • collate_fn:一个可调用对象,用于将 list of samples 转换为一个 batch
      • collate_fn_args:一个字典,作为关键字参数传递给 collate_fn
      • label_cols:一个字符串或字符串列表,指定哪一列是 label 列。因为有些模型在内部计算损失函数(而不是让 Keras 来计算),因此需要指定 label 列。
      • prefetch:一个布尔值,指定是否在独立的线程中运行 dataloader,并维持一个小 bufferbatch 数据用于训练,即 batch 预取。这可以提高性能。

      返回一个 tf.data.Dataset

    • push_to_hub():将数据集作为一个 Parquet dataset 推送到 hub 上。推送是通过 HTTP 请求进行的,无需 gitgit-lfs

      结果的 Parquet 文件是自包含的。如果你的数据集包含 Image 数据或 Audio 数据,那么 Parquet 文件将存储图片文件或音频文件的 bytes 。你可以通过设置 embed_external_filesFalse 来禁止这个行为。

      参数:

      • repo_id:一个字符串,指定 repository ID(推动的目的地),例如 "<organization>/<dataset_id>"

      • split:一个字符串,指定提供给数据集的 split name,默认为 self.split

      • private:一个布尔值,指定是否设置 dataset repository 为私有的。

      • token:一个字符串,指定用于 Hugging Face Hubauthentication token 。如果未指定,则使用 huggingface-cli 登录时在本地保存的 token 。如果未指定且用户也没有登录,则抛出异常。

      • branch:一个字符串,指定数据集要推送到哪个分支。默认为你的 repository 的默认分支(通常为 "main" 分支)。

      • max_shard_size:一个整数或字符串,指定上传到 hub 的数据集分片的最大大小。如果为字符串,则需要提供单位,如 "5MB"

      • shard_size:一个整数,被废弃,推荐使用 max_shard_size

      • embed_external_files:一个布尔值,指定是否在分片中嵌入 file bytes。具体而言,这将在推送之前为以下类型的字段执行如下操作:

        • Audio/Image:移除本地路径信息,然后再 Parquet 文件中嵌入文件内容。
    • save_to_disk(dataset_path: str, fs=None):保存数据集到目录或 S3FileSystem

      参数:

      • dataset_path:一个字符串,指定本地路径或者一个 remote URI 从而指定数据集存放的位置。
      • fs:一个 S3FileSystem,指定数据集存放的位置。和 dataset_path 二选一。

      注意,对于本地的图片数据和音频数据,arrow file 存储的是这些数据的文件路径。如果你希望存储这些数据的内容,那么你需要首先读取它们,然后在 arrow file 中包含它们的内容。

    • load_from_disk(dataset_path: str, fs=None, keep_in_memory: Optional[bool] = None) -> Dataset :从 save_to_disk() 存储的目录中加载数据集。

      参数:

      • keep_in_memory:一个布尔值,指定是否加载数据集到内存。如果为 None,那么数据集根据 datasets.config.IN_MEMORY_MAX_SIZE 非零时才拷贝到内存。
      • 其它参数参考 save_to_disk()

      返回一个 Dataset

    • flatten_indices():通过展平 indices mapping 来创建并缓存一个新的 Dataset

      参数:参考 map()

      返回值:一个新的 Dataset

    • to_csv():数据集导出为 csv 文件。

      参数:

      • path_or_buf:一个文件路径,或者一个 BinaryIO,指定目标 csv 文件。
      • batch_size:一个整数,指定单次写入的样本数量。默认由 datasets.config.DEFAULT_MAX_BATCH_SIZE 决定。
      • num_proc:一个整数,指定多进程的进程数量。默认不使用多进程。
      • to_csv_kwargs:关键字参数,用于传递给 pandas.DataFrame.to_csv()

      返回一个整数,表示已经写了多少个字符或字节。

    • to_pandas( batch_size: Optional[int] = None, batched: bool = False) -> Union[pd.DataFrame, Iterator[pd.DataFrame]]:将数据集转换为 pandas.DataFrame。对于较大的数据集,也可以返回一个 generator

      参数:

      • batched:一个布尔值,如果为 True 则返回一个 generator (它 yield 批量的样本)。如果为 False 则返回整个数据集。
      • batch_size:参考 to_csv()

      返回一个 pandas.DataFrame 或者一个 generator

    • to_dict(batch_size: Optional[int] = None, batched: bool = False) -> Union[dict, Iterator[dict]]:将数据集转换为 Python 字典。对于较大的数据集,也可以返回一个 generator

      参数:参考 to_pandas

      返回值一个字典或者一个 generator

    • to_json():将数据集导出为 JSON 文件。

      参数:

      • lines:一个布尔值,指定是否输出 JSON lines 格式。
      • to_json_kwargs:关键字参数,传递给 pandas.DataFrame.to_json()
      • 其它参数参考 to_csv()

      返回一个整数,表示已经写了多少个字符或字节。

    • to_parquet():将数据集导出为 parquet 文件。

      参数:

      • parquet_writer_kwargs:关键字参数,传递给 pyarrow.parquet.ParquetWriter
      • 其它参数参考 to_csv()

      返回一个整数,表示已经写了多少个字符或字节。

    • to_sql():导出数据集到 SQL 数据库。

      参数:

      • name/con:参考 from_sql
      • batch_size:参考 to_csv()
      • sql_writer_kwargs:关键字参数,传递给 Dataframe.to_sql()

      返回一个整数,表示已经写入了多少行记录。

    • add_faiss_index():添加一个 dense index (使用 Faiss)来用于快速检索。默认情况下,索引是在指定的列上的向量上完成的。如果要在 GPU 上运行,也可以指定设备。

      参数:

      • column:一个字符串,指定在哪一列的向量上添加这个 dense index
      • index_name :一个字符串,指定新加的 dense index 的名字。这个名词常被用于 get_nearest_examples()search()
      • device:一个整数或者整数列表。如果是正整数,则指定 GPU 的编号;如果是负整数,则表示所有的 GPU 。如果是正整数列表,则表示在指定的一组 GPU 上运行。默认使用 CPU
      • string_factory:一个字符串,它被传递给 Faissindex factory 来创建 dense index
      • metric_type:一个整数,指定指标的类型。例如,faiss.METRIC_INNER_PRODUCTfaiss.METRIC_L2
      • custom_index:一个 faiss.Index,指定自定义的 Faiss index
      • batch_size:一个整数,指定单词添加多少个 vectorFaissIndex
      • train_size:一个整数,如果 index 需要训练,那么指定多少个 vector 来训练。
      • faiss_verbose:一个布尔值,开启 faiss 的日志输出。
      • dtype:一个数据类型,指定 dense indexnumpy array 类型。默认为 np.float32

      示例(FAISS 语义检索):

    • add_faiss_index_from_external_arrays():添加一个 dense index (使用 Faiss)来用于快速检索。索引是在 external_arrays 的向量上创建的。如果要在 GPU 上运行,也可以指定设备。

      参数:

      • external_arrays:一个 np.array 对象,指定在哪一列(外部的列)的向量上添加这个 dense index
      • 其它参数参考 add_faiss_index()
    • save_faiss_index(index_name: str, file: typing.Union[str, pathlib.PurePath]):保存 FaissIndex 到磁盘。

      参数:

      • index_name:一个字符串,指定 faiss index 的列名。
      • file:一个字符串,指定序列化之后的 faiss index 所保存的文件的文件名。
    • load_faiss_index():从硬盘加载 FaissIndex

      参数:

      • deviceadd_faiss_index()
      • 其它参数参考 save_faiss_index()
    • add_elasticsearch_index():添加一个 text index (使用 ElasticSearch)来用于快速检索。这是原地操作。

      参数:

      • column/index_name :参考 add_faiss_index()

      • host:一个字符串,指定 ElasticSearch 运行的主机,默认为 'localhost'

      • port:一个字符串,指定 ElasticSearch 运行的端口号,默认为 '9200'

      • es_client:一个 Elasticsearch 对象,如果 hostport 都是 None,那么使用这个 elasticsearch client 来创建 text index

      • es_index_name:一个字符串,指定被用于创建 text indexelasticsearch index name

      • es_index_config:一个字典,指定 elasticsearch index 的配置。默认的配置为:

    • load_elasticsearch_index():加载已有的 text index (使用 ElasticSearch)用于快速检索。

      参数:参考 add_elasticsearch_index()

    • list_indexes():列出所有 attached indexes 的列名。

    • get_index(index_name: str ) -> BaseIndex:返回指定列上 attached indexes 的列名。

      参数:index_name:一个字符串,指定列名。

    • drop_index(index_name: str):移除指定列上的 index

      参数:参考 get_index()

    • search():在数据集中寻找与给定 query 最近邻的样本,返回临近度得分。

      参数:

      • index_name:一个字符串,指定索引的名字。
      • query:一个字符串或一个 np.ndarray,指定 query。如果 index_name 对应于 text index,那么 query 是一个字符串;如果 index_name 是一个 vector index,那么 query 是一个 np.ndarray
      • k:一个整数,指定寻找最近邻的多少个。

      返回一组最近邻的样本的近邻分。

    • search_batch():在数据集中寻找与给定的一组 query 最近邻的样本,返回针对每个 query 的临近度得分。

      参数:参考 search()

      返回多组最邻近的样本的近邻分,每一组对应一个 query

    • get_nearest_examples(index_name: str, query: Union[str, np.array], k: int = 10) -> scores (List[float])类似于 search()

      参数:参考 search()

      返回一组最近邻的样本的近邻分。

    • get_nearest_examples_batch(index_name: str, queries: typing.Union[typing.List[str], <built-in function array>], k: int = 10) -> total_scores (List[List[float]):参考 search_batch()

      参数:参考 search_batch()

      返回多组最邻近的样本的近邻分,每一组对应一个 query

    • prepare_for_task(task: Union[str, TaskTemplate], id: int = 0) -> Dataset :通过将数据集的 Features 强制类型转换为标准化的列名和列类型(由 dataset.tasks 中描述),从而为给定的 task 来准备数据集。

      仅供一次性使用,因此在强制类型转换之后,所有的 task template 都将从 datasets.DatasetInfo.task_templates 中移除。

      参数:

      • task:一个字符串或者 TaskTemplate,指定为哪个任务准备数据集。

        • 如果是字符串,那么必须为: "text-classification""question-answering"

        • 如果是 TaskTemplate,那么必须是 dataset.tasks 中定义的 task templates 之一。

          目前支持(位于 dataset.tasks 内):

      • id:一个整数,当支持多个相同类型的 task template 时,显式标识 task template 所需的 id

      返回一个 Dataset

    • align_labels_with_mapping(label2id: Dict, label_column: str) -> Dataset:根据输入的 label2id 来对齐数据集的 label IDlabel name 。注意,对齐的过程中,对 label name 使用小写。

      参数:

      • label2id:一个字典,指定 label namelabel ID 的映射。
      • label_column:一个字符串,指定数据集的哪一列为 label 列。

      返回值一个 Dataset

  2. datasets 的函数:

    • datasets.concatenate_datasets():拼接多个 Dataset 到单个 Dataset

      参数:

      • dsets:一个 Dataset 的列表,指定多个数据集。
      • info:一个 DatasetInfo ,指定新的 Dataset 的信息,如描述信息等等。
      • axis:一个整数,可以为 01,表示沿着行拼接(0,从上到下拼接)或者列拼接(1,从左到右拼接)。
    • datasets.interleave_datasets():将几个数据集交错而成一个新的数据集。新的数据集是通过在 source dataset 之间进行交错迭代从而获得样本。

      参数:

      • datases:一个 DatasetIterableDataset 的列表,指定对哪些数据集进行交错。

      • probabilities:一个浮点数列表。

        • 如果为 None,则表示在每个源数据集之间轮流迭代(即第一个样本来自于第一个源数据集,第二个样本来自于第二个源数据集,...)。
        • 如果不是 None,则每次根据给定的概率随机选择一个源数据集来进行迭代。
      • seed:一个整数,指定随机数种子,用于配合 probabilities 来随机选择一个源数据集。

      • info:一个 DatasetInfo 对象,指定新数据集的信息。

      • split:一个 NamedSplit 对象,指定 dataset split 的名字。

      • stopping_strategy:一个字符串,目前支持两种策略:

        • "first_exhausted ":一旦某个数据集耗尽样本,则停止构建数据集。
        • "all_exhausted":每个数据集至少被完全迭代过一次,当且仅当所有数据集都被迭代过一次,则停止构建数据集。注意,此时新数据集的规模可能非常大。如果 probabilities = None,那么新数据集的规模为 max_length_datasets*num_dataset ;如果 probabilities != None,并且如果某个数据集的访问概率非常低,那么新数据集可能包含非常非常多的样本。

      返回一个 Dataset (当 datasesDataset 列表时)或 IterableDataset (当 datasesIterableDataset 列表时)。

    • datasets.enable_caching():启用缓存。

      当对数据集应用 transform 时,数据被存储在缓存文件中。缓存机制允许重新加载已经计算过的、现有的缓存文件。重新加载数据集是可能的,因为缓存文件是使用数据集指纹 dataset fingerprint 命名的,指纹在每次 transform 后都会更新。

      如果禁用缓存,那么当对数据集应用 transform 时,Datasets library 将不再重新加载缓存的数据文件。具体而言,如果禁用缓存:

      • 缓存文件总是被重新创建。
      • 缓存文件被写入临时目录,当会话关闭时,该目录将被删除。
      • 使用随机哈希而不是数据集指纹来命名缓存文件。
      • 使用 datasets.Dataset.save_to_disk() 来保存一个 transformerd dataset 或者在会话关闭时删除 transformerd dataset
      • 缓存不会影响 datasets.load_dataset() 。如果要从头重新生成数据集,应该使用 datasets.load_dataset() 中的 download_mode 参数。
    • datasets.disable_caching():禁用缓存。

    • datasets.is_caching_enabled() -> bool: 返回缓存是否被启用。

  3. class DatasetDict:继承自 Python dict,包含 Dataset 的字典,其中键为 split name (如 'train', 'test' 等等)。它也包含一些 dataset transform 方法,如 map/filter,作用到每个 split 上。

    属性:

    • data -> Dict[str, Table]:一个字典,返回每个 splitApache Arrow table
    • cache_files -> Dict[str, Dict]:一个字典,返回每个 split 的缓存文件。
    • num_columns -> Dict[str, int]:一个字典,返回每个 split 的列数。
    • num_rows -> Dict[str, int]:一个字典,返回每个 split 的行数。
    • column_names -> Dict[str, List[str]]:一个字典,返回每个 split 的列名。
    • shape -> Dict[str, Tuple[int]] :一个字典,返回每个 split 的形状(列数,行数)。

    方法:参考 Dataset 的对应方法,其中 DatasetDict 的方法会应用到字典中的每个 Dataset 上,并且返回 DatasetDict 而不是Dataset

  4. class datasets.IterableDataset:基于 python generator 实现的迭代式数据集。

    参数:文档未给出,同时源码也未给出。

    属性:参考 Dataset

    方法:

    • skip(n) -> IterableDataset :创建一个新的 IterableDataset ,它跳过了旧 IterableDataset 的前 n 的元素。

      参数:n :一个整数,指定跳过多少个元素。

      返回一个新的 IterableDataset

    • take(n) -> IterableDataset :创建一个新的 IterableDataset ,它仅包含旧 IterableDataset 的前 n 的元素。

      参数:n :一个整数,指定包含多少个元素。

      返回一个新的 IterableDataset

    • 下列方法参考 Dataset,其中 IterableDataset 的方法返回 IterableDataset 而不是Dataset

  5. class datasets.IterableDatasetDict:继承自 Python dict,包含 IterableDataset 的字典,其中键为 split name (如 'train', 'test' 等等)。它也包含一些 dataset transform 方法,如 map/filter,作用到每个 split 上。

    方法:参考 DatasetDict 的对应方法,其中 IterableDatasetDict 的方法返回 IterableDatasetDict 而不是DatasetDict

3.3 Features

  1. class datasets.Features(*args, **kwargs):一个特殊的字典,定义了数据集的内部结构。

    Features 通过 dict[str, FieldType] 类型的字典来实例化,其中键是列名、值为该列的类型。FieldType 可以为:

    • datasets.Value:该特征指定了 single typed value,如 int64string
    • datasets.ClassLabel:该特征指定了一个字段,该字段包含一组预定义的类别,这些类别关联了一些整数标签(数据集中以整数标签来存储)。
    • 一个 python 字典:该特征指定了一个嵌套的字段,其中将 sub-field 名称映射到 sub-field 类型。
    • 一个 python 列表或 datasets.Sequence:该特征指定了一个字段,该字段包含对象的一个列表。 python 列表或 datasets.Sequence 的每个元素都是 single sub-feature
    • 一个 Array2D/Array3D/Array4D/Array5D:该特征是多维数组。
    • 一个 Audio:该特征存储音频文件的绝对路径,或者存储音频文件的相对路径( "path" 键)映射到音频内容("bytes" 键)的字典。
    • 一个 Image:该特征存储图片文件的绝对路径、或者 np.ndarray 对象、或者 PIL.Image.Image 对象,或者存储图片文件的相对路径( "path" 键)映射到图片内容("bytes" 键)的字典。
    • Translation/TranslationVariableLanguages:仅用于机器翻译。

    方法:

    • copy() -> Features:创建当前 Featuresdeep copy

    • decode_batch(batch: dict[str, list[Any]]) -> dict[str, list[Any]]:对一个 batch 的数据根据当前的特征格式来解码。

      参数:batch:一个字典,表示一个 batch 的数据。

      返回解码后的数据。

    • decode_column(column: list[Any], column_name: str) -> list[Any]:对一列数据根据当前的特征格式来解码。

      参数:

      • column:一个列表,包含一列数据。
      • column_name:一个字符串,表示列名。

      返回解码后的数据。

    • decode_example(example: dict[str, Any], token_per_repo_id: Optional[Dict[str, Union[str, bool, None]]] = None) -> dict[str, Any]:根据当前的特征格式来解码一个样本。

      参数:

      • example:一个字典,表示数据集的一行(代表一个样本)。
      • token_per_repo_id:一个字典,为了从 Hub 上的私有 repository 中访问和解码音频文件、图像文件,可以传递一个字典 repo_id (str) -> token (bool or str)

      返回解码后的样本。

    • encode_batch(batch: dict[str, list[Any]]) -> dict[str, list[Any]]:编码 batch 样本到 Arrow 的格式。

      参数:batch:一个 batch 的样本。

      返回编码后的 batch 的样本。

    • encode_example(example: dict[str, Any]) -> dict[str, Any]:编码单个样本到 Arrow 的格式。

      参数:example:单个样本。

      返回编码后的样本。

    • flatten(max_depth=16) -> Features:特征展平,返回展平后的特征。

      每个 dictionary column 被移除,并代之以它包含的所有 subfields。新的字段名字由原始的里恶名和 subfield name 拼接而成,如 <original>.<subfield> 。如果有多层嵌套,那么为 <original>.<subfield>.<subsubfield>

      参数:max_depth:一个整数,指定最多展平多少层。

    • from_arrow_schema( pa_schema: pyarrow.Schema) -> Features :从 Arrow Schema 构建 Features

    • from_dict(dic: dict[str, Any]) -> Features:从字典中构建 Features 。我们使用 "_type" 键来推断 feature FieldTypedataclass name

    • reorder_fields_as(other: Features) -> Features :重新排列当前 Features 的字段,从而匹配 other Features 的字段顺序。

      字段的顺序很重要,因为它关系到底层的 arrow data

    示例:

  2. class datasets.Sequence( feature: typing.Any, length: int = -1, id: typing.Optional[str] = None) :根据单个类型、或者类型的字典来构建 feature 的一个列表。

    参数:

    • feature:单个类型、或者类型的字典的一个列表。
    • length:一个整数,指定 sequence 的长度。

    示例:

  3. class datasets.ClassLabel:用于整数类别标签的 feature type

    参数:

    • num_classes:一个整数,指定类别的数量。所有的标签取值必须小于 num_classes
    • names:一个字符串列表,指定整数类别的类别名字,这些字符串的顺序很重要,对应于对应的整数标签。
    • names_file:一个字符串,存储类别名字,每行一个。

    底层的 label 存储为整数。你可以使用负的整数代表 unknown/missinglabel

    方法:

    • cast_storage( storage: typing.Union[pyarrow.lib.StringArray, pyarrow.lib.IntegerArray]) -> pa.Int64Array:将一个 Arrow array 强制类型转换为 ClassLabel arrow storage 类型。只有 pa.string()pa.int() 这两种类型能够执行这种强制类型转换。

      参数:

      • storage:一个 pa.StringArraypa.IntegerArray 类型,表示要被强制类型转换的 PyArrow array

      返回值一个 pa.Int64Array

    • int2str( values: typing.Union[int, collections.abc.Iterable] ):将整数转换为 class name 字符串。如果有负的整数,则抛出异常。

      参数:values:一个整数或整数的可迭代对象,表示待转换的整数。

      返回值一个字符串或字符串的可迭代对象,表示 class name

    • str2int(values: typing.Union[str, collections.abc.Iterable]) :将 class name 字符串转换为整数。

      参数:values:一个字符串或字符串的可迭代对象,表示待转化的 class name

      返回一个整数或整数的可迭代对象,表示 class label

    示例:

  4. class dataset.Value(dtype: str, id: typing.Optional[str] = None ) :值类型。可以为如下类型:

    参数:dtype:一个字符串,表示具体的类型。如 Value(dtype='int32')

    示例:

  5. class datasets.Translation(languages: typing.List[str], id: typing.Optional[str] = None ):用于翻译的 FeatureConnector ,其中翻译的每个样本包含固定的语言实例。

    参数:languages:一个字符串列表,表示样本包含的语言。

    方法:

    • flatten() :将 Translation feature 展平到一个字典中。

    Translation 特征的输入输出:

    • 输入:每个样本对应一个字典,该字典将 language code 字符串映射到 translation 字符串。
    • 输出:一个字典,该字典将 language code 字符串映射到以 Text 特征的 translation

    示例:

  6. class datasets.TranslationVariableLanguages:用于翻译的 FeatureConnector ,其中翻译的每个样本包含可变的语言实例。

    参数:

    • languages:一个字符串列表,表示样本包含的语言。
    • num_languages:一个整数,表示最大的实例数量。

    方法:

    • flatten() :将 TranslationVariableLanguages feature 展平到一个字典中。

    TranslationVariableLanguages 特征的输入输出:

    • 输入:每个样本对应一个字典,该字典将 language code 字符串映射到一个或多个 translation 字符串。
    • 输出:一个字典,"language" 键对应了一个可变长度的一维张量(升序排列),代表 language code"translation" 键对应了一个可变长度的一维张量(与 language 张量对齐且升序排列),代表翻译文本。

    示例:

  7. class datasets.Array2D/Array3D/Array4D/Array5D:代表 2D/3D/4D/5D 的数组。

    参数:

    • shape:一个元组,代表数组每个维度的大小。
    • dtype:一个字符串,代表数组元素的类型。

    示例:

  8. class datasets.Audio:音频特征,用于从音频文件中抽取音频数据。

    参数:

    • sampling_rate:一个整数,指定采样率。如果为 None,则使用负的采样率。
    • mono:一个布尔值,指定是否通过跨通道的平均采样从而将音频信号转换为单声道。
    • decode:一个布尔值,指定是否解码音频数据。如果为 False,则以格式 {"path": audio_path, "bytes": audio_bytes} 的格式返回底层的字典。

    方法:

    • cast_storage(storage: typing.Union[pyarrow.lib.StringArray, pyarrow.lib.StructArray] ) -> pa.StructArray:将一个 Arrow array 强制类型转换为 Audio arrow storage 类型。可以强制类型转换的 Arrow array 类型包括:pa.string() (它必须包含 "path" 数据)、pa.struct({"bytes": pa.binary()})pa.struct({"path": pa.string()})pa.struct({"bytes": pa.binary(), "path": pa.string()}) (顺序不重要)。

    • decode_example( value: dict, token_per_repo_id: typing.Union[typing.Dict[str, typing.Union[str, bool, NoneType]], NoneType] = None) :解码音频文件到音频数据。

      参数:

      • value:一个字典,包含两个 key"path" ,指定音频文件的相对路径;"bytes":音频文件的字节。
      • token_per_repo_id:个字典,为了从 Hub 上的私有 repository 中访问和解码音频文件、图像文件,可以传递一个字典 repo_id (str) -> token (bool or str)
    • encode_example( value: typing.Union[str, dict] ) -> dict: 编码样本到一个字典,用于 Arrow 格式。

      参数:

      • value:一个字符串或字典,作为 Audio 特征的 input
    • embed_storage(storage: StructArray, drop_paths: bool = True ) -> pa.StructArray :将音频文件嵌入到 Arrow array

      参数:

      • storage:一个 pa.StructArray,指定被嵌入的 PyArrow
      • drop_paths:一个布尔值,指定是否将 path 设为 None

      返回一个 Audio arrow storage 类型的 Array,格式为 pa.struct({"bytes" : pa.binary(), "path" : pa.string()})

    • flatten():展平当前特征到一个字典。

    Audio 特征的输入和输出:

    • 输入:可以为:

      • 一个字符串:表示音频文件的绝对路径。
      • 一个字典,包含: "path" 键,给出音频文件相对于 archive 文件的相对路径;"bytes" 键,给出音频文件的字节内容。
      • 一个字典,包含:"path" 键,给出音频文件相对于 archive 文件的相对路径;"array" 键,给出包含音频样本的数组;"sampling_rate" 键,给出一个整数,对应于音频样本的采样率。

    示例:

  9. class datasets.Image(decode: bool = True, id: typing.Optional[str] = None ):图片特征。

    参数:

    • decode:一个布尔值,指定是否解码图片数据。如果为 False,则以格式 {"path": image_path, "bytes": image_bytes} 的格式返回底层的字典。

    方法:

    • cast_storage( storage: typing.Union[pyarrow.lib.StringArray, pyarrow.lib.StructArray, pyarrow.lib.ListArray]) -> pa.StructArray:将一个 Arrow array 强制类型转换到 Image arrow storage 类型。可以强制类型转换的 Arrow array 类型包括:pa.string() (它必须包含 "path" 数据)、pa.struct({"bytes": pa.binary()})pa.struct({"path": pa.string()})pa.struct({"bytes": pa.binary(), "path": pa.string()}) (顺序不重要)、pa.list(*) (必须包含 image array data)。

      参数:参考 datasets.Audio.cast_storage()

    • decode_example(value: dict, token_per_repo_id = None ) :参考 datasets.Audio.decode_example()

    • embed_storage(storage: StructArray, drop_paths: bool = True) -> pa.StructArray:参考 datasets.Audio.embed_storage()

    • encode_example( value: typing.Union[str, dict, numpy.ndarray, ForwardRef('PIL.Image.Image')]) :参考 datasets.Audio.encode_example()

    • flattern():参考 datasets.Audio.flattern()

    Image 特征的输入和输出:

    • 输入:可以为:

      • 一个字符串:表示图片文件的绝对路径。
      • 一个字典,包含: "path" 键,给出图片文件相对于 archive 文件的相对路径;"bytes" 键,给出图片文件的字节内容。
      • 一个 np.ndarray:代表一张图片的 numpy array
      • 一个 PIL.Image:一个 PIL image 对象。

    示例:

3.4 DatasetBuilder

  1. class datasets.DatasetBuilder:所有数据集的抽象基类。

    参数:

    • cache_dir:一个字符串,指定缓存数据的位置,默认为 "~/.cache/huggingface/datasets"
    • config_name:一个字符串,指定数据集配置的名字。不同的配置拥有不同的子目录和版本。如果未提供,则使用默认的配置(如果有的话)。
    • hash:一个字符串,指定数据集代码的哈希,用于更新缓存目录。
    • base_path:一个字符串,指定一个那个目录作为下载文件的 base 目录。
    • features:一个 Features 对象,制定数据集的 Features
    • use_auth_token :一个字符串或者布尔值,用于访问 Datasets Hub。如果为 True,则从 ~/.huggingface" 获取 token;如果为字符串,则直接指定 token
    • repo_id:一个字符串,指定 dataset repositoryID
    • data_files:一个字符串或者序列或者映射,指定源数据文件的路径。
    • data_dir:一个字符串,指定包含源数据文件的目录的路径。如果 data_files 未提供,那么使用 os.path.join(data_dir, '**')
    • name:一个字符串,指定数据集的配置名(被废弃,推荐用 config_name )。
    • config_kwargs:关键字参数,传递给对应的 builder 配置类。

    DatasetBuilder 有三个主要的方法:

    • info() :对数据集进行说明,包括特征名字、特征类型、数据形状、版本、split 等等。

    • download_and_prepare():下载源数据并写入磁盘。

      参数:

      • output_dir :一个字符串,指定数据集的输出目录。默认为 "~/.cache/huggingface/datasets"
      • download_config:一个 DownloadConfig对象,指定下载配置。
      • download_mode:一个 DownloadMode 对象,指定下载/生成的模式。默认为 REUSE_DATASET_IF_EXISTS
      • ignore_verifications:一个布尔值,指定是否忽略对下载的数据进行校验。
      • try_from_hf_gcs:一个布尔值,指定是否从 Hf google cloud storage 下载 prepared dataset
      • dl_manager:一个 DownloadManager 对象,指定使用哪个下载管理器。
      • base_path:一个字符串,指定用哪个目录作为下载文件的 base 目录。
      • use_auth_token:一个字符串,参考 DatasetBuilder 构造方法。
      • file_format:一个字符串,指定数据文件的格式。支持 "arrow""parquet" 。如果是 "parquet" ,那么图片数据和音频数据将被嵌入到 Parquet 文件中,而不是指向本地文件的路径。
      • max_shard_size:一个字符串或整数,指定每个分片所写入的最大字节数。仅支持对 "parquet" 格式使用默认的 "500MB" 的大小。这个 size 是基于未压缩的数据大小,因此对于 Parquet compression,分片文件可能要小于 max_shard_size
      • num_proc:一个整数,指定用于下载和生成本地数据集的进程数。默认不使用多进程。
      • storage_options:一个字典,key-value pair ,被传入缓存文件系统。
      • download_and_prepare_kwargs:额外的关键字参数。
    • as_dataset(split: typing.Optional[datasets.splits.Split] = None, run_post_process = True, ignore_verifications = False, in_memory = False ):生成一个数据集。

      参数:

      • split:一个 Split,指定返回数据的哪个子集。
      • run_post_process:一个布尔值,指定是否对数据集运行后处理。
      • ignore_verifications:一个布尔值,指定是否忽略对下载后/处理后的数据集的信息进行校验。
      • in_memory:一个布尔值,指定是否将数据拷贝到内存中。
  2. class datasets.BuilderConfigBuilder 配置的基类。

  3. class datasets.DownloadManager:下载管理器。

  4. class datasets.StreamingDownloadManager:流式下载管理器。

  5. class datasets.DownloadConfig:下载配置

  6. class class datasets.DownloadMode:下载模式的枚举类。包括:

  7. class datasets.Split:数据集拆分的枚举类。包括:

3.5 加载数据集

  1. 数据集加载:

    • datasets.list_datasets(with_community_datasets = True, with_details = False ):列出 Hugging Face Hub 上所有的可用数据集。

      参数:

      • with_community_datasets:一个布尔值,指定是否包含社区提供的数据集。
      • with_details:一个布尔值,指定是否返回完整的细节而不是简称。
    • datasets.load_dataset():从 Hugging Face Hub 或本地加载数据集。

      注意,也可能下载的是 dataset script,然后该脚本从任意其他地方下载数据集。

      参数:

      • path:一个字符串,指定数据集的路径或名字。

        对于本地数据集:

        • 如果 path 是一个本地目录(仅包含数据文件),那么 Datasets 基于目录的内容加载一个通用的 dataset builder (如,csv, json, text)。
        • 如果 path 是一个本地的 dataset script 或包含一个本地的 dataset script ,那么从这个 dataset script 加载 dataset builder

        对于 Hugging Face Hub 数据集:

        • 如果 path 是一个 dataset repository(仅包含数据文件),那么 Datasets 基于 repository 的内容加载一个通用的 dataset builder (如,csv, json, text)。
        • 如果 path 是一个带有 dataset scriptdataset repository,那么从这个 dataset script 加载 dataset builder
      • name:一个字符串,指定数据集配置的名字。

      • data_dir:一个字符串,指定数据集配置的 data_dir

      • data_files:一个字符串或字符串序列或字符串映射,指定源数据文件的路径。

      • split:一个字符串或 Split,指定加载数据集的哪个部分。如果为 None,则返回一个字典,该字典包含所有的 split

      • cache_dir:一个字符串,指定读写数据的缓存位置,默认为 "~/.cache/huggingface/datasets"

      • features:一个 Features,指定数据集的特征类型。

      • download_config:一个 DownloadConfig,指定下载配置。

      • download_mode:一个 DownloadMode,指定下载模式。

      • ignore_verifications:一个布尔值,指定是否验证下载/处理的数据集。

      • keep_in_memory:一个布尔值,指定是否拷贝数据集到内存中。

      • save_infos:一个布尔值,指定是否保存数据集信息(如 checksums/size/splits/... )。

      • revision:一个字符串或 Version,指定加载 dataser script 的哪个版本。默认为 "main" 分支。

      • use_auth_token:一个字符串或布尔值,参考 DatasetBuilder 构造方法。

      • task:一个字符串,指定该数据集需要为哪个任务进行 prepare 从而训练和评估。将会对数据集的 Features 强制类型转换,从而匹配该任务的标准列名和列类型。

      • streaming:一个布尔值。如果为 True,则不会下载数据文件,而是流式地迭代该数据集。仅 txt, csv, jsonl 文件支持流式下载,而 Json 文件需要完整地下载。

      • num_proc:一个整数,指定下载和生成数据集的进程数。默认不使用多进程。

      • config_kwargs:关键字参数,被传递给 BuilderConfigDatasetBuilder

      如果 streaming = False,返回一个 DatasetDatasetDict

      • 如果 split 不是 None,则返回 Dataset
      • 如果 split = None,则返回 DatasetDict,它包含每个 split

      或者,如果 streaming = True,则返回一个 IterableDatasetIterableDatasetDict

    • datasets.load_from_disk(dataset_path: str, fs=None, keep_in_memory: Optional[bool] = None) -> Union[Dataset, DatasetDict]:从磁盘上加载数据集,该数据集之前通过 Dataset.save_to_disk() 写入到磁盘的。

      参数:

      • dataset_path:一个字符串,指定数据集的本地路径或远程 URI
      • fs:一个 S3FileSystemfsspec.spec.AbstractFileSystem,指定远程文件系统用于下载文件。
      • keep_in_memory:一个布尔值,指定是否拷贝数据集到内存。

      返回一个 DatasetDatasetDict ,这取决于 dataset_path 是否包含单个 split 还是多个 split

    • datasets.load_dataset_builder():从 Hugging Face Hub 或本地数据集中加载一个 dataset builder

      一个 dataset builder 可以用于探查数据集的通用信息而无需下载该数据集。

      参数:参考 load_dataset()

      返回一个 DatasetBuilder

    • datasets.get_dataset_config_names():对于给定的数据集,返回可用的配置名字的列表。

      参数:参考 load_dataset()

    • datasets.get_dataset_infos():获取数据集的源信息,返回一个字典,键位配置名字、值为 DatasetInfoDict

      参数:参考 load_dataset()

    • datasets.get_dataset_split_names():对于给定的数据和配置,返回可用 split 的列表。

      参数:

      • config_name:一个字符串,指定数据集配置的名字。
      • 其它参数参考 load_dataset()
    • datasets.inspect_dataset():将 dataset script 拷贝到本地磁盘从而允许探查和修改它。

      参数:

      • local_path:一个字符串,指定 dataset script 要拷贝到哪里。
      • 其它参数参考 load_dataset()
  2. 你可以传入一些参数到 load_dataset 从而配置数据加载。例如,对于 csv 文件的加载,你可以指定 sep 参数:

    针对不同文件格式的配置类,可以在 load_dataset 中指定相应的参数:

    • class datasets.packaged_modules.text.TextConfig:针对文本文件的 BuilderConfig

    • class datasets.packaged_modules.csv.CsvConfig:针对csv 文件的 BuilderConfig

    • class datasets.packaged_modules.json.JsonConfig:针对json 文件的 BuilderConfig

    • class datasets.packaged_modules.parquet.ParquetConfig:针对parquet 文件的 BuilderConfig

    • class datasets.packaged_modules.sql.SqlConfig:针对 sqlBuilderConfig

    • class datasets.packaged_modules.imagefolder.ImageFolderConfig:针对 ImageFolderBuilderConfig

    • class datasets.packaged_modules.audiofolder.AudioFolderConfig:针对 AudioFolderBuilderConfig

  3. 修改 Datasets 的日志等级:

  4. class datasets.table.Table(table: Table):对 pyarrow Table 的一个封装,是 InMemoryTable, MemoryMappedTable, ConcatenationTable 的基类。

    Table 类实现了 pyarrow Table 的所有基础属性和方法,除了如下的 Table transform

  5. datasets.table.list_table_cache_files( table: Table) -> List[str]:返回指定的 table 所加载的缓存文件的路径。

    参数:table:一个 Table 对象,表示指定的 Table