PyArrow

Arrow, sütun tabanlı bir biçimdir ve hızlı veri değişimi ile bellek içi analitik için bir araç kutusudur. PyArrow, uzak verileri okumak ve yazmak için fsspec desteklediğinden, Hub üzerindeki verileri okumak ve yazmak için Hugging Face yollarını (hf://) kullanabilirsiniz. Bu, özellikle Parquet verileri için faydalıdır, çünkü Parquet, Hugging Face üzerindeki en yaygın dosya biçimidir. Gerçekten de Parquet, yapısı, veri tipleri, meta verileri ve sıkıştırması sayesinde özellikle verimlidir.

Tablo Yükle

Yerel dosyalardan veya Hugging Face Datasets gibi uzak depolama birimlerinden veri yükleyebilirsiniz. PyArrow, CSV, JSON ve daha da önemlisi Parquet dahil olmak üzere birçok formatı destekler:

>>> import pyarrow.parquet as pq
>>> table = pq.read_table("path/to/data.parquet")

Hugging Face'ten bir dosya yüklemek için yolun hf:// ile başlaması gerekir. Örneğin, stanfordnlp/imdb veri seti deposunun yolu hf://datasets/stanfordnlp/imdb'dir. Hugging Face'teki veri seti birden çok Parquet dosyası içerir. Parquet dosya biçimi, veri çerçevelerini okumayı ve yazmayı verimli hale getirmek ve veri analiz dilleri arasında veri paylaşımını kolaylaştırmak üzere tasarlanmıştır. plain_text/train-00000-of-00001.parquet dosyasını bir pyarrow Table olarak yüklemenin yolu aşağıdaki gibidir (pyarrow>=21.0 gerektirir):

>>> import pyarrow.parquet as pq
>>> table = pq.read_table("hf://datasets/stanfordnlp/imdb/plain_text/train-00000-of-00001.parquet")
>>> table
pyarrow.Table
text: string
label: int64
----
text: [["I rented I AM CURIOUS-YELLOW from my video store because of all the controversy that surrounded it (... 1542 chars omitted)", ...],...,[..., "The story centers around Barry McKenzie who must go to England if he wishes to claim his inheritan (... 221 chars omitted)"]]
label: [[0,0,0,0,0,...,0,0,0,0,0],...,[1,1,1,1,1,...,1,1,1,1,1]]

Tam Parquet verilerini yüklemek istemiyorsanız, bunun yerine Parquet meta verilerini alabilir veya satır gruplarını grup grup yükleyebilirsiniz:

>>> import pyarrow.parquet as pq
>>> pf = pq.ParquetFile("hf://datasets/stanfordnlp/imdb/plain_text/train-00000-of-00001.parquet")
>>> pf.metadata
<pyarrow._parquet.FileMetaData object at 0x1171b4090>
  created_by: parquet-cpp-arrow version 12.0.0
  num_columns: 2
  num_rows: 25000
  num_row_groups: 25
  format_version: 2.6
  serialized_size: 62036
>>> for i in pf.num_row_groups:
...     table = pf.read_row_group(i)
...     ...

Hugging Face yolları ve bunların nasıl uygulandığına dair daha fazla bilgi için lütfen HfFileSystem hakkında istemci kütüphanesinin belgelerine başvurun.

Tablo Kaydet

Bir pyarrow Tablosunu pyarrow.parquet.write_table kullanarak yerel bir dosyaya veya doğrudan Hugging Face'e kaydedebilirsiniz.

Hugging Face'te Tablo'yu kaydetmek için önce Hugging Face hesabınızla oturum açmanız gerekir, örneğin şunu kullanarak:

hf auth login

Ardından bir veri seti deposu oluşturabilirsiniz, örneğin şunu kullanarak:

from huggingface_hub import HfApi

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

Son olarak, PyArrow'da Hugging Face yollarını kullanabilirsiniz:

import pyarrow.parquet as pq

pq.write_table(table, "hf://datasets/username/my_dataset/imdb.parquet", use_content_defined_chunking=True)

# or write in separate files if the dataset has train/validation/test splits
pq.write_table(table_train, "hf://datasets/username/my_dataset/train.parquet", use_content_defined_chunking=True)
pq.write_table(table_valid, "hf://datasets/username/my_dataset/validation.parquet", use_content_defined_chunking=True)
pq.write_table(table_test , "hf://datasets/username/my_dataset/test.parquet", use_content_defined_chunking=True)

Hugging Face'taki Parquet dosyalarının, depolama verimliliğini artırmak, indirme ve yükleme işlemlerini hızlandırmak ve verimli veri seti akışını ve düzenlemeyi mümkün kılmak üzere optimize edildiğini unutmayın:

• Parquet İçerik Tanımlı Parçalama, Hugging Face'in depolama altyapısı olan Xet için Parquet'i optimize eder. Parça tabanlı kopya azaltma sayesinde yüklemeleri ve indirmeleri hızlandırır ve verimli dosya düzenlemeye olanak tanır
• Page index, akış sırasında filtreleri hızlandırır ve Dataset Viewer gibi durumlarda verimli rastgele erişim sağlar.

PyArrow, optimize edilmiş Parquet dosyaları yazmak için ek argümanlar gerektirir:

import pyarrow.parquet as pq

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

• Parquet İçerik Tanımlı Parçalama'yı etkinleştirmek için use_content_defined_chunking=True kullanın; bu, ayıklama ve düzenleme için gereklidir (pyarrow>=21.0 gerektirir)
• Parquet metaverisinde sayfa dizini içermek için write_page_index=True, akış ve rastgele erişim için

İçerik tanımlı parçalama (CDC), Parquet yazıcısının veri sayfalarını, kopya verilerin aynı şekilde parçalanıp sıkıştırılmasını sağlayacak biçimde parçalamasını sağlar. CDC olmadan, sayfalar keyfi olarak parçalanır ve bu nedenle kopya veriler, sıkıştırma nedeniyle tespit edilemez. CDC sayesinde, kopya veriler yalnızca bir kez yüklendiği veya indirildiği için Hugging Face'den Parquet yükleme ve indirme işlemleri daha hızlıdır.

Xet hakkında daha fazla bilgiyi burada bulabilirsiniz.

Parquet için Xet çakışma giderme özelliğinden yararlanın

Optimize edilmiş Parquet dosyaları, yinelenen verilerin kaldırılmasını (deduplication) mümkün kılan Content Defined Chunking ile yazılır. Bu, Hugging Face üzerinde zaten var olan veri parçacıklarının yeniden yüklenmesine gerek kalmadığı için yüklemeleri hızlandırır ve bu da çok fazla I/O tasarrufu sağlar.

Örneğin, bu kod table içeriğini yükler ve ardından edited_table için yalnızca değişen parçaları yüklediğinden yükleme daha hızlıdır:

import pyarrow.parquet as pq

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

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

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

Parçalar ~64kB boyutundadır ve Parquet verileri sütun sütun kaydettiğinden, pratikte bir Optimize Edilmiş Parquet dosyası düzenlendiğinde şunlar gerçekleşir:

• yeni bir sütun ekleyin -> yalnızca yeni sütunun parçaları yüklenir
• satır ekleme/düzenleme/silme -> her sütun için bir parça yüklenir

Bunun yanı sıra, Parquet altbilgisindeki metadata içeren parçalar da yüklenir.

Görüntüler Kullanın

Bir klasör yükleyebilirsiniz; bu klasör, görsellerin adlarını veya yollarını içeren bir alanı barındıran bir meta veri dosyası içerir ve şu şekilde yapılandırılmıştır:

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

Görsel yollarını şu şekilde döngüye alabilirsiniz:

from pathlib import Path
import pyarrow as pq

folder_path = Path("path/to/folder")
table = pq.read_table(folder_path + "metadata.parquet")
for file_name in table["file_name"].to_pylist():
    image_path = folder_path / file_name
    ...

Veri seti desteklenen bir yapıda (file_name alanına sahip bir metadata.parquet dosyası) olduğundan, bu veri setini Hugging Face'e kaydedebilir ve Dataset Viewer hem metadata'yı hem de görüntüleri gösterebilir.

from huggingface_hub import HfApi
api = HfApi()

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

Parquet İçinde Görseller Yerleştirme

PyArrow, Arrow tablolarında görüntü baytlarını barındırmaya olanak tanıyan bir ikili (binary) tipe sahiptir. Bu sayede, görüntülerin (baytlar ve yollar) ve örneklerin (samples) metadata'sının her ikisini de içeren tek bir Parquet dosyası olarak veri setini kaydetmeyi mümkün kılar:

import pyarrow as pa
import pyarrow.parquet as pq

# Embed the image bytes in Arrow
image_array = pa.array([
    {
        "bytes": (folder_path / file_name).read_bytes(),
        "path": file_name,
    }
    for file_name in table["file_name"].to_pylist()
])
table.append_column("image", image_array)

# (Optional) Set the HF Image type for the Dataset Viewer and the `datasets` library
features = {"image": {"_type": "Image"}}  # or using datasets.Features(...).to_dict()
schema_metadata = {"huggingface": {"dataset_info": {"features": features}}}
table = table.replace_schema_metadata(schema_metadata)

# Save to Parquet
# (Optional) with use_content_defined_chunking for faster uploads and downloads
pq.write_table(table, "data.parquet", use_content_defined_chunking=True)

Arrow şeması meta verilerinde Image türünü ayarlamak, diğer kütüphanelerin ve Hugging Face Dataset Viewer'ın “image” alanının yalnızca ikili veri değil, görseller içerdiğini bilmesini sağlar.

Sesleri Kullanın

İçinde seslerin adlarını veya yollarını içeren bir alan bulunan bir metadata dosyası içeren bir klasörü şu şekilde yapılandırılmış olarak yükleyebilirsiniz:

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

Ses dosyası yollarını şu şekilde döngüye alabilirsiniz:

from pathlib import Path
import pyarrow as pq

folder_path = Path("path/to/folder")
table = pq.read_table(folder_path + "metadata.parquet")
for file_name in table["file_name"].to_pylist():
    audio_path = folder_path / file_name
    ...

Veri seti desteklenen bir yapıda (file_name alanına sahip bir metadata.parquet dosyası) olduğundan, Hugging Face'e kaydedebilirsiniz ve Hub Veri Seti Görüntüleyici hem metadata'yı hem de ses dosyalarını gösterir.

from huggingface_hub import HfApi
api = HfApi()

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

Parquet içinde Ses Gömme

PyArrow, Arrow tablolarında ses baytlarının bulunmasına olanak tanıyan bir ikili türüne sahiptir. Bu sayede, hem ses (baytlar ve yol) hem de örneklerin meta verilerini içeren veri setinin tek bir Parquet dosyası olarak kaydedilmesini sağlar:

import pyarrow as pa
import pyarrow.parquet as pq

# Embed the audio bytes in Arrow
audio_array = pa.array([
    {
        "bytes": (folder_path / file_name).read_bytes(),
        "path": file_name,
    }
    for file_name in table["file_name"].to_pylist()
])
table.append_column("audio", audio_array)

# (Optional) Set the HF Audio type for the Dataset Viewer and the `datasets` library
features = {"audio": {"_type": "Audio"}}  # or using datasets.Features(...).to_dict()
schema_metadata = {"huggingface": {"dataset_info": {"features": features}}}
table = table.replace_schema_metadata(schema_metadata)

# Save to Parquet
# (Optional) with use_content_defined_chunking for faster uploads and downloads
pq.write_table(table, "data.parquet", use_content_defined_chunking=True)

Arrow şema meta verilerinde Audio türünü ayarlamak, diğer kütüphanelerin ve Hugging Face Dataset Viewer'ın “audio” alanının yalnızca ikili veri değil, ses verisi içerdiğini tanımasını sağlar.