Hugging Face Datasets: مرجع المطور

تمثل مجموعة بيانات Hugging Face مجموعة بيانات منظمة ومُدارة بالإصدارات، مخزَّنة على منصة Hugging Face Hub، ويتم استهلاكها عبر مكتبة بايثون datasets . وتعرض كل مجموعة بيانات مقسِّمًا واحدًا أو أكثرمقسِّمات (عادةً ما تكون: تدريب، تحقق، واختبار)، ومخططًا مُحدَّد الأنواعالسمات يصف كل عمود فيها، بالإضافة إلى بيانات وصفية تشمل رخصة الاستخدام، والفئة المهمة، وعلامات اللغة. وتتولى المكتبة تنزيل المجموعات، وتخزينها مؤقتًا، وتحويل تنسيقاتها، لذا نادرًا ما تتعامل مباشرةً مع الملفات الأولية.

البحث عن مجموعات البيانات على المنصة

الواجهة الرئيسية لاكتشاف المجموعات هي huggingface.co/datasets. والمرشحات المتاحة في واجهة المستخدم تشمل:

• المهمة — تصنيف النصوص، والإجابة عن الأسئلة، وتجزئة الصور، والترجمة، والتلخيص، وغيرها الكثير
• اللغة — رموز ISO 639-1 (مثل: en، zh، fr، de، إلخ)
• الترخيص — رخصة Apache 2.0، ورخصة MIT، ورخصة CC-BY، ورخصة CC0، ورخصة OpenRAIL، وغيرها
• فئة الحجم — من أقل من 1000 صف إلى أكثر من مليار صف
• النمط — نص، صورة، صوت، فيديو، جداول، متعددة الوسائط

يمكنك أيضًا البحث برمجيًّا عبر عميل بايثون الخاص بالمنصة:

from huggingface_hub import list_datasets

results = list_datasets(filter='task_categories:text-classification', limit=20)
for ds in results:
    print(ds.id, ds.downloads)

ويوفِّر واجهة برمجة التطبيقات REST لمخدم مجموعات البيانات (Datasets Server) نقطة نهاية /valid تسرد جميع مجموعات البيانات التي تحتوي على تصدير مسبق بصيغة Parquet، مما يمكِّن من عرض سريع وعينات من الصفوف دون الحاجة لتنزيل المجموعة كاملة.

التثبيت

الـdatasets تعمل هذه المكتبة على بايثون 3.8 فأحدث، وهي مستقلة عن نظام التشغيل.

pip install datasets

لدعم الصور والصوت، ثبِّت الحزم الإضافية ذات الصلة:

pip install datasets[vision]# Pillow
pip install datasets    # librosa، soundfile

للمصادقة عند الوصول إلى مجموعات البيانات الخاصة أو لنشر البيانات على المنصة:

pip install huggingface_hub
huggingface-cli login          # يطلب إدخال رمز الدخول الخاص بك على Hugging Face

يتم تخزين الرمز في المسار ~/.cache/huggingface/token على أنظمة macOS/Linux، أو في المسار %USERPROFILE%.cachehuggingfacetoken على أنظمة Windows. أو يمكنك تعيين متغير البيئة HF_TOKEN بشكل مباشر.

تحميل مجموعة بيانات

نقطة الدخول الأساسية هي الدالة load_dataset(). وإذا لم تُحدَّد وسيلة إدخال للمعاملsplit فإنها تعيد قائمة بيانات مُنظمة (DatasetDict) تحتوي على جميع التقسيمات المتاحة:

من المكتبة datasets استورد الدالة load_dataset

ds = load_dataset('stanfordnlp/imdb')
print(ds)
# قائمة بيانات مُنظمة (DatasetDict)({
#     train: مجموعة بيانات (Dataset)({الميزات: ['text', 'label']، عدد الصفوف: 25000})
#     test:  مجموعة بيانات (Dataset)({الميزات: ['text', 'label']، عدد الصفوف: 25000})
# })

