# VQDiffusionScheduler

`VQDiffusionScheduler`는 transformer 모델의 출력을 이전 diffusion timestep의 노이즈가 제거된 이미지의 샘플로 변환합니다. Shuyang Gu, Dong Chen, Jianmin Bao, Fang Wen, Bo Zhang, Dongdong Chen, Lu Yuan, Baining Guo가 발표한 [Vector Quantized Diffusion Model for Text-to-Image Synthesis](https://huggingface.co/papers/2111.14822)에서 소개되었습니다.

해당 논문의 초록은 다음과 같습니다:

*텍스트-이미지 생성을 위한 벡터 양자화 확산(VQ-Diffusion) 모델을 제시합니다. 이 방법은 최근 개발된 노이즈 제거 확률적 모델(Denoising Diffusion Probabilistic Model, DDPM)의 조건부 변형을 사용하여 잠재 공간을 모델링하는 벡터 양자화 변분 오토인코더(VQ-VAE)에 기반합니다. 이 잠재 공간 방식은 기존 방법의 단방향 편향을 제거할 뿐만 아니라, 기존 방법에서 심각한 문제인 오류 축적을 피하기 위해 마스크-교체(mask-and-replace) 확산 전략을 적용할 수 있어 텍스트-이미지 생성 작업에 적합하다는 것을 발견했습니다. 실험 결과, 유사한 매개변수 수를 가진 기존 자기회귀(AR) 모델과 비교할 때 VQ-Diffusion이 훨씬 더 나은 텍스트-이미지 생성 결과를 산출하는 것으로 나타났습니다. 이전 GAN 기반 텍스트-이미지 방법과 비교하면, VQ-Diffusion은 더 복잡한 장면을 처리할 수 있고 합성 이미지 품질을 크게 향상시킵니다. 마지막으로, 재매개변수화(reparameterization)를 통해 제안된 방법의 이미지 생성 계산이 매우 효율적으로 수행될 수 있음을 보여줍니다. 전통적인 AR 방법에서는 텍스트-이미지 생성 시간이 출력 이미지 해상도에 따라 선형으로 증가하여 일반적인 크기의 이미지에서도 상당한 시간이 소요됩니다. VQ-Diffusion은 품질과 속도 사이의 더 나은 트레이드오프를 달성할 수 있게 합니다. 실험 결과, 재매개변수화를 적용한 VQ-Diffusion 모델은 더 나은 이미지 품질을 달성하면서 전통적인 AR 방법보다 15배 빠릅니다.*

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

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

**매개변수:**

num_vec_classes (`int`) : 잠재 픽셀의 벡터 임베딩 클래스 수. 마스킹된 잠재 픽셀의 클래스를 포함합니다.

num_train_timesteps (`int`, 기본값 `100`) : 모델을 학습할 때 사용할 diffusion step 수입니다.

alpha_cum_start (`float`, 기본값 `0.99999`) : 시작 누적 alpha 값입니다.

alpha_cum_end (`float`, 기본값 `0.000009`) : 종료 시 누적 alpha 값입니다.

gamma_cum_start (`float`, 기본값 `0.000009`) : 시작 누적 감마 값입니다.

gamma_cum_end (`float`, 기본값 `0.99999`) : 종료 누적 감마 값입니다.

벡터 양자화 확산을 위한 스케줄러입니다.

이 모델은 [SchedulerMixin](/docs/diffusers/main/ko/api/schedulers/overview#diffusers.SchedulerMixin)과 [ConfigMixin](/docs/diffusers/main/ko/api/configuration#diffusers.ConfigMixin)을 상속합니다. 로딩 및 저장과 같은 모든 스케줄러에 대해 라이브러리가 구현하는 일반적 메서드에 대해서는 상위 클래스 문서를 확인하세요.

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

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

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

**매개변수:**

q (`torch.Tensor`, shape `(batch size, num classes - 1, num latent pixels)`) : 마스킹되지 않은 잠재 픽셀 클래스에 대한 로그 확률.

t (`int` 또는 `torch.Tensor`) : 어떤 누적 전이 행렬이 사용될지를 결정하는 시간 단계(timestep)입니다.

**반환값:** `torch.Tensor`, shape `(batch size, num classes, num latent pixels)`

마스크 클래스 확률이 추가된 전환된 로그 확률입니다.

Apply the cumulative transition matrix at a timestep to log probabilities over non-mask classes.

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

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

**매개변수:**

t (`int` 또는 `torch.Tensor`) : 어떤 전이 행렬을 사용할지를 결정하는 시간 단계입니다.

x_t (`torch.LongTensor`, shape `(batch size, num latent pixels)`) : 시간 `t` 시점의 각 latent pixel의 클래스입니다.

log_onehot_x_t (`torch.Tensor`, shape `(batch size, num classes, num latent pixels)`) : `x_t`의 로그 원-핫 벡터입니다.

cumulative (`bool`) : cumulative가 `False`인 경우, 단일 단계 전이 행렬 `t-1`->`t`이 사용됩니다. cumulative가 `True`인 경우, 누적 전이 행렬 `0`->`t`이 사용됩니다.

**반환값:** `torch.Tensor`

반환되는 행렬의 각 _열_은 완전한 확률 전이 행렬의 로그 확률 _행_입니다. `cumulative`가 `True`인 경우 텐서의 모양은 `(batch size, num classes - 1, num latent pixels)`이고, 그렇지 않은 경우 `(batch size, num classes, num latent pixels)`입니다.

누적(cumulative)인 경우, 초기 잠재 픽셀은 마스킹할 수 없으므로 텐서의 행이 하나 적습니다.

여기서:
- `q_n`은 `n`번째 잠재 픽셀의 전방 과정에 대한 확률 분포입니다.
- C_0 은 잠재 픽셀 임베딩의 클래스입니다
- C_k 은 마스킹된 잠재 픽셀의 클래스입니다

누적되지 않은 결과 (로그 제외):
```
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)
```

누적 결과 (로그 생략):
```
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})
```

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

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

**매개변수:**

log_p_x_0 (`torch.Tensor`, shape `(batch size, num classes - 1, num latent pixels)`) : 초기 latent 픽셀의 예측된 클래스에 대한 로그 확률입니다. 초기 노이즈가 제거된 이미지는 마스킹될 수 없으므로 마스킹된 클래스에 대한 예측은 포함되지 않습니다.

x_t (`torch.LongTensor`, shape `(batch size, num latent pixels)`) : 시간 `t` 시점의 각 latent pixel의 클래스입니다.

t (`int` 또는 `torch.Tensor`) : 어떤 전이 행렬을 사용할지를 결정하는 시간 단계입니다.

**반환값:** `torch.Tensor`, shape `(batch size, num classes, num latent pixels)`

`t-1` 타임스텝에서 이미지의 예측된 클래스에 대한 로그 확률입니다.

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

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

**매개변수:**

num_inference_steps (`int`) : 사전 학습된 모델로 샘플을 생성할 때 사용되는 확산 단계의 수.

device (`str` 또는 `torch.device`, *선택 사항*) : timesteps와 diffusion process 매개변수(alpha, beta, gamma)를 이동할 대상 device입니다.

추론 실행 전에 실행할 diffusion chain에 사용할 이산 timesteps를 설정합니다.

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

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

**매개변수:**

model_output (`torch.Tensor`, shape `(batch size, num classes - 1, num latent pixels)`) : 초기 latent 픽셀의 예측된 클래스에 대한 로그 확률입니다. 초기 노이즈가 제거된 이미지는 마스킹될 수 없으므로 마스킹된 클래스에 대한 예측은 포함되지 않습니다.

timestep (`int` 또는 `torch.Tensor`) : 어떤 전이 행렬을 사용할지 결정하는 시간 단계입니다.

sample (`torch.LongTensor`, shape `(batch size, num latent pixels)`) : 현재 timestep에서 각 latent pixel의 클래스.

generator (`torch.Generator`, *선택 사항*) : `p(x_{t-1} | x_t)`에서 샘플링하기 전에 적용되는 노이즈에 사용할 난수 생성기입니다.

return_dict (`bool`, 기본값 `True`) : [VQDiffusionSchedulerOutput](/docs/diffusers/main/ko/api/schedulers/vq_diffusion#diffusers.schedulers.scheduling_vq_diffusion.VQDiffusionSchedulerOutput) 또는 `tuple`을 반환할지 여부.

**반환값:** [VQDiffusionSchedulerOutput](/docs/diffusers/main/ko/api/schedulers/vq_diffusion#diffusers.schedulers.scheduling_vq_diffusion.VQDiffusionSchedulerOutput) 또는 `tuple[torch.LongTensor]`

return_dict가 `True`인 경우 [VQDiffusionSchedulerOutput](/docs/diffusers/main/ko/api/schedulers/vq_diffusion#diffusers.schedulers.scheduling_vq_diffusion.VQDiffusionSchedulerOutput)이 반환되고, 그렇지 않으면 첫 번째 요소가 샘플 텐서인 튜플이 반환됩니다.

이전 시간 단계의 샘플을 역 전이 분포를 사용하여 예측합니다. 분포가 계산되는 방법에 대한 자세한 내용은 [q_posterior()](/docs/diffusers/main/ko/api/schedulers/vq_diffusion#diffusers.VQDiffusionScheduler.q_posterior)를 참조하세요.

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

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

**매개변수:**

prev_sample (`torch.LongTensor`, shape `(batch size, num latent pixels)`) : 이전 timestep에서 계산된 샘플. `prev_sample`은 denoising 루프에서 다음 모델 입력으로 사용해야 합니다.

스케줄러의 step 함수 출력용 출력 클래스.