TRL documentation

Fungsi Reward

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Fungsi Reward

Modul ini berisi beberapa fungsi reward yang berguna, terutama ditujukan untuk digunakan dengan GRPOTrainer dan RLOOTrainer.

accuracy_reward

trl.rewards.accuracy_reward

< >

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

Parameter

  • completions (list[list[dict[str, str]]]) — Daftar completion yang akan dievaluasi. Setiap completion harus berupa daftar berisi satu pesan, yaitu kamus 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, yang disediakan secara otomatis oleh trainer. Nilainya secara default 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.

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:

>>> 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

< >

( completions: list[list[dict[str, str]]]solution: list[str]reasoning_delimiters: list[str] | None = Nonelog_extra: collections.abc.Callable[[str, list], None] | None = None**kwargs )

Parameter

  • completions (list[list[dict[str, str]]]) — Daftar completion yang akan dievaluasi. Setiap completion harus berupa daftar berisi satu pesan, yaitu kamus 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, yang disediakan secara otomatis oleh trainer. Nilainya secara default 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.

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:

>>> 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

< >

( max_len: intmin_value_wrong: float = -1.0max_value_wrong: float = -0.5min_value_correct: float = 0.5max_value_correct: float = 1.0 ) → Callable

Parameter

  • max_len (int) — Panjang maksimum penyelesaian (dalam token) yang digunakan untuk menormalisasi jadwal kosinus, $L_{\max}$.
  • min_value_wrong (float, opsional, default -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 dalam accuracy_reward()), dan panjangnya adalah jumlah token penyelesaian. Reward diinterpolasi sepanjang jadwal kosinus antara batas penyelesaian pendek dan penyelesaian panjang: Rcosine(y)=vmin⁡+12(vmax⁡−vmin⁡)(1+cos⁡(∣y∣Lmax⁡π)) 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, batas-batasnya ditukar menjadi $(v{\min}, v{\max}) = (\texttt{max_value_wrong}, \texttt{min_value_wrong})$, sehingga penyelesaian yang lebih pendek diberi penalti lebih besar (penyelesaian salah yang lebih panjang diberi penalti lebih kecil, sehingga eksplorasi tetap terjaga). Ketika solusi emas tidak dapat diurai, contoh tersebut dilewati (imbalan None), sebagaimana pada accuracy_reward().

Contoh:

>>> 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

< >

( completions: list[list[dict[str, str]]]**kwargs ) → list[float]

Parameter

  • completions (list[list[dict[str, str]]]) — Daftar completion yang akan dievaluasi. Setiap completion harus berupa daftar berisi satu pesan, yaitu kamus 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.

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:

>>> 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

< >

( ngram_size: int = 3max_penalty: float = -1.0 ) → Callable

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 ini berbanding lurus dengan fraksi n-gram yang berulang dalam penyelesaian: Rrepetition(y)=(1−# unique n-grams# total n-grams)×p R_{\text{repetition}}(y) = \left(1 - \frac{\#\,\text{unique } n\text{-grams}}{\#\,\text{total } n\text{-grams}}\right) \times p

di mana pp adalah max_penalty. Sebuah completion yang tidak memiliki n-gram berulang mendapatkan reward sebesar 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 mendapatkan reward sebesar 0.0.

Contoh:

>>> 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

< >

( max_completion_len: intsoft_punish_cache: int )

Parameter

  • max_completion_len (int) — Panjang maksimum dari completion, ( L_{\max} ).
  • soft_punish_cache (int) — Panjang minimum dari completion, ( L_{\text{cache}‌} ). Jika diatur ke 0, tidak ada panjang minimum yang 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) Rlength(y)={0,∣y∣≤Lmax⁡−Lcache(Lmax⁡−Lcache)−∣y∣Lcache,Lmax⁡−Lcache<∣y∣≤Lmax⁡−1,Lmax⁡<∣y∣ 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:

>>> 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]
Update on GitHub