Hướng dẫn ra quyết định tải lên Dataset Hugging Face

Hướng dẫn này chủ yếu được thiết kế cho LLM để hỗ trợ người dùng tải lên các bộ dữ liệu lên Hugging Face Hub ở định dạng tương thích nhất. Người dùng cũng có thể tham khảo hướng dẫn này để hiểu quy trình tải lên và các thực hành tốt nhất.

Hướng dẫn ra quyết định khi tải lên bộ dữ liệu lên Hugging Face Hub. Được tối ưu hóa cho khả năng tương thích với Dataset Viewer và tích hợp với hệ sinh thái Hugging Face.

Nếu bạn là một LLM hoặc agent đang làm theo hướng dẫn này, hãy kiểm tra hf --help và hf <command> --help (ví dụ: hf upload --help, hf auth --help) để biết chính xác các cờ trước khi chạy các lệnh upload. CLI khớp với phiên bản huggingface_hub đã cài đặt, vì vậy hãy ưu tiên sử dụng đầu ra của nó thay vì các cờ được nhớ lại từ bộ nhớ.

Tổng quan

Mục tiêu của bạn là hỗ trợ người dùng tải lên một bộ dữ liệu lên Hugging Face Hub. Lý tưởng nhất, bộ dữ liệu nên tương thích với Dataset Viewer (và do đó là hàm load_dataset) để đảm bảo khả năng truy cập và sử dụng dễ dàng. Bạn nên hướng tới việc đáp ứng các tiêu chí sau:

Làm việc Không Có Quyền Truy Cập Tệp

Khi bạn không có quyền truy cập trực tiếp vào tệp của người dùng (ví dụ: giao diện web), hãy yêu cầu người dùng chạy các lệnh này để hiểu về bộ dữ liệu của họ:

Cấu trúc bộ dữ liệu:

# Show directory tree (install with: pip install tree or brew install tree)
tree -L 3 --filelimit 20

# Alternative without tree:
find . -type f -name "*.csv" -o -name "*.json" -o -name "*.parquet" | head -20

Kiểm tra kích thước tệp:

# Total dataset size
du -sh .

# Individual file sizes
ls -lh data/

Xem trước định dạng dữ liệu:

# First few lines of CSV/JSON
head -n 5 data/train.csv

# Check image folder structure
ls -la images/ | head -10

Đếm nhanh tệp:

# Count files by type
find . -name "*.jpg" | wc -l

Ràng buộc quan trọng

Hạn mức lưu trữ:

Nếu các giá trị này khác với storage-limits, thì storage-limits là giá trị chính xác.

# Machine-readable Hub limits
hub_limits:
  max_file_size_gb: 500 # absolute hard stop per file
  recommended_file_size_gb: 200 # split larger files into chunks below this
  max_files_per_folder: 10000 # Git performance threshold
  max_files_per_repo: 100000 # recommended maximum; keep well below
  viewer_row_size_mb: 2 # approximate per-row viewer limit
  # No per-repo size limit: repo size counts against the account's storage quota

Tóm tắt dễ đọc:

• Mỗi tệp: tối đa 500GB, khuyến nghị <200GB
• Mỗi thư mục: <10k tệp
• Mỗi kho: <100k tệp được khuyến nghị
• Bộ nhớ lưu trữ tài khoản (công khai và riêng tư) phụ thuộc vào gói: xem các gói lưu trữ

Xem https://huggingface.co/docs/hub/storage-limits để biết các gói lưu trữ hiện tại và khuyến nghị về kho lưu trữ.

Tham Khảo Nhanh Theo Kiểu Dữ Liệu

Quy trình tải lên

0. ✓ Thu thập thông tin bộ dữ liệu (nếu cần):

   • Loại dữ liệu nào? (ảnh, văn bản, âm thanh, CSV, v.v.)
   • Nó được tổ chức như thế nào? (cấu trúc thư mục, một tệp duy nhất, nhiều tệp)
   • Kích thước xấp xỉ là bao nhiêu?
   • Các tệp ở định dạng nào?
   • Có yêu cầu đặc biệt nào không? (ví dụ: streaming, truy cập riêng tư)
   • Kiểm tra các tệp README hoặc tài liệu hiện có mô tả bộ dữ liệu

