Loading Methods

Datasets

datasets.list_datasets

return：List all the datasets scripts available on the Hugging Face Hub.

from datasets import list_datasets
# 展示HFhub上地数据集： https://huggingface.co/datasets
# with_community_datasets: 是否列出所有的（hugging face）社区提供的所有数据集，默认为True
# with_details：是否打印数据的详细信息，默认为False
data_names = list_datasets( with_community_datasets = True, with_details = False )
print(data_names)

datasets.load_dataset

path：数据集的名称（HF hub 上）或者路径（可以是本地路径）。支持的脚本文件包括 JSON, CSV, Parquet, text 等，也支持python脚本

• 在加载 HF hub 上的数据时，path是数据集的名称
• 在加载本地数据时，path 可以用作指明要加载的数据文件格式的类型（包括：text、csv、json、parquet、images等）。
• 在加载本地数据时，当path不用于指定文件格式类型时，可作为资源文件路径的一部份，并可配合参数data_dir和data_files使用，具体路径为：path/data_dir/data_files

name：定义数据集配置的名称。该名称主要用于指定子数据集的名称。例如机器翻译数据集opus_books中包含了多种语言之间的语料，故而在加载该数据集时，需要利用name参数指定是哪两种语言对应的语料，例如指定 name = 'en-fr'，即选择加载英法对应的语料。

data_dir： 指定数据集配置的数据路径。就是指源数据的加载路径（通常是存放数据文件（csv, text 等）的文件夹名）。指定该参数后，程序会加载os.path.join(path, data_dir)目录下的所有文件，但只会在目录中选择某一种命名格式的数据文件进行加载。若要希望加载目录中所有文件，则需要让目录中的文件命名格式保持一致。

data_files： 指定具体要加载的文件名（支持的格式包括 'csv', 'tsv', 'json', 'jsonl', 'jpg', 'txt' 等等）。传入的参数类型包括str、Sequence、Mapping。具体加载的路径是 path/data_dir/data_files

split：返回数据集的指定分割（'train'或'test' ）。允许传入的参数类型为：str 和 datasets.Split

cache_dir：读取和写入数据的文件夹。默认路径为~/.cache/huggingface/datasets

features： 为当前数据集设置特征（数据字段）。传入参数的类型为Features。

download_config： 指定下载的配置参数。

download_mode： 下载模式。默认是重用已存在的数据进行下载（REUSE_DATASET_IF_EXISTS）。

ignore_verifications： 是否忽略下载/处理的数据集信息的验证（默认False）。这些信息包括checksums/size/splits/…

keep_in_memory： 是否将数据集赋值到内存中，如果是None，则不会将数据加载到内存中，除非显式地设置datasets.config.IN_MEMORY_MAX_SIZE不等于零。

save_infos：保存数据集信息（checksums/size/splits/...）。

revision: 要加载的数据集脚本的版本。

use_auth_token： 可选字符串或布尔值，用作数据集集线器上远程文件的承载令牌。

task： 为训练和验证准备数据集地任务。将数据集地Features转换成对应任务地标准列名和类型

streaming： 如果设置为True将不会加载（下载）数据文件。而是在数据集上迭代时逐步流化数据。在这种情况下会使load_dataset()返回一个IterableDataset 或者IterableDatasetDict 迭代器。

**config_kwargs：额外的关键字参数。传递给BuilderConfig并在DatasetBuilder中使用的关键字参数。

此函数后台执行原理：

• 如果数据脚本库中没有对应地数据脚本，则从path下载并导入数据脚本到数据脚本库
  • 如果没有数据脚本，则可以导入通用数据脚本（JSON, CSV, Parquet, text, etc）
  • 数据集脚本是定义数据集构建器的小型 Python 脚本。它们定义了数据集的引用、信息和格式，包含原始数据文件的路径或 URL 以及从原始数据文件加载示例的代码。你可以从https://github.com/huggingface/datasets/tree/main/datasets 找到一些脚本。
• 运行数据集脚本
  • 如果数据集文件在本地或缓存中不可用，则从原始 URL（可参看数据集脚本）下载数据集文件。
  • 在用于缓存的类型化 Arrow table 中处理和缓存数据。
  • Arrow table 是任意长度、类型的表。它们可以存储嵌套对象，也可以被映射到 numpy/pandas/python 等通用类型。它们可以从硬盘上直接被获取，也可以被加载到内存中，甚至是以数据流的形式在网页上被传输。
