Buckets:

hf-doc-build
/

doc

Files

xet

hf-doc-build/doc / diffusers /main /pt /api /schedulers /block_refinement.md

mishig

8 days ago

preview code

download

raw

9.98 kB

# BlockRefinementScheduler

O `BlockRefinementScheduler` gerencia o refinamento iterativo por bloco para difusão de tokens discretos. A cada etapa, ele confirma os tokens mais confiantes e, opcionalmente, edita tokens já confirmados quando o modelo prevê um token diferente com alta confiança.

Este scheduler é usado por [LLaDA2Pipeline](/docs/diffusers/main/pt/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)
```

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

Agendador para refinamento iterativo por blocos (commit por confiança).

A cada etapa, o agendador amostra tokens candidatos dos logits do modelo e confirma aqueles com a maior confiança. O número de tokens a serem confirmados por etapa é determinado distribuindo uniformemente o comprimento do bloco pelo número de etapas de refinamento.

Suporta opcionalmente edição: após todos os tokens de máscara serem resolvidos, os tokens podem ser substituídos se o modelo prever um token diferente com confiança acima de um `editing_threshold` positivo (`None`, `0.0` ou negativo desativa a edição).

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

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

**Parâmetros:**

original_samples (`torch.LongTensor` de forma `(batch_size, seq_len)`) : IDs de tokens limpos.
attention_mask (`torch.LongTensor` de forma `(batch_size, seq_len)`) : Máscara de preenchimento (1 para válido, 0 para preenchimento).

prompt_length (`int`) : Número de tokens de prompt iniciais a manter sem máscara.
block_length (`int`) : Tamanho do bloco para mascaramento.

mask_token_id (`int`) : ID do token a ser usado para posições mascaradas.

generator (`torch.Generator`, *opcional*) : RNG para reprodutibilidade.

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

`(noisy, noisy_rev, masked, masked_rev)` — as duas sequências ruidosas complementares e suas respectivas máscaras booleanas.

Aplique o processo de encaminhamento (adição de ruído) para mascaramento de blocos semi-autorregressivos.

Para cada bloco após o prompt, uma fração aleatória de tokens válidos (não de preenchimento) é substituída por `mask_token_id`. Duas visões complementares são retornadas: `noisy` e `noisy_rev`, em que as posições mascaradas em uma correspondem às posições não mascaradas na outra.

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

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

**Parâmetros:**

step_idx (`int`) : Índice atual da etapa de refinamento dentro deste bloco.
masks_remaining (`bool`) : Se há tokens de máscara restantes no bloco.

editing_enabled (`bool`) : Se o modo de edição está ativo.
editing_transfer_index (`torch.BoolTensor`) : Quais tokens foram editados nesta etapa.
post_steps (`int`) : Número de etapas de edição pós-máscara realizadas até o momento.

max_post_steps (`int`) : Etapas de edição pós-máscara máximas permitidas.

finished (`torch.BoolTensor`) : Flags de conclusão por lote (da detecção de EOS).

**Retorna:** `bool`

`True` se o refinamento deve continuar, `False` para interromper.

Determine se o loop de refinamento interno deve continuar para o bloco atual.

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

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

**Parâmetros:**

cur_x (`torch.LongTensor` de forma `(batch_size, seq_len)`) : Sequência completa atual, incluindo todos os blocos até a janela atual.
sampled_tokens (`torch.LongTensor` de forma `(batch_size, block_length)`) : Tokens amostrados pelo agendador nesta etapa.

final_transfer (`torch.BoolTensor` de forma `(batch_size, block_length)`) : Máscara combinada das posições confirmadas e editadas.
finished (`torch.BoolTensor` de forma `(batch_size,)`) : Flags de finalização atuais por lote.

eos_token_id (`int`) : ID do token EOS.

mask_token_id (`int`) : ID do token de máscara.

prompt_length (`int`) : Número de tokens de prompt no início da sequência.
**Retorna:** `torch.BoolTensor`
Atualizados os flags de finalização.
Atualize as flags de conclusão por lote quando os tokens EOS forem confirmados.
#### get_num_transfer_tokens[[diffusers.BlockRefinementScheduler.get_num_transfer_tokens]]
```python
get_num_transfer_tokens(block_length: int, num_inference_steps: int)
```
[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/schedulers/scheduling_block_refinement.py#L102)
Distribua uniformemente os `block_length` tokens entre as `num_inference_steps` etapas.

#### etapa[[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)
```

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

**Parâmetros:**

model_output (`torch.Tensor` de forma `(batch_size, block_length, vocab_size)`) : Logits brutos do modelo para o bloco atual.

timestep (`int` ou `torch.Tensor`) : Índice do passo atual dentro da agenda de refinamento do bloco.

sample (`torch.LongTensor` de forma `(batch_size, block_length)`) : IDs dos tokens do bloco atual (contém tokens de máscara para posições não confirmadas no modo baseado em máscara).

