TRL documentation

Funciones de recompensa

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Funciones de recompensa

Este módulo contiene algunas funciones de recompensa útiles, destinadas principalmente a su uso con GRPOTrainer y 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 )

Parámetros

  • completions (list[list[dict[str, str]]]) — Lista de completions a evaluar. Cada completion debe ser una lista de un mensaje, es decir, un diccionario que contiene la clave "content" cuyo valor es el texto del completion.
  • solution (list[str]) — Lista de las soluciones en texto sin formato a las preguntas/problemas/indicaciones.
  • log_extra (callable, opcional) — Función para registrar columnas adicionales en la tabla de completados, proporcionada automáticamente por el trainer. El valor predeterminado es None para permitir llamar a la función directamente fuera de un trainer (p. ej., para pruebas).
  • **kwargs — Argumentos de palabra clave adicionales. Esta función no los utiliza, pero son necesarios en la firma de la función para garantizar la compatibilidad con entrenadores como GRPOTrainer.

Función de recompensa que comprueba si la finalización coincide con la respuesta correcta.

  • Si tanto el valor de referencia como la predicción son analizables → use la verificación matemática.
  • Si el oro no es interpretable → devuelve None para omitir el ejemplo.

Ejemplo:

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

Parámetros

  • completions (list[list[dict[str, str]]]) — Lista de completions a evaluar. Cada completion debe ser una lista de un mensaje, es decir, un diccionario que contiene la clave "content" cuyo valor es el texto del completion.
  • solution (list[str]) — Lista de las soluciones en texto sin formato a las preguntas/problemas/indicaciones.
  • reasoning_delimiters (list[str]], opcional) — Lista de cadenas que indican dónde termina el contenido de razonamiento. Se asume que la respuesta final se encuentra después de la última aparición de cualquiera de estos delimitadores. Si es None, el valor predeterminado es ["</think>"].
  • log_extra (callable, opcional) — Función para registrar columnas adicionales en la tabla de completados, proporcionada automáticamente por el trainer. El valor predeterminado es None para permitir llamar a la función directamente fuera de un trainer (p. ej., para pruebas).
  • **kwargs — Argumentos de palabra clave adicionales. Esta función no los utiliza, pero son necesarios en la firma de la función para garantizar la compatibilidad con entrenadores como GRPOTrainer.

Función de recompensa que elimina el contenido de razonamiento y comprueba si la respuesta final coincide con la respuesta correcta.

  • Si tanto el valor de referencia como la predicción son analizables → use la verificación matemática.
  • Si el oro no es interpretable → devuelve None para omitir el ejemplo.

Ejemplo:

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

Parámetros

  • max_len (int) — Longitud máxima de la finalización (en tokens) utilizada para normalizar la programación coseno, $L_{\max}$.
  • min_value_wrong (float, opcional, valor predeterminado -1.0) — Recompensa de una finalización incorrecta en la longitud más corta.
  • max_value_wrong (float, opcional, valor predeterminado -0.5) — Recompensa de una finalización incorrecta en la longitud máxima.
  • min_value_correct (float, opcional, valor predeterminado 0.5) — Recompensa de una finalización correcta en la longitud máxima.
  • max_value_correct (float, opcional, valor predeterminado 1.0) — Recompensa de una finalización correcta en la longitud más corta.

Devuelve

Callable

Una función de recompensa que toma las finalizaciones, sus soluciones y los ids de tokens, y devuelve una lista de recompensas (None para los ejemplos con una solución dorada no interpretable).

Función de recompensa que escala una recompensa de corrección según la longitud de la finalización, siguiendo un programa coseno, para favorecer el razonamiento conciso. Referencia: Apéndice C.1 del artículo “Demystifying Long Chain-of-Thought Reasoning” (https://huggingface.co/papers/2502.03373).

La corrección se determina mediante la verificación matemática (como en accuracy_reward()), y la longitud es el número de tokens de finalización. La recompensa interpola a lo largo de una programación coseno entre un límite de finalización corta y un límite de finalización larga: 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)

Para una finalización correcta, $(v{\min}, v{\max}) = (\texttt{min_value_correct}, \texttt{max_value_correct})$, por lo que una finalización más corta recibe una mayor recompensa. Para una finalización incorrecta, los límites se intercambian para $(v{\min}, v{\max}) = (\texttt{max_value_wrong}, \texttt{min_value_wrong})$, de modo que una finalización más corta se penaliza más (una finalización incorrecta más larga se penaliza menos, preservando la exploración). Cuando la solución de referencia no es analizable, el ejemplo se omite (recompensa None), al igual que en accuracy_reward().

Ejemplo:

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

Parámetros

  • completions (list[list[dict[str, str]]]) — Lista de completions a evaluar. Cada completion debe ser una lista de un mensaje, es decir, un diccionario que contiene la clave "content" cuyo valor es el texto del completion.
  • **kwargs — Argumentos de palabra clave adicionales. Esta función no los utiliza, pero son necesarios en la firma de la función para garantizar la compatibilidad con entrenadores como GRPOTrainer.

Devuelve

list[float]

Una lista de recompensas, donde cada recompensa es 1.0 si la finalización coincide con el formato esperado, y 0.0 en caso contrario.

Función de recompensa que comprueba si el proceso de razonamiento está encerrado entre las etiquetas "<think>" y "</think>". La función devuelve una recompensa de 1.0 si el formato es correcto, y 0.0 en caso contrario.

Ejemplo:

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

Parámetros

  • ngram_size (int, opcional, valor predeterminado 3) — Tamaño de los n-gramas de tokens a considerar.
  • max_penalty (float, opcional, valor predeterminado -1.0) — Penalización negativa máxima, aplicada a una finalización completamente repetitiva. Debe ser no positiva.

Devuelve

Callable

Una función de recompensa que toma una lista de ids de tokens de finalización y devuelve una lista de penalizaciones (cada una en [max_penalty, 0.0]).

Función de recompensa que penaliza los n-gramas repetidos en una finalización, utilizada para desalentar el texto degenerado y repetitivo (un modo de fallo común y una estrategia de hackeo de recompensas cuando se utilizan recompensas que moldean la longitud o el formato). Referencia: Apéndice C.2 del artículo “Demystifying Long Chain-of-Thought Reasoning” (https://huggingface.co/papers/2502.03373).

La penalización es proporcional a la fracción de n-gramas repetidos en la finalización: 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

donde pp es max_penalty. Una finalización sin n-gramas repetidos recibe una recompensa de 0.0, mientras que una completamente repetitiva se acerca a max_penalty. Los n-gramas se calculan sobre los ids de tokens de la finalización (el artículo aplica la penalización a los tokens repetidos), por lo que la recompensa está definida por el tokenizador y es independiente del idioma. Las finalizaciones con menos de ngram_size tokens reciben una recompensa de 0.0.

Ejemplo:

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

Parámetros

  • max_completion_len (int) — Longitud máxima de la finalización, ( L_{\max} ).
  • soft_punish_cache (int) — Longitud mínima de la finalización, ( L_{\text{cache}‌} ). Si se establece en 0, no se aplica ninguna longitud mínima.

Función de recompensa que penaliza las finalizaciones demasiado largas. Se utiliza para penalizar las finalizaciones demasiado largas, pero no para recompensar las finalizaciones más cortas. Referencia: Ecuación (13) del artículo 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}

Ejemplo:

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