# Pelatih Distilasi

[![model badge](https://img.shields.io/badge/All_models-Distillation-blue)](https://huggingface.co/models?other=distillation,trl)

## Ikhtisar

Distillation Trainer mengimplementasikan distilasi pengetahuan on-policy sebagaimana dijelaskan dalam [On-Policy Distillation of Language Models: Learning from Self-Generated Mistakes](https://huggingface.co/papers/2306.13649) oleh [Rishabh Agarwal](https://huggingface.co/agarwl), Nino Vieillard, Yongchao Zhou, [Piotr Stanczyk](https://huggingface.co/PiotrStanczyk), Sabela Ramos, [Matthieu Geist](https://huggingface.co/matthieu-geist), dan [Olivier Bachem](https://huggingface.co/bachem).

Abstrak dari makalah tersebut adalah sebagai berikut:

> Knowledge distillation (KD) banyak digunakan untuk mengompresi model guru guna mengurangi biaya inferensi dan jejak memorinya, dengan melatih model siswa yang lebih kecil. Namun, metode KD saat ini untuk model sekuens auto-regresif mengalami ketidakcocokan distribusi antara sekuens output yang dilihat selama pelatihan dan yang dihasilkan oleh siswa selama inferensi. Untuk mengatasi masalah ini, kami memperkenalkan Generalized Knowledge Distillation (GKD). Alih-alih hanya mengandalkan set sekuens output yang tetap, GKD melatih siswa pada sekuens output yang dihasilkan sendiri oleh siswa dengan memanfaatkan umpan balik dari guru pada sekuens tersebut. Berbeda dengan pendekatan KD yang diawasi, GKD juga menawarkan fleksibilitas untuk menggunakan fungsi loss alternatif antara siswa dan guru, yang dapat berguna ketika siswa tidak memiliki ekspresivitas untuk meniru distribusi guru.

`DistillationTrainer` melatih model student yang lebih kecil agar sesuai dengan distribusi next-token dari teacher pada generasi on-policy milik student itu sendiri. Ia menghasilkan kelengkapan (completions) student secara on-policy (opsional dengan dukungan vLLM) dan mencocokkan teacher pada distribusi next-token lengkapnya menggunakan kerugian (loss) Jensen-Shannon divergence yang di-chunk secara hemat memori, sehingga distribusi padat dari teacher tidak pernah dimaterialisasi secara penuh.

Trainer ini disumbangkan oleh [Carlos Miguel Patiño](https://huggingface.co/cmpatino).

Untuk padanan asinkron yang memisahkan generasi dari pelatihan dan menilai terhadap guru yang disajikan melalui HTTP alih-alih langkah maju lokal, lihat [`AsyncDistillationTrainer`](async_distillation_trainer).

## Mulai cepat

Contoh ini menunjukkan cara melatih model menggunakan metode distilasi. Kami mendistilasi [model Qwen 2.5 0.5B Instruct](https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct) dari [guru Qwen 2.5 1.5B Instruct](https://huggingface.co/Qwen/Qwen2.5-1.5B-Instruct) pada prompt dari [dataset prompt UltraFeedback](https://huggingface.co/datasets/trl-lib/ultrafeedback-prompt). Anda dapat melihat data dalam dataset di sini:

<iframe src="https://huggingface.co/datasets/trl-lib/ultrafeedback-prompt/embed/viewer/default/train?row=0" frameborder="0" width="100%" height="560px"
>

Di bawah ini adalah skrip untuk melatih model.

```python
# train_distillation.py
from datasets import load_dataset
from trl import DistillationTrainer

dataset = load_dataset("trl-lib/ultrafeedback-prompt", split="train")

trainer = DistillationTrainer(
    model="Qwen/Qwen2.5-0.5B-Instruct",
    teacher_model="Qwen/Qwen2.5-1.5B-Instruct",
    train_dataset=dataset,
)
trainer.train()
```

Jalankan skrip menggunakan perintah berikut:

```bash
torchrun --nproc_per_node 8 train_distillation.py
```

## Menggali lebih dalam ke metode distilasi

On-policy knowledge distillation melatih model student untuk mereproduksi distribusi next-token dari model teacher pada completion yang dihasilkan oleh student itu sendiri, bukan pada set output teacher yang tetap. Belajar dari generasi sendiri memungkinkan student untuk memperbaiki kesalahannya sendiri, yang umumnya menghasilkan kinerja lebih baik daripada off-policy distillation. Bagian ini menguraikan cara kerjanya dalam praktik, mencakup dua langkah utama: **menghasilkan completion** dan **menghitung loss**.

### Membuat kelengkapan

Pada setiap langkah pelatihan, model siswa menghasilkan satu batch penyelesaian untuk prompt yang diambil secara acak.

### Menghitung loss

Loss-nya adalah **divergensi Jensen-Shannon (JSD) yang digeneralisasi** antara distribusi siswa \\( p_S \\) dan distribusi guru \\( p_T \\) pada token pelengkap yang dihasilkan, diinterpolasi oleh `beta` dan didefinisikan sebagai:

$$ \mathcal{L}_\beta = \beta \, \mathbb{D}_{\mathrm{KL}}\!\left[ p_T \| p_M \right] + (1 - \beta) \, \mathbb{D}_{\mathrm{KL}}\!\left[ p_S \| p_M \right], \qquad p_M = (1 - \beta) \, p_S + \beta \, p_T, $$

di mana  \\( p_M \\)  adalah campuran  \\( \beta \\)  dari dua distribusi tersebut. Titik-titik ujungnya mereduksi menjadi divergensi murni:  `beta=0.0`  menghasilkan KL maju  \\( \mathbb{D}_{\mathrm{KL}}\!\left[ p_T \| p_S \right] \\)  dan  `beta=1.0`  menghasilkan KL mundur  \\( \mathbb{D}_{\mathrm{KL}}\!\left[ p_S \| p_T \right] \\).

Dalam praktiknya, proyeksi ke logit kosakata dan divergensi dihitung dalam potongan-potongan, sehingga memori aktivasi puncak tidak berskala dengan tensor logit kosakata penuh × panjang sekuens. Lihat [Mengurangi Penggunaan Memori](reducing_memory_usage).

### Jenis dataset yang diharapkan

Dataset harus diformat sebagai dataset [conversational](dataset_formats#conversational) [prompt-only](dataset_formats#prompt-only). Siswa menghasilkan komplitnya sendiri secara on-policy, sehingga hanya prompt yang diperlukan:

```python
{"prompt": [{"role": "user", "content": "What color is the sky?"}]}
```

## Metrik yang dicatat

Selama pelatihan dan evaluasi, kami mencatat metrik berikut:

- `num_tokens`: Total jumlah token yang diproses sejauh ini, termasuk prompt dan completion. Saat menggunakan tools, hanya token non-tool yang dihitung.
- `step_time`: Rata-rata waktu (dalam detik) yang dibutuhkan per langkah pelatihan (termasuk generasi).
- `completions/mean_length`: Rata-rata panjang dari completion yang dihasilkan. Saat menggunakan tools, hanya token non-tool yang dihitung.
- `completions/min_length`: Panjang minimum dari komposisi yang dihasilkan. Saat menggunakan tools, hanya token non-tool yang dihitung.
- `completions/max_length`: Panjang maksimum dari komplitasi yang dihasilkan. Saat menggunakan tools, hanya token non-tool yang dihitung.
- `completions/mean_terminated_length`: Rata-rata panjang dari kelengkapan yang dihasilkan yang diakhiri dengan EOS. Saat menggunakan alat, hanya token non-alat yang dihitung.
- `completions/min_terminated_length`: Panjang minimum dari completion yang dihasilkan yang diakhiri dengan EOS. Saat menggunakan tools, hanya token non-tool yang dihitung.
- `completions/max_terminated_length`: Panjang maksimum dari completion yang dihasilkan yang diakhiri dengan EOS. Saat menggunakan tools, hanya token non-tool yang dihitung.
- `completions/clipped_ratio`: Rasio penyelesaian yang dipotong (clipped).
- `tools/call_frequency`: Rata-rata jumlah pemanggilan alat per penyelesaian dalam batch generasi. Dicatat hanya ketika `tools` disediakan.
- `tools/failure_frequency`: Proporsi pemanggilan alat yang gagal (alat tidak ditemukan, memicu pengecualian, atau tipe pemanggilan tidak didukung). Nilainya `0.0` jika tidak ada alat yang dipanggil. Dicatat hanya ketika `tools` disediakan.
- `entropy`: Entropi rata-rata dari prediksi token di seluruh kelengkapan yang dihasilkan (dalam nats).

## Kustomisasi

### Percepat pelatihan dengan generasi yang didukung vLLM

Generasi sering menjadi bottleneck utama saat melatih dengan metode on-policy. Untuk mempercepat generasi, Anda dapat menggunakan [vLLM](https://github.com/vllm-project/vllm), mesin inferensi ber-throughput tinggi dan latensi rendah untuk LLM. Untuk mengaktifkannya, pertama instal paketnya dengan

```shell
pip install trl[vllm]
```

Kami mendukung dua cara penggunaan vLLM selama pelatihan: **mode colocate** dan **mode server**.

#### Opsi 1: Mode Colocate

Pada mode ini, vLLM berjalan di dalam proses trainer dan berbagi memori GPU dengan model pelatihan. Hal ini menghindari peluncuran server terpisah dan dapat meningkatkan pemanfaatan GPU, tetapi dapat menyebabkan perebutan memori pada GPU pelatihan. Ini adalah mode default.

```python
from trl import DistillationConfig

training_args = DistillationConfig(
    ...,
    use_vllm=True,  # vllm_mode="colocate" by default
)
```

#### Opsi 2: Mode server

Pada mode ini, vLLM berjalan dalam proses terpisah (dan menggunakan GPU terpisah) serta berkomunikasi dengan trainer melalui HTTP. Ini ideal jika Anda memiliki GPU khusus untuk inferensi.

1. **Mulai server vLLM**:

   ```bash
   VLLM_SERVER_DEV_MODE=1 vllm serve <model_name> \
       --weight-transfer-config '{"backend": "nccl"}' \
       --logprobs-mode processed_logprobs \
       --max-logprobs -1
   ```

2. **Aktifkan mode server di skrip pelatihan Anda**:

   ```python
   from trl import DistillationConfig

   training_args = DistillationConfig(
       ...,
       use_vllm=True,
       vllm_mode="server",
   )
   ```

> [!WARNING]
> Pastikan server menggunakan GPU yang berbeda dari trainer, jika tidak Anda mungkin akan menemui error NCCL. Anda dapat menentukan GPU yang akan digunakan dengan variabel lingkungan `CUDA_VISIBLE_DEVICES`.

> [!TIP]
> Tergantung pada ukuran model dan kebutuhan memori GPU keseluruhan untuk pelatihan, Anda mungkin perlu menyesuaikan parameter `vllm_gpu_memory_utilization` di [DistillationConfig](/docs/trl/v1.18.0/id/distillation_trainer#trl.DistillationConfig) untuk menghindari underutilization atau error out-of-memory.

Untuk informasi lebih lanjut, lihat [Mempercepat pelatihan dengan vLLM](speeding_up_training#vllm-for-fast-generation-in-online-methods).

### Latih adapter dengan PEFT

Kami mendukung integrasi yang erat dengan pustaka 🤗 PEFT, memungkinkan Anda melatih adapter dan membagikannya di Hub, alih-alih melatih seluruh model siswa.

```python
from datasets import load_dataset
from trl import DistillationTrainer
from peft import LoraConfig

dataset = load_dataset("trl-lib/ultrafeedback-prompt", split="train")

trainer = DistillationTrainer(
    model="Qwen/Qwen2.5-0.5B-Instruct",
    teacher_model="Qwen/Qwen2.5-1.5B-Instruct",
    train_dataset=dataset,
    peft_config=LoraConfig(),
)
trainer.train()
```

> [!WARNING]
> Loss distilasi membaca `lm_head.weight` secara langsung dan menjalankan backbone student tanpa melewati `PeftModel.forward()`. Adapter pada `lm_head` (melalui `target_modules`) dan metode prompt-learning (PromptTuning, PrefixTuning, P-Tuning) karenanya ditolak, karena akan diabaikan secara diam-diam. Untuk melatih head, gunakan `modules_to_save=["lm_head"]` sebagai gantinya.

## Pelatihan Agen

[DistillationTrainer](/docs/trl/v1.18.0/id/distillation_trainer#trl.DistillationTrainer) mendukung **pelatihan agen**: siswa memanggil alat selama generasi dan didistilasi pada trajektori yang dihasilkan. Token hasil alat dimasker dari loss, sehingga siswa hanya dilatih pada token yang dihasilkannya sendiri.

### Alat

Argumen `tools` mengharapkan daftar fungsi Python yang mendefinisikan alat yang tersedia untuk agen:

```python
from trl import DistillationTrainer

trainer = DistillationTrainer(
    tools=[tool1, tool2],
    ...,
)
```

Setiap tool harus berupa fungsi Python standar dengan **argumen dan tipe pengembalian yang diberi type-hint**, serta **docstring bergaya Google** yang menjelaskan tujuannya, argumennya, dan nilai pengembaliannya. Untuk detail lebih lanjut, lihat [Panduan meneruskan tools](https://huggingface.co/docs/transformers/en/chat_extras#passing-tools).

> [!TIP]
> Loop panggilan alat memerlukan template obrolan yang *menjaga prefiks* (menambahkan pesan alat tidak boleh mengubah cara pesan sebelumnya dirender). Untuk keluarga model yang dikenal (misalnya Qwen3, DeepSeek-V3), TRL secara otomatis mengganti dengan template pelatihan yang telah diperbaiki ketika alat diaktifkan. Lihat [Template Obrolan](chat_templates#training-templates) untuk daftar lengkap.

Gunakan `max_tool_calling_iterations` di [DistillationConfig](/docs/trl/v1.18.0/id/distillation_trainer#trl.DistillationConfig) untuk membatasi jumlah giliran pemanggilan alat. Secara default tidak ada batas, dan generasi berhenti ketika student menghasilkan giliran respons tanpa pemanggilan alat, ketika completion (semua giliran dan hasil alat) mencapai `max_completion_length` token, atau ketika urutan penuh mencapai panjang maksimum model (`vllm_max_model_length` dengan `vllm_mode="colocate"`, atau `max_position_embeddings` model lainnya).

Contoh:

```python
from trl import DistillationTrainer

def multiply(a: int, b: int) -> int:
    """
    Multiplies two integers.

    Args:
        a: The first integer.
        b: The second integer.

    Returns:
        The product of the two integers.
    """
    return a * b

trainer = DistillationTrainer(
    tools=[multiply],
    ...,
)
```

> [!WARNING]
> Alat asinkron belum didukung — gunakan fungsi sinkron.

### Respons Alat Multimodal

Tools dapat mengembalikan gambar bersama teks dengan mengembalikan daftar blok konten. Hal ini berguna untuk pelatihan agen VLM di mana tools menyediakan umpan balik visual (misalnya, tangkapan layar, plot, tangkapan kamera).

```python
from PIL import Image

def take_screenshot() -> list:
    """
    Takes a screenshot of the current screen.

    Returns:
        The screenshot image with a description.
    """
    img = Image.open("screenshot.png")
    return [{"type": "image", "image": img}, {"type": "text", "text": "Here is the screenshot."}]
```

Gambar yang dikembalikan secara otomatis disuntikkan ke dalam percakapan dan diteruskan ke VLM untuk giliran generasi berikutnya.

## Pelatihan Model Bahasa Visual

[DistillationTrainer](/docs/trl/v1.18.0/id/distillation_trainer#trl.DistillationTrainer) mendukung distilasi Vision-Language Models (VLM) pada dataset multimodal yang berisi teks dan gambar. Sampaikan VLM sebagai student dan teacher, serta berikan dataset hanya berisi prompt dengan kolom `image` (satu gambar per sampel) atau kolom `images` (daftar gambar per sampel). Untuk informasi lebih lanjut tentang struktur dataset yang diharapkan, lihat bagian [Dataset Format — Vision datasets](dataset_formats#vision-datasets).

Diuji dengan:

- **Gemma 3** — misalnya, `google/gemma-3-4b-it`
- **LLaVA-NeXT** — misalnya, `llava-hf/llava-v1.6-mistral-7b-hf`
- **Qwen2-VL** — misalnya, `Qwen/Qwen2-VL-2B-Instruct`
- **Qwen2.5-VL** — misalnya, `Qwen/Qwen2.5-VL-3B-Instruct`

> [!TIP]
> Kompatibilitas dengan semua VLM tidak dijamin. Jika Anda yakin suatu model harus didukung, silakan buka issue di GitHub — atau lebih baik lagi, kirimkan pull request dengan perubahan yang diperlukan.

## Antarmuka baris perintah

Gunakan [`trl distillation` CLI](clis) untuk memulai pelatihan distilasi dari baris perintah. Ia mendukung pelatihan penuh dan LoRA melalui flag standar `ModelConfig`.

```bash
# Full training:
trl distillation \
    --model_name_or_path Qwen/Qwen2.5-0.5B-Instruct \
    --teacher_model_name_or_path Qwen/Qwen2.5-1.5B-Instruct \
    --dataset_name trl-lib/ultrafeedback-prompt \
    --learning_rate 2e-5 \
    --per_device_train_batch_size 4 \
    --gradient_accumulation_steps 8 \
    --output_dir distilled-model \
    --num_train_epochs 1
```

```bash
# LoRA:
trl distillation \
    --model_name_or_path Qwen/Qwen2.5-0.5B-Instruct \
    --teacher_model_name_or_path Qwen/Qwen2.5-1.5B-Instruct \
    --dataset_name trl-lib/ultrafeedback-prompt \
    --learning_rate 2e-4 \
    --per_device_train_batch_size 4 \
    --gradient_accumulation_steps 8 \
    --output_dir distilled-model \
    --num_train_epochs 1 \
    --use_peft \
    --lora_r 64 \
    --lora_alpha 16
```

## DistillationTrainer[[trl.DistillationTrainer]]

#### trl.DistillationTrainer[[trl.DistillationTrainer]]

```python
trl.DistillationTrainer(model: str | PreTrainedModel | PeftModel, teacher_model: str | transformers.modeling_utils.PreTrainedModel | None = None, args: trl.trainer.distillation_config.DistillationConfig | None = None, train_dataset: datasets.arrow_dataset.Dataset | None = None, eval_dataset: datasets.arrow_dataset.Dataset | dict[str, datasets.arrow_dataset.Dataset] | None = None, processing_class: transformers.tokenization_utils_base.PreTrainedTokenizerBase | transformers.processing_utils.ProcessorMixin | None = None, callbacks: list[transformers.trainer_callback.TrainerCallback] | None = None, optimizers: tuple[typing.Optional[torch.optim.Optimizer], typing.Optional[torch.optim.lr_scheduler.LambdaLR]] = (None, None), quantization_config: BitsAndBytesConfig | None = None, peft_config: PeftConfig | None = None, tools: list[collections.abc.Callable] | None = None)
```

[Sumber](https://github.com/huggingface/trl/blob/v1.18.0/trl/trainer/distillation_trainer.py#L220)

**Parameter:**

model (`str` atau [PreTrainedModel](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel) atau `PeftModel`) : Model yang akan dilatih. Bisa berupa:  - String, yaitu *model id* dari model pretrained yang dihosting di dalam repo model di huggingface.co, atau path ke *directory* yang berisi bobot model yang disimpan menggunakan [save_pretrained](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel.save_pretrained), misalnya `'./my_model_directory/'`. Model dimuat menggunakan `<ModelArchitecture>.from_pretrained` (di mana `<ModelArchitecture>` diturunkan dari konfigurasi model) dengan argumen kata kunci dalam `args.model_init_kwargs`. Jika `dtype` tidak ditentukan dalam `args.model_init_kwargs`, nilainya secara default adalah `float32`. Ini berbeda dari [from_pretrained](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel.from_pretrained), di mana (sejak Transformers v5) dtype disimpulkan dari konfigurasi model. - Objek [PreTrainedModel](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel). Hanya model bahasa kausal yang didukung. - Objek `PeftModel`. Hanya model bahasa kausal yang didukung.

teacher_model (`str` or [PreTrainedModel](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel), *optional*) : Teacher model whose next-token distribution the student is trained to match. Can be a *model id* / path (loaded like `model`, using `args.teacher_model_init_kwargs`) or an instantiated [PreTrainedModel](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel). It must share the student's vocabulary. May be omitted by subclasses that supply the teacher another way (e.g. a remote server).

args ([DistillationConfig](/docs/trl/v1.18.0/id/distillation_trainer#trl.DistillationConfig), *opsional*) : Konfigurasi untuk trainer ini. Jika `None`, konfigurasi default akan digunakan.

train_dataset ([Dataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.Dataset) atau [IterableDataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.IterableDataset)) : Dataset yang digunakan untuk pelatihan. Dataset ini harus menyertakan kolom `"prompt"`. Kolom tambahan apa pun dalam dataset akan diabaikan. Format sampel dapat berupa salah satu dari berikut ini:  - [Standar](dataset_formats#standard): Setiap sampel berisi teks polos. - [Konversasional](dataset_formats#conversational): Setiap sampel berisi pesan terstruktur (misalnya, role dan content).  Ketika `train_dataset` adalah [IterableDataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.IterableDataset) (misalnya dataset streaming), `max_steps` harus diatur dalam argumen pelatihan, karena panjangnya tidak dapat disimpulkan dan jumlah total langkah pelatihan diperlukan untuk membatasi loop pelatihan serta mengonfigurasi learning rate scheduler.

eval_dataset ([Dataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.Dataset), [IterableDataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.IterableDataset), [DatasetDict](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.DatasetDict), [IterableDatasetDict](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.IterableDatasetDict) atau `dict[str, Dataset | IterableDataset]`) : Dataset yang digunakan untuk evaluasi. Dataset ini harus memenuhi persyaratan yang sama dengan `train_dataset`.

processing_class ([PreTrainedTokenizerBase](https://huggingface.co/docs/transformers/v5.23.0/en/internal/tokenization_utils#transformers.PreTrainedTokenizerBase), [ProcessorMixin](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/processors#transformers.ProcessorMixin), *opsional*) : Kelas pemrosesan yang digunakan untuk memproses data. Sisi padding harus diatur ke "left". Jika `None`, kelas pemrosesan dimuat dari nama model dengan [from_pretrained](https://huggingface.co/docs/transformers/v5.23.0/en/model_doc/auto#transformers.AutoProcessor.from_pretrained). Token padding, `tokenizer.pad_token`, harus diatur. Jika kelas pemrosesan belum mengatur token padding, `tokenizer.eos_token` akan digunakan sebagai default.

callbacks (daftar [TrainerCallback](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/callback#transformers.TrainerCallback), *opsional*) : Daftar callback untuk menyesuaikan loop pelatihan. Callback tersebut akan ditambahkan ke daftar callback default yang dijelaskan di [di sini](https://huggingface.co/docs/transformers/main_classes/callback). Jika Anda ingin menghapus salah satu callback default yang digunakan, gunakan metode [remove_callback](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/trainer#transformers.Trainer.remove_callback).

optimizers (`tuple[torch.optim.Optimizer | None, torch.optim.lr_scheduler.LambdaLR | None]`, *opsional*, defaultnya `(None, None)`) : Tuple yang berisi optimizer dan scheduler yang akan digunakan. Secara default akan menggunakan instance `AdamW` pada model Anda dan scheduler yang diberikan oleh [get_linear_schedule_with_warmup](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/optimizer_schedules#transformers.get_linear_schedule_with_warmup) yang dikendalikan oleh `args`.

quantization_config ([BitsAndBytesConfig](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/quantization#transformers.BitsAndBytesConfig), *opsional*) : Konfigurasi kuantisasi yang digunakan saat memuat model dari pengidentifikasi model. Gabungkan dengan `peft_config` untuk pelatihan QLoRA. Diabaikan jika model sudah diinstansiasi.

peft_config (`PeftConfig`, *opsional*) : Konfigurasi PEFT yang digunakan untuk membungkus model. Jika `None`, model tidak dibungkus.

tools (daftar `Callable`, *opsional*) : Daftar fungsi tool callable yang dapat dipanggil oleh model selama generasi. Setiap tool harus berupa fungsi Python standar dengan argumen dan nilai return yang diberi type-hint dengan benar, serta docstring bergaya Google yang menjelaskan tujuannya, argumennya, dan nilai returnnya. Untuk detail lebih lanjut, lihat: https://huggingface.co/docs/transformers/en/chat_extras#passing-tools. Model menggunakan nama fungsi, type hints, dan docstring untuk menentukan cara memanggilnya. Pastikan bahwa chat template model mendukung penggunaan tool dan telah di-fine-tune untuk tool calling.

Trainer untuk distilasi pengetahuan. Model siswa dilatih secara on-policy — ia menghasilkan kelengkapan (completions) sendiri — untuk mencocokkan distribusi token berikutnya dari model guru di bawah divergensi Jensen-Shannon yang digeneralisasi (menginterpolasi KL maju, KL mundur, dan JSD melalui `beta`), sebagaimana diperkenalkan dalam [On-Policy Distillation of Language Models](https://huggingface.co/papers/2306.13649).

Contoh:

```python
>>> from trl import DistillationTrainer
>>> from datasets import load_dataset

>>> dataset = load_dataset("trl-lib/tldr", split="train")

>>> trainer = DistillationTrainer(
...     model="Qwen/Qwen2.5-0.5B-Instruct",
...     teacher_model="Qwen/Qwen2.5-1.5B-Instruct",
...     train_dataset=dataset,
... )
>>> trainer.train()
```

#### train[[trl.DistillationTrainer.train]]

```python
train(resume_from_checkpoint: str | bool | None = None, trial: optuna.Trial | dict[str, Any] | None = None, ignore_keys_for_eval: list[str] | None = None)
```

[Sumber](https://github.com/huggingface/trl/blob/v1.18.0/transformers/trainer.py#L1450)

**Parameter:**

resume_from_checkpoint (`str` atau `bool`, *opsional*) : Jika berupa `str`, path lokal ke checkpoint yang disimpan oleh instance `Trainer` sebelumnya. Jika berupa `bool` dan bernilai `True`, muat checkpoint terakhir di *args.output_dir* yang disimpan oleh instance `Trainer` sebelumnya. Jika ada, pelatihan akan dilanjutkan dari state model/optimizer/scheduler yang dimuat di sini.

trial (`optuna.Trial` atau `dict[str, Any]`, *opsional*) : Jalur percobaan atau kamus hiperparameter untuk pencarian hiperparameter.

ignore_keys_for_eval (`list[str]`, *opsional*) : Daftar kunci dalam output model Anda (jika berupa kamus) yang harus diabaikan saat mengumpulkan prediksi untuk evaluasi selama pelatihan.

**Mengembalikan:** `~trainer_utils.TrainOutput`

Objek yang berisi jumlah langkah global, kerugian pelatihan, dan metrik.

Titik masuk utama pelatihan.

#### save_model[[trl.DistillationTrainer.save_model]]

```python
save_model(output_dir: str | None = None, _internal_call: bool = False)
```

[Sumber](https://github.com/huggingface/trl/blob/v1.18.0/transformers/trainer.py#L4077)

Akan menyimpan model, sehingga Anda dapat memuatnya kembali menggunakan `from_pretrained()`.

Hanya akan menyimpan dari proses utama.

#### push_to_hub[[trl.DistillationTrainer.push_to_hub]]

```python
push_to_hub(commit_message: str | None = 'End of training', blocking: bool = True, token: str | None = None, revision: str | None = None, private: bool | None = None, **kwargs)
```

[Sumber](https://github.com/huggingface/trl/blob/v1.18.0/transformers/trainer.py#L4337)

**Parameter:**

commit_message (`str`, *opsional*, defaultnya `"End of training"`) : Pesan untuk commit saat push.

blocking (`bool`, *opsional*, defaultnya `True`) : Apakah fungsi harus hanya mengembalikan nilai setelah `git push` selesai.

token (`str`, *opsional*, defaultnya `None`) : Token dengan izin tulis untuk menimpa argumen asli Trainer.

revision (`str`, *opsional*) : Revisi git untuk di-commit. Secara default menggunakan head dari cabang "main".

private (`bool`, *opsional*) : Apakah membuat repo menjadi privat saat dibuat. Bawaan adalah `args.hub_private_repo`. Tidak berpengaruh jika repo sudah ada.

kwargs (`dict[str, Any]`, *opsional*) : Argumen kata kunci tambahan yang diteruskan ke `~Trainer.create_model_card`.

**Mengembalikan:**

URL repositori tempat model didorong jika `blocking=False`, atau objek `Future` yang melacak kemajuan commit jika `blocking=True`.

Unggah `self.model` dan `self.processing_class` ke 🤗 model hub di repo `self.args.hub_model_id`.

## DistillationConfig[[trl.DistillationConfig]]

#### trl.DistillationConfig[[trl.DistillationConfig]]

```python
trl.DistillationConfig(output_dir: str | None = None, per_device_train_batch_size: int = 8, num_train_epochs: float = 3.0, max_steps: int = -1, learning_rate: float = 1e-06, lr_scheduler_type: transformers.trainer_utils.SchedulerType | str = 'linear', lr_scheduler_kwargs: dict | str | None = None, warmup_steps: float = 0, optim: transformers.training_args.OptimizerNames | str = 'adamw_torch_fused', optim_args: str | None = None, weight_decay: float = 0.0, adam_beta1: float = 0.9, adam_beta2: float = 0.999, adam_epsilon: float = 1e-08, optim_target_modules: None | str | list[str] = None, gradient_accumulation_steps: int = 1, average_tokens_across_devices: bool = True, max_grad_norm: float = 1.0, label_smoothing_factor: float = 0.0, bf16: bool | None = None, fp16: bool = False, bf16_full_eval: bool = False, fp16_full_eval: bool = False, tf32: bool | None = None, activation_checkpointing: bool | None = None, activation_checkpointing_kwargs: dict[str, typing.Any] | str | None = None, gradient_checkpointing: bool = True, gradient_checkpointing_kwargs: dict[str, typing.Any] | str | None = None, torch_compile: bool = False, torch_compile_backend: str | None = None, torch_compile_mode: str | None = None, use_liger_kernel: bool = False, liger_kernel_config: dict[str, bool] | None = None, use_cache: bool = False, neftune_noise_alpha: float | None = None, torch_empty_cache_steps: int | None = None, auto_find_batch_size: bool = False, logging_strategy: transformers.trainer_utils.IntervalStrategy | str = 'steps', logging_steps: float = 10, logging_first_step: bool = False, log_on_each_node: bool = True, logging_nan_inf_filter: bool = True, include_num_input_tokens_seen: str | bool = 'no', log_level: str = 'passive', log_level_replica: str = 'warning', disable_tqdm: bool | None = None, report_to: None | str | list[str] = 'none', run_name: str | None = None, project: str = 'huggingface', trackio_space_id: str | None = None, trackio_bucket_id: str | None = None, trackio_static_space_id: typing.Union[str, NoneType, typing.Literal[False]] = None, eval_strategy: transformers.trainer_utils.IntervalStrategy | str = 'no', eval_steps: float | None = None, eval_delay: float = 0, per_device_eval_batch_size: int = 8, prediction_loss_only: bool = False, eval_on_start: bool = False, eval_do_concat_batches: bool = True, eval_use_gather_object: bool = False, eval_accumulation_steps: int | None = None, include_for_metrics: list[str] = <factory>, batch_eval_metrics: bool = False, save_only_model: bool = False, save_strategy: transformers.trainer_utils.SaveStrategy | str = 'steps', save_steps: float = 500, save_on_each_node: bool = False, save_total_limit: int | None = None, enable_jit_checkpoint: bool = False, push_to_hub: bool = False, hub_token: str | None = None, hub_private_repo: bool | None = None, hub_model_id: str | None = None, hub_strategy: transformers.trainer_utils.HubStrategy | str = 'every_save', hub_always_push: bool = False, hub_revision: str | None = None, load_best_model_at_end: bool = False, metric_for_best_model: str | None = None, greater_is_better: bool | None = None, ignore_data_skip: bool = False, restore_callback_states_from_checkpoint: bool = False, full_determinism: bool = False, seed: int = 42, data_seed: int | None = None, use_cpu: bool = False, accelerator_config: dict | str | None = None, parallelism_config: accelerate.parallelism_config.ParallelismConfig | None = None, dataloader_drop_last: bool = False, dataloader_num_workers: int = 0, dataloader_pin_memory: bool = True, dataloader_persistent_workers: bool = False, dataloader_prefetch_factor: int | None = None, dataloader_multiprocessing_context: str | None = None, dataloader_in_order: bool = True, remove_unused_columns: bool | None = False, label_names: list[str] | None = None, train_sampling_strategy: str = 'random', length_column_name: str = 'length', ddp_find_unused_parameters: bool | None = None, ddp_bucket_cap_mb: int | None = None, ddp_broadcast_buffers: bool | None = None, ddp_static_graph: bool | None = None, ddp_backend: str | None = None, ddp_timeout: int = 1800, fsdp: str | None = None, fsdp_config: dict[str, typing.Any] | str | None = None, deepspeed: dict | str | None = None, debug: str | list[transformers.debug_utils.DebugOption] = '', skip_memory_metrics: bool = True, do_train: bool = False, do_eval: bool = False, do_predict: bool = False, resume_from_checkpoint: str | None = None, local_rank: int = -1, model_init_kwargs: dict[str, typing.Any] | str | None = None, trust_remote_code: bool = False, teacher_model_name_or_path: str | None = None, teacher_model_revision: str | None = None, teacher_model_init_kwargs: dict[str, typing.Any] | str | None = None, disable_dropout: bool = False, max_completion_length: int | None = 512, ds3_gather_for_generation: bool = True, shuffle_dataset: bool | None = True, pad_to_multiple_of: int | str | None = 'auto', temperature: float = 1.0, top_p: float = 1.0, top_k: int = 0, min_p: float | None = None, generation_kwargs: dict | str | None = None, chat_template_kwargs: dict | str | None = None, repetition_penalty: float = 1.0, cache_implementation: str | None = None, use_vllm: bool = False, vllm_mode: str = 'colocate', vllm_model_impl: str = 'vllm', vllm_enable_sleep_mode: bool = False, vllm_structured_outputs_regex: str | None = None, vllm_server_base_url: str | None = None, vllm_server_host: str = '0.0.0.0', vllm_server_port: int = 8000, vllm_server_timeout: float = 240.0, vllm_group_port: int = 51216, vllm_gpu_memory_utilization: float = 0.3, vllm_max_model_length: int | None = None, vllm_tensor_parallel_size: int = 1, beta: float = 1.0, max_tool_calling_iterations: int | None = None, log_completions: bool = False, num_completions_to_print: int | None = None, log_unique_prompts: bool = False)
```

[Sumber](https://github.com/huggingface/trl/blob/v1.18.0/trl/trainer/distillation_config.py#L22)

**Parameter yang mengontrol model dan model guru:**

model_init_kwargs (`str` atau `dict[str, Any]`, *opsional*) : Argumen kata kunci untuk `AutoModelForCausalLM.from_pretrained`, digunakan ketika argumen `model` dari trainer diberikan sebagai string. Nilai `revision` juga digunakan saat memuat kelas pemrosesan.

trust_remote_code (`bool`, *opsional*, defaultnya `False`) : Apakah mengizinkan pemuatan model dan tokenizer yang menyertakan kode Python kustom dari Hub. Diteruskan ke [from_pretrained](https://huggingface.co/docs/transformers/v5.23.0/en/model_doc/auto#transformers.AutoModelForCausalLM.from_pretrained) dan [from_pretrained](https://huggingface.co/docs/transformers/v5.23.0/en/model_doc/auto#transformers.AutoTokenizer.from_pretrained), untuk baik student maupun teacher.

teacher_model_name_or_path (`str`, *opsional*) : Nama atau path model untuk model teacher. Digunakan ketika teacher dimuat secara lokal.

teacher_model_revision (`str`, *opsional*) : Revisi model dari model guru (misalnya, nama cabang, tag, atau hash commit).

teacher_model_init_kwargs (`str` atau `dict[str, Any]`, *opsional*) : Argumen kata kunci yang diteruskan ke `AutoModelForCausalLM.from_pretrained` saat menginstansiasi model guru dari string.

disable_dropout (`bool`, *opsional*, defaultnya `False`) : Apakah akan menonaktifkan dropout pada model student selama pelatihan.

**Parameter yang mengontrol pra-pemrosesan data:**

remove_unused_columns (`bool`, *opsional*, defaultnya `False`) : Apakah hanya kolom `"prompt"` yang akan dipertahankan dalam dataset. Trainer mengonsumsi kolom prompt mentah dan menghasilkan kelengkapan secara on-policy, sehingga defaultnya adalah `False`.

max_completion_length (`int` atau `None`, *opsional*, defaultnya `512`) : Jumlah maksimum token yang akan dihasilkan per penyelesaian selama generasi on-policy.

ds3_gather_for_generation (`bool`, *opsional*, defaultnya `True`) : Pengaturan ini berlaku untuk DeepSpeed ZeRO-3. Jika diaktifkan, bobot model kebijakan akan dikumpulkan untuk generasi, sehingga meningkatkan kecepatan generasi. Namun, menonaktifkan opsi ini memungkinkan pelatihan model yang melebihi kapasitas VRAM dari satu GPU, meskipun dengan biaya kecepatan generasi yang lebih lambat. Menonaktifkan opsi ini tidak kompatibel dengan generasi vLLM.

shuffle_dataset (`bool`, *opsional*, defaultnya `True`) : Apakah akan mengacak dataset pelatihan.

pad_to_multiple_of (`int` atau `str`, *opsional*, defaultnya `"auto"`) : Jika diatur, id prompt dan id kelengkapan akan di-*pad* menjadi kelipatan dari nilai ini. `"auto"` melakukan *padding* menjadi kelipatan 128 pada Neuron (AWS Trainium), yang dikompilasi sekali per bentuk input, dan tidak melakukan *padding* di tempat lain.

**Parameter yang mengontrol generasi:**

temperature (`float`, *opsional*, default `1.0`) : Suhu untuk sampling selama generasi dan untuk menghitung distillation loss. Nilai yang lebih tinggi menghasilkan distribusi probabilitas yang lebih lembut.

top_p (`float`, *opsional*, default `1.0`) : Parameter sampling top-p (nucleus) untuk generasi on-policy.

top_k (`int`, *opsional*, defaultnya `0`) : Parameter top-k sampling untuk generasi on-policy. `0` menonaktifkan penyaringan top-k.

min_p (`float`, *opsional*) : Probabilitas token minimum, yang akan diskalakan oleh probabilitas token yang paling mungkin. Nilainya harus berada di antara `0.0` dan `1.0`. Nilai tipikal berada dalam rentang `0.01-0.2`.

generation_kwargs (`dict[str, Any]`, *opsional*) : Argumen kata kunci tambahan untuk diteruskan ke [GenerationConfig](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/text_generation#transformers.GenerationConfig) (jika menggunakan transformers) atau `SamplingParams` (jika menggunakan vLLM) saat mengambil sampel kelengkapan. Ini dapat digunakan untuk lebih menyesuaikan perilaku generasi, seperti mengatur `suppress_tokens`, `num_beams`, dll. Jika berisi kunci yang bertentangan dengan parameter generasi lainnya (seperti `min_p`, `top_p`, dll.), mereka akan menimpanya.

chat_template_kwargs (`dict[str, Any]`, *opsional*) : Argumen kata kunci tambahan untuk diteruskan ke fungsi `apply_chat_template` saat menghasilkan kelengkapan.

repetition_penalty (`float`, *opsional*, default `1.0`) : Float yang menghukum token baru berdasarkan apakah token tersebut muncul dalam prompt dan teks yang telah dihasilkan sejauh ini. Nilai > `1.0` mendorong model untuk menggunakan token baru, sedangkan nilai < `1.0` mendorong model untuk mengulang token.

cache_implementation (`str`, *opsional*) : Implementasi metode cache untuk generasi yang lebih cepat ketika `use_vllm` diatur ke `False`.

**Parameter yang mengontrol akselerasi generasi yang didukung oleh vLLM:**

use_vllm (`bool`, *opsional*, defaultnya `False`) : Apakah akan menggunakan vLLM untuk menghasilkan kelengkapan on-policy dari model siswa.

vllm_mode (`str`, *opsional*, defaultnya `"colocate"`) : Mode untuk integrasi vLLM student. Bisa `"server"` atau `"colocate"`.

vllm_model_impl (`str`, *opsional*, defaultnya `"vllm"`) : Backend implementasi model untuk vLLM. Gunakan `"vllm"` atau `"transformers"`.

vllm_enable_sleep_mode (`bool`, *opsional*, defaultnya `False`) : Aktifkan mode tidur vLLM untuk mengoffload bobot siswa selama langkah optimizer.

vllm_structured_outputs_regex (`str`, *opsional*) : Pola regex untuk output terstruktur vLLM.

**Parameter yang mengontrol server vLLM (hanya digunakan ketika `vllm_mode` adalah `"server"`):**

vllm_server_base_url (`str`, *opsional*) : URL dasar untuk server vLLM siswa. Jika diberikan, `vllm_server_host` dan `vllm_server_port` diabaikan.

vllm_server_host (`str`, *opsional*, defaultnya `"0.0.0.0"`) : Host dari server vLLM student.

vllm_server_port (`int`, *opsional*, defaultnya `8000`) : Port dari server vLLM student.

vllm_server_timeout (`float`, *opsional*, defaultnya `240.0`) : Timeout untuk terhubung ke server vLLM student.

vllm_group_port (`int`, *opsional*, defaultnya `51216`) : Port untuk grup pembaruan bobot vLLM (komunikator NCCL).

**Parameter yang mengontrol eksekusi vLLM yang terkolokasi (hanya digunakan ketika `vllm_mode` adalah `"colocate"`):**

vllm_gpu_memory_utilization (`float`, *opsional*, default `0.3`) : utilisasi memori GPU untuk mesin vLLM siswa yang dikolokasi.

vllm_max_model_length (`int`, *opsional*) : Panjang maksimum urutan model untuk mesin vLLM yang terkolokasi.

vllm_tensor_parallel_size (`int`, *opsional*, defaultnya `1`) : Ukuran paralel tensor untuk mesin vLLM siswa yang terkolokasi.

**Parameter yang mengontrol pelatihan:**

beta (`float`, *opsional*, default `1.0`) : Koefisien interpolasi untuk loss Generalized Jensen-Shannon Divergence. Ketika `0.0`, loss-nya adalah forward KL divergence. Ketika `1.0`, loss-nya adalah reverse KL divergence. Ketika `0.5`, loss-nya adalah JSD standar. Berbeda dengan `beta` pada GRPO (koefisien penalti KL terhadap model referensi), di sini parameter ini memilih divergensi itu sendiri; tidak ada penalti KL model referensi.

max_tool_calling_iterations (`int`, *opsional*) : Jumlah maksimum giliran pemanggilan alat saat melatih agen. Jika `None`, tidak ada batas dan generasi berhenti ketika model menghasilkan giliran respons tanpa pemanggilan alat, ketika kelengkapan (semua giliran dan hasil alat) mencapai `max_completion_length` token, atau ketika urutan penuh mencapai panjang maksimum model (`vllm_max_model_length` dengan `vllm_mode="colocate"`, `max_position_embeddings` model lainnya).

**Parameter yang mengontrol pencatatan log:**

log_completions (`bool`, *opsional*, defaultnya `False`) : Apakah akan mencatat sampel dari pasangan (prompt, completion) setiap `logging_steps` langkah. Jika `rich` terinstal, sampel tersebut akan dicetak. Jika pencatatan `wandb` dan/atau `trackio` diaktifkan, sampel tersebut akan dicatat ke `wandb` dan/atau `trackio`.

num_completions_to_print (`int`, *opsional*) : Jumlah penyelesaian yang dicetak dengan `rich`. Jika `None`, semua penyelesaian dicatat.

log_unique_prompts (`bool`, *opsional*, defaultnya `False`) : Apakah akan mencatat prompt unik. Jika `True`, hanya prompt unik yang dicatat. Jika `False`, semua prompt dicatat.

Kelas konfigurasi untuk [DistillationTrainer](/docs/trl/v1.18.0/id/distillation_trainer#trl.DistillationTrainer).

Memperluas [TrainingArguments](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/trainer#transformers.TrainingArguments) dengan parameter yang spesifik untuk knowledge distillation. Semua field yang diperlukan dideklarasikan di sini.

Dengan [HfArgumentParser](https://huggingface.co/docs/transformers/v5.23.0/en/internal/trainer_utils#transformers.HfArgumentParser), kita dapat mengubah kelas ini menjadi argumen [argparse](https://docs.python.org/3/library/argparse#module-argparse) yang dapat ditentukan di baris perintah.

> [!NOTE]
> Parameter ini memiliki nilai default yang berbeda dari [TrainingArguments](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/trainer#transformers.TrainingArguments): - `logging_steps`: Defaultnya adalah `10` alih-alih `500`. - `gradient_checkpointing`: Defaultnya adalah `True` alih-alih `False`. - `bf16`: Defaultnya adalah `True` jika `fp16` tidak diatur, alih-alih `False`. - `learning_rate`: Defaultnya adalah `1e-6` alih-alih `5e-5`.

