Pandas
Pandas
Pandas는 널리 사용되는 Python 데이터 분석 툴킷이에요. fsspec으로 원격 데이터를 읽고 쓰기 때문에 Hugging Face 경로(hf://)를 사용해 Hub의 데이터를 읽고 쓸 수 있습니다.
출처: 문서
본문
Pandas는 널리 사용되는 Python 데이터 분석 툴킷입니다. fsspec으로 원격 데이터를 읽고 쓰기 때문에 Hugging Face 경로(hf://)를 사용해 Hub에서 데이터를 읽고 쓸 수 있어요.
DataFrame 불러오기 (Load a 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 문서를 참고하세요.
[!TIP] 동일한
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 저장하기 (Save a DataFrame)
to_csv/to_json/to_parquet로 pandas DataFrame을 로컬 파일이나 Hugging Face에 직접 저장할 수 있어요.
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")
# 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")
Hugging Face의 Parquet 파일은 저장 효율을 높이고 업로드·다운로드를 가속화하며 효율적인 데이터셋 스트리밍·편집을 가능하게 하도록 최적화되어 있습니다:
- Parquet Content Defined Chunking은 Hugging Face 저장 백엔드인 Xet에 맞춰 Parquet을 최적화합니다. 청크 기반 중복 제거로 업로드·다운로드를 가속화하고 효율적인 파일 편집을 가능하게 해요.
- 페이지 인덱스(page index)는 스트리밍 시 필터를 가속화하고 Dataset Viewer 같은 효율적인 랜덤 접근을 가능하게 합니다.
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 메타데이터에 페이지 인덱스 포함
[!TIP] Content defined chunking (CDC)은 Parquet writer가 데이터 페이지를 중복 데이터가 동일하게 청킹·압축되도록 청킹하게 만듭니다. CDC가 없으면 페이지가 임의로 청킹되어 압축 때문에 중복 데이터를 감지할 수 없습니다. CDC 덕분에 Hugging Face의 Parquet 업로드·다운로드가 더 빨라집니다. 중복 데이터가 한 번만 업로드·다운로드되기 때문이에요.
Xet에 대한 자세한 정보는 여기에서 확인하세요.
Parquet에 Xet 중복 제거 활용하기 (Leverage Xet deduplication for 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 footer의 청크도 업로드됩니다.
이미지 사용하기 (Use Images)
이미지 이름이나 경로 필드가 있는 메타데이터 파일을 포함한 폴더를 불러올 수 있어요. 다음처럼 구조화됩니다:
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가 메타데이터와 이미지를 모두 보여줍니다.
from huggingface_hub import HfApi
api = HfApi()
api.upload_folder(
folder_path=folder_path,
repo_id="username/my_image_dataset",
repo_type="dataset",
)
이미지 메서드와 Parquet (Image methods and 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)
오디오 사용하기 (Use 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"]):
...
데이터셋이 지원되는 구조(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 (Audio methods and 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 사용하기 (Use Transformers)
pandas DataFrame에 transformers 파이프라인을 사용해 텍스트·이미지 분류, 텍스트 생성 등을 할 수 있어요. 이 섹션은 진행 바를 위한 tqdm 예시 몇 가지를 보여줍니다.
[!TIP] 파이프라인은
tqdm객체를 입력으로 받지 않지만x for x in tqdm(...)형식의 Python 제너레이터를 대신 사용할 수 있어요.
텍스트 분류 (Text Classification)
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"]))]
텍스트 생성 (Text Generation)
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"]))]
더 알아보기 (Learn more)
hf://datasets/<repo>/<file>.parquet 경로로 Pandas가 Hub 데이터를 직접 읽고 쓸 수 있어요. 최적화된 Parquet 파일을 쓰려면 use_content_defined_chunking=True와 write_page_index=True를 켜면 Xet 중복 제거로 편집·동기화가 빨라집니다. 이미지·오디오·Transformers 파이프라인 예시와 HfFileSystem 문서를 함께 참고하세요.