# 使用 CLI 共享数据集

在 Hugging Face，我们的使命是让优质的机器学习技术惠及大众，我们坚信开源的价值。正因如此，我们设计了 🤗 Datasets，让任何人都可以与更广泛的机器学习社区共享数据集。目前，Hugging Face Hub 上已有数千个数据集，涵盖 100 多种语言，Hugging Face 团队始终欢迎新的贡献！

数据集仓库提供以下功能：

- 免费数据集托管
- 数据集版本控制
- 提交历史记录和差异
- 用于可发现性的元数据
- 用于文档、许可、局限性等的数据集卡片
- [数据集查看器](https://huggingface.co/docs/hub/datasets-viewer)

本指南将向你展示如何共享一个数据集文件夹或仓库，以便任何人都可以轻松访问。

## 添加数据集

您可以通过 Hugging Face Hub 上的数据集仓库与社区共享您的数据集。如果您希望控制谁可以访问该数据集，也可以将其设置为私有数据集。

在数据集仓库中，您可以托管所有数据文件，并[配置您的数据集](./repository_structure#define-your-splits-and-subsets-in-yaml)以定义每个文件属于哪个拆分。支持的格式包括：CSV、TSV、JSON、JSON lines、文本、Parquet、Arrow、SQLite、WebDataset。还支持多种压缩文件类型：GZ、BZ2、LZ4、LZMA 或 ZSTD。例如，您的数据集可以由`.json.gz`文件组成。

从 Hub 加载数据集时，将按照[仓库结构](./repository_structure)加载所有受支持格式的文件。

有关如何从 Hub 加载数据集的更多信息，请参阅 [从 Hub 加载数据集](./load_hub) 教程。

### 创建仓库

若要共享社区数据集，如果您还没有账号，需要在 [hf.co](https://huggingface.co/join) 上创建一个账号。您可以直接在 Hugging Face Hub 的账号中创建 [新的数据集仓库](https://huggingface.co/login?next=%2Fnew-dataset)，但本指南将向您展示如何从终端上传数据集。

1. 请确保您处于安装 Datasets 的虚拟环境中，然后运行以下命令：

```
hf auth login
```

2. 使用您的 Hugging Face Hub 凭据登录，并创建一个新的数据集仓库：

```
hf repos create my-cool-dataset --type dataset
```

在仓库名称前加上组织名称，即可在该组织下创建仓库：

```
hf repos create your-org-name/my-cool-dataset --type dataset
```

## 准备您的文件

检查你的目录，确保你上传的文件只有：

- 数据集的数据文件

- 数据集卡片 `README.md`

## hf upload

使用 `hf upload` 命令可直接将文件上传到 Hub。其内部使用了与 [上传指南](https://huggingface.co/docs/huggingface_hub/guides/upload) 中描述的 `upload_file` 和 `upload_folder` 相同的辅助函数。在下面的示例中，我们将介绍最常见的用例。要查看可用选项的完整列表，可以运行：

```bash
>>> hf upload --help
```

有关 `hf` 的更多通用信息，您可以查看 [CLI 指南](https://huggingface.co/docs/huggingface_hub/guides/cli)。

### 上传整个文件夹

此命令的默认用法为：

```bash
# Usage:  hf upload [dataset_repo_id] [local_path] [path_in_repo] --repo-type dataset
```

要在仓库的根目录上传当前目录，请使用：

```bash
>>> hf upload my-cool-dataset . . --repo-type dataset
https://huggingface.co/datasets/Wauplin/my-cool-dataset/tree/main/
```

> [!TIP]
> 如果该仓库尚不存在，系统将自动创建它。

您也可以上传特定的文件夹：

```bash
>>> hf upload my-cool-dataset ./data . --repo-type dataset
https://huggingface.co/datasetsWauplin/my-cool-dataset/tree/main/
```

最后，您可以将文件夹上传到仓库中的特定位置：

```bash
>>> hf upload my-cool-dataset ./path/to/curated/data /data/train --repo-type dataset
https://huggingface.co/datasetsWauplin/my-cool-dataset/tree/main/data/train
```

### 上传单个文件

你还可以通过将 `local_path` 设置为指向本地机器上的文件来上传单个文件。在这种情况下，`path_in_repo` 是可选的，默认值为你本地文件的名称：

```bash
>>> hf upload Wauplin/my-cool-dataset ./files/train.csv --repo-type dataset
https://huggingface.co/datasetsWauplin/my-cool-dataset/blob/main/train.csv
```

如果要上传单个文件到特定目录，请相应地设置 `path_in_repo`：

```bash
>>> hf upload Wauplin/my-cool-dataset ./files/train.csv /data/train.csv --repo-type dataset
https://huggingface.co/datasetsWauplin/my-cool-dataset/blob/main/data/train.csv
```

### 上传多个文件

若要一次性从文件夹上传多个文件而不上传整个文件夹，请使用 `--include` 和 `--exclude` 模式。它还可以与 `--delete` 选项结合使用，在上传新文件的同时删除仓库中的文件。在下面的示例中，我们通过删除远程文件并上传所有 CSV 文件来同步本地 Space：

```bash
# Sync local Space with Hub (upload new CSV files, delete removed files)
>>> hf upload Wauplin/my-cool-dataset --repo-type dataset --include="/data/*.csv" --delete="*" --commit-message="Sync local dataset with Hub"
...
```

### 上传到组织

要将内容上传到组织拥有的仓库而非个人仓库，您必须在 `repo_id` 中明确指定：

```bash
>>> hf upload MyCoolOrganization/my-cool-dataset . . --repo-type dataset
https://huggingface.co/datasetsMyCoolOrganization/my-cool-dataset/tree/main/
```

### 上传到特定版本

默认情况下，文件会上传到 `main` 分支。如果您想将文件上传到其他分支或引用，请使用 `--revision` 选项：

```bash
# Upload files to a PR
hf upload bigcode/the-stack . . --repo-type dataset --revision refs/pr/104
...
```

**注意：**如果 `revision` 不存在且未设置 `--create-pr`，则会自动从 `main` 分支创建一个分支。

### 上传并创建 PR

如果您没有向仓库推送的权限，则必须打开一个 PR 并告知作者您想要进行的更改。您可以通过设置 `--create-pr` 选项来实现：

```bash
# Create a PR and upload the files to it
>>> hf upload bigcode/the-stack --repo-type dataset --revision refs/pr/104 --create-pr . .
https://huggingface.co/datasets/bigcode/the-stack/blob/refs%2Fpr%2F104/
```

### 定期上传

在某些情况下，您可能希望定期向仓库推送更新。例如，如果您的数据集随时间不断增长，并且希望每 10 分钟上传一次数据文件夹，这就会很有用。您可以使用 `--every` 选项来实现：

```bash
# Upload new logs every 10 minutes
hf upload my-cool-dynamic-dataset data/ --every=10
```

### 指定提交信息

使用 `--commit-message` 和 `--commit-description` 来为提交设置自定义消息和描述，而不是使用默认值

```bash
>>> hf upload Wauplin/my-cool-dataset ./data . --repo-type dataset --commit-message="Version 2" --commit-description="Train size: 4321. Check Dataset Viewer for more details."
...
https://huggingface.co/datasetsWauplin/my-cool-dataset/tree/main
```

### 指定一个标记

要上传文件，必须使用令牌。默认情况下，将使用本地保存的令牌（通过 `hf auth login` 保存）。若要显式进行身份验证，请使用 `--token` 选项：

```bash
>>> hf upload Wauplin/my-cool-dataset ./data . --repo-type dataset --token=hf_****
...
https://huggingface.co/datasetsWauplin/my-cool-data/tree/main
```

### 安静模式

默认情况下，`hf upload` 命令会输出详细信息，包括警告消息、已上传文件的信息以及进度条。如果您希望静默所有这些输出，请使用 `--quiet` 选项。此时仅会打印最后一行（即已上传文件的 URL）。如果您希望在脚本中将输出传递给其他命令，这会非常有用。

```bash
>>> hf upload Wauplin/my-cool-dataset ./data . --repo-type dataset --quiet
https://huggingface.co/datasets/Wauplin/my-cool-dataset/tree/main
```

## 尽情享用！

恭喜，您的数据集现已上传至 Hugging Face Hub，任何人都可以用一行代码加载它！🥳

```
dataset = load_dataset("Wauplin/my-cool-dataset")
```

如果您的数据集受到支持，那么它也应该有一个[数据集查看器](https://huggingface.co/docs/hub/datasets-viewer)，供所有人浏览数据集内容。

最后，别忘了丰富数据集卡片，以记录你的数据集并提高其可发现性！查看 [创建数据集卡片](dataset_card) 指南以了解更多信息。