train = ds['train']
print(train.features)
# {'text': Value(dtype='string')، 'label': ClassLabel(names=['neg', 'pos'])}

print(train[0]['text'][:120])

تحميل تقسيم واحد فقط

train = load_dataset('stanfordnlp/imdb', split='train')
# تُرجع هذه الجملة مباشرةً كائن مجموعة بيانات (Dataset)، وليس قائمة بيانات مُنظمة (DatasetDict)

تحميل تهيئة مُسَمَّاة

تحدد العديد من مجموعات البيانات تهيئةً مُسَمَّاةً لمتغيرات اللغة أو مجموعات المجال أو إصدارات المخطط. ويجري تمرير اسم التهيئة كوسيطة موضعية ثانية:

ds = load_dataset('Helsinki-NLP/opus_books', 'en-fr')

لعرض قائمة بجميع التهيئة المتاحة لمجموعة بيانات ما قبل تحميلها:

من المكتبة datasets استورد الدالة get_dataset_config_names
print(get_dataset_config_names('Helsinki-NLP/opus_books'))

التحميل من ملفات محلية

مرر اسم التنسيق ومسار الملف بدلًا من معرف مجموعة البيانات في Hub. وتشمل التنسيقات المدعومة: CSV، JSON/JSONL، Parquet، Arrow، النص العادي، واتفاقيات ImageFolder/AudioFolder.

ds = load_dataset('csv', data_files='my_data.csv')
ds = load_dataset('json', data_files={'train': 'train.jsonl', 'test': 'test.jsonl'})
ds = load_dataset('imagefolder', data_dir='./photos/')

هيكل مجموعة البيانات: المقسِّمات والخصائص

تحقق من التقسيمات المتاحة لمجموعة البيانات قبل تحميلها:

من المكتبة datasets استورد الدالة get_dataset_split_names
print(get_dataset_split_names('stanfordnlp/imdb'))
# ['train', 'test', 'unsupervised']

الـالسمات القاموس يُطابق أسماء الأعمدة مع واصفات نوعية. وأكثر أنواع الميزات شيوعًا هي:

نوع الميزة	مثال على ذلك	ملاحظات
القيمة	Value(dtype='string')	كمية قياسية — سلسلة نصية (string)، عدد صحيح 32 بت (int32)، عدد عشري 32 بت (float32)، قيمة منطقية (bool)، إلخ.
ClassLabel	ClassLabel(names=['neg','pos'])	يُخزن كعدد صحيح؛ ويُفك ترميزه إلى الاسم عند الوصول إليه
Sequence	Sequence(Value('int32'))	قائمة ذات طول متغير تحتوي على قيمة ذات نوع محدد
Image	Image()	صورة باستخدام مكتبة PIL؛ تُخزن كبايت، ويُفك ترميزها عند الحاجة (بشكل كسول)
الصوت	Audio(sampling_rate=16000)	قاموس يحتوي على array و معدل أخذ العينات (sampling_rate) المفاتيح
Translation	Translation(languages=['en','fr'])	قاموس مفتاحه رمز اللغة

تدفُّق مجموعات البيانات الكبيرة

لمجموعات البيانات الكبيرة جدًّا التي لا يمكن تنزيلها — مثل Common Crawl وThe Pile وLAION-5B — مرر المعامل streaming=True، فتُستجلَب البيانات وتُفك ترميزها ديناميكيًّا دون امتلاء القرص الصلب لديك:

ds = load_dataset('allenai/c4', 'en', split='train', streaming=True)

for example in ds.take(1000):
    print(example['text'][:80])

يُعيد التحميل الديناميكي (Streaming) كائنIterableDataset rather than a Dataset. It supports.map(), .filter(), .shuffle(buffer_size=N)، و .take(N), but not random indexing or len(). To get a fixed slice without streaming the whole dataset:

ds = load_dataset('allenai/c4', 'en', split='train[:50000]')

