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

يحدد Features البنية الداخلية لمجموعة البيانات. ويُستخدم لتحديد تنسيق التسلسل الأساسي. لكن ما هو أكثر إثارة للاهتمام بالنسبة لك هو أن Features يحتوي على معلومات عالية المستوى عن كل شيء، بدءًا من أسماء الأعمدة وأنواعها، وصولًا إلى ClassLabel. يمكنك اعتبار Features العمود الفقري لمجموعة البيانات.

تنسيق Features بسيط: dict[column_name, column_type]. وهو قاموس من أزواج اسم العمود ونوع العمود. يوفر نوع العمود مجموعة واسعة من الخيارات لوصف نوع البيانات التي لديك.

لنلقِ نظرة على خصائص مجموعة بيانات MRPC من معيار GLUE:

>>> from datasets import load_dataset
>>> dataset = load_dataset('nyu-mll/glue', 'mrpc', split='train')
>>> dataset.features
{'idx': Value('int32'),
 'label': ClassLabel(names=['not_equivalent', 'equivalent']),
 'sentence1': Value('string'),
 'sentence2': Value('string'),
}

يُخبر الميزة Value مكتبة 🤗 Datasets:

• نوع البيانات idx هو int32.
• أنواع البيانات sentence1 وsentence2 هي string.

🤗 يدعم Datasets العديد من أنواع البيانات الأخرى مثل bool وfloat32 وbinary على سبيل المثال لا الحصر.

راجع قيمة للحصول على قائمة كاملة بأنواع البيانات المدعومة.

تُخبر ميزة ClassLabel مكتبة 🤗 Datasets أن عمود label يحتوي على فئتين. وتُسمّى الفئتان not_equivalent وequivalent. تُخزَّن التسميات كأعداد صحيحة في مجموعة البيانات. عند استرجاع التسميات، تقوم الدالتان ClassLabel.int2str() وClassLabel.str2int() بتنفيذ التحويل من القيمة العددية إلى اسم التسمية، والعكس.

إذا كان نوع بياناتك يحتوي على قائمة من الكائنات، فإنك تريد استخدام ميزة List. هل تتذكر مجموعة بيانات SQuAD؟

>>> from datasets import load_dataset
>>> dataset = load_dataset('rajpurkar/squad', split='train')
>>> dataset.features
{'id': Value('string'),
 'title': Value('string'),
 'context': Value('string'),
 'question': Value('string'),
 'answers': {'text': List(Value('string')),
  'answer_start': List(Value('int32'))}}

يُبنى حقل answers باستخدام قاموس الميزات لأنه يحتوي على حقلين فرعيين، هما text وanswer_start، وهما قائمتان من نوع string وint32 على التوالي.

راجع قسم flatten لمعرفة كيفية استخراج الحقول الفرعية المتداخلة كعمود مستقل بذاته.

يُعدّ نوع الميزة المصفوفي مفيدًا لإنشاء مصفوفات بأحجام مختلفة. يمكنك إنشاء مصفوفات بعدّين باستخدام Array2D، وحتى مصفوفات بخمسة أبعاد باستخدام Array5D.

>>> features = Features({'a': Array2D(shape=(1, 3), dtype='int32')})

يسمح نوع المصفوفة أيضًا بأن يكون البُعد الأول من المصفوفة ديناميكيًا. وهذا مفيد للتعامل مع تسلسلات ذات أطوال متغيرة مثل الجمل، دون الحاجة إلى ملء المدخلات أو تقصيرها لتتوافق مع شكل موحد.

>>> features = Features({'a': Array3D(shape=(None, 5, 2), dtype='int32')})

ميزة الصوت

تتميز مجموعات بيانات الصوت بعمود من النوع Audio، يحتوي على ثلاثة حقول مهمة:

• array: بيانات الصوت المُفكّكة ممثّلةً كمصفوفة أحادية البُعد.
• path: المسار إلى ملف الصوت المُحمَّل.
• sampling_rate: معدل أخذ العينات لبيانات الصوت.

عند تحميل مجموعة بيانات صوتية واستدعاء العمود الصوتي، يقوم الميزة Audio تلقائيًا بفك ترميز ملف الصوت وإعادة عينته:

>>> from datasets import load_dataset, Audio

>>> dataset = load_dataset("PolyAI/minds14", "en-US", split="train")
>>> dataset[0]["audio"]
<datasets.features._torchcodec.AudioDecoder object at 0x11642b6a0>

استخدم فهرس الصف أولاً ثم عمود audio للوصول إلى مجموعة بيانات الصوت - dataset[0]["audio"] - لتجنب فك ترميز جميع ملفات الصوت في المجموعة وإعادة أخذ عيناتها. وإلا، فقد يكون هذا الأمر بطيئاً ومستهلكاً للوقت إذا كانت لديك مجموعة بيانات كبيرة.

