# DDIMScheduler

[Denoising Diffusion Implicit Models](https://huggingface.co/papers/2010.02502) (DDIM) de Jiaming Song, Chenlin Meng y Stefano Ermon.

El resumen del artículo es:

*Los modelos probabilísticos de difusión de desruido (DDPM) han logrado una generación de imágenes de alta calidad sin entrenamiento adversarial, pero requieren simular una cadena de Markov durante muchos pasos para producir una muestra. Para acelerar el muestreo, presentamos los modelos implícitos de difusión de desruido (DDIM), una clase más eficiente de modelos probabilísticos iterativos implícitos con el mismo procedimiento de entrenamiento que los DDPM. En los DDPM, el proceso generativo se define como la inversa de un proceso de difusión markoviano. Construimos una clase de procesos de difusión no markovianos que conducen al mismo objetivo de entrenamiento, pero cuyo proceso inverso permite un muestreo mucho más rápido. Demostramos empíricamente que los DDIM pueden producir muestras de alta calidad de 10 a 50 veces más rápido en términos de tiempo real en comparación con los DDPM, nos permiten intercambiar cómputo por calidad de muestra y pueden realizar interpolaciones de imágenes con significado semántico directamente en el espacio latente.*

El código original de este artículo se encuentra en [ermongroup/ddim](https://github.com/ermongroup/ddim), y puedes contactar al autor en [tsong.me](https://tsong.me/).

## Consejos

El artículo [Common Diffusion Noise Schedules and Sample Steps are Flawed](https://huggingface.co/papers/2305.08891) afirma que una discrepancia entre la configuración de entrenamiento y la de inferencia conduce a resultados subóptimos en la generación de inferencia para Stable Diffusion. Para corregir esto, los autores proponen:

> [!WARNING]
> 🧪 ¡Esta es una función experimental!

1. escalar el programa de ruido para aplicar una relación señal-ruido (SNR) terminal cero

```py
pipe.scheduler = DDIMScheduler.from_config(pipe.scheduler.config, rescale_betas_zero_snr=True)
```

2. Entrenar un modelo con `v_prediction` (añade el siguiente argumento a los scripts [train_text_to_image.py](https://github.com/huggingface/diffusers/blob/main/examples/text_to_image/train_text_to_image.py) o [train_text_to_image_lora.py](https://github.com/huggingface/diffusers/blob/main/examples/text_to_image/train_text_to_image_lora.py))

```bash
--prediction_type="v_prediction"
```

3. cambiar el muestreador para que siempre comience desde el último paso temporal

```py
pipe.scheduler = DDIMScheduler.from_config(pipe.scheduler.config, timestep_spacing="trailing")
```

4. reescalar la guía libre de clasificador para evitar sobreexposición

```py
image = pipe(prompt, guidance_rescale=0.7).images[0]
```

Por ejemplo:

```py
from diffusers import DiffusionPipeline, DDIMScheduler
import torch

pipe = DiffusionPipeline.from_pretrained("ptx0/pseudo-journey-v2", dtype=torch.float16)
pipe.scheduler = DDIMScheduler.from_config(
    pipe.scheduler.config, rescale_betas_zero_snr=True, timestep_spacing="trailing"
)
pipe.to("cuda")  # or "mps", "xpu", "cpu"

prompt = "A lion in galaxies, spirals, nebulae, stars, smoke, iridescent, intricate detail, octane render, 8k"
image = pipe(prompt, guidance_rescale=0.7).images[0]
image
```

## DDIMScheduler[[diffusers.DDIMScheduler]]

#### diffusers.DDIMScheduler[[diffusers.DDIMScheduler]]

```python
diffusers.DDIMScheduler(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, clip_sample: bool = True, set_alpha_to_one: bool = True, steps_offset: int = 0, prediction_type: typing.Literal['epsilon', 'sample', 'v_prediction'] = 'epsilon', thresholding: bool = False, dynamic_thresholding_ratio: float = 0.995, clip_sample_range: float = 1.0, sample_max_value: float = 1.0, timestep_spacing: typing.Literal['leading', 'trailing', 'linspace'] = 'leading', rescale_betas_zero_snr: bool = False)
```

[Fuente](https://github.com/huggingface/diffusers/blob/main/src/diffusers/schedulers/scheduling_ddim.py#L139)

**Parámetros:**

num_train_timesteps (`int`, por defecto 1000) : El número de pasos de difusión para entrenar el modelo.

beta_start (`float`, por defecto 0.0001) : El valor inicial de `beta` para la inferencia.

beta_end (`float`, por defecto 0.02) : El valor final de `beta`.

beta_schedule (`Literal["linear", "scaled_linear", "squaredcos_cap_v2"]`, por defecto `"linear"`) : El plan de betas, una correspondencia desde un rango de betas hasta una secuencia de betas para dar pasos al modelo. Debe ser uno de `"linear"`, `"scaled_linear"` o `"squaredcos_cap_v2"`.

trained_betas (`np.ndarray`, *opcional*) : Pasa un array de betas directamente al constructor para omitir `beta_start` y `beta_end`.

clip_sample (`bool`, por defecto `True`) : Recorta la muestra predicha para la estabilidad numérica.

clip_sample_range (`float`, por defecto 1.0) : La magnitud máxima para el recorte de muestras. Solo es válido cuando `clip_sample=True`.

set_alpha_to_one (`bool`, por defecto `True`) : Cada paso de difusión utiliza el valor del producto de alfas en ese paso y en el anterior. En el paso final no hay un alfa anterior. Cuando esta opción es `True`, el producto de alfas anterior se fija en `1`; de lo contrario, se utiliza el valor de alfa en el paso 0.

steps_offset (`int`, valor predeterminado 0) : Un desplazamiento que se suma a los pasos de inferencia, tal como lo requieren algunas familias de modelos.

prediction_type (`Literal["epsilon", "sample", "v_prediction"]`, por defecto `"epsilon"`) : Tipo de predicción de la función del programador. Debe ser uno de `"epsilon"` (predice el ruido del proceso de difusión), `"sample"` (predice directamente la muestra con ruido) o `"v_prediction"` (ver la sección 2.4 del artículo [Imagen Video](https://huggingface.co/papers/2210.02303)).

thresholding (`bool`, por defecto `False`) : Si se debe utilizar el método de "umbral dinámico". No es adecuado para modelos de difusión en el espacio latente, como Stable Diffusion.

dynamic_thresholding_ratio (`float`, por defecto 0.995) : La proporción para el método de umbral dinámico. Solo es válido cuando `thresholding=True`.

sample_max_value (`float`, por defecto 1.0) : El valor de umbral para el umbral dinámico. Solo es válido cuando `thresholding=True`.

timestep_spacing (`Literal["leading", "trailing", "linspace"]`, por defecto `"leading"`) : La forma en que se deben escalar los pasos de tiempo. Debe ser uno de `"leading"`, `"trailing"` o `"linspace"`. Consulte la tabla 2 de [Common Diffusion Noise Schedules and Sample Steps are Flawed](https://huggingface.co/papers/2305.08891) para obtener más información.

rescale_betas_zero_snr (`bool`, por defecto `False`) : Si se deben reescalar los betas para tener un SNR terminal cero. Esto permite al modelo generar muestras muy brillantes y oscuras en lugar de limitarlo a muestras con un brillo medio. Relacionado de forma laxa con [`--offset_noise`](https://github.com/huggingface/diffusers/blob/74fd735eb073eb1d774b1ab4154a0876eb82f055/examples/dreambooth/train_dreambooth.py#L506).

`DDIMScheduler` extiende el procedimiento de desruido introducido en los modelos probabilísticos de difusión de desruido (DDPM) con una guía no markoviana.

Este modelo hereda de [SchedulerMixin](/docs/diffusers/main/es/api/schedulers/overview#diffusers.SchedulerMixin) y [ConfigMixin](/docs/diffusers/main/es/api/configuration#diffusers.ConfigMixin). Consulta la documentación de la clase superior para los métodos genéricos que la biblioteca implementa para todos los programadores, como la carga y el guardado.

#### add_noise[[diffusers.DDIMScheduler.add_noise]]

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

[Fuente](https://github.com/huggingface/diffusers/blob/main/src/diffusers/schedulers/scheduling_ddim.py#L517)

**Parámetros:**

original_samples (`torch.Tensor`) : Las muestras originales a las que se les añadirá ruido.

noise (`torch.Tensor`) : El ruido que se añadirá a las muestras.

timesteps (`torch.IntTensor`) : Los pasos de tiempo que indican el nivel de ruido para cada muestra.

**Devuelve:** `torch.Tensor`

Las muestras ruidosas.

Añada ruido a las muestras originales según la magnitud del ruido en cada paso temporal (este es el proceso de difusión hacia adelante).

#### get_velocity[[diffusers.DDIMScheduler.get_velocity]]

```python
get_velocity(sample: Tensor, noise: Tensor, timesteps: IntTensor)
```

[Fuente](https://github.com/huggingface/diffusers/blob/main/src/diffusers/schedulers/scheduling_ddim.py#L560)

**Parámetros:**

sample (`torch.Tensor`) : La muestra de entrada.

noise (`torch.Tensor`) : El tensor de ruido.

timesteps (`torch.IntTensor`) : Los pasos de tiempo para el cálculo de la velocidad.

**Devuelve:** `torch.Tensor`

La velocidad calculada.

Calcule la predicción de velocidad a partir de la muestra y el ruido según la fórmula de velocidad.

#### scale_model_input[[diffusers.DDIMScheduler.scale_model_input]]

```python
scale_model_input(sample: Tensor, timestep: int = None)
```

[Fuente](https://github.com/huggingface/diffusers/blob/main/src/diffusers/schedulers/scheduling_ddim.py#L245)

**Parámetros:**

sample (`torch.Tensor`) : La muestra de entrada.

timestep (`int`, *opcional*) : El paso temporal actual en la cadena de difusión.

**Devuelve:** `torch.Tensor`

Una muestra de entrada escalada.

Garantiza la interoperabilidad con los programadores que necesitan escalar la entrada del modelo de desruido en función del paso temporal actual.

#### set_timesteps[[diffusers.DDIMScheduler.set_timesteps]]

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

[Fuente](https://github.com/huggingface/diffusers/blob/main/src/diffusers/schedulers/scheduling_ddim.py#L334)

**Parámetros:**

num_inference_steps (`int`) : El número de pasos de difusión utilizados al generar muestras con un modelo preentrenado.

device (`str | torch.device`, *opcional*) : El dispositivo a utilizar para los pasos de tiempo.

**Excepciones:** ``ValueError``

- ``ValueError`` -- Si `num_inference_steps` es mayor que `self.config.num_train_timesteps`.

Establece los pasos discretos utilizados para la cadena de difusión (para ejecutarse antes de la inferencia).

#### paso[[diffusers.DDIMScheduler.step]]

```python
step(model_output: Tensor, timestep: int, sample: Tensor, eta: float = 0.0, use_clipped_model_output: bool = False, generator: typing.Optional[torch.Generator] = None, variance_noise: typing.Optional[torch.Tensor] = None, return_dict: bool = True)
```

[Fuente](https://github.com/huggingface/diffusers/blob/main/src/diffusers/schedulers/scheduling_ddim.py#L384)

**Parámetros:**

model_output (`torch.Tensor`) : La salida directa del modelo de difusión aprendido.

timestep (`int`) : El paso de tiempo discreto actual en la cadena de difusión.

sample (`torch.Tensor`) : Una instancia actual de una muestra creada por el proceso de difusión.

eta (`float`, *opcional*, valor predeterminado 0.0) : El peso del ruido para el ruido añadido en el paso de difusión. Un valor de 0 corresponde a DDIM (determinista) y 1 corresponde a DDPM (totalmente estocástico).

use_clipped_model_output (`bool`, *opcional*, valor predeterminado `False`) : Si `True`, calcula el `model_output` "corregido" a partir de la muestra original predicha recortada. Es necesario porque la muestra original predicha se recorta a [-1, 1] cuando `self.config.clip_sample` es `True`. Si no se ha realizado ningún recorte, el `model_output` "corregido" coincidiría con el proporcionado como entrada y `use_clipped_model_output` no tendría efecto.

generator (`torch.Generator`, *opcional*) : Un generador de números aleatorios para muestreos reproducibles.

variance_noise (`torch.Tensor`, *opcional*) : Alternativa a generar ruido con `generator` proporcionando directamente el ruido para la varianza en sí. Útil para métodos como `CycleDiffusion`.

return_dict (`bool`, *opcional*, valor predeterminado `True`) : Indica si se debe devolver un [DDIMSchedulerOutput](/docs/diffusers/main/es/api/schedulers/ddim#diffusers.schedulers.scheduling_ddim.DDIMSchedulerOutput) o una `tuple`.

**Devuelve:** [DDIMSchedulerOutput](/docs/diffusers/main/es/api/schedulers/ddim#diffusers.schedulers.scheduling_ddim.DDIMSchedulerOutput) o `tuple`

Si return_dict es `True`, se devuelve [DDIMSchedulerOutput](/docs/diffusers/main/es/api/schedulers/ddim#diffusers.schedulers.scheduling_ddim.DDIMSchedulerOutput); en caso contrario, se devuelve una tupla cuyo primer elemento es el tensor de la muestra.

Predice la muestra del paso de tiempo anterior invirtiendo el SDE. Esta función propaga el proceso de difusión desde las salidas del modelo aprendido (con mayor frecuencia, el ruido predicho).

## DDIMSchedulerOutput[[diffusers.schedulers.scheduling_ddim.DDIMSchedulerOutput]]

#### diffusers.schedulers.scheduling_ddim.DDIMSchedulerOutput[[diffusers.schedulers.scheduling_ddim.DDIMSchedulerOutput]]

```python
diffusers.schedulers.scheduling_ddim.DDIMSchedulerOutput(prev_sample: Tensor, pred_original_sample: typing.Optional[torch.Tensor] = None)
```

[Fuente](https://github.com/huggingface/diffusers/blob/main/src/diffusers/schedulers/scheduling_ddim.py#L33)

**Parámetros:**

prev_sample (`torch.Tensor` de forma `(batch_size, num_channels, height, width)` para imágenes) : Muestra `(x_{t-1})` calculada del paso de tiempo anterior. `prev_sample` debe usarse como entrada del modelo en la siguiente iteración del bucle de desruido.

pred_original_sample (`torch.Tensor` de forma `(batch_size, num_channels, height, width)` para imágenes) : La muestra desruidada predicha `(x_{0})` basada en la salida del modelo del paso de tiempo actual. `pred_original_sample` se puede usar para previsualizar el progreso o para la guía.

Clase de salida para la salida de la función `step` del programador.