使用 CLI 共享数据集

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

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

免费数据集托管
数据集版本控制
提交历史记录和差异
用于可发现性的元数据
用于文档、许可、局限性等的数据集卡片
数据集查看器

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

添加数据集

您可以通过 Hugging Face Hub 上的数据集仓库与社区共享您的数据集。如果您希望控制谁可以访问该数据集，它也可以是一个私有数据集。

在数据集仓库中，你可以托管所有数据文件，并配置你的数据集以定义每个文件属于哪个 split。支持的格式包括：CSV、TSV、JSON、JSON lines、text、Parquet、Arrow、SQLite、WebDataset。还支持多种压缩文件类型：GZ、BZ2、LZ4、LZMA 或 ZSTD。例如，你的数据集可以由.json.gz文件组成。

从 Hub 加载数据集时，将按照仓库结构加载所有受支持格式的文件。

有关如何从 Hub 加载数据集的更多信息，请参阅从 Hub 加载数据集教程。

创建仓库

如果您还没有账号，共享社区数据集需要您在 hf.co 上创建一个账号。您可以直接在 Hugging Face Hub 的账户中创建新的数据集仓库，但本指南将向您展示如何从终端上传数据集。

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

hf auth login

使用您的 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。其内部使用了与上传指南中描述的 upload_file 和 upload_folder 相同的辅助函数。在下面的示例中，我们将介绍最常见的用例。要查看可用选项的完整列表，可以运行：

>>> hf upload --help

有关 hf 的更多通用信息，您可以查看 CLI 指南。

上传整个文件夹

此命令的默认用法为：

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

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

如果该仓库尚不存在，系统将自动创建它。

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

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

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

>>> 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 是可选的，默认值为你本地文件的名称：

>>> 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：

>>> 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：

# 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 中明确指定：

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

上传到特定版本

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

# 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 选项来实现：

# 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 选项来实现：

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

指定提交信息

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

>>> 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 选项：

>>> 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）。如果您希望在脚本中将输出传递给其他命令，这会非常有用。

>>> 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")

如果您的数据集受到支持，那么它也应该有一个数据集查看器，供所有人浏览数据集内容。

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

Update on GitHub