• 根据指定分割（默认：all）返回数据集

说明：它还允许从本地目录或 Hugging Face Hub 上的数据集存储库加载数据集，而无需数据集脚本。在这种情况下，它会自动从目录或数据集存储库中加载所有数据文件。当您想要访问私有数据集时，需要指定use_auth_token=True

实例展示：

• 从HF hub上加载数据集

  from datasets import load_dataset
  ds = load_dataset('rotten_tomatoes', split='train')
  
  # Map data files to splits
  data_files = {'train': 'train.csv', 'test': 'test.csv'}
  ds = load_dataset('namespace/your_dataset_name', data_files=data_files) # 感觉这是在加载本地数据集
  

• 加载本地数据

  # Load a CSV file
  from datasets import load_dataset
  ds = load_dataset('csv', data_files='path/to/local/my_dataset.csv')
  
  # Load a JSON file
  from datasets import load_dataset
  ds = load_dataset('json', data_files='path/to/local/my_dataset.json')
  
  # Load from a local loading script
  from datasets import load_dataset
  ds = load_dataset('path/to/local/loading_script/loading_script.py', split='train')
  

• Load an [~datasets.IterableDataset]:

  from datasets import load_dataset
  ds = load_dataset('rotten_tomatoes', split='train', streaming=True)
  

• 利用ImageFolder 数据集构造器加载图片数据集

  from datasets import load_dataset
  ds = load_dataset('imagefolder', data_dir='/path/to/images', split='train')
  

datasets.load_from_disk

dataset_path (str)：数据集的 Path（或远程URI）或者加载数据的DatasetDict 的文件夹

fs：下载文件的远程文件系统的实例。 可以是S3FileSystem 或 fsspec.spec.AbstractFileSystem。默认None

keep_in_memory：是否赋值数据集到内存中。如果设置为None则不会，除非显式地指定datasets.config.IN_MEMORY_MAX_SIZE为非零

函数返回结果： Dataset 或者 DatasetDict

• 如果dataset_path 是一个dataset 目录：则会请求dataset
• 如果dataset_path 是一个dataset dict目录：每个数据分割都会返回一个datasets.DatasetDict

实例：

from datasets import load_from_disk
ds = load_from_disk('path/to/dataset/directory')

datasets.load_dataset_builder

参数与datasets.load_dataset基本一致，本方法的可以在不下载数据集的情况下获取到数据集的有关信息（包括：cache directory, config, dataset info, etc.）

返回结果：DatasetBuilder

一个数据集是一个目录，该目录包含：

• 通用格式（JSON, CSV, Parquet, text, etc.）的数据文件
• 如果需要code去读取数据文件，则可以包含可选的数据集脚本。该脚本被用于加载任意数据格式和结构

当您想要访问私有数据集时，需要指定use_auth_token=True

Returns：DatasetBuilder

实例展示:

from datasets import load_dataset_builder
ds_builder = load_dataset_builder('rotten_tomatoes')
print(ds_builder.info.features)
'''
	{'label': ClassLabel(num_classes=2, names=['neg', 'pos'], id=None),
 	'text': Value(dtype='string', id=None)}
'''

datasets.get_dataset_config_names

path (str)：利用dataset builder 的数据集处理脚本的路径。它可以是：

• 一个本地路径，如果这个脚本具有与该目录相同的名称。例如，'./dataset/squad' 或则 './dataset/squad/squad.py'

• HF hub上的一个数据集标识。例如，'squad', 'glue' or 'openai/webtext'

revision：如果指定，数据集模块将从此版本的数据集存储库加载。支持传入参数的格式为str和datasets.Version。默认情况下：

• 它设置为 lib 的本地版本。
• 如果它在本地版本的 lib 中不可用，它也会尝试从主分支加载它。指定与本地 lib 版本不同的版本可能会导致兼容性问题。

download_config： 指定下载配置参数。参数类型是DownloadConfig

download_mode：指定下载和生成的模式。 参数类型DownloadMode

dynamic_modules_path： 动态模块保存目录的可选路径。它需要HF_MODULES_CACHE 进行实例化。默认情况下，datasets 和 metrics是保存在datasets_modules中的。参数类型str。默认是HF_MODULES_CACHE / “datasets_modules”。例如， i.e. ~/.cache/huggingface/modules/datasets_modules。

