# 缓存管理

从 Hugging Face 下载数据集时，数据会存储在您的计算机本地。来自 Hugging Face 的文件会像往常一样存储在 `huggingface_hub` 缓存中，其默认位置为 `~/.cache/huggingface/hub`。有关更多详细信息以及如何更改其位置，请参阅 [Hub 缓存文档](https://huggingface.co/docs/huggingface_hub/guides/manage-cache)。

Hub 缓存可让 🤗 Datasets 在每次使用时避免从 Hugging Face 重新下载数据集文件。

🤗 Datasets 还有自己的缓存，用于存储以 Arrow 格式（[Dataset](/docs/datasets/v5.2.0/zh/package_reference/main_classes#datasets.Dataset) 对象所使用的格式）转换后的数据集。

本指南专注于 🤗 Datasets 缓存，并将向您展示如何：

- 更改缓存目录。
- 控制数据集如何从缓存中加载。
- 清理目录中的缓存文件。
- 启用或禁用缓存。

## 缓存目录

默认的 🤗 Datasets 缓存目录是 `~/.cache/huggingface/datasets`。通过将 shell 环境变量 `HF_HOME` 设置为其他目录来更改缓存位置：

```
$ export HF_HOME="/path/to/another/directory"
```

或者，您可以设置 `HF_DATASETS_CACHE` 环境变量，以仅控制数据集专用的缓存目录：

```
$ export HF_DATASETS_CACHE="/path/to/datasets_cache"
```

⚠️ 此说明仅适用于由 `datasets` 库写入的文件（例如 Arrow 文件和索引）。它**不会**影响从 Hugging Face Hub 下载的文件（例如模型、分词器或原始数据集源），这些文件默认位于 `~/.cache/huggingface/hub`，并通过 `HF_HUB_CACHE` 变量单独控制：

```
$ export HF_HUB_CACHE="/path/to/hub_cache"
```

💡 如果您希望将所有 Hugging Face 缓存（包括数据集和 hub 下载）迁移到其他位置，请改用 `HF_HOME` 变量：

```
$ export HF_HOME="/path/to/cache_root"
```

这将导致：
- datasets 缓存 → `/path/to/cache_root/datasets`
- hub 缓存 → `/path/to/cache_root/hub`

这些区别在共享环境或网络文件系统（例如 NFS）中尤为有用。有关用户如何在未将 `HF_HUB_CACHE` 与 `HF_DATASETS_CACHE` 同时设置时遇到意外缓存位置的讨论，请参阅 [issue #7480](https://github.com/huggingface/datasets/issues/7480)。

加载数据集时，您还可以更改数据的缓存位置。将 `cache_dir` 参数更改为您想要的路径：

```py
>>> from datasets import load_dataset
>>> dataset = load_dataset('username/dataset', cache_dir="/path/to/another/directory/datasets")
```

## 下载模式

使用 `download_mode` 参数来控制 [load_dataset()](/docs/datasets/v5.2.0/zh/package_reference/loading_methods#datasets.load_dataset) 中已下载的源文件和已准备数据集的复用。默认情况下，🤗 Datasets 如果这些文件已存在，则会复用它们。若要重新下载源文件并重建数据集，请使用 `force_redownload`：

```py
>>> from datasets import load_dataset
>>> dataset = load_dataset('rajpurkar/squad', download_mode='force_redownload')
```

有关下载模式的完整列表，请参阅 [DownloadMode](/docs/datasets/v5.2.0/zh/package_reference/builder_classes#datasets.DownloadMode)。

## 缓存文件

使用 [Dataset.cleanup_cache_files()](/docs/datasets/v5.2.0/zh/package_reference/main_classes#datasets.Dataset.cleanup_cache_files) 清理该目录中的 Arrow 缓存文件：

```py
# Returns the number of removed cache files
>>> dataset.cleanup_cache_files()
2
```

## 启用或禁用缓存

如果您在本地使用缓存文件，系统将自动重新加载数据集，并应用您之前对该数据集所做的任何转换。通过在 [Dataset.map()](/docs/datasets/v5.2.0/zh/package_reference/main_classes#datasets.Dataset.map) 中设置参数 `load_from_cache_file=False` 可以禁用此行为：

```py
>>> updated_dataset = small_dataset.map(add_prefix, load_from_cache_file=False)
```

在上面的示例中，🤗 Datasets 将再次对整个数据集执行函数 `add_prefix`，而不是从数据集的先前状态加载它。

使用 [disable_caching()](/docs/datasets/v5.2.0/zh/package_reference/main_classes#datasets.disable_caching) 在全局范围内禁用缓存：

```py
>>> from datasets import disable_caching
>>> disable_caching()
```

禁用缓存后，🤗 Datasets 在对数据集应用转换时将不再重新加载缓存文件。您应用于数据集的任何转换都需要重新应用。

> [!TIP]
> 如果您想从头开始重新使用某个数据集，请尝试在 [load_dataset()](/docs/datasets/v5.2.0/zh/package_reference/loading_methods#datasets.load_dataset) 中设置 `download_mode` 参数。

## 提升性能

禁用缓存并在内存中复制数据集可以加快数据集操作的速度。在内存中复制数据集有两种方式：

1. 将 `datasets.config.IN_MEMORY_MAX_SIZE` 设置为一个非零值（以字节为单位），使其适合您的 RAM 内存。

2. 将环境变量 `HF_DATASETS_IN_MEMORY_MAX_SIZE` 设置为非零值。请注意，第一种方法的优先级更高。