# UniPCMultistepScheduler

`UniPCMultistepScheduler` é um framework sem treinamento projetado para amostragem rápida de modelos de difusão. Foi introduzido em [UniPC: A Unified Predictor-Corrector Framework for Fast Sampling of Diffusion Models](https://huggingface.co/papers/2302.04867) por Wenliang Zhao, Lujia Bai, Yongming Rao, Jie Zhou, Jiwen Lu.

Ele consiste em um corretor (UniC) e um preditor (UniP) que compartilham uma forma analítica unificada e suportam ordens arbitrárias. O UniPC é, por design, agnóstico em relação ao modelo, suportando DPMs em espaço de pixels/espaço latente em amostragem incondicional/condicional. Ele também pode ser aplicado a modelos de predição de ruído e de predição de dados. O corretor UniC também pode ser aplicado após qualquer solver pronto para aumentar a ordem de precisão.

O resumo do artigo é:

*Os modelos probabilísticos de difusão (DPMs) demonstraram uma capacidade muito promissora na síntese de imagens em alta resolução. No entanto, a amostragem de um DPM pré-treinado é demorada devido às múltiplas avaliações da rede de remoção de ruído, tornando cada vez mais importante acelerar a amostragem dos DPMs. Apesar dos avanços recentes no design de amostradores rápidos, os métodos existentes ainda não conseguem gerar imagens satisfatórias em muitos aplicativos em que um número menor de etapas (por exemplo, <10) é preferido. Neste artigo, desenvolvemos um corretor unificado (UniC) que pode ser aplicado após qualquer amostrador DPM existente para aumentar a ordem de precisão sem avaliações extras do modelo, e derivamos um preditor unificado (UniP) que suporta ordem arbitrária como subproduto. Combinando UniP e UniC, propomos um framework unificado de preditor-corretor chamado UniPC para a amostragem rápida de DPMs, que possui uma forma analítica unificada para qualquer ordem e pode melhorar significativamente a qualidade da amostragem em relação a métodos anteriores, especialmente em um número extremamente pequeno de etapas. Avaliamos nossos métodos por meio de extensos experimentos, incluindo amostragem incondicional e condicional usando DPMs em espaço de pixels e espaço latente. Nosso UniPC pode alcançar 3,87 FID no CIFAR10 (incondicional) e 7,51 FID no ImageNet 256×256 (condicional) com apenas 10 avaliações de função. O código está disponível em [este URL https](https://github.com/wl-zhao/UniPC).*

## Dicas

É recomendado definir `solver_order` como 2 para amostragem guiada e `solver_order=3` para amostragem incondicional.

O thresholding dinâmico do [Imagen](https://huggingface.co/papers/2205.11487) é suportado e, para modelos de difusão no espaço de pixels, você pode definir tanto `predict_x0=True` quanto `thresholding=True` para usar o thresholding dinâmico. Esse método de thresholding não é adequado para modelos de difusão no espaço latente, como o Stable Diffusion.

## UniPCMultistepScheduler[[diffusers.UniPCMultistepScheduler]]

#### diffusers.UniPCMultistepScheduler[[diffusers.UniPCMultistepScheduler]]

```python
diffusers.UniPCMultistepScheduler(num_train_timesteps: int = 1000, beta_start: float = 0.0001, beta_end: float = 0.02, beta_schedule: str = 'linear', trained_betas: numpy.ndarray | list[float] | None = None, solver_order: int = 2, prediction_type: typing.Literal['epsilon', 'sample', 'v_prediction', 'flow_prediction'] = 'epsilon', thresholding: bool = False, dynamic_thresholding_ratio: float = 0.995, sample_max_value: float = 1.0, predict_x0: bool = True, solver_type: typing.Literal['bh1', 'bh2'] = 'bh2', lower_order_final: bool = True, disable_corrector: list[int] = [], solver_p: SchedulerMixin = None, use_karras_sigmas: bool = False, use_exponential_sigmas: bool = False, use_beta_sigmas: bool = False, use_flow_sigmas: bool = False, flow_shift: float = 1.0, timestep_spacing: typing.Literal['linspace', 'leading', 'trailing'] = 'linspace', steps_offset: int = 0, final_sigmas_type: typing.Literal['zero', 'sigma_min'] = 'zero', rescale_betas_zero_snr: bool = False, use_dynamic_shifting: bool = False, time_shift_type: typing.Literal['exponential'] = 'exponential', sigma_min: float | None = None, sigma_max: bool | None = None, shift_terminal: bool | None = None)
```

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

**Parâmetros:**

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

beta_start (`float`, padrão 0.0001) : O valor inicial de `beta` para a inferência.

beta_end (`float`, padrão 0.02) : O valor final de `beta`.

beta_schedule (`"linear"`, `"scaled_linear"` ou `"squaredcos_cap_v2"`, padrão é `"linear"`) : O agendamento de beta, um mapeamento de um intervalo de beta para uma sequência de betas para dar passos no modelo. Escolha entre `linear`, `scaled_linear` ou `squaredcos_cap_v2`.

trained_betas (`np.ndarray`, *opcional*) : Passe um array de betas diretamente para o construtor para ignorar `beta_start` e `beta_end`.

solver_order (`int`, padrão `2`) : A ordem do UniPC, que pode ser qualquer inteiro positivo. A ordem de precisão efetiva é `solver_order + 1` devido ao UniC. Recomenda-se usar `solver_order=2` para amostragem guiada e `solver_order=3` para amostragem incondicional.

prediction_type (`"epsilon"`, `"sample"`, `"v_prediction"`, or `"flow_prediction"`, defaults to `"epsilon"`, *optional*) : Prediction type of the scheduler function; can be `epsilon` (predicts the noise of the diffusion process), `sample` (directly predicts the noisy sample`), `v_prediction` (see section 2.4 of [Imagen Video](https://huggingface.co/papers/2210.02303) paper), or `flow_prediction`.

thresholding (`bool`, padrão `False`) : Se deve usar o método de "limiar dinâmico". Isso não é adequado para modelos de difusão em espaço latente, como o Stable Diffusion.

dynamic_thresholding_ratio (`float`, padrão 0.995) : A proporção para o método de limiar dinâmico. Válido apenas quando `thresholding=True`.

sample_max_value (`float`, padrão 1.0) : O valor de limiar para o limiar dinâmico. Válido apenas quando `thresholding=True` e `predict_x0=True`.

predict_x0 (`bool`, padrão `True`) : Se deve usar o algoritmo de atualização no x0 previsto.

solver_type (`"bh1"` ou `"bh2"`, padrão `"bh2"`) : Tipo de solver para UniPC. Recomenda-se usar `bh1` para amostragem incondicional quando steps < 10, e `bh2` caso contrário.

lower_order_final (`bool`, padrão `True`) : Se deve usar solucionadores de ordem inferior nas etapas finais. Válido apenas para < 15 etapas de inferência. Isso pode estabilizar a amostragem do DPMSolver para etapas < 15, especialmente para etapas <= 10.

disable_corrector (`list`, padrão `[]`) : Define em qual etapa desativar o corretor para mitigar o desalinhamento entre `epsilon_theta(x_t, c)` e `epsilon_theta(x_t^c, c)`, o que pode influenciar a convergência para uma escala de orientação grande. O corretor geralmente é desativado nas primeiras etapas.

solver_p (`SchedulerMixin`, padrão `None`) : Qualquer outro scheduler que, se especificado, faz o algoritmo se tornar `solver_p + UniC`.

use_karras_sigmas (`bool`, *opcional*, padrão `False`) : Se deve usar sigmas de Karras para os tamanhos de passo no agendamento de ruído durante o processo de amostragem. Se `True`, os sigmas são determinados de acordo com uma sequência de níveis de ruído {σi}.

use_exponential_sigmas (`bool`, *opcional*, padrão `False`) : Se deve usar sigmas exponenciais para os tamanhos de passo no agendamento de ruído durante o processo de amostragem.

use_beta_sigmas (`bool`, *opcional*, padrão `False`) : Se deve usar betas sigmas para os tamanhos de passo no agendamento de ruído durante o processo de amostragem. Consulte [Beta Sampling is All You Need](https://huggingface.co/papers/2407.12173) para mais informações.

use_flow_sigmas (`bool`, *opcional*, padrão `False`) : Se deve usar sigmas de fluxo para os tamanhos de passo no agendamento de ruído durante o processo de amostragem.

timestep_spacing (`"linspace"`, `"leading"` ou `"trailing"`, padrão `"linspace"`) : A forma como os timesteps devem ser escalados. Consulte a Tabela 2 do [Common Diffusion Noise Schedules and Sample Steps are Flawed](https://huggingface.co/papers/2305.08891) para mais informações.

steps_offset (`int`, padrão 0) : Um deslocamento adicionado às etapas de inferência, conforme exigido por algumas famílias de modelos.

final_sigmas_type (`"zero"` ou `"sigma_min"`, padrão `"zero"`) : O valor final de `sigma` para o agendamento de ruído durante o processo de amostragem. Se `"sigma_min"`, o sigma final é o mesmo que o último sigma no agendamento de treinamento. Se `zero`, o sigma final é definido como 0.

rescale_betas_zero_snr (`bool`, padrão `False`) : Se deve reescalar os betas para ter SNR terminal zero. Isso permite que o modelo gere amostras muito claras e escuras, em vez de limitá-lo a amostras com brilho médio. Relacionado de forma solta a [`--offset_noise`](https://github.com/huggingface/diffusers/blob/74fd735eb073eb1d774b1ab4154a0876eb82f055/examples/dreambooth/train_dreambooth.py#L506).

`UniPCMultistepScheduler` é um framework sem treinamento projetado para a amostragem rápida de modelos de difusão.

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.

#### add_noise[[diffusers.UniPCMultistepScheduler.add_noise]]

```python
add_noise(original_samples: Tensor, noise: Tensor, timesteps: IntTensor)
```

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

**Parâmetros:**

original_samples (`torch.Tensor`) : As amostras originais sem ruído.

noise (`torch.Tensor`) : O ruído a ser adicionado às amostras.

timesteps (`torch.IntTensor`) : Os passos de tempo nos quais adicionar ruído às amostras.

**Retorna:** `torch.Tensor`

As amostras ruidosas.

Adicione ruído às amostras originais de acordo com o agendamento de ruído nos timesteps especificados.

#### convert_model_output[[diffusers.UniPCMultistepScheduler.convert_model_output]]

```python
convert_model_output(model_output: Tensor, *args, sample: Tensor = None, **kwargs)
```

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

**Parâmetros:**

model_output (`torch.Tensor`) : A saída direta do modelo de difusão aprendido.

timestep (`int`) : O passo de tempo discreto atual na cadeia de difusão.

sample (`torch.Tensor`) : Uma instância atual de uma amostra criada pelo processo de difusão.

**Retorna:** `torch.Tensor`

A saída do modelo convertido.

Converta a saída do modelo para o tipo correspondente necessário pelo algoritmo UniPC.

#### index_for_timestep[[diffusers.UniPCMultistepScheduler.index_for_timestep]]

```python
index_for_timestep(timestep: typing.Union[int, torch.Tensor], schedule_timesteps: typing.Optional[torch.Tensor] = None)
```

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

**Parâmetros:**

timestep (`int` ou `torch.Tensor`) : O timestep para o qual encontrar o índice.

schedule_timesteps (`torch.Tensor`, *opcional*) : O cronograma de passos de tempo a ser pesquisado. Se `None`, usa `self.timesteps`.

**Retorna:** `int`

O índice do timestep no agendamento.

Encontre o índice para um passo de tempo (timestep) específico no agendamento.

#### multistep_uni_c_bh_update[[diffusers.UniPCMultistepScheduler.multistep_uni_c_bh_update]]

```python
multistep_uni_c_bh_update(this_model_output: Tensor, *args, last_sample: Tensor = None, this_sample: Tensor = None, order: int = None, **kwargs)
```

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

**Parâmetros:**

this_model_output (`torch.Tensor`) : As saídas do modelo em `x_t`.

this_timestep (`int`) : O timestep atual `t`.

last_sample (`torch.Tensor`) : A amostra gerada antes do último preditor `x_{t-1}`.

this_sample (`torch.Tensor`) : A amostra gerada após o último preditor `x_{t}`.

order (`int`) : O `p` do UniC-p nesta etapa. A ordem de precisão efetiva deve ser `order + 1`.

**Retorna:** `torch.Tensor`

O tensor de amostra corrigido no timestep atual.

Um passo para o UniC (versão B(h)).

#### multistep_uni_p_bh_update[[diffusers.UniPCMultistepScheduler.multistep_uni_p_bh_update]]

```python
multistep_uni_p_bh_update(model_output: Tensor, *args, sample: Tensor = None, order: int = None, **kwargs)
```

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

**Parâmetros:**

model_output (`torch.Tensor`) : A saída direta do modelo de difusão aprendido no timestep atual.

prev_timestep (`int`) : O passo de tempo discreto anterior na cadeia de difusão.

sample (`torch.Tensor`) : Uma instância atual de uma amostra criada pelo processo de difusão.

order (`int`) : A ordem do UniP neste timestep (corresponde ao *p* em UniPC-p).

**Retorna:** `torch.Tensor`

O tensor de amostra no passo de tempo anterior.

Um passo para o UniP (versão B(h)). Alternativamente, `self.solver_p` é usado se especificado.

#### scale_model_input[[diffusers.UniPCMultistepScheduler.scale_model_input]]

```python
scale_model_input(sample: Tensor, *args, **kwargs)
```

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

**Parâmetros:**

sample (`torch.Tensor`) : A amostra de entrada.

**Retorna:** `torch.Tensor`

Uma amostra de entrada escalada.

Garante a intercambiabilidade com agendadores que precisam escalar a entrada do modelo de desruidamento dependendo do passo de tempo atual.

#### set_begin_index[[diffusers.UniPCMultistepScheduler.set_begin_index]]

```python
set_begin_index(begin_index: int = 0)
```

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

**Parâmetros:**

begin_index (`int`, padrão `0`) : O índice inicial para o agendador.

Define o índice inicial para o agendador. Esta função deve ser executada a partir do pipeline antes da inferência.

#### set_timesteps[[diffusers.UniPCMultistepScheduler.set_timesteps]]

```python
set_timesteps(num_inference_steps: int | None = None, device: typing.Union[str, torch.device] = None, sigmas: list[float] | None = None, mu: bool | None = None)
```

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

**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 devem ser movidos. Se `None`, os timesteps não são movidos.

sigmas (`List[float]`, *opcional*) : Valores personalizados para sigmas a serem usados em cada etapa de difusão. Se `None`, os sigmas são calculados automaticamente.

mu (`float`, *opcional*) : Parâmetro mu opcional para deslocamento dinâmico ao usar o tipo de deslocamento de tempo exponencial.

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

#### etapa[[diffusers.UniPCMultistepScheduler.step]]

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

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

**Parâmetros:**

model_output (`torch.Tensor`) : A saída direta do modelo de difusão aprendido.

timestep (`int` ou `torch.Tensor`) : O passo de tempo discreto atual na cadeia de difusão.

sample (`torch.Tensor`) : Uma instância atual de uma amostra criada pelo processo de difusão.

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

**Retorna:** [SchedulerOutput](/docs/diffusers/main/pt/api/schedulers/ipndm#diffusers.schedulers.scheduling_utils.SchedulerOutput) ou `tuple`

Se return_dict for `True`, [SchedulerOutput](/docs/diffusers/main/pt/api/schedulers/ipndm#diffusers.schedulers.scheduling_utils.SchedulerOutput) é retornado; caso contrário, uma tupla é retornada, em que o primeiro elemento é o tensor de amostras.

Preveja a amostra do passo de tempo anterior revertendo o SDE. Esta função propaga a amostra com o UniPC multistep.

#### stretch_shift_to_terminal[[diffusers.UniPCMultistepScheduler.stretch_shift_to_terminal]]

```python
stretch_shift_to_terminal(t: Tensor)
```

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

**Parâmetros:**

t (`torch.Tensor`) : Um tensor de timesteps a serem esticados e deslocados.

**Retorna:** `torch.Tensor`

Um tensor de timesteps ajustados de modo que o valor final seja igual a `self.config.shift_terminal`.

Estica e desloca o cronograma de timesteps para garantir que ele termine no valor de configuração `shift_terminal` configurado.

Referência: https://github.com/Lightricks/LTX-Video/blob/a01a171f8fe3d99dce2728d60a73fecf4d4238ae/ltx_video/schedulers/rf.py#L51

#### time_shift[[diffusers.UniPCMultistepScheduler.time_shift]]

```python
time_shift(mu: float, sigma: float, t: Tensor)
```

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

**Parâmetros:**

mu (`float`) : O parâmetro mu para o deslocamento de tempo.

sigma (`float`) : O parâmetro sigma para o deslocamento de tempo.

t (`torch.Tensor`) : Os timesteps de entrada.

**Retorna:** `torch.Tensor`

Os timesteps deslocados no tempo.

Aplicar o deslocamento temporal aos sigmas.

## SchedulerOutput[[diffusers.schedulers.scheduling_utils.SchedulerOutput]]

#### diffusers.schedulers.scheduling_utils.SchedulerOutput[[diffusers.schedulers.scheduling_utils.SchedulerOutput]]

```python
diffusers.schedulers.scheduling_utils.SchedulerOutput(prev_sample: Tensor)
```

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

**Parâmetros:**

prev_sample (`torch.Tensor` de forma `(batch_size, num_channels, height, width)` para imagens) : Amostra calculada `(x_{t-1})` do passo anterior. `prev_sample` deve ser usado como entrada do próximo modelo no loop de remoção de ruído.

Classe base para a saída da função `step` de um agendador.