Hugging Face's logo

Hub 文件

函式庫

Hugging Face's logo
加入 Hugging Face 社群

並獲得增強的文件體驗

開始使用

函式庫

Datasets Hub 已支援開源生態系統中的多個函式庫。感謝 huggingface_hub Python 函式庫，讓您能輕鬆地在 Hub 上分享資料集。我們很高興能歡迎這套推動機器學習前進的開源函式庫加入 Hub。

函式庫列表

下表摘要列出了支援的函式庫及其整合程度。

程式庫 說明 從 Hub 下載 從 Hub 串流 推送到 Hub 串流至 Hub 最佳化的 Parquet 檔案
Argilla 為重視高品質數據的 AI 工程師和領域專家設計的協作工具。 ✅ ❌ ✅ ❌ ❌
Daft 適用於大規模、多模態資料處理的資料引擎，具備 Python 原生介面。 ✅ ✅ ✅ ✅ ✅
Dask 平行與分佈式計算函式庫，可擴展現有的 Python 與 PyData 生態系統。 ✅ ✅ ✅ ✅ ✅*
Data Designer NVIDIA NeMo 框架，用於使用 LLM 生成合成資料集。 ✅ ❌ ✅ ❌ ❌
資料集 (Datasets) 🤗 Datasets 是一個用於存取和分享音訊、電腦視覺與自然語言處理 (NLP) 資料集的函式庫。 ✅ ✅ ✅ ✅ ✅
Distilabel 用於合成資料生成與 AI 反饋的框架。 ✅ ❌ ✅ ❌ ❌
DuckDB 進程內 (In-process) SQL OLAP 資料庫管理系統。 ✅ ✅ ❌ ❌ ❌
Embedding Atlas 用於大規模嵌入 (embeddings) 的互動式視覺化與探索工具。 ✅ ✅ ❌ ❌ ❌
Fenic 受 PySpark 啟發的 DataFrame 框架，用於構建生產級 AI 與代理 (agentic) 應用程式。 ✅ ✅ ❌ ❌ ❌
FiftyOne FiftyOne 是一個用於策劃與視覺化圖像、影片及 3D 資料的函式庫。 ✅ ✅ ✅ ❌ ❌
Lance 為多模態 AI 設計的開放湖倉 (lakehouse) 格式。 ✅ ✅ ❌ ❌ ❌
Pandas Python 資料分析工具包。 ✅ ❌ ✅ ❌ ✅*
Polars 基於 OLAP 查詢引擎的 DataFrame 函式庫。 ✅ ✅ ✅ ❌ ❌
PyArrow Apache Arrow 是一種欄式格式，也是一個用於快速資料交換和記憶體內分析的工具箱。 ✅ ✅ ✅ ❌ ✅*
Spark 分佈式環境中的即時、大規模資料處理工具。 ✅ ✅ ✅ ✅ ✅
WebDataset 為大型資料集編寫 I/O 管線的函式庫。 ✅ ✅ ❌ ❌ ❌

* 需要傳遞額外參數以寫入最佳化的 Parquet 檔案

資料處理函式庫

串流 (Streaming)

資料集串流允許從 Hugging Face 逐步迭代資料集，而無需完整下載。由於資料不會保留在硬碟上，因此節省了本地硬碟空間。因為一次僅使用資料集的一小部分，所以節省了記憶體。同時這也節省了時間，因為在啟動 CPU 或 GPU 工作負載之前不需要下載所有資料。

除了*從* Hugging Face 串流外，許多函式庫也支援*回傳串流*至 Hugging Face。因此，它們可以執行端到端的串流管線：從來源串流並逐步寫入 Hugging Face，下載、上傳與處理步驟通常會重疊進行。

有關如何進行串流的更多詳細資訊，請查看支援串流的函式庫文檔（見上表），或者如果您想自行從 Hugging Face 串流資料集，請參閱串流資料集文檔。

最佳化的 Parquet 檔案