data_files： (Union[Dict, List, str], optional) — 定义数据集配置的data_files

**download_kwargs： (additional keyword arguments) — DownloadConfig()的可选属性，该属性将重写download_config中的属性（如果提供）。例如use_auth_token。

return：获取特定数据集的可用配置名称列表。

实例：

from datasets import get_dataset_config_names
get_dataset_config_names("glue")
'''
	['cola',
     'sst2',
     'mrpc',
     'qqp',
     'stsb',
     'mnli',
     'mnli_mismatched',
     'mnli_matched',
     'qnli',
     'rte',
     'wnli',
     'ax']
'''

datasets.get_dataset_infos

path (str)：利用dataset builder 的数据集处理脚本的路径。它可以是：

• 一个本地路径，如果这个脚本具有与该目录相同的名称。例如，'./dataset/squad' 或则 './dataset/squad/squad.py'

• HF hub上的一个数据集标识。例如，'squad', 'glue' or 'openai/webtext'

revision：如果指定，数据集模块将从此版本的数据集存储库加载。支持传入参数的格式为str和datasets.Version。默认情况下：

• 它设置为 lib 的本地版本。
• 如果它在本地版本的 lib 中不可用，它也会尝试从主分支加载它。指定与本地 lib 版本不同的版本可能会导致兼容性问题。

download_config： 指定下载配置参数。参数类型是DownloadConfig

download_mode：指定下载和生成的模式。 参数类型DownloadMode

data_files： (Union[Dict, List, str], optional) — 定义数据集配置的data_files

use_auth_token (str or bool, optional) — 可选字符串或布尔值，用作数据集集线器上远程文件的承载令牌。如果是True，则将从“~/.huggingface”上获取token。

**download_kwargs： (additional keyword arguments) — 生成器类的可选属性，如果提供，将覆盖这些属性。

return：获取关于数据集的元信息，作为dict映射配置名称返回到DatasetInfoDict。

实例：

from datasets import get_dataset_infos
print(get_dataset_infos('rotten_tomatoes'))
'''
	{'default': DatasetInfo(description="Movie Review Dataset.
 is a dataset of containing 5,331 positive and 5,331 negative processed
ences from Rotten Tomatoes movie reviews...), ...}
'''

datasets.get_dataset_split_names

path (str)：利用dataset builder 的数据集处理脚本的路径。它可以是：

• 一个本地路径，如果这个脚本具有与该目录相同的名称。例如，'./dataset/squad' 或则 './dataset/squad/squad.py'

• HF hub上的一个数据集标识。例如，'squad', 'glue' or `'openai/webtext'

config_name (str, optional) — 定义数据集配置的名称。

data_files (str or Sequence or Mapping, optional) — 原始数据文件的路径。

download_config (DownloadConfig, optional) — 特定下载配置参数。

download_mode (DownloadMode, default REUSE_DATASET_IF_EXISTS) — 下载或生成的模式。

revision (Version or str, optional) — 要加载的数据集脚本的版本。

• 对于 GitHub 上的huggingface/datasets库中的数据集，例如“squad”，该模块的默认版本是该库的本地版本。您可以指定与本地版本的 lib 不同的版本（例如“main”或“1.2.0”），但这可能会导致兼容性问题。
• 对于lhoestq/squad这类在Datasets Hub 上有自己的git仓库的社区数据集，其默认版本main对应着其main分支。您可以使用数据集存储库的commit sha或git tag指定默认“main”的不同版本。

use_auth_token (str or bool, optional) — 可选字符串或布尔值，用作数据集集线器上远程文件的承载令牌。如果是True，则将从“~/.huggingface”上获取token。

**config_kwargs (additional keyword arguments) — 生成器类的可选属性，如果提供，将覆盖这些属性。

return：获取特定配置和数据集的可用拆分列表。即数据集可用的分割名称

实例：

from datasets import get_dataset_split_names
print(get_dataset_split_names('rotten_tomatoes'))
'''
	['train', 'validation', 'test']
'''

datasets.inspect_dataset

path** (str)：利用dataset builder 的数据集处理脚本的路径。它可以是：

• 一个本地路径，如果这个脚本具有与该目录相同的名称。例如，'./dataset/squad' 或则 './dataset/squad/squad.py'
• HF hub上的一个数据集标识。例如，'squad', 'glue' or `'openai/webtext'