1. ✓ Xác thực:

   • CLI: hf auth login
   • Hoặc sử dụng token: HfApi(token="hf_...") hoặc đặt biến môi trường HF_TOKEN

2. ✓ Xác định kiểu dữ liệu của bạn: Kiểm tra bảng Tham khảo nhanh ở trên

3. ✓ Chọn phương thức tải lên:

   • Các tệp nhỏ (<1GB) có định dạng tương thích với hub: Có thể sử dụng Hub UI để tải lên nhanh
   • Trình tải tích hợp khả dụng: Sử dụng trình tải + push_to_hub() (xem bảng Tham khảo nhanh)
   • Dữ liệu lớn hoặc nhiều tệp: Sử dụng upload_folder / hf upload để xử lý các lần tải lên lớn (tự động nhiều commit, có thể tiếp tục).
   • Định dạng tùy chỉnh: Chuyển đổi sang định dạng tương thích với hub nếu có thể, nếu không thì tài liệu hóa kỹ lưỡng

4. ✓ Thử nghiệm cục bộ (nếu dùng trình nạp tích hợp):

   Đã sao chép

   # Validate your dataset loads correctly before uploading
   dataset = load_dataset("loader_name", data_dir="./your_data")
   print(dataset)

5. ✓ Tải lên Hub:

   Đã sao chép

   # Basic upload
   dataset.push_to_hub("username/dataset-name")
   
   # With options for large datasets
   dataset.push_to_hub(
       "username/dataset-name",
       max_shard_size="5GB",  # Control memory usage
       private=True  # For private datasets
   )

6. ✓ Xác minh tệp đã tải lên:

   • Kiểm tra Dataset Viewer: https://huggingface.co/datasets/username/dataset-name
   • Kiểm tra việc tải: load_dataset("username/dataset-name")
   • Nếu trình xem hiển thị lỗi, hãy kiểm tra phần Khắc phục sự cố

Các mẫu chuyển đổi phổ biến

Khi bộ nạp tích hợp không khớp với cấu trúc dữ liệu của bạn, hãy sử dụng thư viện datasets như một lớp tương thích. Chuyển đổi dữ liệu của bạn thành một đối tượng Dataset, sau đó sử dụng push_to_hub() để có tính linh hoạt tối đa và khả năng tương thích với Dataset Viewer.

Từ DataFrames

Nếu bạn đã có dữ liệu hoạt động trong pandas, polars hoặc các thư viện dataframe khác, bạn có thể chuyển đổi trực tiếp:

# From pandas DataFrame
import pandas as pd
from datasets import Dataset

df = pd.read_csv("your_data.csv")
dataset = Dataset.from_pandas(df)
dataset.push_to_hub("username/dataset-name")

# From polars DataFrame (direct method)
import polars as pl
from datasets import Dataset

df = pl.read_csv("your_data.csv")
dataset = Dataset.from_polars(df)  # Direct conversion
dataset.push_to_hub("username/dataset-name")

# From PyArrow Table (useful for scientific data)
import pyarrow as pa
from datasets import Dataset

# If you have a PyArrow table
table = pa.table({'data': [1, 2, 3], 'labels': ['a', 'b', 'c']})
dataset = Dataset(table)
dataset.push_to_hub("username/dataset-name")

# For Spark/Dask dataframes, see https://huggingface.co/docs/hub/datasets-libraries

Chuyển đổi Định dạng Tùy chỉnh

Khi trình nạp tích hợp không khớp với định dạng dữ liệu của bạn, hãy chuyển đổi sang các đối tượng Dataset theo các nguyên tắc sau:

Nguyên tắc thiết kế

1. Ưu tiên cấu trúc rộng/phẳng hơn là các phép nối

• Biến đổi dữ liệu quan hệ thành các dòng đơn lẻ để dễ sử dụng hơn
• Bao gồm tất cả thông tin liên quan trong mỗi ví dụ
• Ưu tiên dữ liệu lớn hơn nhưng dễ sử dụng hơn - hạ tầng của Hugging Face sử dụng khử trùng lặp tiên tiến (XetHub) và tối ưu hóa Parquet để xử lý sự dư thừa một cách hiệu quả

