使用 CLI 分享数据集

在 Hugging Face，我们的使命是使优秀的机器学习民主化，我们相信开源的价值。因此，我们设计了 🤗 数据集，以便任何人都可以与更广泛的机器学习社区分享数据集。Hugging Face Hub 目前拥有数千个超过 100 种语言的数据集，Hugging Face 团队始终欢迎新的贡献！

数据集仓库提供以下功能

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

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

添加数据集

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

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

另一方面，如果您的数据集不是受支持的格式，或者如果您希望更详细地控制数据集的加载方式，您可以编写自己的数据集脚本。请注意，对于使用加载脚本定义的数据集，某些功能不可用，例如数据集查看器。用户还必须传递trust_remote_code=True才能加载数据集。通常建议数据集尽可能不依赖于加载脚本，以利用 Hub 的所有功能。

从 Hub 加载数据集时，会加载所有受支持格式的文件，遵循仓库结构。但是，如果存在数据集脚本，则会下载并执行该脚本以代替下载和准备数据集。

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

创建仓库

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

确保您位于安装了 Datasets 的虚拟环境中，并运行以下命令

huggingface-cli login

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

huggingface-cli repo create my-cool-dataset --type dataset

添加-organization标志以在特定组织下创建仓库

huggingface-cli repo create my-cool-dataset --type dataset --organization your-org-name

准备您的文件

检查您的目录以确保您要上传的唯一文件是

数据集的数据文件
数据集卡片README.md
（可选）your_dataset_name.py是您的数据集加载脚本（如果您的数据文件已采用受支持的格式 csv/jsonl/json/parquet/txt，则可选）。要创建数据集脚本，请参阅数据集脚本页面。请注意，对于使用加载脚本定义的数据集，某些功能不可用，例如数据集查看器。用户还必须传递trust_remote_code=True才能加载数据集。通常建议数据集尽可能不依赖于加载脚本，以利用 Hub 的所有功能。

huggingface-cli 上传

使用huggingface-cli upload命令直接将文件上传到 Hub。在内部，它使用上传指南中描述的相同的upload_file和upload_folder帮助程序。在下面的示例中，我们将逐步介绍最常见的用例。有关可用选项的完整列表，您可以运行

>>> huggingface-cli upload --help

有关huggingface-cli的更多一般信息，您可以查看CLI 指南。

上传整个文件夹

此命令的默认用法是

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

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

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

您还可以上传特定文件夹

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

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

>>> huggingface-cli 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是可选的，并将默认为您本地文件的名称

>>> huggingface-cli 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

>>> huggingface-cli 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 文件来同步本地空间

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

上传到组织

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

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

上传到特定版本

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

# Upload files to a PR
huggingface-cli 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
>>> huggingface-cli 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
huggingface-cli upload my-cool-dynamic-dataset data/ --every=10

指定提交消息

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

>>> huggingface-cli 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

指定令牌

要上传文件，您必须使用令牌。默认情况下，将使用本地保存的令牌（使用huggingface-cli login）。如果要显式认证，请使用--token选项

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

静默模式

默认情况下，huggingface-cli upload命令将非常详细。它将打印详细信息，例如警告消息、上传文件的信息和进度条。如果要静默所有这些，请使用--quiet选项。仅打印最后一行（即上传文件的URL）。如果您想在脚本中将输出传递给另一个命令，这将非常有用。

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

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

最后，不要忘记丰富数据集卡片以记录您的数据集并使其可被发现！查看创建数据集卡片指南以了解更多信息。

< > 在GitHub上更新