local_path (str) — 要将数据集脚本复制到的本地文件夹的路径。（存放本地数据集脚本的路径？）

download_config ([DownloadConfig], optional) — 特定下载配置参数。

**download_kwargs (additional keyword arguments) — [DownloadConfig]的可选参数，如果提供，将覆盖download_config的属性。

作用：Allow inspection/modification of a dataset script by copying on local drive at local_path.

Metrics

datasets.list_metrics

with_community_metrics (bool, optional, default True) — 包括社区提供的评估指标。

with_details (bool, optional, default False) — Return the full details on the metrics instead of only the short name.

return：List all the metrics script available on the Hugging Face Hub.

from datasets import list_metrics
print(list_metrics())
'''
	['accuracy',
     'bertscore',
     'bleu',
     'bleurt',
     'cer',
     'chrf',
     ...
	]
'''

datasets.load_metric

path (str) — 度量生成器的度量处理脚本的路径。可以是：

• 处理脚本或包含脚本的目录的本地路径（如果脚本与目录同名）。例如，'./metrics/rouge' 或者 './metrics/rogue/rouge.py'
• HuggingFace datasets repo上的指标标识（用 datasets.list_metrics()罗列所有可用的评估指标），如：'rouge' 或 'bleu'

config_name (str, optional) — 为度量选择配置（例如，GLUE评价指标对每个子集都有一个配置）

process_id (int, optional) — 进行分布式评价时，进程的 id 号

num_process (int, optional) — 进行分布式评估时，进程总数

cache_dir (Optional str) — 存储临时predictions 和references 的路径（default to ~/.cache/huggingface/metrics/）。

experiment_id (str) — 一个特定的实验id。如果多个分布式评估共享同一个文件系统，则使用该id。这对于计算分布式设置中的度量非常有用（特别是像F1这样的非加性度量）。

keep_in_memory (bool) — 是否将临时结果存储在内存中（默认为False）

