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 文件格式旨在使读取和写入数据框高效，并使跨数据分析语言共享数据变得容易。以下是如何加载文件 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 的文档。

保存 DataFrame

你可以使用 to_csv/to_json/to_parquet 将 pandas DataFrame 保存到本地文件或直接保存到 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")

最后，你可以在 Pandas 中使用 Hugging Face 路径：

import pandas as pd

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

# 或者如果数据集有训练/验证/测试切分，则写入单独的文件
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")

使用图像

你可以加载一个包含元数据文件的文件夹，该文件包含图像名称或路径的字段，结构如下：

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"]):
    ...

由于数据集采用支持的结构（带有 file_name 字段的 metadata.csv 或 .jsonl 文件），你可以将此数据集保存到 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"]):
    ...

由于数据集采用支持的结构（带有 file_name 字段的 metadata.csv 或 .jsonl 文件），你可以将其保存到 Hugging Face，Hub Dataset Viewer 会显示元数据和音频。

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

你可以在 pandas DataFrames 上使用 transformers pipelines 进行分类、生成文本、图像等。本节展示一些使用 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"]))]

加载 DataFrame​

保存 DataFrame​

使用图像​

图像方法和 Parquet​

使用音频​

音频方法和 Parquet​

使用 Transformers​

文本分类​

文本生成​