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 — это широко используемый набор инструментов для анализа данных на Python. Поскольку для чтения и записи удалённых данных он использует fsspec, вы можете использовать пути Hugging Face (hf://) для чтения и записи данных на Hub.

Загрузка DataFrame

Вы можете загрузить данные из локальных файлов или из удалённого хранилища, например 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 разработан для эффективного чтения и записи data frames, а также для упрощения обмена данными между языками анализа данных. Вот как загрузить файл 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")

Сохранение DataFrame

Вы можете сохранить pandas DataFrame с помощью 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 на блоки оптимизирует Parquet для Xet, хранилища Hugging Face. Это ускоряет загрузку и скачивание благодаря дедупликации на уровне блоков и позволяет эффективно редактировать файлы
Page index ускоряет фильтрацию при потоковой передаче и обеспечивает эффективный случайный доступ, например, в Dataset Viewer

Для записи оптимизированных файлов Parquet в Pandas требуется дополнительный аргумент:

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 формировать страницы данных таким образом, чтобы дублирующиеся данные разбивались и сжимались идентично. Без 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,
)

Размер чанков составляет ~64 КБ, а Parquet сохраняет данные по столбцам, поэтому на практике при редактировании файла Optimized 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)

Использование Audios

Вы можете загрузить папку с файлом метаданных, содержащим поле с именами или путями к аудиофайлам, структурированным следующим образом:

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 DataFrames для классификации, генерации текста, изображений и т. д. В этом разделе приведено несколько примеров с использованием tqdm для отображения прогресса.

Pipelines не принимают объект tqdm в качестве входных данных, но вместо него можно использовать генератор Python в виде 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→