Hugging Face 上的 Parquet 檔案經過最佳化，可提高儲存效率、加速上傳下載，並實現高效的資料集串流與編輯。

最佳化的 Parquet 檔案是具備額外功能的 Parquet 檔案

某些函式庫（如 Pandas 和 PyArrow）需要額外參數才能寫入最佳化的 Parquet 檔案

  • use_content_defined_chunking=True 用於啟用 Parquet 內容定義切分，以便進行 去重 與 編輯
  • write_page_index=True 用於在 Parquet 元數據中包含頁面索引，以便進行 串流與隨機存取

訓練函式庫

與 Hub 資料集整合用於模型訓練的訓練函式庫。下表顯示了它們的串流能力——即在不預先下載資料集的情況下進行訓練的能力。

程式庫 說明 從 Hub 串流
Axolotl 低程式碼 LLM 微調框架 ✅
LlamaFactory 支援 100+ 種 LLM 的統一微調 ✅
Sentence Transformers 文字嵌入與語義相似度 ✅
Transformers 🤗 Transformers Trainer 用於微調模型 ✅
TRL 使用強化學習 (SFT, DPO, GRPO) 訓練 LLM ⚠️*
Unsloth 快速 LLM 微調 (速度提升 2 倍，記憶體減少 70%) ✅

* SFTTrainer 和 DPOTrainer 支援串流；GRPOTrainer 尚不支援串流輸入

從 Hub 串流

串流允許在不預先下載的情況下對海量資料集進行訓練。這在以下情況非常寶貴：

  • 資料集太大，無法完整放入硬碟
  • 您希望立即開始訓練
  • 您正在使用 HF Jobs，其中主機共置 (co-located compute) 提供更快的串流速度

最近的改進使串流效率提升了最高 100 倍，具備更快的啟動速度、預取功能，以及更出色的多 worker 擴展能力。

注意：由於資料集長度未知，串流需要在訓練參數中設定 max_steps，並使用基於緩衝區的打亂 (shuffling)。詳情請參閱 串流資料集。

記錄至 Hub

某些工具可以在訓練期間將訓練數據實時串流回 Hub

  • Trackio：即時將訓練指標串流至 Hub 資料集

將資料函式庫與工具與 Hub 整合

本指南專為希望與 Hugging Face Hub 整合的資料函式庫和工具開發者與維護者設計。無論您是在構建資料處理函式庫、分析工具，還是任何需要與資料集互動的軟體，本文件都將幫助您實現 Hub 整合。

本指南內容涵蓋：

  • 將資料從 Hub 載入到您的函式庫/工具中的可能方法
  • 將資料從您的函式庫/工具上傳到 Hub 的可能方法

從 Hub 載入資料

如果您擁有一個處理資料的函式庫，讓使用者能從 Hub 載入資料將非常有幫助。

一般來說，我們建議依靠現有的函式庫如 datasets、pandas 或 polars 來完成這項工作，除非您有特定原因需要自行實作。如果您需要對載入過程有更多的控制，可以使用 huggingface_hub 函式庫，例如它允許您從儲存庫中下載特定的檔案子集。

您可以在這裡找到更多關於從 Hub 載入資料的資訊。

透過 Dataset Viewer 與 Parquet 檔案整合

Hub 的資料集檢視器 (dataset viewer) 與 Parquet 轉換系統提供了一種標準化的方式來與資料集整合，無論其原始格式為何。該基礎設施是 Hub 與外部函式庫之間可靠的整合層。

如果資料集尚未採用 Parquet 格式，Hub 會自動將每個資料集的前 5GB 轉換為 Parquet 格式，以驅動資料集檢視器並提供一致的存取模式。這種標準化為函式庫整合帶來了幾項好處：

  • 無論原始格式為何，均有一致的資料存取模式
  • 透過 Hub 的資料集檢視器內建資料集預覽與探索功能。資料集檢視器也可以作為 iframe 嵌入到您的應用程式中，從而輕鬆提供豐富的資料集預覽。有關嵌入檢視器的更多資訊，請參閱 資料集檢視器嵌入文件。
  • 針對查詢進行最佳化的高效欄式儲存。例如，您可以使用像 DuckDB 這樣的工具來查詢或過濾特定的資料子集。
  • Parquet 在機器學習與資料科學生態系統中得到了廣泛支援。

