# VQDiffusionScheduler

`VQDiffusionScheduler` converte a saída do modelo transformer em uma amostra para a imagem sem ruído no passo de difusão anterior. Foi introduzido em [Vector Quantized Diffusion Model for Text-to-Image Synthesis](https://huggingface.co/papers/2111.14822), de Shuyang Gu, Dong Chen, Jianmin Bao, Fang Wen, Bo Zhang, Dongdong Chen, Lu Yuan e Baining Guo.

O resumo do artigo é:

*Apresentamos o modelo de difusão com quantização vetorial (VQ-Diffusion) para geração de imagens a partir de texto. Este método é baseado em um autoencoder variacional com quantização vetorial (VQ-VAE) cujo espaço latente é modelado por uma variante condicional do Modelo Probabilístico de Difusão de Desruído (DDPM) desenvolvido recentemente. Verificamos que este método de espaço latente é adequado para tarefas de geração de imagens a partir de texto, pois não apenas elimina o viés unidirecional dos métodos existentes, mas também nos permite incorporar uma estratégia de difusão de máscara e substituição para evitar o acúmulo de erros, um problema sério nos métodos existentes. Nossos experimentos mostram que o VQ-Diffusion produz resultados significativamente melhores na geração de imagens a partir de texto quando comparado a modelos autoregressivos (AR) convencionais com números de parâmetros semelhantes. Em comparação com métodos anteriores baseados em GAN para geração de imagens a partir de texto, nosso VQ-Diffusion pode lidar com cenas mais complexas e melhorar a qualidade das imagens sintetizadas em grande margem. Finalmente, mostramos que o cálculo de geração de imagens em nosso método pode ser altamente eficiente por meio de reparametrização. Com os métodos AR tradicionais, o tempo de geração de imagens a partir de texto aumenta linearmente com a resolução da imagem de saída e, portanto, é bastante demorado mesmo para imagens de tamanho normal. O VQ-Diffusion nos permite alcançar um melhor equilíbrio entre qualidade e velocidade. Nossos experimentos indicam que o modelo VQ-Diffusion com reparametrização é quinze vezes mais rápido que os métodos AR tradicionais, ao mesmo tempo em que atinge uma melhor qualidade de imagem.*

## VQDiffusionScheduler[[diffusers.VQDiffusionScheduler]]

#### diffusers.VQDiffusionScheduler[[diffusers.VQDiffusionScheduler]]

```python
diffusers.VQDiffusionScheduler(num_vec_classes: int, num_train_timesteps: int = 100, alpha_cum_start: float = 0.99999, alpha_cum_end: float = 9e-06, gamma_cum_start: float = 9e-06, gamma_cum_end: float = 0.99999)
```

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

**Parâmetros:**

num_vec_classes (`int`) : O número de classes dos embeddings vetoriais dos pixels latentes. Inclui a classe para o pixel latente mascarado.

num_train_timesteps (`int`, padrão `100`) : O número de etapas de difusão para treinar o modelo.

alpha_cum_start (`float`, padrão `0.99999`) : O valor inicial de alfa cumulativo.

alpha_cum_end (`float`, padrão `0.000009`) : O valor final cumulativo de alpha.

gamma_cum_start (`float`, padrão `0.000009`) : O valor inicial de gamma cumulativo.

gamma_cum_end (`float`, padrão `0.99999`) : O valor final de gamma cumulativo.

Um agendador para difusão com quantização vetorial.

Este modelo herda de [SchedulerMixin](/docs/diffusers/main/pt/api/schedulers/overview#diffusers.SchedulerMixin) e [ConfigMixin](/docs/diffusers/main/pt/api/configuration#diffusers.ConfigMixin). Consulte a documentação da superclasse para os métodos genéricos que a biblioteca implementa para todos os agendadores, como carregamento e salvamento.

#### apply_cumulative_transitions[[diffusers.VQDiffusionScheduler.apply_cumulative_transitions]]

```python
apply_cumulative_transitions(q: Tensor, t: typing.Union[int, torch.Tensor])
```

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

**Parâmetros:**

q (`torch.Tensor` de forma `(batch size, num classes - 1, num latent pixels)`) : As probabilidades logarítmicas sobre as classes de pixels latentes não mascarados.

t (`int` ou `torch.Tensor`) : O timestep que determina qual matriz de transição cumulativa é utilizada.

**Retorna:** `torch.Tensor` de forma `(batch size, num classes, num latent pixels)`

As probabilidades de log transicionadas com as probabilidades de classe da máscara anexadas.

Aplique a matriz de transição cumulativa em um passo de tempo às probabilidades logarítmicas sobre as classes não mascaradas.

#### log_Q_t_transitioning_to_known_class[[diffusers.VQDiffusionScheduler.log_Q_t_transitioning_to_known_class]]

```python
log_Q_t_transitioning_to_known_class(t: typing.Union[int, torch.Tensor], x_t: LongTensor, log_onehot_x_t: Tensor, cumulative: bool)
```

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

**Parâmetros:**

t (`int` ou `torch.Tensor`) : O timestep que determina qual matriz de transição é utilizada.

x_t (`torch.LongTensor` de forma `(batch size, num latent pixels)`) : As classes de cada pixel latente no tempo `t`.

log_onehot_x_t (`torch.Tensor` de forma `(batch size, num classes, num latent pixels)`) : Os vetores log one-hot de `x_t`.

cumulative (`bool`) : Se cumulative for `False`, a matriz de transição de etapa única `t-1`->`t` é usada. Se cumulative for `True`, a matriz de transição cumulativa `0`->`t` é usada.

**Retorna:** `torch.Tensor`

Cada _coluna_ da matriz retornada é uma _linha_ de log probabilidades da matriz completa de transição de probabilidades. O tensor tem forma `(batch size, num classes - 1, num latent pixels)` quando `cumulative` é `True` e forma `(batch size, num classes, num latent pixels)` caso contrário.

Quando cumulativo, o tensor tem uma linha a menos porque o pixel latente inicial não pode ser mascarado.

Onde:
- `q_n` é a distribuição de probabilidade do processo de propagação do pixel latente de ordem `n`.
- C_0 é uma classe de um embedding latente de pixels
- C_k é a classe do pixel latente mascarado

resultado não cumulativo (omitindo logaritmos):
```
q_0(x_t | x_{t-1} = C_0) ... q_n(x_t | x_{t-1} = C_0)
          .      .                     .
          .               .            .
          .                      .     .
q_0(x_t | x_{t-1} = C_k) ... q_n(x_t | x_{t-1} = C_k)
```

resultado cumulativo (omitindo logaritmos):
```
q_0_cumulative(x_t | x_0 = C_0)    ...  q_n_cumulative(x_t | x_0 = C_0)
          .               .                          .
          .                        .                 .
          .                               .          .
q_0_cumulative(x_t | x_0 = C_{k-1}) ... q_n_cumulative(x_t | x_0 = C_{k-1})
```

Calcula as probabilidades logarítmicas das linhas da matriz de transição (cumulativa ou não cumulativa) para cada pixel latente em `x_t`.

#### q_posterior[[diffusers.VQDiffusionScheduler.q_posterior]]

```python
q_posterior(log_p_x_0: Tensor, x_t: LongTensor, t: typing.Union[int, torch.Tensor])
```

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

**Parâmetros:**

log_p_x_0 (`torch.Tensor` de forma `(batch size, num classes - 1, num latent pixels)`) : As probabilidades logarítmicas para as classes previstas dos pixels latentes iniciais. Não inclui uma previsão para a classe mascarada, pois a imagem inicial sem ruído não pode ser mascarada.

x_t (`torch.LongTensor` de forma `(batch size, num latent pixels)`) : As classes de cada pixel latente no tempo `t`.

t (`int` ou `torch.Tensor`) : O timestep que determina qual matriz de transição é utilizada.

**Retorna:** `torch.Tensor` de forma `(batch size, num classes, num latent pixels)`

As probabilidades de log para as classes previstas da imagem no passo de tempo `t-1`.

Calcula as probabilidades logarítmicas para as classes previstas da imagem no passo de tempo `t-1`:

```
p(x_{t-1} | x_t) = sum( q(x_t | x_{t-1}) * q(x_{t-1} | x_0) * p(x_0) / q(x_t | x_0) )
```

#### set_timesteps[[diffusers.VQDiffusionScheduler.set_timesteps]]

```python
set_timesteps(num_inference_steps: int, device: typing.Union[str, torch.device, NoneType] = None)
```

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

**Parâmetros:**

num_inference_steps (`int`) : O número de etapas de difusão usadas ao gerar amostras com um modelo pré-treinado.

device (`str` ou `torch.device`, *opcional*) : O dispositivo para o qual os timesteps e os parâmetros do processo de difusão (alpha, beta, gamma) devem ser movidos.

Define os passos discretos usados para a cadeia de difusão (a ser executado antes da inferência).

#### etapa[[diffusers.VQDiffusionScheduler.step]]

```python
step(model_output: Tensor, timestep: typing.Union[int, torch.Tensor], sample: LongTensor, generator: typing.Optional[torch.Generator] = None, return_dict: bool = True)
```

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

**Parâmetros:**

model_output (`torch.Tensor` de forma `(batch size, num classes - 1, num latent pixels)`) : As probabilidades logarítmicas para as classes previstas dos pixels latentes iniciais. Não inclui uma previsão para a classe mascarada, pois a imagem inicial sem ruído não pode ser mascarada.

timestep (`int` ou `torch.Tensor`) : O timestep que determina quais matrizes de transição são usadas.

sample (`torch.LongTensor` de forma `(batch size, num latent pixels)`) : As classes de cada pixel latente no timestep atual.

generator (`torch.Generator`, *opcional*) : Um gerador de números aleatórios para o ruído aplicado a `p(x_{t-1} | x_t)` antes de ser amostrado.

return_dict (`bool`, padrão `True`) : Se deve ou não retornar um [VQDiffusionSchedulerOutput](/docs/diffusers/main/pt/api/schedulers/vq_diffusion#diffusers.schedulers.scheduling_vq_diffusion.VQDiffusionSchedulerOutput) ou `tuple`.

**Retorna:** [VQDiffusionSchedulerOutput](/docs/diffusers/main/pt/api/schedulers/vq_diffusion#diffusers.schedulers.scheduling_vq_diffusion.VQDiffusionSchedulerOutput) ou `tuple[torch.LongTensor]`

If return_dict is `True`, [VQDiffusionSchedulerOutput](/docs/diffusers/main/pt/api/schedulers/vq_diffusion#diffusers.schedulers.scheduling_vq_diffusion.VQDiffusionSchedulerOutput) is returned, otherwise a tuple is returned where the first element is the sample tensor.

Preveja a amostra do passo de tempo anterior pela distribuição de transição reversa. Consulte [q_posterior()](/docs/diffusers/main/pt/api/schedulers/vq_diffusion#diffusers.VQDiffusionScheduler.q_posterior) para mais detalhes sobre como a distribuição é calculada.

## VQDiffusionSchedulerOutput[[diffusers.schedulers.scheduling_vq_diffusion.VQDiffusionSchedulerOutput]]

#### diffusers.schedulers.scheduling_vq_diffusion.VQDiffusionSchedulerOutput[[diffusers.schedulers.scheduling_vq_diffusion.VQDiffusionSchedulerOutput]]

```python
diffusers.schedulers.scheduling_vq_diffusion.VQDiffusionSchedulerOutput(prev_sample: LongTensor)
```

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

**Parâmetros:**

prev_sample (`torch.LongTensor` de forma `(batch size, num latent pixels)`) : A amostra calculada no passo de tempo anterior. `prev_sample` deve ser usado como a próxima entrada do modelo no loop de remoção de ruído.

Classe de saída para a saída da função de passo do agendador.