Split slicing accepts absolute row counts ([:50000]), percentages ([:10%]), and stepped ranges ([10%:20%]).

تصفية ومعالجة البيانات

All operations run in Apache Arrow and use multiprocessing by default. The result is cached on disk; re-running the same .map() on the same data returns the cache instantly.

# Filter rows
short = train.filter(lambda x: len(x['text']) < 500)

# Batched map — much faster for tokenization
def tokenize(batch):
    return tokenizer(batch['text'], truncation=True, padding='max_length')

tokenized = train.map(tokenize, batched=True, batch_size=256, num_proc=4)

# Column operations
tokenized = tokenized.remove_columns(['text'])
ds = ds.rename_column('label', 'labels')

# Shuffle and select
ds = ds.shuffle(seed=42).select(range(10000))

تحويل التنسيق إلى صيغ أخرى

Target Format	الطريقة
Pandas DataFrame	ds.to_pandas()
PyTorch Dataset	ds.with_format('torch')
TensorFlow Dataset	ds.to_tf_dataset(columns=[...], batch_size=32)
NumPy arrays	ds.with_format('numpy')
Parquet file	ds.to_parquet('output.parquet')
JSON / JSONL	ds.to_json('output.jsonl')
CSV	ds.to_csv('output.csv')

نشر مجموعة بياناتك الخاصة على المنصة

After running huggingface-cli login, push anyDataset أو قائمة بيانات مُنظمة (DatasetDict) object directly:

from datasets import Dataset, DatasetDict
import pandas as pd

df = pd.read_csv('my_data.csv')
ds = Dataset.from_pandas(df)

ds.push_to_hub('your-username/my-dataset', private=False)

To push train and test splits together:

split = ds.train_test_split(test_size=0.1)
DatasetDict({'train': split['train'], 'test': split['test']}).push_to_hub('your-username/my-dataset')

The Hub stores datasets as sharded Parquet files and auto-generates a dataset preview viewer. Add a README.md (Dataset Card) with YAML front-matter to make your dataset filterable by task, language, and license in the Hub search UI.

ملاحظات حول المنصة

Cache Paths

المنصة	Default Cache Path	Override Env Var
macOS / Linux	~/.cache/huggingface/datasets/	HF_DATASETS_CACHE
ويندوز	%USERPROFILE%.cachehuggingfacedatasets	HF_DATASETS_CACHE

ويندوز

Windows uses thespawn start method for multiprocessing, which requires your script entry point to be inside a if __name__ == '__main__': guard. Without this,.map(num_proc=4) will either hang or raise a RuntimeError. If you’re running in a Jupyter notebook, either use num_proc=1 or installmultiprocess إلى جانب datasets, which the library will prefer over the standard-library multiprocessing module.

Disk Space

Large datasets (Common Crawl, RedPajama, LAION) consume hundreds of gigabytes when fully cached. Use streaming=True to avoid downloads. To see what’s in your cache, run python -c "from datasets import inspect_dataset; print(inspect_dataset.__doc__)" or browse the cache directory directly. Cached datasets are stored as Arrow files organized by dataset name and hash; delete subfolders manually to reclaim space.

استخدام مجموعات البيانات لضبط النماذج وتقدير أدائها

The standard fine-tuning pipeline is: load dataset → tokenize with.map(batched=True) → set format to 'torch' → pass to aTrainer or a custom training loop. The Hugging Face transformers library’s Trainer class accepts a Dataset object directly for its train_dataset و eval_dataset arguments.

When evaluating models against benchmark datasets, the لوحة تصنيف النماذج اللغوية الكبيرة (LLM) provides scores across common evaluation sets — useful context when deciding which dataset to target for your own benchmark. If you’re weighing whether to fine-tune and self-host versus calling an API, the self-hosting vs API break-even calculator can model the cost crossover by request volume. For raw per-token API cost across providers, use the حاسبة تكلفة واجهة برمجة التطبيقات (API). And if you plan to run a fine-tuned model locally, VRAM is the hard constraint — the حاسبة VRAM estimates GPU memory requirements from model size and quantization precision.

