数据集文档

使用 CLI 分享数据集

Hugging Face's logo
加入 Hugging Face 社区

并获得增强的文档体验

开始使用

使用 CLI 分享数据集

在 Hugging Face,我们的使命是普及良好的机器学习,并且我们坚信开源的价值。因此,我们设计了 🤗 Datasets,以便任何人都可以与更广泛的 ML 社区分享数据集。在 Hugging Face Hub 中,目前有数千个数据集,超过 100 种语言,Hugging Face 团队始终欢迎新的贡献!

数据集仓库提供以下功能,例如

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

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

添加数据集

您可以使用 Hugging Face Hub 上的数据集仓库与社区分享您的数据集。如果您想控制谁可以访问您的数据集,它也可以是私有数据集。

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

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

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

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

创建仓库

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

  1. 确保您位于安装了 Datasets 的虚拟环境中,并运行以下命令
huggingface-cli login
  1. 使用您的 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 upload

使用 huggingface-cli upload 命令直接将文件上传到 Hub。在内部,它使用与上传指南中描述的相同的 upload_fileupload_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 文件来同步本地 Space

# 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 上更新