download_config (Optional datasets.DownloadConfig） — 特定下载配置参数

download_mode (DownloadMode, default REUSE_DATASET_IF_EXISTS) — 下载和生成模式

revision (Optional Union[str, datasets.Version]) — 如果指定，将从此版本的数据集存储库加载模块。默认情况下，它设置为库的本地版本。指定与库的本地版本不同的版本可能会导致兼容性问题。

return：加载一个datasets.Metric

from datasets import load_metric
accuracy = load_metric('accuracy')
print(accuracy.compute(references=[1, 0], predictions=[1, 1]))
'''
	{'accuracy': 0.5}
'''

datasets.inspect_metric

path (str) — 使用数据集生成器的数据集处理脚本的路径。可以是：

• 处理脚本或包含脚本的目录的本地路径（如果脚本与目录同名）。例如，'./dataset/squad' 或者 './dataset/squad/squad.py'
• Hugging Face Hub 上的数据集标识（datasets.list_datasets()可以罗列出所有可用数据集及其ids） e.g. 'squad', 'glue' or 'openai/webtext'

local_path (str) — 数据集脚本要复制到的本地文件夹的路径

download_config (Optional datasets.DownloadConfig) — 特定下载配置参数。

**download_kwargs (additional keyword arguments) — DownloadConfig() 的可选属性，如果提供，将覆盖download_config中的属性。

作用：允许通过将度量脚本复制到 local_path 的本地驱动器上，检查/修改度量脚本。

From files

用于加载数据文件的配置。它们在加载本地文件或数据集存储库时使用：

• local files: load_dataset("parquet", data_dir="path/to/data/dir")
• dataset repository: load_dataset("allenai/c4")

你可以通过load_dataset的参数去配置数据加载。比如你可以指定sep参数去定义用于加载数据的CsvConfig

load_dataset("csv", data_dir="path/to/data/dir", sep="\t")

Text

class datasets.packaged_modules.text.TextConfig

( name: str = 'default',

version: typing.Union[str, datasets.utils.version.Version, NoneType] = 0.0.0,

data_dir: typing.Optional[str] = None,

data_files: typing.Optional[datasets.data_files.DataFilesDict] = None,

description: typing.Optional[str] = None,

features: typing.Optional[datasets.features.features.Features] = None,

encoding: str = 'utf-8',

chunksize: int = 10485760,

keep_linebreaks: bool = False,

sample_by: str = 'line' )

BuilderConfig for text files.

CSV

class datasets.packaged_modules.csv.CsvConfig

( name: str = 'default',
 version: typing.Union[str, datasets.utils.version.Version, NoneType] = 0.0.0,
 data_dir: typing.Optional[str] = None,
 data_files: typing.Optional[datasets.data_files.DataFilesDict] = None,
 description: typing.Optional[str] = None,
 sep: str = ',',
 delimiter: typing.Optional[str] = None,
 header: typing.Union[int, typing.List[int], str, NoneType] = 'infer',
 names: typing.Optional[typing.List[str]] = None,
 column_names: typing.Optional[typing.List[str]] = None,
 index_col: typing.Union[int, str, typing.List[int], typing.List[str], NoneType] = None,
 usecols: typing.Union[typing.List[int], typing.List[str], NoneType] = None,
 prefix: typing.Optional[str] = None,
 mangle_dupe_cols: bool = True,
 engine: typing.Optional[str] = None,
 true_values: typing.Optional[list] = None,
 false_values: typing.Optional[list] = None,
 skipinitialspace: bool = False,
 skiprows: typing.Union[int, typing.List[int], NoneType] = None,
 nrows: typing.Optional[int] = None,
 na_values: typing.Union[str, typing.List[str], NoneType] = None,
 keep_default_na: bool = True,
 na_filter: bool = True,
 verbose: bool = False,
 skip_blank_lines: bool = True,
 thousands: typing.Optional[str] = None,
 decimal: str = '.',
 lineterminator: typing.Optional[str] = None,
 quotechar: str = '"',
 quoting: int = 0,
 escapechar: typing.Optional[str] = None,
 comment: typing.Optional[str] = None,
 encoding: typing.Optional[str] = None,
 dialect: typing.Optional[str] = None,
 error_bad_lines: bool = True,
 warn_bad_lines: bool = True,
 skipfooter: int = 0,
 doublequote: bool = True,
 memory_map: bool = False,
 float_precision: typing.Optional[str] = None,
 chunksize: int = 10000,
 features: typing.Optional[datasets.features.features.Features] = None,
 encoding_errors: typing.Optional[str] = 'strict',
 on_bad_lines: typing.Literal['error', 'warn', 'skip'] = 'error'
)

BuilderConfig for JSON.

JSON

class datasets.packaged_modules.json.JsonConfig

( name: str = 'default',
 version: typing.Union[str, datasets.utils.version.Version, NoneType] = 0.0.0,
 data_dir: typing.Optional[str] = None,
 data_files: typing.Optional[datasets.data_files.DataFilesDict] = None,
 description: typing.Optional[str] = None,
 features: typing.Optional[datasets.features.features.Features] = None,
 field: typing.Optional[str] = None,
 use_threads: bool = True,
 block_size: typing.Optional[int] = None,
 chunksize: int = 10485760,
 newlines_in_values: typing.Optional[bool] = None )

BuilderConfig for JSON.

Parquet

class datasets.packaged_modules.parquet.ParquetConfig

( name: str = 'default',
 version: typing.Union[str, datasets.utils.version.Version, NoneType] = 0.0.0,
 data_dir: typing.Optional[str] = None,
 data_files: typing.Optional[datasets.data_files.DataFilesDict] = None,
 description: typing.Optional[str] = None,
 batch_size: int = 10000,
 columns: typing.Optional[typing.List[str]] = None,
 features: typing.Optional[datasets.features.features.Features] = None )

BuilderConfig for Parquet.

Images

class datasets.packaged_modules.imagefolder.ImageFolderConfig

( name: str = 'default',
 version: typing.Union[str, datasets.utils.version.Version, NoneType] = 0.0.0,
 data_dir: typing.Optional[str] = None,
 data_files: typing.Optional[datasets.data_files.DataFilesDict] = None,
 description: typing.Optional[str] = None,
 features: typing.Optional[datasets.features.features.Features] = None,
 drop_labels: bool = None,
 drop_metadata: bool = None )

BuilderConfig for ImageFolder.