عند استخدام decode=False، يعطيك نوع Audio ببساطة مسار ملف الصوت أو بياناته الثنائية (bytes) دون فك ترميزه إلى كائن AudioDecoder من torchcodec،

>>> dataset = load_dataset("PolyAI/minds14", "en-US", split="train").cast_column("audio", Audio(decode=False))
>>> dataset[0]
{'audio': {'bytes': None,
  'path': '/root/.cache/huggingface/datasets/downloads/extracted/f14948e0e84be638dd7943ac36518a4cf3324e8b7aa331c5ab11541518e9368c/en-US~JOINT_ACCOUNT/602ba55abb1e6d0fbce92065.wav'},
 'english_transcription': 'I would like to set up a joint account with my partner',
 'intent_class': 11,
 'lang_id': 4,
 'path': '/root/.cache/huggingface/datasets/downloads/extracted/f14948e0e84be638dd7943ac36518a4cf3324e8b7aa331c5ab11541518e9368c/en-US~JOINT_ACCOUNT/602ba55abb1e6d0fbce92065.wav',
 'transcription': 'I would like to set up a joint account with my partner'}

ميزة الصور

تمتلك مجموعات بيانات الصور عمودًا من النوع Image، يقوم بتحميل كائنات PIL.Image من صور مخزنة على شكل بايتات:

عند تحميل مجموعة بيانات للصور واستدعاء عمود الصور، يقوم الميزة Image تلقائيًا بفك ترميز ملف الصورة:

>>> from datasets import load_dataset, Image

>>> dataset = load_dataset("AI-Lab-Makerere/beans", split="train")
>>> dataset[0]["image"]
<PIL.JpegImagePlugin.JpegImageFile image mode=RGB size=500x500 at 0x125506CF8>

استخدم فهرس الصف أولاً ثم عمود image للوصول إلى مجموعة بيانات الصور - dataset[0]["image"] - لتجنب فك ترميز جميع ملفات الصور في مجموعة البيانات. وإلا، فقد يكون هذا الأمر بطيئاً ومستهلكاً للوقت إذا كانت لديك مجموعة بيانات كبيرة.

مع decode=False، يعطيك نوع Image ببساطة مسار ملف الصورة أو بايتاته، دون فك ترميزه إلى PIL.Image،

>>> dataset = load_dataset("AI-Lab-Makerere/beans", split="train").cast_column("image", Image(decode=False))
>>> dataset[0]["image"]
{'bytes': None,
 'path': '/Users/username/.cache/huggingface/datasets/downloads/extracted/772e7c1fba622cff102b85dd74bcce46e8168634df4eaade7bedd3b8d91d3cd7/train/healthy/healthy_train.265.jpg'}

يعتمد على مجموعة البيانات، فقد تحصل على المسار إلى الصورة المحمّلة محليًا، أو على محتوى الصورة على شكل بايتات إذا لم تكن مجموعة البيانات مكوّنة من ملفات فردية.

يمكنك أيضًا تعريف مجموعة بيانات من الصور من مصفوفات numpy:

>>> ds = Dataset.from_dict({"i": [np.zeros(shape=(16, 16, 3), dtype=np.uint8)]}, features=Features({"i": Image()}))

وفي هذه الحالة يتم ترميز مصفوفات numpy إلى PNG (أو TIFF إذا كانت دقة قيم البكسلات مهمة).

في المصفوفات متعددة القنوات مثل RGB أو RGBA، يُدعم النوع uint8 فقط. إذا استخدمت دقة أعلى، ستظهر لك تحذيرة وستُخفَّض دقة المصفوفة إلى uint8. بالنسبة للصور الرمادية، يمكنك استخدام دقة عددية صحيحة أو عشرية تريدها طالما أنها متوافقة مع Pillow. ستظهر تحذيرة إذا كانت دقة الصورة العددية الصحيحة أو العشرية مرتفعة جداً، وفي هذه الحالة تُخفَّض دقة المصفوفة: تُخفَّض مصفوفة int64 إلى int32، وتُخفَّض مصفوفة float64 إلى float32.

ميزة الشبكة

تحتوي مجموعات بيانات الشبكات (Mesh) على عمود من النوع Mesh، يقوم بتحميل ملفات الشبكات ثلاثية الأبعاد ككائنات trimesh.

عند تحميل مجموعة بيانات شبكية واستدعاء العمود الشبكي، يقوم الميزة Mesh تلقائيًا بفك ترميز الملف الشبكي:

>>> from datasets import load_dataset, Mesh

