使用 CLI 分享数据集

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

数据集存储库提供以下功能：

免费数据集托管
数据集版本控制
提交历史记录和差异对比
用于提高可发现性的元数据
用于记录文档、许可协议、局限性等信息的数据集卡片（Dataset cards）
数据集查看器

本指南将向您展示如何分享一个可供任何人轻松访问的数据集文件夹或存储库。

添加数据集

您可以通过在 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 的虚拟环境中，然后运行以下命令：

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

huggingface-cli upload

使用 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（Pull Request），让作者了解您想要进行的更改。这可以通过设置 --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

指定令牌（Token）

要上传文件，必须使用令牌。默认情况下，将使用本地保存的令牌（通过 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")

如果您的数据集受支持，它还应该具有数据集查看器（Dataset Viewer），供所有人浏览数据集内容。

最后，别忘了完善数据集卡片来记录您的数据集并使其更易于被发现！查看创建数据集卡片指南以了解更多信息。

在 GitHub 上更新