2. Sử dụng configs cho các biến thể logic của dataset

• Ngoài việc chia dữ liệu thành tập huấn luyện/kiểm định/xác thực, hãy sử dụng các cấu hình cho các tập con hoặc góc nhìn khác nhau của dữ liệu của bạn
• Mỗi cấu hình có thể có các tính năng hoặc cách tổ chức dữ liệu khác nhau
• Ví dụ: cấu hình theo ngôn ngữ, chế độ xem theo tác vụ, hoặc các phương thức dữ liệu

Các phương pháp chuyển đổi

Dữ liệu nhỏ (vừa trong bộ nhớ) - sử dụng Dataset.from_dict():

# Parse your custom format into a dictionary
data_dict = {
    "text": ["example1", "example2"],
    "label": ["positive", "negative"],
    "score": [0.9, 0.2]
}

# Create dataset with appropriate features
from datasets import Dataset, Features, Value, ClassLabel
features = Features({
    'text': Value('string'),
    'label': ClassLabel(names=['negative', 'positive']),
    'score': Value('float32')
})

dataset = Dataset.from_dict(data_dict, features=features)
dataset.push_to_hub("username/dataset")

Dữ liệu lớn (tiết kiệm bộ nhớ) - sử dụng Dataset.from_generator():

def data_generator():
    # Parse your custom format progressively
    for item in parse_large_file("data.custom"):
        yield {
            "text": item["content"],
            "label": item["category"],
            "embedding": item["vector"]
        }

# Specify features for Dataset Viewer compatibility
from datasets import Features, Value, ClassLabel, List
features = Features({
    'text': Value('string'),
    'label': ClassLabel(names=['cat1', 'cat2', 'cat3']),
    'embedding': List(feature=Value('float32'), length=768)
})

dataset = Dataset.from_generator(data_generator, features=features)
dataset.push_to_hub("username/dataset", max_shard_size="1GB")

Mẹo: Với các bộ dữ liệu lớn, hãy thử nghiệm trước với một tập con bằng cách thêm giới hạn vào trình tạo của bạn hoặc sử dụng .select(range(100)) sau khi tạo.

Sử dụng Configs cho các biến thể của Dataset

# Push different configurations of your dataset
dataset_en = Dataset.from_dict(english_data, features=features)
dataset_en.push_to_hub("username/multilingual-dataset", config_name="english")

dataset_fr = Dataset.from_dict(french_data, features=features)
dataset_fr.push_to_hub("username/multilingual-dataset", config_name="french")

# Users can then load specific configs
dataset = load_dataset("username/multilingual-dataset", "english")

Ví dụ đa phương thức

Văn bản + Âm thanh (nhận dạng giọng nói):

def speech_generator():
    for audio_file in Path("audio/").glob("*.wav"):
        transcript_file = audio_file.with_suffix(".txt")
        yield {
            "audio": str(audio_file),
            "text": transcript_file.read_text().strip(),
            "speaker_id": audio_file.stem.split("_")[0]
        }

features = Features({
    'audio': Audio(sampling_rate=16000),
    'text': Value('string'),
    'speaker_id': Value('string')
})

dataset = Dataset.from_generator(speech_generator, features=features)
dataset.push_to_hub("username/speech-dataset")

Nhiều hình ảnh cho mỗi ví dụ:

# Before/after images, medical imaging, etc.
data = {
    "image_before": ["img1_before.jpg", "img2_before.jpg"],
    "image_after": ["img1_after.jpg", "img2_after.jpg"],
    "treatment": ["method_A", "method_B"]
}

features = Features({
    'image_before': Image(),
    'image_after': Image(),
    'treatment': ClassLabel(names=['method_A', 'method_B'])
})

dataset = Dataset.from_dict(data, features=features)
dataset.push_to_hub("username/before-after-images")

Lưu ý: Đối với văn bản + hình ảnh, hãy cân nhắc sử dụng ImageFolder với metadata.csv, công cụ này sẽ xử lý tự động.

Các tính năng thiết yếu

