# BlockRefinementScheduler

Le `BlockRefinementScheduler` gère le raffinement itératif par blocs pour la diffusion de jetons discrets. À chaque étape, il valide les jetons les plus confiants et modifie éventuellement les jetons déjà validés lorsque le modèle prédit un jeton différent avec une forte confiance.

Ce planificateur est utilisé par [LLaDA2Pipeline](/docs/diffusers/main/fr/api/pipelines/llada2#diffusers.LLaDA2Pipeline).

## BlockRefinementScheduler[[diffusers.BlockRefinementScheduler]]

#### diffusers.BlockRefinementScheduler[[diffusers.BlockRefinementScheduler]]

```python
diffusers.BlockRefinementScheduler(block_length: int = 32, num_inference_steps: int = 32, threshold: float = 0.95, editing_threshold: float | None = None, minimal_topk: int = 1)
```

[Source](https://github.com/huggingface/diffusers/blob/main/src/diffusers/schedulers/scheduling_block_refinement.py#L54)

Planificateur pour le raffinement itératif par blocs (engagement par confiance).

À chaque étape, le planificateur échantillonne des jetons candidats à partir des logits du modèle et valide ceux qui présentent la plus forte confiance. Le nombre de jetons à valider par étape est déterminé en répartissant uniformément la longueur du bloc sur le nombre d'étapes de raffinement.

Prend en charge la modification en option : une fois tous les jetons de masque résolus, les jetons peuvent être remplacés si le modèle prédit un jeton différent avec une confiance supérieure à un `editing_threshold` positif (`None`, `0.0` ou une valeur négative désactive la modification).

#### add_noise[[diffusers.BlockRefinementScheduler.add_noise]]

```python
add_noise(original_samples: torch.LongTensor, attention_mask: torch.LongTensor, prompt_length: int, block_length: int, mask_token_id: int, generator: torch.Generator | None = None)
```

[Source](https://github.com/huggingface/diffusers/blob/main/src/diffusers/schedulers/scheduling_block_refinement.py#L456)

**Paramètres :**

original_samples (`torch.LongTensor` de forme `(batch_size, seq_len)`) : ID de jetons propres.

attention_mask (`torch.LongTensor` de forme `(batch_size, seq_len)`) : Masque de bourrage (1 pour les positions valides, 0 pour le bourrage).

prompt_length (`int`) : Nombre de jetons de prompt initiaux à conserver non masqués.

block_length (`int`) : Taille du bloc pour le masquage.

mask_token_id (`int`) : ID de jeton à utiliser pour les positions masquées.

generator (`torch.Generator`, *facultatif*) : générateur de nombres aléatoires pour la reproductibilité.

**Retourne :** `tuple[torch.LongTensor, torch.LongTensor, torch.BoolTensor, torch.BoolTensor]`

`(noisy, noisy_rev, masked, masked_rev)` — les deux séquences bruitées complémentaires et leurs masques booléens correspondants.

Appliquer le processus avant (bruitage) pour le masquage de blocs semi-autorégressifs.

Pour chaque bloc après le prompt, une fraction aléatoire de jetons valides (non de bourrage) est remplacée par `mask_token_id`. Deux vues complémentaires sont renvoyées : `noisy` et `noisy_rev`, où les positions masquées dans l'une correspondent aux positions non masquées dans l'autre.

#### check_block_should_continue[[diffusers.BlockRefinementScheduler.check_block_should_continue]]

```python
check_block_should_continue(step_idx: int, masks_remaining: bool, editing_enabled: bool, editing_transfer_index: torch.BoolTensor, post_steps: int, max_post_steps: int, finished: torch.BoolTensor)
```

[Source](https://github.com/huggingface/diffusers/blob/main/src/diffusers/schedulers/scheduling_block_refinement.py#L412)

**Paramètres :**

step_idx (`int`) : Index de l'étape de raffinement actuelle au sein de ce bloc.

masks_remaining (`bool`) : Indique s'il reste des jetons de masque dans le bloc.

editing_enabled (`bool`) : Indique si le mode d'édition est actif.

editing_transfer_index (`torch.BoolTensor`) : Les jetons modifiés à cette étape.

post_steps (`int`) : Nombre d'étapes d'édition post-masque effectuées jusqu'à présent.

max_post_steps (`int`) : Nombre maximal de étapes d'édition autorisées après le masquage.

finished (`torch.BoolTensor`) : Indicateurs de fin par lot (issus de la détection de EOS).

**Retourne :** `bool`

`True` si le raffinement doit se poursuivre, `False` pour l’interrompre.

Déterminer si la boucle de raffinement interne doit se poursuivre pour le bloc actuel.

#### check_eos_finished[[diffusers.BlockRefinementScheduler.check_eos_finished]]

```python
check_eos_finished(cur_x: torch.LongTensor, sampled_tokens: torch.LongTensor, final_transfer: torch.BoolTensor, finished: torch.BoolTensor, eos_token_id: int, mask_token_id: int, prompt_length: int)
```

[Source](https://github.com/huggingface/diffusers/blob/main/src/diffusers/schedulers/scheduling_block_refinement.py#L362)

**Paramètres :**

cur_x (`torch.LongTensor` de forme `(batch_size, seq_len)`) : Séquence complète actuelle incluant tous les blocs jusqu'à la fenêtre courante.

sampled_tokens (`torch.LongTensor` de forme `(batch_size, block_length)`) : Jetons échantillonnés par le planificateur à cette étape.

final_transfer (`torch.BoolTensor` de forme `(batch_size, block_length)`) : Masque combiné des positions validées et modifiées.

finished (`torch.BoolTensor` de forme `(batch_size,)`) : Drapeaux de fin actuels par lot.

eos_token_id (`int`) : ID du jeton EOS.

mask_token_id (`int`) : ID du jeton de masque.

prompt_length (`int`) : Nombre de jetons de l'invite au début de la séquence.

**Retourne :** `torch.BoolTensor`

Mise à jour des indicateurs de fin.

Mettre à jour les indicateurs de fin par lot lorsque les jetons EOS sont validés.

#### get_num_transfer_tokens[[diffusers.BlockRefinementScheduler.get_num_transfer_tokens]]

```python
get_num_transfer_tokens(block_length: int, num_inference_steps: int)
```

[Source](https://github.com/huggingface/diffusers/blob/main/src/diffusers/schedulers/scheduling_block_refinement.py#L102)

Répartir uniformément les `block_length` jetons sur `num_inference_steps` étapes.

#### étape[[diffusers.BlockRefinementScheduler.step]]

```python
step(model_output: torch.Tensor, timestep: int | torch.Tensor, sample: torch.LongTensor, mask_token_id: int | None = None, temperature: float = 0.0, top_p: float | None = None, top_k: int | None = None, sampling_method: str = 'auto', threshold: float | None = None, editing_threshold: float | None = None, minimal_topk: int | None = None, prompt_mask: torch.BoolTensor | None = None, generator: torch.Generator | None = None, return_dict: bool = True)
```

[Source](https://github.com/huggingface/diffusers/blob/main/src/diffusers/schedulers/scheduling_block_refinement.py#L181)

**Paramètres :**

model_output (`torch.Tensor` de forme `(batch_size, block_length, vocab_size)`) : Logits bruts du modèle pour le bloc actuel.

timestep (`int` ou `torch.Tensor`) : Index de l'étape actuelle dans le calendrier de raffinement du bloc.

sample (`torch.LongTensor` de forme `(batch_size, block_length)`) : ID des jetons du bloc actuel (contient des jetons de masque pour les positions non confirmées en mode basé sur le masque).

mask_token_id (`int`, *facultatif*) : ID de jeton utilisé pour les positions masquées. Lorsque `None`, le planificateur fonctionne en mode de corruption uniforme : il suit les positions validées en interne (réinitialisées à `timestep == 0`) et ré-ajoute du bruit aux positions non validées avec des jetons aléatoires uniformes, conformément à l'échantillonneur de raffinement par blocs de DiffusionGemma.

temperature (`float`) : Température d'échantillonnage.

top_p (`float`, *facultatif*) : Seuil d'échantillonnage par noyau.

top_k (`int`, *facultatif*) : Seuil d'échantillonnage Top-k.

sampling_method (`str`) : Méthode d'échantillonnage (`auto`, `greedy`, `multinomial`).

threshold (`float`, *facultatif*) : Seuil de confiance pour valider les jetons. Par défaut, la valeur de la configuration est utilisée.

editing_threshold (`float`, *facultatif*) : Seuil de confiance pour l'édition des jetons non masqués ; doit être positif pour activer l'édition. Valeur par défaut : valeur de la configuration.

minimal_topk (`int`, *facultatif*) : Nombre minimal de jetons à valider à chaque étape. Par défaut, la valeur de la configuration est utilisée.

prompt_mask (`torch.BoolTensor`, *facultatif*) : masque booléen de forme `(block_length,)` où `True` marque les positions du prompt (non modifiables).

generator (`torch.Generator`, *facultatif*) : générateur de nombres aléatoires pour l'échantillonnage.

return_dict (`bool`) : Indique s'il faut retourner un `BlockRefinementSchedulerOutput` ou un tuple.

Effectuer une étape unique de raffinement : échantillonner à partir des logits, valider les jetons confiants et, le cas échéant, modifier les jetons existants.

## BlockRefinementSchedulerOutput[[diffusers.BlockRefinementSchedulerOutput]]

#### diffusers.BlockRefinementSchedulerOutput[[diffusers.BlockRefinementSchedulerOutput]]

```python
diffusers.BlockRefinementSchedulerOutput(prev_sample: torch.LongTensor, transfer_index: torch.BoolTensor, editing_transfer_index: torch.BoolTensor, sampled_tokens: torch.LongTensor, sampled_probs: torch.Tensor, pred_logits: torch.Tensor)
```

[Source](https://github.com/huggingface/diffusers/blob/main/src/diffusers/schedulers/scheduling_block_refinement.py#L27)

**Paramètres :**

prev_sample (`torch.LongTensor` de forme `(batch_size, block_length)`) : Jetons de bloc mis à jour après l'étape de raffinement actuelle.

transfer_index (`torch.BoolTensor` de forme `(batch_size, block_length)`) : masque booléen indiquant quels jetons ont été validés (remplissage du masque).

editing_transfer_index (`torch.BoolTensor` de forme `(batch_size, block_length)`) : masque booléen indiquant quels jetons ont été modifiés (remplacement non masqué).

sampled_tokens (`torch.LongTensor` de forme `(batch_size, block_length)`) : Identifiants des jetons échantillonnés à partir des logits du modèle.

sampled_probs (`torch.Tensor` de forme `(batch_size, block_length)`) : Probabilités des jetons échantillonnés.

pred_logits (`torch.Tensor` de forme `(batch_size, block_length, vocab_size)`) : Les logits du débruiteur, transmis pour l'auto-conditionnement de l'étape suivante.

Classe de sortie pour la planification du raffinement de blocs.