# Fonctions de récompense

Ce module contient certaines fonctions de récompense utiles, destinées principalement à être utilisées avec [GRPOTrainer](/docs/trl/v1.18.2/fr/grpo_trainer#trl.GRPOTrainer) et [RLOOTrainer](/docs/trl/v1.18.2/fr/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)
```

[Source](https://github.com/huggingface/trl/blob/v1.18.2/trl/rewards/accuracy_rewards.py#L127)

**Paramètres :**

completions (`list[list[dict[str, str]]]`) : Liste des complétions à évaluer. Chaque complétion doit être une liste d'un seul message, c'est-à-dire un dictionnaire contenant la clé `"content"` dont la valeur est le texte de la complétion.

solution (`list[str]`) : Liste des solutions au format texte brut aux questions / problèmes / invites.

log_extra (`callable`, *facultatif*) : Fonction à appeler pour journaliser des colonnes supplémentaires dans le tableau des complétions, fournie automatiquement par le formateur. La valeur par défaut est `None` pour permettre d'appeler la fonction directement en dehors d'un formateur (par exemple, pour les tests).

- ****kwargs** : Arguments supplémentaires par mot-clé. Cette fonction ne les utilise pas, mais ils sont requis dans la signature de la fonction pour garantir la compatibilité avec des formateurs comme [GRPOTrainer](/docs/trl/v1.18.2/fr/grpo_trainer#trl.GRPOTrainer).

Fonction de récompense qui vérifie si l'achèvement correspond à la vérité de terrain.
- Si la référence et la prédiction sont toutes deux analysables → utiliser la vérification mathématique.
- Si l'or n'est pas analysable → retourner `None` pour ignorer l'exemple.

Exemple :
```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)
```

[Source](https://github.com/huggingface/trl/blob/v1.18.2/trl/rewards/accuracy_rewards.py#L290)

**Paramètres :**

completions (`list[list[dict[str, str]]]`) : Liste des complétions à évaluer. Chaque complétion doit être une liste d'un seul message, c'est-à-dire un dictionnaire contenant la clé `"content"` dont la valeur est le texte de la complétion.

solution (`list[str]`) : Liste des solutions au format texte brut aux questions / problèmes / invites.

reasoning_delimiters (`list[str]]`, *facultatif*) : Liste de chaînes de caractères indiquant où se termine le contenu de raisonnement. La réponse finale est supposée se situer après la dernière occurrence de l'un de ces délimiteurs. Si `None`, la valeur par défaut est `["</think>"]`.

log_extra (`callable`, *facultatif*) : Fonction à appeler pour journaliser des colonnes supplémentaires dans le tableau des complétions, fournie automatiquement par le formateur. La valeur par défaut est `None` pour permettre d'appeler la fonction directement en dehors d'un formateur (par exemple, pour les tests).

- ****kwargs** : Arguments supplémentaires par mot-clé. Cette fonction ne les utilise pas, mais ils sont requis dans la signature de la fonction pour garantir la compatibilité avec des formateurs comme [GRPOTrainer](/docs/trl/v1.18.2/fr/grpo_trainer#trl.GRPOTrainer).

Fonction de récompense qui supprime le contenu de raisonnement et vérifie si la réponse finale correspond à la vérité de terrain.
- Si la référence et la prédiction sont toutes deux analysables → utiliser la vérification mathématique.
- Si l'or n'est pas analysable → retourner `None` pour ignorer l'exemple.

Exemple :
```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)
```

[Source](https://github.com/huggingface/trl/blob/v1.18.2/trl/rewards/accuracy_rewards.py#L185)

**Paramètres :**

max_len (`int`) : Longueur maximale de complétion (en jetons) utilisée pour normaliser le plan cosinus, $L_{\max}$.

min_value_wrong (`float`, *facultatif*, par défaut `-1.0`) : Récompense d'une complétion incorrecte à la longueur minimale.

max_value_wrong (`float`, *facultatif*, valeur par défaut `-0.5`) : Récompense d'une complétion incorrecte à la longueur maximale.

min_value_correct (`float`, *facultatif*, valeur par défaut `0.5`) : Récompense d'une complétion correcte à la longueur maximale.

max_value_correct (`float`, *facultatif*, par défaut `1.0`) : Récompense d'une complétion correcte à la longueur la plus courte.

**Retourne :** `Callable`

Une fonction de récompense qui prend des complétions, leurs solutions et les identifiants de jetons, et renvoie une liste de récompenses (`None` pour les exemples dont la solution dorée n'est pas analysable).

Fonction de récompense qui met à l'échelle une récompense de justesse en fonction de la longueur de la complétion, selon un calendrier cosinus, afin de favoriser un raisonnement concis. Référence : Annexe C.1 de l'article « Demystifying Long Chain-of-Thought Reasoning » (https://huggingface.co/papers/2502.03373).

La justesse est déterminée par la vérification mathématique (comme dans [accuracy_reward()](/docs/trl/v1.18.2/fr/rewards#trl.rewards.accuracy_reward)), et la longueur correspond au nombre de jetons de complétion. La récompense est interpolée selon un calendrier cosinus entre une borne de complétion courte et une borne de complétion longue :

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

Pour une complétion **correcte**, $(v_{\min}, v_{\max}) = (\texttt{min\_value\_correct}, \texttt{max\_value\_correct})$, de sorte qu'une complétion plus courte est davantage récompensée. Pour une complétion **erronée**, les bornes sont inversées : $(v_{\min}, v_{\max}) = (\texttt{max\_value\_wrong}, \texttt{min\_value\_wrong})$, de sorte qu'une complétion plus courte est davantage pénalisée (une complétion erronée plus longue est moins pénalisée, ce qui préserve l'exploration). Lorsque la solution de référence n'est pas analysable, l'exemple est ignoré (récompense `None`), comme dans [accuracy_reward()](/docs/trl/v1.18.2/fr/rewards#trl.rewards.accuracy_reward).

Exemple :
```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)
```

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

**Paramètres :**

completions (`list[list[dict[str, str]]]`) : Liste des complétions à évaluer. Chaque complétion doit être une liste d'un seul message, c'est-à-dire un dictionnaire contenant la clé `"content"` dont la valeur est le texte de la complétion.

- ****kwargs** : Arguments supplémentaires par mot-clé. Cette fonction ne les utilise pas, mais ils sont requis dans la signature de la fonction pour garantir la compatibilité avec des formateurs comme [GRPOTrainer](/docs/trl/v1.18.2/fr/grpo_trainer#trl.GRPOTrainer).

**Retourne :** `list[float]`

Une liste de récompenses, où chaque récompense vaut 1.0 si l'achèvement correspond au format attendu, et 0.0 sinon.

Fonction de récompense qui vérifie si le processus de raisonnement est encadré par les balises `"<think>"` et `"</think>"`. La fonction renvoie une récompense de 1.0 si le format est correct, sinon 0.0.

Exemple :
```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)
```

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

**Paramètres :**

ngram_size (`int`, *facultatif*, par défaut `3`) : Taille des n-grammes de jetons à prendre en compte.

max_penalty (`float`, *facultatif*, valeur par défaut `-1.0`) : Pénalité négative maximale, appliquée à une complétion entièrement répétitive. Doit être non positive.

**Retourne :** `Callable`

Une fonction de récompense qui prend une liste d'identifiants de jetons de complétion et renvoie une liste de pénalités (chacune dans `[max_penalty, 0.0]`).

Fonction de récompense qui pénalise les n-grammes répétés dans une complétion, utilisée pour décourager les textes dégénérés et répétitifs (un mode d’échec courant et une stratégie de fraude de la récompense lorsque des récompenses de façonnage de la longueur ou du format sont utilisées). Référence : Annexe C.2 de l’article « Demystifying Long Chain-of-Thought Reasoning » (https://huggingface.co/papers/2502.03373).

La pénalité est proportionnelle à la fraction de n-grammes répétés dans la complétion :

$$ R_{\text{repetition}}(y) = \left(1 - \frac{\#\,n\text{-grammes uniques}}{\#\,n\text{-grammes totaux}}\right) \times p $$

où $p$ est `max_penalty`. Une complétion sans n-gramme répété reçoit une récompense de `0.0`, tandis qu’une complétion entièrement répétitive se rapproche de `max_penalty`. Les n-grammes sont calculés sur les identifiants de jetons de la complétion (l’article applique la pénalité aux jetons répétés), de sorte que la récompense est définie par le tokeniseur et indépendante de la langue. Les complétions contenant moins de `ngram_size` jetons reçoivent une récompense de `0.0`.

Exemple :
```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)
```

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

**Paramètres :**

max_completion_len (`int`) : Longueur maximale de la complétion,  \( L_{\max} \).

soft_punish_cache (`int`) : Longueur minimale de la complétion,  \( L_{\text{cache}} \). Si défini à `0`, aucune longueur minimale n'est appliquée.

Fonction de récompense qui pénalise les compléments trop longs. Elle est utilisée pour pénaliser les compléments trop longs, mais pas pour récompenser les compléments plus courts. Référence : équation (13) de l'article 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} $$

Exemple :
```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]
```