>>> dataset = load_dataset("VINAY-UMRETHE/My-Mesh-Dataset", split="train")
>>> dataset[0]["mesh"]
<trimesh.Scene(len(geometry)=33)>

اعتمادًا على محتوى الملف، قد يُرجع trimesh كائنًا من نوع trimesh.Trimesh أو كائنًا من نوع trimesh.Scene.

استخدم فهرس الصف أولاً ثم عمود mesh للوصول إلى مجموعة بيانات الشبكة - dataset[0]["mesh"] - لتجنب فك ترميز جميع ملفات الشبكة في مجموعة البيانات. وإلا، فقد يكون هذا الأمر بطيئاً ومستهلكاً للوقت إذا كانت لديك مجموعة بيانات كبيرة.

عند استخدام decode=False، يمنحك النوع Mesh مسار ملف الشبكة أو بياناته الثنائية دون فك ترميزه باستخدام trimesh:

>>> dataset = load_dataset("VINAY-UMRETHE/My-Mesh-Dataset", split="train").cast_column("mesh", Mesh(decode=False))
>>> dataset[0]["mesh"]
{'bytes': b'...',
 'path': '00001.glb'}

يدعم ميزات Mesh الملفات .glb و.gltf و.ply و.stl. وفيما يتعلق بالبايتات المضمنة، يُستخدم المسار المخزن path لاستنتاج نوع ملف الشبكة.

ميزة Json

تستند مجموعات البيانات إلى Arrow وهو تنسيق أعمدة، ولذلك يتوقع أن يكون لكل مثال نفس النوع والأنواع الفرعية، وأن تكون القواميس ذات نفس المفاتيح وأنواع القيم. عند تحميل مجموعة بيانات، يظهر خطأ إذا كانت الأنواع غير متطابقة بين الحقول، وتُملأ الحقول الناقصة في القواميس بقيمة None بحيث تمتلك جميع القواميس نفس المفاتيح وأنواع القيم.

لتجنّب ذلك والسماح بأنواع مختلطة دون أخطاء، يمكنك استخدام on_mixed_types="use_json" أو تحديد features= مع نوع Json:

>>> ds = Dataset.from_dict({"a": [0, "foo", {"subfield": "bar"}]})
Traceback (most recent call last):
  ...
  File "pyarrow/error.pxi", line 92, in pyarrow.lib.check_status
pyarrow.lib.ArrowInvalid: Could not convert 'foo' with type str: tried to convert to int64

>>> features = Features({"a": Json()})
>>> ds = Dataset.from_dict({"a": [0, "foo", {"subfield": "bar"}]}, features=features)
>>> ds.features
{'a': Json()}
>>> list(ds["a"])
[0, "foo", {"subfield": "bar"}]

يُفيد هذا أيضًا في حالة قوائم من القواميس ذات مفاتيح وقيم عشوائية، لتجنب ملء الحقول الناقصة بقيمة None:

>>> ds = Dataset.from_dict({"a": [[{"b": 0}, {"c": 0}]]})
>>> ds.features
{'a': List({'b': Value('int64'), 'c': Value('int64')})}
>>> list(ds["a"])
[[{'b': 0, 'c': None}, {'b': None, 'c': 0}]]  # missing fields are filled with None

>>> features = Features({"a": List(Json())})
>>> ds = Dataset.from_dict({"a": [[{"b": 0}, {"c": 0}]]}, features=features)
>>> ds.features
{'a': List(Json())}
>>> list(ds["a"])
[[{'b': 0}, {'c': 0}]]  # OK

مثال آخر مع بيانات استدعاء الأدوات وحجة on_mixed_types="use_json" (مفيد لتجنب الحاجة إلى تحديد features= يدويًا):

>>> messages = [
...     {"role": "user", "content": "Turn on the living room lights and play my electronic music playlist."},
...     {"role": "assistant", "tool_calls": [
...         {"type": "function", "function": {
...             "name": "control_light",
...             "arguments": {"room": "living room", "state": "on"}
...         }},
...         {"type": "function", "function": {
...             "name": "play_music",
...             "arguments": {"playlist": "electronic"}  # mixed-type here since keys ["playlist"] and ["room", "state"] are different
...         }}]
...     },
...     {"role": "tool", "name": "control_light", "content": "The lights in the living room are now on."},
...     {"role": "tool", "name": "play_music", "content": "The music is now playing."},
...     {"role": "assistant", "content": "Done!"}
... ]
>>> ds = Dataset.from_dict({"messages": [messages]}, on_mixed_types="use_json")
>>> ds.features
{'messages': List({'role': Value('string'), 'content': Value('string'), 'tool_calls': List(Json()), 'name': Value('string')})}
>>> ds[0][1]["tool_calls"][0]["function"]["arguments"]
{"room": "living room", "state": "on"}