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。

要在 Hugging Face 上儲存 DataFrame，你首先需要使用你的 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")

# 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")

使用影像

你可以載入一個包含元資料檔案的資料夾，該檔案包含影像名稱或路徑的欄位，其結構如下：

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，並且資料集檢視器會在 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 資料集檢視器會同時顯示元資料和音訊。

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 DataFrame 上使用 transformers pipeline 來進行分類、生成文字、影像等。本節展示了幾個使用 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"]))]

< > 在 GitHub 上更新