# 构建器类

## 构建者[[datasets.DatasetBuilder]]

🤗 Datasets 在构建数据集的过程中主要依赖两个类：[DatasetBuilder](/docs/datasets/v5.2.0/zh/package_reference/builder_classes#datasets.DatasetBuilder) 和 [BuilderConfig](/docs/datasets/v5.2.0/zh/package_reference/builder_classes#datasets.BuilderConfig)。

#### datasets.DatasetBuilder[[datasets.DatasetBuilder]]

```python
datasets.DatasetBuilder(cache_dir: typing.Optional[str] = None, dataset_name: typing.Optional[str] = None, config_name: typing.Optional[str] = None, hash: typing.Optional[str] = None, base_path: typing.Optional[str] = None, info: typing.Optional[datasets.info.DatasetInfo] = None, features: typing.Optional[datasets.features.features.Features] = None, token: typing.Union[bool, str, NoneType] = None, repo_id: typing.Optional[str] = None, data_files: typing.Union[str, list, dict, datasets.data_files.DataFilesDict, NoneType] = None, data_dir: typing.Optional[str] = None, storage_options: typing.Optional[dict] = None, writer_batch_size: typing.Optional[int] = None, config_id: typing.Optional[str] = None, **config_kwargs)
```

[源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/builder.py#L214)

**参数：**

cache_dir (`str`, *可选*) : 用于缓存数据的目录。默认为 `"~/.cache/huggingface/datasets"`。

dataset_name (`str`, *可选*) : 数据集的名称，如果与构建器名称不同。对于 csv、imagefolder、audiofolder 等打包构建器，此参数可用于区分使用相同打包构建器的不同数据集。

config_name (`str`, *可选*) : 数据集配置的名称。它会影响磁盘上生成的数据。不同的配置将拥有各自的子目录和版本。如果未提供，则使用默认配置（如果存在）。    参数 `name` 已重命名为 `config_name`。

hash (`str`, *可选*) : 特定于数据集构建器代码的哈希值。用于在数据集构建器代码更新时更新缓存目录（以避免重用旧数据）。典型的缓存目录（定义在 `self._relative_data_dir` 中）为 `name/version/hash/`。

base_path (`str`, *可选*) : 用于下载文件的相对路径的基础路径。这可以是一个远程 URL。

features （[Features](/docs/datasets/v5.2.0/zh/package_reference/main_classes#datasets.Features)，*可选*）：用于此数据集的 Features 类型。例如，可用于更改数据集的 [Features](/docs/datasets/v5.2.0/zh/package_reference/main_classes#datasets.Features) 类型。

token (`str` 或 `bool`，*可选*) : 用作 Datasets Hub 上远程文件 Bearer token 的字符串或布尔值。如果为 `True`，则从 `"~/.huggingface"` 获取 token。

repo_id (`str`, *可选*) : 数据集仓库的 ID。用于区分同名但来自不同命名空间的构建器，例如 "rajpurkar/squad" 和 "lhoestq/squad" 仓库 ID。在后一种情况下，构建器名称为 "lhoestq___squad"。

data_files (`str` 或 `Sequence` 或 `Mapping`，*可选*)：源数据文件的路径。对于需要用户指定数据文件的构建器（如 "csv" 或 "json"）适用。这些文件可以是本地文件或远程文件。为了方便起见，您可以使用 `DataFilesDict`。

data_dir (`str`, *可选*) : 包含源数据文件的目录路径。仅在未传入 `data_files` 时使用，此时等同于将 `os.path.join(data_dir, "**")` 作为 `data_files` 传入。对于需要手动下载的构建器，它必须是包含手动下载数据的本地目录路径。

storage_options (`dict`, *可选*) : 要传递给数据集文件系统后端的键值对（如果存在）。

writer_batch_size (`int`, *可选*) : ArrowWriter 使用的批处理大小。它定义了写入前保留在内存中的样本数量，同时也决定了 arrow 块（chunks）的长度。None 表示 ArrowWriter 将使用其默认值。

- ****config_kwargs**（额外的关键字参数）：传递给对应构建器配置类（设置在类属性 [DatasetBuilder.BUILDER_CONFIG_CLASS](/docs/datasets/v5.2.0/zh/package_reference/builder_classes#datasets.BuilderConfig) 上）的关键字参数。该构建器配置类为 [BuilderConfig](/docs/datasets/v5.2.0/zh/package_reference/builder_classes#datasets.BuilderConfig) 或其子类。

所有数据集的抽象基类。

`DatasetBuilder` 有 3 个关键方法：

- `DatasetBuilder.info`：记录数据集的文档信息，包括特征名称、类型、形状、版本、数据划分、引用等。
- [DatasetBuilder.download_and_prepare()](/docs/datasets/v5.2.0/zh/package_reference/builder_classes#datasets.DatasetBuilder.download_and_prepare)：下载源数据并将其写入磁盘。
- [DatasetBuilder.as_dataset()](/docs/datasets/v5.2.0/zh/package_reference/builder_classes#datasets.DatasetBuilder.as_dataset)：生成一个 [Dataset](/docs/datasets/v5.2.0/zh/package_reference/main_classes#datasets.Dataset)。

某些 `DatasetBuilder` 通过定义 [BuilderConfig](/docs/datasets/v5.2.0/zh/package_reference/builder_classes#datasets.BuilderConfig) 子类并在构造时接受配置对象（或名称）来公开数据集的多个变体。可配置数据集会在 `DatasetBuilder.builder_configs()` 中公开一组预定义的配置。

#### as_dataset[[datasets.DatasetBuilder.as_dataset]]

```python
as_dataset(split: typing.Union[str, datasets.splits.Split, list[str], list[datasets.splits.Split], NoneType] = None, in_memory = False)
```

[源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/builder.py#L991)

**参数：**

split (`datasets.Split`) : 要返回的数据子集。

verification_mode ([VerificationMode](/docs/datasets/v5.2.0/zh/package_reference/builder_classes#datasets.VerificationMode) 或 `str`，默认为 `BASIC_CHECKS`)：验证模式，用于确定对下载/处理后的数据集信息（校验和/大小/分片/...）要执行的检查。

in_memory (`bool`，默认为 `False`)：是否将数据复制到内存中。

**返回：**

datasets.Dataset

返回指定 split 的 Dataset。

示例：

```py
>>> from datasets import load_dataset_builder
>>> builder = load_dataset_builder('cornell-movie-review-data/rotten_tomatoes')
>>> builder.download_and_prepare()
>>> ds = builder.as_dataset(split='train')
>>> ds
Dataset({
    features: ['text', 'label'],
    num_rows: 8530
})
```

#### download_and_prepare[[datasets.DatasetBuilder.download_and_prepare]]

```python
download_and_prepare(output_dir: typing.Optional[str] = None, download_config: typing.Optional[datasets.download.download_config.DownloadConfig] = None, download_mode: typing.Union[datasets.download.download_manager.DownloadMode, str, NoneType] = None, verification_mode: typing.Union[datasets.utils.info_utils.VerificationMode, str, NoneType] = None, dl_manager: typing.Optional[datasets.download.download_manager.DownloadManager] = None, base_path: typing.Optional[str] = None, file_format: str = 'arrow', max_shard_size: typing.Union[str, int, NoneType] = None, num_proc: typing.Optional[int] = None, storage_options: typing.Optional[dict] = None, **download_and_prepare_kwargs)
```

[源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/builder.py#L702)

**参数：**

output_dir (`str`, *可选*) : 数据集的输出目录。默认为此构建器的 `cache_dir`，其默认位于 `~/.cache/huggingface/datasets` 内。

download_config (`DownloadConfig`，*可选*)：特定的下载配置参数。

download_mode ([DownloadMode](/docs/datasets/v5.2.0/zh/package_reference/builder_classes#datasets.DownloadMode) 或 `str`，*可选*)：选择下载/生成模式，默认为 `REUSE_DATASET_IF_EXISTS`。

verification_mode ([VerificationMode](/docs/datasets/v5.2.0/zh/package_reference/builder_classes#datasets.VerificationMode) 或 `str`，默认为 `BASIC_CHECKS`)：验证模式，用于确定对下载/处理后的数据集信息（校验和/大小/分片/...）要执行的检查。

dl_manager (`DownloadManager`，*可选*)：要使用的特定 `DownloadManger`。

base_path (`str`, *可选*) : 用于下载文件的相对路径的基础路径。这可以是一个远程 URL。如果未指定，则使用 `base_path` 属性（`self.base_path`）的值。

file_format (`str`, *可选*) : 数据集写入的数据文件格式。支持的格式："arrow"、"parquet"。默认为 "arrow" 格式。如果格式为 "parquet"，则图像和音频数据会嵌入到 Parquet 文件中，而不是指向本地文件。

max_shard_size (`Union[str, int]`, *可选*) : 每个分片写入的最大字节数，默认为 "500MB"。该大小基于未压缩的数据大小，因此实际上，由于 Parquet 压缩等原因，您的分片文件可能小于 `max_shard_size`。

num_proc (`int`，*可选*，默认为 `None`)：在本地下载和生成数据集时使用的进程数。默认情况下禁用多进程。

storage_options (`dict`, *可选*) : 要传递给缓存文件系统后端（如果存在）的键值对。

- ****download_and_prepare_kwargs**（额外的关键字参数）：关键字参数。

下载并准备数据集以供读取。

示例：

下载并准备数据集，将其转换为 Arrow 文件，以便使用 `builder.as_dataset()` 作为 Dataset 加载：

```py
>>> from datasets import load_dataset_builder
>>> builder = load_dataset_builder("cornell-movie-review-data/rotten_tomatoes")
>>> builder.download_and_prepare()
```

在本地下载并准备数据集，将其保存为分片的 Parquet 文件：

```py
>>> from datasets import load_dataset_builder
>>> builder = load_dataset_builder("cornell-movie-review-data/rotten_tomatoes")
>>> builder.download_and_prepare("./output_dir", file_format="parquet")
```

在云存储中下载并准备数据集，将其保存为分片的 Parquet 文件：

```py
>>> from datasets import load_dataset_builder
>>> storage_options = {"key": aws_access_key_id, "secret": aws_secret_access_key}
>>> builder = load_dataset_builder("cornell-movie-review-data/rotten_tomatoes")
>>> builder.download_and_prepare("s3://my-bucket/my_rotten_tomatoes", storage_options=storage_options, file_format="parquet")
```

#### get_imported_module_dir[[datasets.DatasetBuilder.get_imported_module_dir]]

```python
get_imported_module_dir()
```

[源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/builder.py#L694)

返回此类或其子类的模块路径。

#### datasets.GeneratorBasedBuilder[[datasets.GeneratorBasedBuilder]]

```python
datasets.GeneratorBasedBuilder(cache_dir: typing.Optional[str] = None, dataset_name: typing.Optional[str] = None, config_name: typing.Optional[str] = None, hash: typing.Optional[str] = None, base_path: typing.Optional[str] = None, info: typing.Optional[datasets.info.DatasetInfo] = None, features: typing.Optional[datasets.features.features.Features] = None, token: typing.Union[bool, str, NoneType] = None, repo_id: typing.Optional[str] = None, data_files: typing.Union[str, list, dict, datasets.data_files.DataFilesDict, NoneType] = None, data_dir: typing.Optional[str] = None, storage_options: typing.Optional[dict] = None, writer_batch_size: typing.Optional[int] = None, config_id: typing.Optional[str] = None, **config_kwargs)
```

[源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/builder.py#L1292)

基于字典生成器进行数据生成的数据集的基类。

`GeneratorBasedBuilder` 是一个便捷类，它抽象了 `DatasetBuilder` 中大部分的数据写入和读取操作。它要求子类实现针对数据集各个拆分（`_split_generators`）的特征字典生成器。有关详细信息，请参阅方法的文档字符串。

#### datasets.ArrowBasedBuilder[[datasets.ArrowBasedBuilder]]

```python
datasets.ArrowBasedBuilder(cache_dir: typing.Optional[str] = None, dataset_name: typing.Optional[str] = None, config_name: typing.Optional[str] = None, hash: typing.Optional[str] = None, base_path: typing.Optional[str] = None, info: typing.Optional[datasets.info.DatasetInfo] = None, features: typing.Optional[datasets.features.features.Features] = None, token: typing.Union[bool, str, NoneType] = None, repo_id: typing.Optional[str] = None, data_files: typing.Union[str, list, dict, datasets.data_files.DataFilesDict, NoneType] = None, data_dir: typing.Optional[str] = None, storage_options: typing.Optional[dict] = None, writer_batch_size: typing.Optional[int] = None, config_id: typing.Optional[str] = None, **config_kwargs)
```

[源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/builder.py#L1610)

基于 Arrow 加载函数（CSV/JSON/Parquet）进行数据生成的数据集基类。

#### datasets.BuilderConfig[[datasets.BuilderConfig]]

```python
datasets.BuilderConfig(name: str = 'default', version: typing.Union[datasets.utils.version.Version, str, NoneType] = 0.0.0, data_dir: typing.Optional[str] = None, data_files: typing.Union[datasets.data_files.DataFilesDict, datasets.data_files.DataFilesPatternsDict, NoneType] = None, description: typing.Optional[str] = None)
```

[源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/builder.py#L101)

**参数：**

name (`str`，默认为 `default`)：配置的名称。

version (`Version` 或 `str`，默认为 `0.0.0`)：配置的版本。

data_dir (`str`, *可选*) : 包含源数据的目录路径。

data_files (`str` 或 `Sequence` 或 `Mapping`，*可选*)：源数据文件的路径。

description (`str`, *可选*) : 配置的人类可读描述。

`DatasetBuilder` 数据配置的基础类。

带有数据配置选项的 `DatasetBuilder` 子类应继承 `BuilderConfig` 并添加自己的属性。

#### create_config_id[[datasets.BuilderConfig.create_config_id]]

```python
create_config_id(config_kwargs: dict, custom_features: typing.Optional[datasets.features.features.Features] = None)
```

[源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/builder.py#L144)

配置 ID 用于构建缓存目录。默认情况下，它等于配置名称。但是，由于配置名称未考虑以下因素，因此不足以作为正在生成的数据集的唯一标识符：
- 可用于覆盖属性的 config kwargs
- 用于编写数据集的自定义特征
- json/text/csv/pandas 数据集的 data_files

因此，config id 就是 config 名称加上基于这些的可选后缀。

## 下载[[datasets.DownloadManager]]

#### datasets.DownloadManager[[datasets.DownloadManager]]

```python
datasets.DownloadManager(dataset_name: typing.Optional[str] = None, data_dir: typing.Optional[str] = None, download_config: typing.Optional[datasets.download.download_config.DownloadConfig] = None, base_path: typing.Optional[str] = None, record_checksums = False)
```

[源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/download/download_manager.py#L71)

#### 下载[[datasets.DownloadManager.download]]

```python
download(url_or_urls)
```

[源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/download/download_manager.py#L131)

**参数：**

url_or_urls (`str` 或 `list` 或 `dict`) : 要下载的 URL 或 URL 的 `list` 或 `dict`。每个 URL 都是一个 `str`。

**返回：** `str` 或 `list` 或 `dict`

与给定输入 `url_or_urls` 匹配的已下载路径。

下载给定的 URL。

默认情况下，仅使用一个进程进行下载。传入自定义的 `download_config.num_proc` 以更改此行为。

示例：

```py
>>> downloaded_files = dl_manager.download('https://storage.googleapis.com/seldon-datasets/sentence_polarity_v1/rt-polaritydata.tar.gz')
```

#### download_and_extract[[datasets.DownloadManager.download_and_extract]]

```python
download_and_extract(url_or_urls)
```

[源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/download/download_manager.py#L310)

**参数：**

url_or_urls (`str` 或 `list` 或 `dict`)：要下载并解压的 URL 或 URL 的 `list` 或 `dict`。每个 URL 均为 `str`。

**返回：** `extracted_path(s)`

`str`，给定 URL 的提取路径。

下载并解压给定的`url_or_urls`。

大致等同于：

```
extracted_paths = dl_manager.extract(dl_manager.download(url_or_urls))
```

#### extract[[datasets.DownloadManager.extract]]

```python
extract(path_or_paths)
```

[源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/download/download_manager.py#L278)

**参数：**

path_or_paths （路径或 `list` 或 `dict`）：要提取的文件路径。每个路径均为 `str`。

**返回：** `extracted_path(s)`

`str`，与给定输入 path_or_paths 匹配的提取路径。

提取给定的路径。

示例：

```py
>>> downloaded_files = dl_manager.download('https://storage.googleapis.com/seldon-datasets/sentence_polarity_v1/rt-polaritydata.tar.gz')
>>> extracted_files = dl_manager.extract(downloaded_files)
```

#### iter_archive[[datasets.DownloadManager.iter_archive]]

```python
iter_archive(path_or_buf: typing.Union[str, _io.BufferedReader])
```

[源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/download/download_manager.py#L234)

**参数：**

path_or_buf (`str` 或 `io.BufferedReader`)：归档路径或归档二进制文件对象。

**返回值：** `tuple[str, io.BufferedReader]`

2 元组 (path_within_archive, file_object)。文件对象以二进制模式打开。

遍历归档文件中的文件。

示例：

```py
>>> archive = dl_manager.download('https://storage.googleapis.com/seldon-datasets/sentence_polarity_v1/rt-polaritydata.tar.gz')
>>> files = dl_manager.iter_archive(archive)
```

#### iter_files[[datasets.DownloadManager.iter_files]]

```python
iter_files(paths: typing.Union[str, list[str]])
```

[源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/download/download_manager.py#L259)

**参数：**

paths (`str` 或 `list` 类型的 `str`) : 根路径。

**返回值：** `str`

文件路径。

遍历文件路径。

示例：

```py
>>> files = dl_manager.download_and_extract('https://huggingface.co/datasets/AI-Lab-Makerere/beans/resolve/main/data/train.zip')
>>> files = dl_manager.iter_files(files)
```

#### datasets.StreamingDownloadManager[[datasets.StreamingDownloadManager]]

```python
datasets.StreamingDownloadManager(dataset_name: typing.Optional[str] = None, data_dir: typing.Optional[str] = None, download_config: typing.Optional[datasets.download.download_config.DownloadConfig] = None, base_path: typing.Optional[str] = None)
```

[源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/download/streaming_download_manager.py#L47)

使用“::”分隔符来导航（可能为远程的）压缩归档文件的下载管理器。与常规的`DownloadManager`不同，`download`和`extract`方法实际上并不下载或解压数据，而是返回可以使用`xopen`函数打开的路径或 URL。该函数扩展了内置的`open`函数，以从远程文件流式读取数据。

#### 下载[[datasets.StreamingDownloadManager.download]]

```python
download(url_or_urls)
```

[源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/download/streaming_download_manager.py#L75)

**参数：**

url_or_urls (`str` 或 `list` 或 `dict`) : 用于流式传输数据的文件 URL。每个 url 均为 `str`。

**返回：** `url(s)`

（`str` 或 `list` 或 `dict`），用于流式传输与给定 input url_or_urls 匹配的数据的 URL。

将用于流式传输数据的文件 URL 规范化。这是 `DownloadManager.download` 的流式传输惰性版本。

示例：

```py
>>> downloaded_files = dl_manager.download('https://storage.googleapis.com/seldon-datasets/sentence_polarity_v1/rt-polaritydata.tar.gz')
```

#### download_and_extract[[datasets.StreamingDownloadManager.download_and_extract]]

```python
download_and_extract(url_or_urls)
```

[源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/download/streaming_download_manager.py#L151)

**参数：**

url_or_urls (`str` 或 `list` 或 `dict`) : 用于流式传输数据的 URL。每个 url 都是一个 `str`。

**返回：** `url(s)`

（`str` 或 `list` 或 `dict`），用于流式传输数据的 URL，需与给定的输入 `url_or_urls` 匹配。

为给定的 `url_or_urls` 准备流式传输（添加提取协议）。

这是`DownloadManager.download_and_extract`的流式处理惰性版本。

等价于：

```
urls = dl_manager.extract(dl_manager.download(url_or_urls))
```

#### extract[[datasets.StreamingDownloadManager.extract]]

```python
extract(url_or_urls)
```

[源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/download/streaming_download_manager.py#L102)

**参数：**

url_or_urls (`str` 或 `list` 或 `dict`) : 用于流式传输数据的文件 URL。每个 url 均为 `str`。

**返回：** `url(s)`

（`str` 或 `list` 或 `dict`），用于流式传输数据的 URL，需与给定的输入 `url_or_urls` 匹配。

为流式处理添加针对给定 URL 的提取协议。

这是`DownloadManager.extract`的流式处理惰性版本。

示例：

```py
>>> downloaded_files = dl_manager.download('https://storage.googleapis.com/seldon-datasets/sentence_polarity_v1/rt-polaritydata.tar.gz')
>>> extracted_files = dl_manager.extract(downloaded_files)
```

#### iter_archive[[datasets.StreamingDownloadManager.iter_archive]]

```python
iter_archive(urlpath_or_buf: typing.Union[str, _io.BufferedReader])
```

[源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/download/streaming_download_manager.py#L171)

**参数：**

urlpath_or_buf (`str` 或 `io.BufferedReader`)：归档路径或归档二进制文件对象。

**返回值：** `tuple[str, io.BufferedReader]`

2 元组 (path_within_archive, file_object)。文件对象以二进制模式打开。

遍历归档文件中的文件。

示例：

```py
>>> archive = dl_manager.download('https://storage.googleapis.com/seldon-datasets/sentence_polarity_v1/rt-polaritydata.tar.gz')
>>> files = dl_manager.iter_archive(archive)
```

#### iter_files[[datasets.StreamingDownloadManager.iter_files]]

```python
iter_files(urlpaths: typing.Union[str, list[str]])
```

[源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/download/streaming_download_manager.py#L196)

**参数：**

urlpaths (`str` 或 `list` 类型的 `str`) : 根路径。

**返回值：** `str`

文件 URL 路径。

遍历文件。

示例：

```py
>>> files = dl_manager.download_and_extract('https://huggingface.co/datasets/AI-Lab-Makerere/beans/resolve/main/data/train.zip')
>>> files = dl_manager.iter_files(files)
```

#### datasets.DownloadConfig[[datasets.DownloadConfig]]

```python
datasets.DownloadConfig(cache_dir: typing.Union[str, pathlib.Path, NoneType] = None, force_download: bool = False, resume_download: bool = False, local_files_only: bool = False, proxies: typing.Optional[dict] = None, user_agent: typing.Optional[str] = None, extract_compressed_file: bool = False, force_extract: bool = False, delete_extracted: bool = False, extract_on_the_fly: bool = False, use_etag: bool = True, num_proc: typing.Optional[int] = None, max_retries: int = 1, token: typing.Union[str, bool, NoneType] = None, storage_options: dict = <factory>, download_desc: typing.Optional[str] = None, disable_tqdm: bool = False)
```

[源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/download/download_config.py#L10)

**参数：**

cache_dir (`str` 或 `Path`，*可选*)：指定用于保存文件的缓存目录（覆盖默认缓存目录）。

force_download (`bool`，默认为 `False`)：如果为 `True`，即使文件已缓存在缓存目录中，也会重新下载该文件。

resume_download (`bool`，默认为 `False`)：如果为 `True`，当发现未完整接收的文件时，恢复下载。

proxies (`dict`, *可选*) : 已弃用且被忽略。请改为设置 `HTTP_PROXY` / `HTTPS_PROXY` 环境变量，或使用 [huggingface_hub.set_client_factory](https://huggingface.co/docs/huggingface_hub/v2.4.0/en/package_reference/utilities#huggingface_hub.set_client_factory) 配置 HTTP 客户端。

user_agent (`str`, *可选*) : 可选的字符串或字典，将附加到远程请求的用户代理中。

extract_compressed_file (`bool`，默认为 `False`)：如果 `True` 且路径指向 zip 或 tar 文件，则在归档文件所在的文件夹中解压该压缩文件。

force_extract (`bool`，默认为 `False`) : 如果 `True`，当 `extract_compressed_file` 为 `True` 且压缩包已被解压时，重新解压该压缩包并覆盖其解压目录。

delete_extracted (`bool`，默认为 `False`)：是否删除（或保留）提取的文件。

extract_on_the_fly (`bool`，默认为 `False`)：如果为 `True`，则在读取时解压压缩文件。

use_etag (`bool`，默认为 `True`)：是否使用 ETag HTTP 响应头来验证缓存文件。

num_proc (`int`, *可选*) : 用于并行下载文件的进程数。

max_retries (`int`，默认为 `1`)：如果 HTTP 请求失败，重试的次数。

token (`str` 或 `bool`，*可选*)：用于 Datasets Hub 上远程文件的 Bearer token 的可选字符串或布尔值。如果为 `True` 或未指定，则从 `~/.huggingface` 获取 token。

storage_options (`dict`, *可选*) : 要传递给数据集文件系统后端的键值对（如果存在）。

download_desc (`str`, *可选*) : 在下载文件时，与进度条一同显示的说明。

disable_tqdm (`bool`，默认为 `False`)：是否禁用单个文件的下载进度条

我们缓存路径管理器的配置。

#### datasets.DownloadMode[[datasets.DownloadMode]]

```python
datasets.DownloadMode(value, names = None, module = None, qualname = None, type = None, start = 1)
```

[源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/download/download_manager.py#L50)

`Enum`，用于指定如何处理已存在的下载和数据。

默认模式为 `REUSE_DATASET_IF_EXISTS`，如果原始下载文件和已准备好的数据集存在，则会同时复用它们。

生成模式：

|                                     | 下载 | 数据集 |
|-------------------------------------|-----------|---------|
| `REUSE_DATASET_IF_EXISTS`（默认） | 复用     | 复用   |
| `REUSE_CACHE_IF_EXISTS`             | 复用     | 新鲜   |
| `FORCE_REDOWNLOAD`                  | 新鲜     | 新鲜   |

## 验证[[datasets.VerificationMode]]

#### datasets.VerificationMode[[datasets.VerificationMode]]

```python
datasets.VerificationMode(value, names = None, module = None, qualname = None, type = None, start = 1)
```

[源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/utils/info_utils.py#L22)

`Enum`，用于指定要运行哪些验证检查。

默认模式为 `BASIC_CHECKS`，该模式仅执行基础检查，以避免在首次生成/下载数据集时造成速度变慢。

验证模式：

|                           | 验证检查                                                           |
|---------------------------|------------------------------------------------------------------------------ |
| `ALL_CHECKS`              | 拆分检查以及已下载文件的有效性（文件数量、校验和）    |
| `BASIC_CHECKS`（默认）  | 与 `ALL_CHECKS` 相同，但不检查已下载的文件                    |
| `NO_CHECKS`               | 无                                                                          |

## 拆分[[datasets.SplitGenerator]]

#### datasets.SplitGenerator[[datasets.SplitGenerator]]

```python
datasets.SplitGenerator(name: str, gen_kwargs: dict = <factory>)
```

[源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/splits.py#L624)

**参数：**

name (`str`) : 生成器将为其创建示例的 `Split` 的名称。

- ****gen_kwargs**（额外的关键字参数）：要传递给构建器的 `DatasetBuilder._generate_examples` 方法的关键字参数。

定义生成器的拆分信息。

这应作为 `GeneratorBasedBuilder._split_generators` 的返回值。有关更多信息和使用示例，请参阅 `GeneratorBasedBuilder._split_generators`。

示例：

```py
>>> datasets.SplitGenerator(
...     name=datasets.Split.TRAIN,
...     gen_kwargs={"split_key": "train", "files": dl_manager.download_and_extract(url)},
... )
```

#### datasets.Split[[datasets.Split]]

```python
datasets.Split(name)
```

[源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/splits.py#L417)

用于数据集划分的`Enum`。

数据集通常会被拆分为不同的子集，用于训练和评估的各个阶段。

- `TRAIN`：训练数据。
- `VALIDATION`：验证数据。如果存在，通常用作在迭代模型（例如更改超参数、模型架构等）时的评估数据。
- `TEST`：测试数据。这是用于报告指标的数据。通常，在模型迭代过程中不建议使用此数据，因为这可能导致过拟合。
- `ALL`：所有已定义数据集拆分的并集。

所有拆分，包括组合，都继承自 `datasets.SplitBase`。

有关数据划分的更多信息，请参阅[指南](../load_hub#splits)。

示例：

```py
>>> datasets.SplitGenerator(
...     name=datasets.Split.TRAIN,
...     gen_kwargs={"split_key": "train", "files": dl_manager.download_and extract(url)},
... ),
... datasets.SplitGenerator(
...     name=datasets.Split.VALIDATION,
...     gen_kwargs={"split_key": "validation", "files": dl_manager.download_and extract(url)},
... ),
... datasets.SplitGenerator(
...     name=datasets.Split.TEST,
...     gen_kwargs={"split_key": "test", "files": dl_manager.download_and extract(url)},
... )
```

#### datasets.NamedSplit[[datasets.NamedSplit]]

```python
datasets.NamedSplit(name: str)
```

[源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/splits.py#L325)

与命名拆分（train、test 等）对应的描述符。

示例：

每个描述符都可以通过加法或切片与其他描述符组合：

```py
split = datasets.Split.TRAIN.subsplit(datasets.percent[0:25]) + datasets.Split.TEST
```

生成的拆分将对应于 25% 的训练拆分与 100% 的测试拆分合并后的结果。

不能重复添加同一个 split，因此以下操作将会失败：

```py
split = (
        datasets.Split.TRAIN.subsplit(datasets.percent[:25]) +
        datasets.Split.TRAIN.subsplit(datasets.percent[75:])
)  # Error
split = datasets.Split.TEST + datasets.Split.ALL  # Error
```

切片只能应用一次。因此，以下用法是有效的：

```py
split = (
        datasets.Split.TRAIN.subsplit(datasets.percent[:25]) +
        datasets.Split.TEST.subsplit(datasets.percent[:50])
)
split = (datasets.Split.TRAIN + datasets.Split.TEST).subsplit(datasets.percent[:50])
```

但这不是有效的：

```py
train = datasets.Split.TRAIN
test = datasets.Split.TEST
split = train.subsplit(datasets.percent[:25]).subsplit(datasets.percent[:25])
split = (train.subsplit(datasets.percent[:25]) + test).subsplit(datasets.percent[:50])
```

#### datasets.NamedSplitAll[[datasets.NamedSplitAll]]

```python
datasets.NamedSplitAll()
```

[源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/splits.py#L402)

对应于所有已定义数据集分割的并集的分割。

#### datasets.ReadInstruction[[datasets.ReadInstruction]]

```python
datasets.ReadInstruction(split_name, rounding = None, from_ = None, to = None, unit = None)
```

[源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/arrow_reader.py#L456)

用于数据集的读取指令。

示例：

```python
# The following lines are equivalent:
ds = datasets.load_dataset('ylecun/mnist', split='test[:33%]')
ds = datasets.load_dataset('ylecun/mnist', split=datasets.ReadInstruction.from_spec('test[:33%]'))
ds = datasets.load_dataset('ylecun/mnist', split=datasets.ReadInstruction('test', to=33, unit='%'))
ds = datasets.load_dataset('ylecun/mnist', split=datasets.ReadInstruction(
'test', from_=0, to=33, unit='%'))

# The following lines are equivalent:
ds = datasets.load_dataset('ylecun/mnist', split='test[:33%]+train[1:-1]')
ds = datasets.load_dataset('ylecun/mnist', split=datasets.ReadInstruction.from_spec(
'test[:33%]+train[1:-1]'))
ds = datasets.load_dataset('ylecun/mnist', split=(
datasets.ReadInstruction('test', to=33, unit='%') +
datasets.ReadInstruction('train', from_=1, to=-1, unit='abs')))

# The following lines are equivalent:
ds = datasets.load_dataset('ylecun/mnist', split='test[:33%](pct1_dropremainder)')
ds = datasets.load_dataset('ylecun/mnist', split=datasets.ReadInstruction.from_spec(
'test[:33%](pct1_dropremainder)'))
ds = datasets.load_dataset('ylecun/mnist', split=datasets.ReadInstruction(
'test', from_=0, to=33, unit='%', rounding="pct1_dropremainder"))

# 10-fold validation:
tests = datasets.load_dataset(
'ylecun/mnist',
[datasets.ReadInstruction('train', from_=k, to=k+10, unit='%')
for k in range(0, 100, 10)])
trains = datasets.load_dataset(
'ylecun/mnist',
[datasets.ReadInstruction('train', to=k, unit='%') + datasets.ReadInstruction('train', from_=k+10, unit='%')
for k in range(0, 100, 10)])
```

#### from_spec[[datasets.ReadInstruction.from_spec]]

```python
from_spec(spec)
```

[源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/arrow_reader.py#L536)

**参数：**

spec (`str`) : 要读取的 Split(s) + 可选的 slice(s) + 如果以百分比作为切片单位，则可选的舍入。可以使用绝对数字（`int`）或百分比（`int`）来指定 slice。

**返回：**

ReadInstruction 实例。

根据字符串规范创建一个 `ReadInstruction` 实例。

示例：

```
test: test split.
test + validation: test split + validation split.
test[10:]: test split, minus its first 10 records.
test[:10%]: first 10% records of test split.
test[:20%](pct1_dropremainder): first 10% records, rounded with the pct1_dropremainder rounding.
test[:-5%]+train[40%:60%]: first 95% of test + middle 20% of train.
```

#### to_absolute[[datasets.ReadInstruction.to_absolute]]

```python
to_absolute(name2len)
```

[源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/arrow_reader.py#L608)

**参数：**

name2len (`dict`) : 将拆分名称映射到示例数量。

**返回：**

AbsoluteInstruction 实例的列表（对应于规范中的 +）。

将翻译指令转换为绝对指令列表。

然后，将这些绝对指令相加。

## 版本[[datasets.Version]]

#### datasets.Version[[datasets.Version]]

```python
datasets.Version(version_str: str, description: typing.Optional[str] = None, major: typing.Union[str, int, NoneType] = None, minor: typing.Union[str, int, NoneType] = None, patch: typing.Union[str, int, NoneType] = None)
```

[源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/utils/version.py#L30)

**参数：**

version_str (`str`) : 数据集版本。

description (`str`) : 此版本新增内容的描述。

major (`str`) --

minor (`str`) --

patch (`str`) --

数据集版本 `MAJOR.MINOR.PATCH`。

示例：

```py
>>> VERSION = datasets.Version("1.0.0")
```