Features xác định schema và kiểu dữ liệu cho các cột trong dataset của bạn. Việc chỉ định đúng features đảm bảo:

• Xử lý dữ liệu và chuyển đổi kiểu dữ liệu đúng cách
• Chức năng của Dataset Viewer (ví dụ: xem trước hình ảnh/âm thanh)
• Lưu trữ và nạp hiệu quả
• Tài liệu rõ ràng về cấu trúc dữ liệu của bạn

Để xem tài liệu đầy đủ về các tính năng, hãy xem: Tính năng của Dataset

Tổng quan về các loại tính năng

Các kiểu dữ liệu cơ bản:

• Value: Các giá trị vô hướng - string, int64, float32, bool, binary và các kiểu số khác
• ClassLabel: Dữ liệu phân loại với các lớp có tên
• Sequence: Danh sách của bất kỳ loại đặc trưng nào
• LargeList: Dành cho các danh sách rất lớn

Các loại phương tiện (bật xem trước Dataset Viewer):

• Image(): Xử lý các định dạng ảnh khác nhau, trả về các đối tượng PIL Image
• Audio(sampling_rate=16000): Audio với dữ liệu mảng và tần số lấy mẫu tùy chọn
• Video(): Tệp video
• Pdf(): Tài liệu PDF với trích xuất văn bản

Các kiểu mảng (cho tensor/dữ liệu khoa học):

• Array2D, Array3D, Array4D, Array5D: Mảng có độ dài cố định hoặc thay đổi
• Ví dụ: Array2D(shape=(224, 224), dtype='float32')
• Chiều đầu tiên có thể là None cho độ dài thay đổi

Các loại dịch:

• Translation: Đối với các cặp ngôn ngữ dịch cố định
• TranslationVariableLanguages: Đối với các bản dịch có cặp ngôn ngữ thay đổi

Lưu ý: Các loại tính năng mới được thêm vào thường xuyên. Hãy kiểm tra tài liệu để biết các bổ sung mới nhất.

Phương thức tải lên

Đối tượng Dataset (sử dụng push_to_hub): Sử dụng khi bạn đã tải/chuyển đổi dữ liệu bằng thư viện datasets

dataset.push_to_hub("username/dataset", max_shard_size="5GB")

Các tệp có sẵn (dùng upload_folder / hf upload): Dùng khi bạn đã chuẩn bị và sắp xếp sẵn các tệp tương thích với hub (ví dụ: tệp Parquet).

from huggingface_hub import HfApi
api = HfApi()
api.upload_folder(folder_path="./data", repo_id="username/dataset", repo_type="dataset")

# Or from the CLI:
hf upload username/dataset ./data --repo-type=dataset

Quan trọng: Trước khi tải lên, hãy xác minh các tệp đáp ứng giới hạn của kho:

• Kiểm tra cấu trúc thư mục nếu bạn có quyền truy cập tệp: đảm bảo không có thư mục nào chứa >10k tệp
• Yêu cầu người dùng xác nhận: “Các tệp của bạn có ở định dạng tương thích với hub (Parquet/CSV/JSON) và được tổ chức hợp lý không?”
• Đối với các định dạng không chuẩn, hãy cân nhắc chuyển đổi sang các đối tượng Dataset trước để đảm bảo tính tương thích

Kiểm tra

Cân nhắc định dạng lại nhỏ: Nếu dữ liệu gần với định dạng của trình tải tích hợp, hãy đề xuất các thay đổi nhỏ:

• Đổi tên các cột (ví dụ: ‘filename’ → ‘file_name’ cho ImageFolder)
• Tổ chức lại các thư mục (ví dụ: di chuyển hình ảnh vào các thư mục con của lớp)
• Đổi tên tệp để khớp với các mẫu mong đợi (ví dụ: ‘data.csv’ → ‘train.csv’)

Trước khi tải lên:

• Kiểm tra cục bộ: load_dataset("imagefolder", data_dir="./data")

• Kiểm tra các tính năng hoạt động chính xác:

  Đã sao chép

  # Test first example
  print(dataset[0])
  
  # For images: verify they load
  if 'image' in dataset.features:
      dataset[0]['image']  # Should return PIL Image
  
  # Check dataset size before upload
  print(f"Size: {len(dataset)} examples")

