Hub documentation

Pandas

Hub

API docs

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Pandas

Pandas هو مجموعة أدوات تحليل بيانات بايثون تُستخدم على نطاق واسع. وبما أنه يستخدم fsspec لقراءة البيانات عن بُعد وكتابتها، يمكنك استخدام مسارات Hugging Face (hf://) لقراءة البيانات على Hub وكتابتها.

تحميل إطار بيانات

يمكنك تحميل البيانات من ملفات محلية أو من تخزين عن بُعد مثل Hugging Face Datasets. يدعم Pandas العديد من الصيغ بما في ذلك CSV وJSON وParquet:

>>> import pandas as pd
>>> df = pd.read_csv("path/to/data.csv")

لتحميل ملف من Hugging Face، يجب أن يبدأ المسار بـ hf://. على سبيل المثال، المسار إلى مستودع مجموعة البيانات stanfordnlp/imdb هو hf://datasets/stanfordnlp/imdb. تحتوي مجموعة البيانات على Hugging Face على ملفات Parquet متعددة. صُمم تنسيق ملف Parquet لجعل قراءة بيانات الإطارات وكتابتها فعّالة، ولتسهيل مشاركة البيانات عبر لغات تحليل البيانات. فيما يلي كيفية تحميل الملف plain_text/train-00000-of-00001.parquet:

>>> import pandas as pd
>>> df = pd.read_parquet("hf://datasets/stanfordnlp/imdb/plain_text/train-00000-of-00001.parquet")
>>> df
                                                    text  label
0      I rented I AM CURIOUS-YELLOW from my video sto...      0
1      "I Am Curious: Yellow" is a risible and preten...      0
2      If only to avoid making this type of film in t...      0
3      This film was probably inspired by Godard's Ma...      0
4      Oh, brother...after hearing about this ridicul...      0
...                                                  ...    ...
24995  A hit at the time but now better categorised a...      1
24996  I love this movie like no other. Another time ...      1
24997  This film and it's sequel Barry Mckenzie holds...      1
24998  'The Adventures Of Barry McKenzie' started lif...      1
24999  The story centers around Barry McKenzie who mu...      1

لمزيد من المعلومات حول مسارات Hugging Face وكيفية تنفيذها، يُرجى الرجوع إلى توثيق مكتبة العميل الخاصة بـ HfFileSystem.

تعمل مسارات hf:// نفسها أيضاً مع Storage Buckets:
>>> df = pd.read_parquet("hf://buckets/username/my-bucket/data.parquet")
>>> df.to_parquet("hf://buckets/username/my-bucket/output.parquet")

حفظ إطار بيانات

يمكنك حفظ إطار بيانات pandas باستخدام to_csv/to_json/to_parquet في ملف محلي أو مباشرةً على Hugging Face.

لحفظ DataFrame على Hugging Face، تحتاج أولاً إلى تسجيل الدخول بحساب Hugging Face الخاص بك، على سبيل المثال باستخدام:

hf auth login

ثم يمكنك إنشاء مستودع مجموعة بيانات، على سبيل المثال باستخدام:

from huggingface_hub import HfApi

HfApi().create_repo(repo_id="username/my_dataset", repo_type="dataset")

أخيرًا، يمكنك استخدام مسارات Hugging Face في Pandas:

import pandas as pd

df.to_parquet("hf://datasets/username/my_dataset/imdb.parquet")

# or write in separate files if the dataset has train/validation/test splits
df_train.to_parquet("hf://datasets/username/my_dataset/train.parquet")
df_valid.to_parquet("hf://datasets/username/my_dataset/validation.parquet")
df_test .to_parquet("hf://datasets/username/my_dataset/test.parquet")

لاحظ أن ملفات Parquet على Hugging Face مُحسَّنة لتحسين كفاءة التخزين، وتسريع عمليات التنزيل والرفع، وتمكين بثّ مجموعات البيانات وتحريرها بكفاءة:

يحسّن Parquet Content Defined Chunking ملفات Parquet من أجل Xet، وهو نظام تخزين Hugging Face. فهو يسرّع عمليات الرفع والتنزيل بفضل إزالة التكرار على أساس المقاطع، ويتيح تحرير الملفات بكفاءة
يسرّع فهرس الصفحة عمليات التصفية أثناء البث المباشر ويتيح وصولاً عشوائياً فعالاً، على سبيل المثال في عارض مجموعة البيانات

يتطلب Pandas حجة إضافية لكتابة ملفات Parquet مُحسّنة:

import pandas as pd

df.to_parquet(
    "hf://datasets/username/my_dataset/imdb.parquet",
    # Optimize for Xet
    use_content_defined_chunking=True,
    write_page_index=True,
)

use_content_defined_chunking=True لتفعيل Parquet Content Defined Chunking، من أجل إزالة التكرار و التحرير (يتطلب pyarrow>=21.0)
write_page_index=True لتضمين فهرس الصفحات في بيانات Parquet الوصفية، من أجل التدفق والوصول العشوائي

تتيح تقسيمات المحتوى المُعرَّفة (CDC) لبرنامج Parquet writer تقسيم صفحات البيانات بطريقة تجعل البيانات المكررة تُقسَّم وتُضغط بشكل متطابق. بدون CDC، تُقسَّم الصفحات بشكل عشوائي، وبالتالي يصبح من المستحيل اكتشاف البيانات المكررة بسبب الضغط. بفضل CDC، تصبح عمليات رفع وتنزيل Parquet من Hugging Face أسرع، حيث تُرفع أو تُنزَّل البيانات المكررة مرة واحدة فقط.

يمكنك العثور على مزيد من المعلومات حول Xet هنا.

استفد من إزالة التكرار في Xet لملفات Parquet

تُكتب ملفات Parquet المُحسّنة باستخدام تقسيم المحتوى المُعرَّف (Content Defined Chunking)، مما يتيح إزالة التكرار. يُسرع هذا عملية الرفع لأن مقاطع البيانات الموجودة مسبقًا على Hugging Face لا تحتاج إلى إعادة رفع، مما يوفر الكثير من عمليات الإدخال/الإخراج (I/O).

على سبيل المثال، يرفع هذا الكود محتوى df ثم بالنسبة إلى edited_df يكون الرفع أسرع لأنه يرفع فقط المقاطع التي تغيّرت:

import pandas as pd

df.to_parquet(
    "hf://datasets/username/my_dataset/imdb.parquet",
    # Optimize for Xet
    use_content_defined_chunking=True,
    write_page_index=True,
)

edited_df = ...  # e.g. with added/modified/removed rows or columns

edited_df.to_parquet(
    "hf://datasets/username/my_dataset/imdb.parquet",
    # Optimize for Xet
    use_content_defined_chunking=True,
    write_page_index=True,
)

تكون المقاطع بحجم ~64kB تقريبًا، ويحفظ Parquet البيانات عمودًا تلو الآخر، لذا عمليًا هذا ما يحدث عند تحرير ملف Parquet محسّن:

إضافة عمود جديد -> يتم رفع مقاطع العمود الجديد فقط
إضافة/تعديل/حذف صف -> يتم رفع جزء واحد لكل عمود

وبالإضافة إلى ذلك، يتم رفع مقاطع تذييل Parquet التي تحتوي على البيانات الوصفية.

استخدام الصور

يمكنك تحميل مجلد يحتوي على ملف بيانات وصفية يتضمن حقلًا لأسماء الصور أو مساراتها، على النحو التالي:

Example 1:            Example 2:
folder/               folder/
├── metadata.csv      ├── metadata.csv
├── img000.png        └── images
├── img001.png            ├── img000.png
...                       ...
└── imgNNN.png            └── imgNNN.png

يمكنك التكرار على مسارات الصور على النحو التالي:

import pandas as pd

folder_path = "path/to/folder/"
df = pd.read_csv(folder_path + "metadata.csv")
for image_path in (folder_path + df["file_name"]):
    ...

بما أن مجموعة البيانات في بنية مدعومة (ملف metadata.csv أو .jsonl يحتوي على حقل file_name)، يمكنك حفظ هذه المجموعة على Hugging Face، وسيُظهر عارض مجموعات البيانات (Dataset Viewer) البيانات الوصفية والصور معًا على Hugging Face.

from huggingface_hub import HfApi
api = HfApi()

api.upload_folder(
    folder_path=folder_path,
    repo_id="username/my_image_dataset",
    repo_type="dataset",
)

طرق الصور وParquet

باستخدام pandas-image-methods يمكنك تفعيل طرق PIL.Image على عمود الصور. كما يتيح ذلك حفظ مجموعة البيانات كملف Parquet واحد يحتوي على الصور والبيانات الوصفية معًا:

import pandas as pd
from pandas_image_methods import PILMethods

pd.api.extensions.register_series_accessor("pil")(PILMethods)

df["image"] = (folder_path + df["file_name"]).pil.open()
df.to_parquet("data.parquet")

جميع طرق PIL.Image متاحة، على سبيل المثال

df["image"] = df["image"].pil.rotate(90)

استخدام الأصوات

يمكنك تحميل مجلد يحتوي على ملف بيانات وصفية يتضمن حقلًا لأسماء المسارات أو المسارات إلى الملفات الصوتية، على النحو التالي:

Example 1:            Example 2:
folder/               folder/
├── metadata.csv      ├── metadata.csv
├── rec000.wav        └── audios
├── rec001.wav            ├── rec000.wav
...                       ...
└── recNNN.wav            └── recNNN.wav

يمكنك التكرار على مسارات الصوت على النحو التالي:

import pandas as pd

folder_path = "path/to/folder/"
df = pd.read_csv(folder_path + "metadata.csv")
for audio_path in (folder_path + df["file_name"]):
    ...

بما أن مجموعة البيانات في بنية مدعومة (ملف metadata.csv أو .jsonl يحتوي على حقل file_name)، يمكنك حفظها على Hugging Face، ويعرض عارض مجموعات البيانات في Hub البيانات الوصفية والصوت معًا.

from huggingface_hub import HfApi
api = HfApi()

api.upload_folder(
    folder_path=folder_path,
    repo_id="username/my_audio_dataset",
    repo_type="dataset",
)

طرق الصوتيات وملفات Parquet

باستخدام pandas-audio-methods يمكنك تفعيل طرق soundfile على عمود الصوت. كما يتيح حفظ مجموعة البيانات كملف Parquet واحد يحتوي على الصوتيات والبيانات الوصفية معاً:

import pandas as pd
from pandas_audio_methods import SFMethods

pd.api.extensions.register_series_accessor("sf")(SFMethods)

df["audio"] = (folder_path + df["file_name"]).sf.open()
df.to_parquet("data.parquet")

هذا يجعل استخدامه سهلًا مع librosa، على سبيل المثال لإعادة أخذ العينات:

df["audio"] = [librosa.load(audio, sr=16_000) for audio in df["audio"]]
df["audio"] = df["audio"].sf.write()

استخدام Transformers

يمكنك استخدام خطوط أنابيب transformers على إطارات بيانات pandas لتصنيف النصوص، وتوليد النصوص والصور، وما إلى ذلك. تُظهر هذه القسم بعض الأمثلة باستخدام tqdm لأشرطة التقدم.

لا تقبل خطوط الأنابيب كائن tqdm كمدخل، لكن يمكنك استخدام مولّد بايثون بدلاً من ذلك، بالصيغة x for x in tqdm(...)

تصنيف النصوص

from transformers import pipeline
from tqdm import tqdm

pipe = pipeline("text-classification", model="clapAI/modernBERT-base-multilingual-sentiment")

# Compute labels
df["label"] = [y["label"] for y in pipe(x for x in tqdm(df["text"]))]
# Compute labels and scores
df[["label", "score"]] = [(y["label"], y["score"]) for y in pipe(x for x in tqdm(df["text"]))]

توليد النص

from transformers import pipeline
from tqdm import tqdm

pipe = pipeline("text-generation", model="Qwen/Qwen2.5-1.5B-Instruct")

# Generate chat response
prompt = "What is the main topic of this sentence ? REPLY IN LESS THAN 3 WORDS. Sentence: '{}'"
df["output"] = [y["generated_text"][1]["content"] for y in pipe([{"role": "user", "content": prompt.format(x)}] for x in tqdm(df["text"]))]

Update on GitHub

←Lance Polars→