mask_token_id (`int`, *opcional*) : ID do token usado para posições mascaradas. Quando `None`, o agendador opera no modo de corrupção uniforme: ele rastreia internamente as posições confirmadas (reiniciando em `timestep == 0`) e re-ruidifica as não confirmadas com tokens aleatórios uniformes, correspondendo ao amostrador de refinamento de blocos do DiffusionGemma.

temperature (`float`) : Temperatura de amostragem.

top_p (`float`, *opcional*) : Corte de amostragem por núcleo.
top_k (`int`, *opcional*) : Corte de amostragem Top-k.

sampling_method (`str`) : Método de amostragem (`auto`, `greedy`, `multinomial`).
threshold (`float`, *opcional*) : Limiar de confiança para confirmar tokens. O valor padrão é o definido na configuração.
editing_threshold (`float`, *opcional*) : Limiar de confiança para edição de tokens não mascarados; deve ser positivo para habilitar a edição. O valor padrão é o da configuração.

minimal_topk (`int`, *opcional*) : Número mínimo de tokens a serem confirmados por etapa. O valor padrão é o definido na configuração.
prompt_mask (`torch.BoolTensor`, *opcional*) : Máscara booleana de forma `(block_length,)` onde `True` marca as posições do prompt (não editáveis).

generator (`torch.Generator`, *opcional*) : RNG para amostragem.