الأسئلة المتكررة

What is the difference between a Dataset and a DatasetDict?

أ Dataset is a single split — one table of rows and columns. A قائمة بيانات مُنظمة (DatasetDict) is a dict-like container holding multiple splits, and is the default return type of load_dataset() when you omit the split argument. Access individual splits by key: ds['train'], ds['test'], etc. If you passsplit='train', you get a bare Dataset directly.

How do I load a private dataset from the Hub?

Authenticate first with huggingface-cli login, or set the HF_TOKEN environment variable to your access token. Then call load_dataset('org/private-dataset', token=True). The token=True flag tells the library to use the cached or environment-variable credential. For CI/CD pipelines, set HF_TOKEN as a secret and omit the interactive login step.

Why does load_dataset() take a long time on the first call?

يقوم الاستدعاء الأول بتنزيل ملفات البيانات الأولية، وتحويلها إلى صيغة Apache Arrow، ثم كتابتها في الذاكرة المؤقتة على القرص. وقد يستغرق هذا الأمر دقائق أو أكثر لمجموعات البيانات الكبيرة. أما الاستدعاءات اللاحقة على نفس الجهاز فتعيد ملفات Arrow المخبأة فورًا تقريبًا. وإذا كنت تتصل بشبكة بطيئة أو لديك مساحة قرص محدودة، يمكنك تمرير الوسيطة streaming=True لمعالجة البيانات فور حدوثها دون تخزينها مؤقتًا محليًّا.

هل يمكنني استخدام مجموعات بيانات Hugging Face دون اتصالٍ بالإنترنت؟

نعم. وبمجرد تخزين مجموعة البيانات مؤقتًا، عيّن متغير البيئة HF_DATASETS_OFFLINE=1 وload_dataset() فستقرأ المكتبة من الذاكرة المؤقتة المحلية دون إجراء أي طلبات شبكية. وهذه الميزة مفيدة في الخوادم المعزولة تمامًا (air-gapped servers)، أو التشغيلات غير المتصلة بالإنترنت مع ضمان إعادة الإنتاج، أو مجموعات الحوسبة عالية الأداء (HPC clusters) حيث لا تمتلك عُقد العمال اتصالاً بالإنترنت لكنها تتشارك في نظام ملفات شبكي مع دليل الذاكرة المؤقتة.

ما الصيغة الملفية التي يستخدمها المحور (Hub) داخليًّا؟

تُقدَّم مجموعات البيانات المخزَّنة على المحور بصيغة Apache Parquet، مقسَّمة إلى أجزاء (shards). وتقوم المكتبة datasets بتنزيل هذه الأجزاء وتحويلها إلى ملفات Apache Arrow (.arrow) لتخزينها مؤقتًا محليًّا. ويمكنك تجاوز المكتبة تمامًا والوصول إلى أجزاء Parquet مباشرةً عبر مستعرض الملفات في المحور أو باستخدام الدالة huggingface_hub.hf_hub_download().

ما الحد الأقصى لحجم مجموعة بيانات Hugging Face؟

لا يوجد حدٌّ صارمٌ لحجم المجموعة، بل توجد على المحور مجموعات بيانات تبلغ أحجامها تيرابايتات عديدة (مثل أزواج الصور-النصوص في مجموعة LAION-5B، أو لقطات كبيرة من Common Crawl). أما لمجموعات البيانات التي تتجاوز بضعة غيغابايتات، فيخزن المحور بياناتها على هيئة أجزاء متعددة من ملفات Parquet بدلًا من ملفٍ واحدٍ. ويمكنك استخدام streaming=True في المكتبة datasets للتعامل مع هذه المجموعات دون تنزيلها كاملةً، أو تنزيل أجزاء محددة منها عبر وسيطة data_files .