使用 CLI 分享資料集

在 Hugging Face，我們的使命是讓優質的機器學習普及化，且我們堅信開源的價值。因此，我們設計了 🤗 Datasets，讓任何人都能與廣大的 ML 社群分享資料集。目前，Hugging Face Hub 上已有數千個、涵蓋超過 100 種語言的資料集，Hugging Face 團隊隨時歡迎新的貢獻！

資料集儲存庫提供以下功能：

免費的資料集託管
資料集版本控制
提交記錄與差異比對 (Diffs)
用於提高可發現性的元資料 (Metadata)
用於文件、授權、限制說明等的資料集卡片 (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，讓作者知道您想要進行的變更。這可以透過設定 --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

若要上傳檔案，您必須使用 Token。預設情況下，會使用儲存在本機（透過 huggingface-cli login）的 Token。如果您想要明確進行驗證，請使用 --token 選項

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

安靜模式 (Quiet mode)

預設情況下，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 上更新

資料集 (Datasets)

使用 CLI 分享資料集

新增資料集

建立儲存庫

準備您的檔案

huggingface-cli upload

上傳整個資料夾

上傳單一檔案

上傳多個檔案

上傳至組織

上傳至特定修訂版本

上傳並建立 PR

定期上傳

指定提交訊息

指定 Token

安靜模式 (Quiet mode)

享受吧！