return_dict (`bool`) : Se deve retornar um `BlockRefinementSchedulerOutput` ou uma tupla.
Execute uma etapa única de refinamento: amostrar dos logits, confirmar tokens confiantes e, opcionalmente, editar os existentes.
## 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)
```
[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/schedulers/scheduling_block_refinement.py#L27)
**Parâmetros:**
prev_sample (`torch.LongTensor` de forma `(batch_size, block_length)`) : Tokens de bloco atualizados após a etapa de refinamento atual.
transfer_index (`torch.BoolTensor` de forma `(batch_size, block_length)`) : Máscara booleana indicando quais tokens foram confirmados (preenchimento de máscara).
editing_transfer_index (`torch.BoolTensor` de forma `(batch_size, block_length)`) : Máscara booleana indicando quais tokens foram editados (substituição não mascarada).
sampled_tokens (`torch.LongTensor` de forma `(batch_size, block_length)`) : IDs de tokens amostrados dos logits do modelo.
sampled_probs (`torch.Tensor` de forma `(batch_size, block_length)`) : Probabilidades dos tokens amostrados.
pred_logits (`torch.Tensor` de forma `(batch_size, block_length, vocab_size)`) : Os logits do denoiser, passados adiante para autocondicionar o próximo passo.
Classe de saída para agendamento de refinamento de blocos.

Xet Storage Details

Size:: 9.98 kB
Xet hash:: 3e5f070ed0cb1d16c04f8fc3e36531b5e724bfd17e9b7807528804c99e7a2966

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.

	# BlockRefinementScheduler

	O `BlockRefinementScheduler` gerencia o refinamento iterativo por bloco para difusão de tokens discretos. A cada etapa, ele confirma os tokens mais confiantes e, opcionalmente, edita tokens já confirmados quando o modelo prevê um token diferente com alta confiança.

	Este scheduler é usado por [LLaDA2Pipeline](/docs/diffusers/main/pt/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)
	```

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

	Agendador para refinamento iterativo por blocos (commit por confiança).

	A cada etapa, o agendador amostra tokens candidatos dos logits do modelo e confirma aqueles com a maior confiança. O número de tokens a serem confirmados por etapa é determinado distribuindo uniformemente o comprimento do bloco pelo número de etapas de refinamento.

	Suporta opcionalmente edição: após todos os tokens de máscara serem resolvidos, os tokens podem ser substituídos se o modelo prever um token diferente com confiança acima de um `editing_threshold` positivo (`None`, `0.0` ou negativo desativa a edição).

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

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

	Parâmetros:

	original_samples (`torch.LongTensor` de forma `(batch_size, seq_len)`) : IDs de tokens limpos.

	attention_mask (`torch.LongTensor` de forma `(batch_size, seq_len)`) : Máscara de preenchimento (1 para válido, 0 para preenchimento).

	prompt_length (`int`) : Número de tokens de prompt iniciais a manter sem máscara.

	block_length (`int`) : Tamanho do bloco para mascaramento.

	mask_token_id (`int`) : ID do token a ser usado para posições mascaradas.

	generator (`torch.Generator`, opcional) : RNG para reprodutibilidade.

	Retorna: `tuple[torch.LongTensor, torch.LongTensor, torch.BoolTensor, torch.BoolTensor]`

	`(noisy, noisy_rev, masked, masked_rev)` — as duas sequências ruidosas complementares e suas respectivas máscaras booleanas.

	Aplique o processo de encaminhamento (adição de ruído) para mascaramento de blocos semi-autorregressivos.

	Para cada bloco após o prompt, uma fração aleatória de tokens válidos (não de preenchimento) é substituída por `mask_token_id`. Duas visões complementares são retornadas: `noisy` e `noisy_rev`, em que as posições mascaradas em uma correspondem às posições não mascaradas na outra.

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

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

	Parâmetros:

	step_idx (`int`) : Índice atual da etapa de refinamento dentro deste bloco.

	masks_remaining (`bool`) : Se há tokens de máscara restantes no bloco.

	editing_enabled (`bool`) : Se o modo de edição está ativo.

	editing_transfer_index (`torch.BoolTensor`) : Quais tokens foram editados nesta etapa.

	post_steps (`int`) : Número de etapas de edição pós-máscara realizadas até o momento.

	max_post_steps (`int`) : Etapas de edição pós-máscara máximas permitidas.

	finished (`torch.BoolTensor`) : Flags de conclusão por lote (da detecção de EOS).

	Retorna: `bool`

	`True` se o refinamento deve continuar, `False` para interromper.

	Determine se o loop de refinamento interno deve continuar para o bloco atual.

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

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

	Parâmetros:

	cur_x (`torch.LongTensor` de forma `(batch_size, seq_len)`) : Sequência completa atual, incluindo todos os blocos até a janela atual.

	sampled_tokens (`torch.LongTensor` de forma `(batch_size, block_length)`) : Tokens amostrados pelo agendador nesta etapa.

	final_transfer (`torch.BoolTensor` de forma `(batch_size, block_length)`) : Máscara combinada das posições confirmadas e editadas.

	finished (`torch.BoolTensor` de forma `(batch_size,)`) : Flags de finalização atuais por lote.

	eos_token_id (`int`) : ID do token EOS.

	mask_token_id (`int`) : ID do token de máscara.

	prompt_length (`int`) : Número de tokens de prompt no início da sequência.

	Retorna: `torch.BoolTensor`

	Atualizados os flags de finalização.

	Atualize as flags de conclusão por lote quando os tokens EOS forem confirmados.

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

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

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

	Distribua uniformemente os `block_length` tokens entre as `num_inference_steps` etapas.

	#### etapa[[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)
	```

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

	Parâmetros:

	model_output (`torch.Tensor` de forma `(batch_size, block_length, vocab_size)`) : Logits brutos do modelo para o bloco atual.

	timestep (`int` ou `torch.Tensor`) : Índice do passo atual dentro da agenda de refinamento do bloco.

	sample (`torch.LongTensor` de forma `(batch_size, block_length)`) : IDs dos tokens do bloco atual (contém tokens de máscara para posições não confirmadas no modo baseado em máscara).

	mask_token_id (`int`, opcional) : ID do token usado para posições mascaradas. Quando `None`, o agendador opera no modo de corrupção uniforme: ele rastreia internamente as posições confirmadas (reiniciando em `timestep == 0`) e re-ruidifica as não confirmadas com tokens aleatórios uniformes, correspondendo ao amostrador de refinamento de blocos do DiffusionGemma.

	temperature (`float`) : Temperatura de amostragem.

	top_p (`float`, opcional) : Corte de amostragem por núcleo.

	top_k (`int`, opcional) : Corte de amostragem Top-k.

	sampling_method (`str`) : Método de amostragem (`auto`, `greedy`, `multinomial`).

	threshold (`float`, opcional) : Limiar de confiança para confirmar tokens. O valor padrão é o definido na configuração.

	editing_threshold (`float`, opcional) : Limiar de confiança para edição de tokens não mascarados; deve ser positivo para habilitar a edição. O valor padrão é o da configuração.

	minimal_topk (`int`, opcional) : Número mínimo de tokens a serem confirmados por etapa. O valor padrão é o definido na configuração.

	prompt_mask (`torch.BoolTensor`, opcional) : Máscara booleana de forma `(block_length,)` onde `True` marca as posições do prompt (não editáveis).

	generator (`torch.Generator`, opcional) : RNG para amostragem.

	return_dict (`bool`) : Se deve retornar um `BlockRefinementSchedulerOutput` ou uma tupla.

	Execute uma etapa única de refinamento: amostrar dos logits, confirmar tokens confiantes e, opcionalmente, editar os existentes.

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

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

	Parâmetros:

	prev_sample (`torch.LongTensor` de forma `(batch_size, block_length)`) : Tokens de bloco atualizados após a etapa de refinamento atual.

	transfer_index (`torch.BoolTensor` de forma `(batch_size, block_length)`) : Máscara booleana indicando quais tokens foram confirmados (preenchimento de máscara).

	editing_transfer_index (`torch.BoolTensor` de forma `(batch_size, block_length)`) : Máscara booleana indicando quais tokens foram editados (substituição não mascarada).

	sampled_tokens (`torch.LongTensor` de forma `(batch_size, block_length)`) : IDs de tokens amostrados dos logits do modelo.

	sampled_probs (`torch.Tensor` de forma `(batch_size, block_length)`) : Probabilidades dos tokens amostrados.

	pred_logits (`torch.Tensor` de forma `(batch_size, block_length, vocab_size)`) : Os logits do denoiser, passados adiante para autocondicionar o próximo passo.

	Classe de saída para agendamento de refinamento de blocos.