مجموعات بيانات Hugging Face: دليل المطوِّرين

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

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

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

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

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

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 تعمل هذه المكتبة على بايثون ٣.٨ فأحدث، وهي مستقلة عن نظام التشغيل.

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']

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

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

لمجموعات البيانات الكبيرة جدًّا التي لا يمكن تنزيلها — مثل 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 بدلًا من كائن Datasetويدعم العمليات التالية:.map(), .filter(), .shuffle(buffer_size=N)، و .take(N)، لكنه لا يدعم الفهرسة العشوائية أو الدالة len()للحصول على شريحة ثابتة دون تحميل مجموعة البيانات بأكملها ديناميكيًّا:

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

يقبل تقسيم الشريحة أعداد صفوف مطلقة ([:50000])، نسب مئوية ([:10%])، ونطاقات خطية مُحددة الخطوة ([10%:20%]).

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

تنفذ جميع العمليات باستخدام Apache Arrow وتستخدم التعددية (multiprocessing) افتراضيًّا. ويتم تخزين النتيجة مؤقتًا على القرص؛ لذا فإن إعادة تشغيل نفس العملية على نفس البيانات تُعيد التخزين المؤقت فورًا. .map() النتيجة المؤقتة

# تصفية الصفوف
short = train.filter(lambda x: len(x['text']) < 500)

# تعيين دفعي (Batched map) — وهو أسرع بكثير في عملية تجزئة النصوص (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)

# عمليات الأعمدة
tokenized = tokenized.remove_columns(['text'])
ds = ds.rename_column('label', 'labels')

# خلط واختيار
ds = ds.shuffle(seed=42).select(range(10000))

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

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

بعد التشغيل huggingface-cli login، يمكنك رفع أيDataset أو قائمة بيانات مُنظمة (DatasetDict) كائنٍ مباشرةً:

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)

لرفع تقسيمات التدريب والاختبار معًا:

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

يُخزِّن المحور (Hub) مجموعات البيانات على شكل ملفات باركيت مقسَّمة (sharded) ويُولِّد تلقائيًّا عارض معاينة لمجموعة البيانات. أضف README.md بطاقة مجموعة البيانات (Dataset Card) تحتوي على مقدمة بصيغة YAML لجعل مجموعة بياناتك قابلةً للتصفية حسب المهمة واللغة والترخيص في واجهة بحث المحور.

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

مسارات التخزين المؤقت

ويندوز

تستخدم ويندوز طريقة البدءspawn للتعددية (multiprocessing)، والتي تتطلب أن يكون نقطة دخول النص البرمجي داخل جملة شرطية من الشكل if __name__ == '__main__': بدون هذه الجملة الشرطية، فإن الاستدعاء.map(num_proc=4) إما أن يتوقف عن العمل دون استجابة أو يُثير خطأً من نوع RuntimeError. وإذا كنت تعمل ضمن دفتر ملاحظات جوبتر (Jupyter notebook)، فاستخدم إما num_proc=1 أو قم بتثبيت الحزمةmultiprocess إلى جانب datasets، والتي تُفضِّلها المكتبة تلقائيًّا على وحدة المكتبة القياسية multiprocessing .

مساحة القرص

تستهلك مجموعات البيانات الكبيرة (مثل Common Crawl وRedPajama وLAION) مئات الجيجابايت عند التخزين المؤقت الكامل لها. استخدم streaming=True لتفادي التنزيلات. وللاطلاع على محتويات التخزين المؤقت لديك، شغِّل الأمر python -c "from datasets import inspect_dataset; print(inspect_dataset.__doc__)" أو اتصفح دليل التخزين المؤقت مباشرةً. وتُخزَّن مجموعات البيانات المؤقتة على شكل ملفات آرو (Arrow) منظمة حسب اسم مجموعة البيانات وقيمة التجزئة (hash) الخاصة بها؛ ويمكنك حذف المجلدات الفرعية يدويًّا لاستعادة المساحة.

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

إن خط أنابيب التخصيص الدقيق (fine-tuning) القياسي هو: تحميل مجموعة البيانات → ترميزها باستخدام.map(batched=True) → تعيين التنسيق إلى 'torch' → تمريرها إلى كائنTrainer أو حلقة تدريب مخصصة. وتقبل فئة transformers المقدمة من هاغينغ فيس Trainer كائن Dataset مباشرةً كمعامل لها مجموعة التدريب و مجموعة التقييم الوسائط.

عند تقييم النماذج مقابل مجموعات البيانات المرجعية، فإن لوحة تصنيف النماذج اللغوية الكبيرة (LLM) توفر درجات أداءً عبر مجموعات التقييم الشائعة — وهي سياقٌ مفيد عند اتخاذ قرارٍ بشأن مجموعة البيانات التي ستستهدفها في اختبارك المرجعي الخاص. وإذا كنت تُقيّم ما إذا كان ينبغي عليك ضبط النموذج يدويًّا واستضافته ذاتيًّا أم استدعاؤه عبر واجهة برمجة التطبيقات (API)، فإن حاسبة نقطة التعادل بين الاستضافة المحلية وواجهة برمجة التطبيقات (API) يمكنه نمذجة نقطة التكافؤ التكلفي حسب حجم الطلبات. أما بالنسبة إلى التكلفة الأولية لكل رمز (token) عبر موفِّري واجهات برمجة التطبيقات، فاستخدم حاسبة تكلفة واجهة برمجة التطبيقات (API). وإذا كنت تنوي تشغيل نموذجٍ مُعدٍّ مسبقًا محليًّا، فإن ذاكرة الوصول العشوائي للوحدة الرسومية (VRAM) هي القيد الأهم — إذ إن حاسبة الذاكرة VRAM يقدّر متطلبات الذاكرة الخاصة بالوحدة الرسومية استنادًا إلى حجم النموذج ودقة التكميم.

الأسئلة الشائعة

ما الفرق بين «مجموعة بيانات» (Dataset) و«قاموس مجموعة بيانات» (DatasetDict)؟

أ Dataset هي تقسيمٌ واحدٌ فقط — أي جدولٌ واحدٌ من الصفوف والأعمدة. أما قائمة بيانات مُنظمة (DatasetDict) فهو عبارة عن حاوية تشبه القواميس تحتوي على عدة تقسيمات، وهو النوع المُرجع الافتراضي لـ load_dataset() عند حذف وسيطة split . ويمكنك الوصول إلى التقسيمات الفردية باستخدام المفتاح المقابل لها، مثل: ds['train'], ds['test']، إلخ. وإذا مرّرتَ الوسيطةsplit='train'، فستحصل مباشرةً على كائن Dataset غير مُغلف.

كيف أحمّل مجموعة بيانات خاصة من المحور (Hub)؟

قم أولًا بالمصادقة باستخدام الأمر huggingface-cli login، أو عيّن متغير البيئة HF_TOKEN ليحتوي على رمز الوصول الخاص بك. ثم استدعِ الدالة load_dataset('org/private-dataset', token=True). وكتلة تُخبر هذه العلامة المكتبة باستخدام بيانات الاعتماد المخبأة أو المُخزَّنة في متغير البيئة. وفي خطوط أنابيب التكامل والنشر المستمر (CI/CD)، عيّن المتغير كسرّ مستتر (secret) وتجنَّب خطوة تسجيل الدخول التفاعلية. HF_TOKEN كسرية وحذف خطوة تسجيل الدخول التفاعلية.

لماذا تستغرق الدالة load_dataset() وقتًا طويلاً في الاستدعاء الأول؟

يقوم الاستدعاء الأول بتنزيل ملفات البيانات الأولية، وتحويلها إلى صيغة 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 .