# Fungsi Reward

Modul ini berisi beberapa fungsi reward yang berguna, terutama ditujukan untuk digunakan dengan [GRPOTrainer](/docs/trl/v1.18.0/id/grpo_trainer#trl.GRPOTrainer) dan [RLOOTrainer](/docs/trl/v1.18.0/id/rloo_trainer#trl.RLOOTrainer).

## accuracy_reward[[trl.rewards.accuracy_reward]]

#### trl.rewards.accuracy_reward[[trl.rewards.accuracy_reward]]

```python
trl.rewards.accuracy_reward(completions: list[list[dict[str, str]]], solution: list[str], log_extra: collections.abc.Callable[[str, list], None] | None = None, **kwargs)
```

[Sumber](https://github.com/huggingface/trl/blob/v1.18.0/trl/rewards/accuracy_rewards.py#L28)

**Parameter:**

completions (`list[list[dict[str, str]]]`) : Daftar completion yang akan dievaluasi. Setiap completion harus berupa daftar berisi satu pesan, yaitu sebuah dictionary yang mengandung kunci `"content"` dengan nilai berupa teks dari completion tersebut.

solution (`list[str]`) : Daftar solusi teks mentah untuk pertanyaan/soal/prompt.

log_extra (`callable`, *opsional*) : Callable untuk mencatat kolom tambahan ke tabel completions, disediakan secara otomatis oleh trainer. Nilainya secara default adalah `None` untuk memungkinkan pemanggilan fungsi secara langsung di luar trainer (misalnya, untuk pengujian).

- ****kwargs** : Argumen kata kunci tambahan. Fungsi ini tidak menggunakannya, tetapi argumen ini diperlukan dalam tanda tangan fungsi untuk memastikan kompatibilitas dengan trainer seperti [GRPOTrainer](/docs/trl/v1.18.0/id/grpo_trainer#trl.GRPOTrainer).

Fungsi reward yang memeriksa apakah penyelesaian cocok dengan kebenaran dasar.
- Jika baik gold maupun prediction dapat di-parse → gunakan verifikasi matematika.
- Jika gold tidak dapat di-parse → kembalikan `None` untuk melewati contoh tersebut.

Contoh:
```python
>>> from trl.rewards import accuracy_reward

>>> solutions = [r"\frac{1}{3}", r"\frac{1}{3}"]
>>> completions = [
...     [{"role": "assistant", "content": r"My answer is \boxed{\frac{1}{3}}"}],
...     [{"role": "assistant", "content": r"My answer is \boxed{\frac{1}{2}}"}],
... ]
>>> accuracy_reward(completions, solutions)
[1.0, 0.0]
```

## reasoning_accuracy_reward[[trl.rewards.reasoning_accuracy_reward]]

#### trl.rewards.reasoning_accuracy_reward[[trl.rewards.reasoning_accuracy_reward]]

```python
trl.rewards.reasoning_accuracy_reward(completions: list[list[dict[str, str]]], solution: list[str], reasoning_delimiters: list[str] | None = None, log_extra: collections.abc.Callable[[str, list], None] | None = None, **kwargs)
```

[Sumber](https://github.com/huggingface/trl/blob/v1.18.0/trl/rewards/accuracy_rewards.py#L225)

**Parameter:**

completions (`list[list[dict[str, str]]]`) : Daftar completion yang akan dievaluasi. Setiap completion harus berupa daftar berisi satu pesan, yaitu sebuah dictionary yang mengandung kunci `"content"` dengan nilai berupa teks dari completion tersebut.

solution (`list[str]`) : Daftar solusi teks mentah untuk pertanyaan/soal/prompt.

reasoning_delimiters (`list[str]]`, *opsional*) : Daftar string yang menunjukkan di mana konten penalaran berakhir. Jawaban akhir diasumsikan berada setelah kemunculan terakhir dari salah satu delimiter ini. Jika `None`, defaultnya adalah `["</think>"]`.

log_extra (`callable`, *opsional*) : Callable untuk mencatat kolom tambahan ke tabel completions, disediakan secara otomatis oleh trainer. Nilainya secara default adalah `None` untuk memungkinkan pemanggilan fungsi secara langsung di luar trainer (misalnya, untuk pengujian).

- ****kwargs** : Argumen kata kunci tambahan. Fungsi ini tidak menggunakannya, tetapi argumen ini diperlukan dalam tanda tangan fungsi untuk memastikan kompatibilitas dengan trainer seperti [GRPOTrainer](/docs/trl/v1.18.0/id/grpo_trainer#trl.GRPOTrainer).

Fungsi reward yang menghapus konten penalaran dan memeriksa apakah jawaban akhir cocok dengan ground truth.
- Jika baik gold maupun prediction dapat di-parse → gunakan verifikasi matematika.
- Jika gold tidak dapat di-parse → kembalikan `None` untuk melewati contoh tersebut.

Contoh:
```python
>>> from trl.rewards import reasoning_accuracy_reward

>>> reasoning_delimiters = ["</think>"]
>>> solutions = [r"\frac{1}{3}", r"\frac{1}{3}", r"\frac{1}{3}"]
>>> completions = [
...     [
...         {
...             "role": "assistant",
...             "content": r"<think> Reasoning content </think> The final answer is \boxed{\frac{1}{3}}",
...         }
...     ],
...     [
...         {
...             "role": "assistant",
...             "content": r"<think> Reasoning content </think> The final answer is \boxed{\frac{1}{2}}",
...         }
...     ],
...     [
...         {
...             "role": "assistant",
...             "content": r"<think> Reasoning content with partial answers \boxed{\frac{1}{3}} but no final answer",
...         }
...     ],
... ]
>>> reasoning_accuracy_reward(completions, solutions, reasoning_delimiters=reasoning_delimiters)
[1.0, 0.0, 0.0]
```

## get_cosine_scaled_reward[[trl.rewards.get_cosine_scaled_reward]]

#### trl.rewards.get_cosine_scaled_reward[[trl.rewards.get_cosine_scaled_reward]]

```python
trl.rewards.get_cosine_scaled_reward(max_len: int, min_value_wrong: float = -1.0, max_value_wrong: float = -0.5, min_value_correct: float = 0.5, max_value_correct: float = 1.0)
```

[Sumber](https://github.com/huggingface/trl/blob/v1.18.0/trl/rewards/accuracy_rewards.py#L120)

**Parameter:**

max_len (`int`) : Panjang maksimum penyelesaian (dalam token) yang digunakan untuk menormalisasi jadwal kosinus, $L_{\max}$.

min_value_wrong (`float`, *opsional*, defaultnya `-1.0`) : Reward untuk penyelesaian yang salah pada panjang terpendek.

max_value_wrong (`float`, *opsional*, default `-0.5`) : Reward untuk penyelesaian yang salah pada panjang maksimum.

min_value_correct (`float`, *opsional*, default `0.5`) : Reward untuk penyelesaian yang benar pada panjang terpanjang.

max_value_correct (`float`, *opsional*, default `1.0`) : Reward untuk penyelesaian yang benar pada panjang terpendek.

**Mengembalikan:** `Callable`

Fungsi reward yang menerima penyelesaian, solusi mereka, dan id token, lalu mengembalikan daftar reward (`None` untuk contoh dengan solusi emas yang tidak dapat diurai).

Fungsi reward yang menskalakan reward kebenaran berdasarkan panjang penyelesaian mengikuti jadwal kosinus, untuk memprioritaskan penalaran yang ringkas. Referensi: Lampiran C.1 dari paper "Demystifying Long Chain-of-Thought Reasoning" (https://huggingface.co/papers/2502.03373).

Kebenaran ditentukan oleh verifikasi matematis (seperti pada [accuracy_reward()](/docs/trl/v1.18.0/id/rewards#trl.rewards.accuracy_reward)), dan panjangnya adalah jumlah token penyelesaian. Hadiah diinterpolasi sepanjang jadwal kosinus antara batas penyelesaian pendek dan batas penyelesaian panjang:

$$ R_{\text{cosine}}(y) = v_{\min} + \frac{1}{2}(v_{\max} - v_{\min})\left(1 + \cos\left(\frac{|y|}{L_{\max}}\pi\right)\right) $$

Untuk penyelesaian yang **benar**, $(v_{\min}, v_{\max}) = (\texttt{min\_value\_correct}, \texttt{max\_value\_correct})$, sehingga penyelesaian yang lebih pendek diberi imbalan lebih besar. Untuk penyelesaian yang **salah**, batasnya dibalik menjadi $(v_{\min}, v_{\max}) = (\texttt{max\_value\_wrong}, \texttt{min\_value\_wrong})$, sehingga penyelesaian yang lebih pendek dihukum lebih berat (penyelesaian salah yang lebih panjang dihukum lebih ringan, menjaga eksplorasi). Ketika solusi emas tidak dapat diurai, contoh tersebut dilewati (imbalan `None`), seperti pada [accuracy_reward()](/docs/trl/v1.18.0/id/rewards#trl.rewards.accuracy_reward).

Contoh:
```python
>>> from trl.rewards import get_cosine_scaled_reward

>>> cosine_scaled_reward = get_cosine_scaled_reward(max_len=100)
>>> completions = [[{"content": r"\boxed{\frac{1}{3}}"}], [{"content": r"\boxed{\frac{1}{2}}"}]]
>>> solution = [r"\frac{1}{3}", r"\frac{1}{3}"]
>>> completion_ids = [[1] * 50, [1] * 50]  # both completions are 50 tokens, half of max_len
>>> cosine_scaled_reward(completions, solution, completion_ids)
[0.75, -0.75]
```

## think_format_reward[[trl.rewards.think_format_reward]]

#### trl.rewards.think_format_reward[[trl.rewards.think_format_reward]]

```python
trl.rewards.think_format_reward(completions: list[list[dict[str, str]]], **kwargs)
```

[Sumber](https://github.com/huggingface/trl/blob/v1.18.0/trl/rewards/format_rewards.py#L18)

**Parameter:**

completions (`list[list[dict[str, str]]]`) : Daftar completion yang akan dievaluasi. Setiap completion harus berupa daftar berisi satu pesan, yaitu sebuah dictionary yang mengandung kunci `"content"` dengan nilai berupa teks dari completion tersebut.

- ****kwargs** : Argumen kata kunci tambahan. Fungsi ini tidak menggunakannya, tetapi argumen ini diperlukan dalam tanda tangan fungsi untuk memastikan kompatibilitas dengan trainer seperti [GRPOTrainer](/docs/trl/v1.18.0/id/grpo_trainer#trl.GRPOTrainer).

**Mengembalikan:** `list[float]`

Daftar hadiah, di mana setiap hadiah bernilai 1.0 jika penyelesaian sesuai dengan format yang diharapkan, selain itu 0.0.

Fungsi reward yang memeriksa apakah proses penalaran dibungkus dalam tag `"<think>"` dan `"</think>"`. Fungsi ini mengembalikan reward 1.0 jika formatnya benar, dan 0.0 jika tidak.

Contoh:
```python
>>> from trl.rewards import think_format_reward

>>> completions = [
...     [{"content": "<think>\nThis is my reasoning.\n</think>\nThis is my answer."}],
...     [{"content": "<think>\nThis is my reasoning.\nThis is my answer."}],
... ]
>>> think_format_reward(completions)
[1.0, 0.0]
```

## get_repetition_penalty_reward[[trl.rewards.get_repetition_penalty_reward]]

#### trl.rewards.get_repetition_penalty_reward[[trl.rewards.get_repetition_penalty_reward]]

```python
trl.rewards.get_repetition_penalty_reward(ngram_size: int = 3, max_penalty: float = -1.0)
```

[Sumber](https://github.com/huggingface/trl/blob/v1.18.0/trl/rewards/other_rewards.py#L18)

**Parameter:**

ngram_size (`int`, *opsional*, defaultnya `3`) : Ukuran n-gram token yang dipertimbangkan.

max_penalty (`float`, *opsional*, default `-1.0`) : Penalti negatif terbesar, diterapkan pada penyelesaian yang sepenuhnya repetitif. Harus non-positif.

**Mengembalikan:** `Callable`

Fungsi reward yang menerima daftar id token penyelesaian dan mengembalikan daftar penalti (masing-masing dalam `[max_penalty, 0.0]`).

Fungsi reward yang menghukum n-gram berulang dalam sebuah penyelesaian, digunakan untuk mencegah teks yang degeneratif dan repetitif (mode kegagalan umum dan strategi reward-hacking ketika reward yang membentuk panjang atau format digunakan). Referensi: Lampiran C.2 dari paper "Demystifying Long Chain-of-Thought Reasoning" (https://huggingface.co/papers/2502.03373).

Hukuman tersebut sebanding dengan fraksi n-gram yang berulang dalam penyelesaian:

$$ R_{\text{repetition}}(y) = \left(1 - \frac{\#\,\text{unique } n\text{-grams}}{\#\,\text{total } n\text{-grams}}\right) \times p $$

di mana $p$ adalah `max_penalty`. Sebuah completion tanpa n-gram berulang mendapat reward `0.0`, sedangkan yang sepenuhnya repetitif mendekati `max_penalty`. N-gram dihitung berdasarkan token id dari completion (paper tersebut menerapkan penalti pada token yang berulang), sehingga reward ditentukan oleh tokenizer dan tidak bergantung pada bahasa. Completion dengan jumlah token kurang dari `ngram_size` mendapat reward `0.0`.

Contoh:
```python
>>> from trl.rewards import get_repetition_penalty_reward

>>> repetition_penalty = get_repetition_penalty_reward(ngram_size=2, max_penalty=-1.0)
>>> completion_ids = [[1, 2, 3, 4], [5, 5, 5, 5, 5]]
>>> repetition_penalty(completion_ids)
[0.0, -0.75]
```

## get_soft_overlong_punishment[[trl.rewards.get_soft_overlong_punishment]]

#### trl.rewards.get_soft_overlong_punishment[[trl.rewards.get_soft_overlong_punishment]]

```python
trl.rewards.get_soft_overlong_punishment(max_completion_len: int, soft_punish_cache: int)
```

[Sumber](https://github.com/huggingface/trl/blob/v1.18.0/trl/rewards/other_rewards.py#L83)

**Parameter:**

max_completion_len (`int`) : Panjang maksimum dari pelengkap,  \( L_{\max} \).

soft_punish_cache (`int`) : Panjang minimum dari pelengkap,  \( L_{\text{cache}} \). Jika diatur ke `0`, panjang minimum tidak diterapkan.

Fungsi reward yang menghukum penyelesaian yang terlalu panjang. Fungsi ini digunakan untuk menghukum penyelesaian yang terlalu panjang, tetapi tidak untuk memberi reward pada penyelesaian yang lebih pendek. Referensi: Persamaan (13) dari paper DAPO (https://huggingface.co/papers/2503.14476)

$$ R_{\text{length}}(y) = \begin{cases} 0, & |y| \le L_{\max} - L_{\text{cache}} \\ \dfrac{(L_{\max} - L_{\text{cache}}) - |y|}{L_{\text{cache}}}, & L_{\max} - L_{\text{cache}} < |y| \le L_{\max} \\ -1, & L_{\max} < |y| \end{cases} $$

Contoh:
```python
>>> from trl.rewards import get_soft_overlong_punishment

>>> soft_overlong_punishment = get_soft_overlong_punishment(max_completion_len=100, soft_punish_cache=20)
>>> completion_ids = [[1] * 90]  # simulating a completion with 90 tokens. 90 is between 80 and 100.
>>> soft_overlong_punishment(completion_ids)
>>> [-0.5]
```

