# Zephon

[Zephon](https://github.com/datologyai/zephon) adalah data loader untuk pelatihan foundation model, yang dibangun oleh [DatologyAI](https://huggingface.co/DatologyAI). Zephon melakukan tokenisasi, pengemasan, dan pencampuran data selama pelatihan berjalan, serta menghasilkan batch yang sama ketika Anda mengubah jumlah GPU (determinisme elastis). Zephon membaca dataset langsung dari Hugging Face Hub dengan path `hf://`.

## Instalasi

Ekstra `hf` menambahkan dukungan untuk dataset Hub dan file Parquet. Contoh di bawah ini juga membutuhkan `transformers` untuk tokenisasi:

```bash
pip install "zephon[hf]" transformers
```

## Muat dataset dari Hub

Lewati jalur `hf://` ke `Dataset.from_path`. Jalur tersebut menentukan dataset, konfigurasi, dan split, misalnya split `train` dari konfigurasi `sample-10BT` dari [HuggingFaceFW/fineweb-edu](https://huggingface.co/datasets/HuggingFaceFW/fineweb-edu). Zephon membaca dataset Hub melalui [shard cache](https://datologyai.github.io/zephon/datasets/storage_backends_and_shard_cache.html)-nya, sehingga Anda harus mengaktifkan cache. Letakkan cache di disk lokal yang cepat dan atur batas ukuran:

```python
from zephon import Pipeline
from zephon.io import CacheOptions, Dataset, StoreOptions
from zephon.work import MixtureSpec, StaticMixtureWorkSource

dataset = Dataset.from_path("fineweb_edu", "hf://HuggingFaceFW/fineweb-edu/sample-10BT/train")
work_source = StaticMixtureWorkSource(
    datasets=[dataset],
    mixture=MixtureSpec({"fineweb_edu": 1.0}),
    seed=42,
)
cache = CacheOptions(enabled=True, root="/tmp/zephon-cache", limit_bytes=50 << 30)  # 50 GiB

pipeline = (
    Pipeline(work_source)
    .options(io_options=StoreOptions(cache=cache))
    .tokenize(tokenizer_id="gpt2", field="text")
    .pack_flat(max_length=2049, algorithm="wrap")
    .batch(microbatch_size=8)
)

for batch in pipeline:
    tensors = batch.to_training(return_labels=True)
    print(tensors["input_ids"].shape, tensors["labels"].shape)  # (8, 2048) (8, 2048)
    break
```

`tokenize` mengonversi kolom `text` menjadi ID token. `pack_flat` menggabungkan dokumen yang telah ditokenisasi menjadi urutan `max_length` token. Atur `max_length` menjadi panjang konteks ditambah satu: dengan `return_labels=True`, `to_training` menggeser label satu posisi, sehingga `input_ids` dan `labels` keduanya memiliki panjang konteks.

Sebuah `Pipeline` adalah iterable Python, sehingga Anda dapat menggunakannya di loop pelatihan mana pun. Zephon mengunduh shard lengkap sebelum membacanya, sehingga batch pertama mungkin membutuhkan waktu beberapa saat.

Untuk membaca dataset privat atau bergerbang, masuk terlebih dahulu dengan akun Hugging Face Anda, misalnya dengan `hf auth login`. Zephon juga membaca variabel lingkungan `HF_TOKEN`.

## Format jalur

Path `hf://` Zephon untuk dataset Hub memiliki format ini:

```
hf://{org}/{name}[@[{revision}][~{source}]]/[{config}/]{split}
```

- `revision`: cabang, tag, atau commit. Nilainya secara default adalah `main`. Zephon mengunci path ke commit saat memuat dataset, sehingga semua rank membaca file yang sama.
- `source`: `original` membaca file yang diunggah ke repositori, dan `parquet` membaca [konversi Parquet otomatis](https://huggingface.co/docs/dataset-viewer/parquet) dari Hub. Letakkan sumber setelah `@`, misalnya `@~parquet`. Secara default, Zephon membaca file yang diunggah jika formatnya didukung, dan menggunakan konversi Parquet jika tidak.
- `config`: konfigurasi dataset. Sertakan ini ketika dataset memiliki lebih dari satu konfigurasi.

| Jalur                                                       | Membaca                                                                         |
| ---------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `hf://HuggingFaceFW/fineweb-edu/sample-10BT/train`         | Split `train` dari konfigurasi `sample-10BT`, dari branch `main`  |
| `hf://HuggingFaceFW/fineweb-edu@v1.4.0/sample-10BT/train`  | Split yang sama dari cabang `v1.4.0`                                       |
| `hf://yahma/alpaca-cleaned@~parquet/train`                 | Split `train` dari konversi Parquet otomatis                       |

> [!WARNING]
> Path Zephon menamai dataset dan split, bukan file. Path ini tidak menggunakan path file `hf://datasets/...` yang digunakan oleh pandas, Polars, dan DuckDB. Gunakan `hf://HuggingFaceFW/fineweb-edu/sample-10BT/train`, bukan `hf://datasets/HuggingFaceFW/fineweb-edu/sample-10BT/train`.

## Mencampur dataset

Untuk melatih pada beberapa dataset Hub, tambahkan mereka ke sumber kerja dengan proporsi masing-masing. Contoh ini mencampurkan FineWeb-Edu dengan Wikipedia bahasa Inggris, menargetkan campuran 70/30 berdasarkan token:

```python
from zephon import Pipeline
from zephon.io import CacheOptions, Dataset, StoreOptions
from zephon.work import MixtureSpec, StaticMixtureWorkSource, TokenEstimation

work_source = StaticMixtureWorkSource(
    datasets=[
        Dataset.from_path("fineweb_edu", "hf://HuggingFaceFW/fineweb-edu/sample-10BT/train"),
        Dataset.from_path("wikipedia", "hf://wikimedia/wikipedia/20231101.en/train"),
    ],
    mixture=MixtureSpec({"fineweb_edu": 0.7, "wikipedia": 0.3}),
    seed=42,
    token_estimation=TokenEstimation(primer="measure", calibration_samples=2048, calibration_shards_max=4),
)
cache = CacheOptions(enabled=True, root="/tmp/zephon-cache", limit_bytes=50 << 30)  # 50 GiB

pipeline = (
    Pipeline(work_source)
    .options(io_options=StoreOptions(cache=cache))
    .tokenize(tokenizer_id="gpt2", field="text")
    .pack_flat(max_length=2049, algorithm="wrap")
    .batch(microbatch_size=8)
)
```

Untuk mencampur berdasarkan sampel, tinggalkan `token_estimation`.

## Pelajari lebih lanjut

- [Dokumentasi Zephon](https://datologyai.github.io/zephon/)
- [Artikel blog peluncuran](https://www.datologyai.com/blog/zephon)
- [makalah Zephon](https://arxiv.org/abs/2610.03087)
- [DatologyAI di Hub](https://huggingface.co/DatologyAI)