• Kiểm tra xem metadata.csv có cột ‘file_name’

• Xác minh các đường dẫn tương đối, không có dấu gạch chéo ở đầu

• Đảm bảo không có thư mục nào chứa >10k tệp

Sau khi tải lên:

• Kiểm tra trình xem: https://huggingface.co/datasets/username/dataset
• Kiểm tra việc tải: load_dataset("username/dataset")
• Xác nhận các đặc trưng được bảo toàn: print(dataset.features)

Các vấn đề thường gặp → Giải pháp

Cấu hình Dataset Viewer

Lưu ý: Phần này chủ yếu dành cho các bộ dữ liệu được tải lên Hub trực tiếp (thông qua giao diện người dùng, upload_folder hoặc hf upload). Các bộ dữ liệu được tải lên bằng push_to_hub() thường tự động cấu hình trình xem.

Khi phát hiện tự động hoạt động

Dataset Viewer tự động phát hiện các cấu trúc chuẩn:

• Các tệp có tên: train.csv, test.json, validation.parquet
• Các thư mục có tên: train/, test/, validation/
• Tách tên bằng các ký tự phân cách: test-data.csv ✓ (không dùng testdata.csv ✗)

Cấu hình thủ công

Đối với các cấu trúc tùy chỉnh, hãy thêm YAML vào README.md của bạn:

---
configs:
  - config_name: default # Required even for single config!
    data_files:
      - split: train
        path: "data/train/*.parquet"
      - split: test
        path: "data/test/*.parquet"
---

Ví dụ về nhiều cấu hình:

---
configs:
  - config_name: english
    data_files: "en/*.parquet"
  - config_name: french
    data_files: "fr/*.parquet"
---

Các sự cố thường gặp của trình xem

• Không có trình xem sau khi tải lên: Chờ 5-10 phút để xử lý
• Lỗi “Config names”: Thêm trường config_name (bắt buộc!)
• Không phát hiện tệp: Kiểm tra các mẫu đặt tên (cần có ký tự phân cách)
• Trình xem bị vô hiệu hóa: Xóa viewer: false khỏi README YAML

Mẫu nhanh

# ImageFolder with metadata
dataset = load_dataset("imagefolder", data_dir="./images")
dataset.push_to_hub("username/dataset")

# Memory-efficient upload
dataset.push_to_hub("username/dataset", max_shard_size="500MB")

# Multiple CSV files
dataset = load_dataset('csv', data_files={'train': 'train.csv', 'test': 'test.csv'})
dataset.push_to_hub("username/dataset")

Tài liệu

Tài liệu chính: Thêm bộ dữ liệu | Trình xem bộ dữ liệu | Giới hạn lưu trữ | Hướng dẫn tải lên

Thẻ Dữ liệu

Nhắc người dùng thêm thẻ dữ liệu (README.md) với:

• Mô tả và cách sử dụng bộ dữ liệu
• Thông tin giấy phép
• Chi tiết trích dẫn

Xem hướng dẫn Dataset Cards để biết thêm chi tiết.

Phụ lục: Các trường hợp đặc biệt

Cấu trúc WebDataset

Để phát trực tiếp các bộ dữ liệu phương tiện lớn:

• Tạo các shard tar 1-5GB
• Cấu trúc bên trong nhất quán
• Tải lên bằng hf upload

Dữ liệu Khoa học

• HDF5/NetCDF → Chuyển đổi sang Parquet với các tính năng mảng
• Chuỗi thời gian → Array2D(shape=(None, n))
• Metadata phức tạp → Lưu dưới dạng chuỗi JSON

Tài nguyên Cộng đồng

Đối với các định dạng rất chuyên biệt hoặc được thiết kế riêng:

• Tìm kiếm các bộ dữ liệu tương tự trên Hub: https://huggingface.co/datasets
• Yêu cầu tư vấn trên Diễn đàn Hugging Face
• Tham gia Hugging Face Discord để nhận hỗ trợ theo thời gian thực
• Nhiều định dạng chuyên ngành đã có sẵn các ví dụ trên Hub