有關使用 Dataset Viewer API 的更多詳細資訊，請參閱 Dataset Viewer API 文檔

將資料上傳至 Hub

本節介紹了在您的函式庫中加入將資料上傳到 Hub 的功能的可能方法，即如何實作 push_to_hub 方法。

本指南將介紹三種將資料上傳到 Hub 的主要方式：

  • 使用 datasets 函式庫和 push_to_hub 方法
  • 使用 pandas 寫入 Hub
  • 使用 huggingface_hub 函式庫和 hf_hub_download 方法
  • 直接使用 API 或 Git 以及 git-xet

使用 datasets 函式庫

將資料推送到 Hub 最簡單的方法是依靠 datasets 函式庫現有的 push_to_hub 方法。push_to_hub 方法會自動處理：

  • 儲存庫的創建
  • 將資料集轉換為 Parquet 格式
  • 將資料集分割成適當的區塊
  • 上傳資料

例如，如果您有一個回傳字典清單的合成資料生成函式庫，您可以簡單地執行以下操作

from datasets import Dataset

data = [{"prompt": "Write a cake recipe", "response": "Measure 1 cup ..."}]
ds = Dataset.from_list(data)
ds.push_to_hub("USERNAME_OR_ORG/repo_ID")

此類整合的範例

依靠現有函式庫與 Hub 的整合

Polars, Pandas, Dask, Spark, DuckDB 和 Daft 都可以寫入 Hugging Face Hub 儲存庫。詳見 資料集函式庫 了解更多細節。

如果您已經在程式碼中使用這些函式庫之一，那麼加入推送到 Hub 的功能非常簡單。例如，如果您有一個可以回傳 Pandas DataFrame 的合成資料生成函式庫，以下是寫入 Hub 所需的程式碼

from huggingface_hub import HfApi

# Initialize the Hub API
hf_api = HfApi(token=os.getenv("HF_TOKEN"))

# Create a repository (if it doesn't exist)
hf_api.create_repo(repo_id="username/my-dataset", repo_type="dataset")

# Convert your data to a DataFrame and save directly to the Hub
df.to_parquet("hf://datasets/username/my-dataset/data.parquet")

使用 huggingface_hub Python 函式庫

huggingface_hub Python 函式庫提供了一種更靈活的資料上傳方法。它允許您將特定檔案或檔案子集上傳到儲存庫。這在以下情況很有用：如果您有一個不想轉換為 Parquet 的大型資料集、只想上傳特定的檔案子集，或者想要對儲存庫結構有更多控制。

根據您的使用場景，您可以在程式碼的特定位置上傳檔案或資料夾，例如：當使用者點擊「推送至 Hub」時，將工具中的標註資料導出至 Hub。例如，

from huggingface_hub import HfApi
api = HfApi(token=HF_TOKEN)

api.upload_folder(
    folder_path="/my-cool-library/data-folder",
    repo_id="username/my-cool-space",
    repo_type="dataset",
    commit_message="Push annotations to Hub"
    allow_patterns="*.jsonl",
)

您可以在這裡找到更多關於上傳資料至 Hub 的方法。

另外，在某些情況下您可能希望在背景上傳資料，例如每 10 分鐘生成的合成資料。在這種情況下，您可以使用 huggingface_hub 函式庫的 scheduled_uploads (定時上傳) 功能。更多詳情請參閱 定時上傳文件。

您可以在以下項目中看到使用此方法上傳資料到 Hub 的範例：

更多支援

有關整合的技術問題，歡迎聯繫 datasets 團隊：datasets@huggingface.co。

在 GitHub 上更新

←串流資料集 Argilla→
© . This site is unofficial and not affiliated with Hugging Face, Inc.