Buckets:

hf-doc-build
/

doc

Files

xet

hf-doc-build/doc / diffusers /main /ko /api /models /autoencoder_rae.md

mishig

about 15 hours ago

preview code

download

raw

9.27 kB

# AutoencoderRAE

NYU VISIONx의 Boyang Zheng, Nanye Ma, Shengbang Tong, Saining Xie가 [Diffusion Transformers with Representation Autoencoders](https://huggingface.co/papers/2510.11690)에서 소개한 Representation Autoencoder(RAE) 모델입니다.

RAE는 동결된 사전 학습된 비전 인코더(DINOv2, SigLIP2 또는 MAE)와 학습 가능한 ViT-MAE 스타일의 디코더를 결합합니다. 2단계 RAE 학습 레시피에서 오토인코더는 1단계(재구성)에서 학습되고, 이후 2단계(생성)에서 생성된 잠재 공간(latent space)에 대해 확산 모델(diffusion model)이 학습됩니다.

다음 RAE 모델들이 Diffusers에서 릴리스되고 지원됩니다:

| 모델 | 인코더 | Latent shape (224px 입력) |
|:------|:--------|:---------------------------|
| [`nyu-visionx/RAE-dinov2-wReg-base-ViTXL-n08`](https://huggingface.co/nyu-visionx/RAE-dinov2-wReg-base-ViTXL-n08) | DINOv2-base | 768 x 16 x 16 |
| [`nyu-visionx/RAE-dinov2-wReg-base-ViTXL-n08-i512`](https://huggingface.co/nyu-visionx/RAE-dinov2-wReg-base-ViTXL-n08-i512) | DINOv2-base (512px) | 768 x 32 x 32 |
| [`nyu-visionx/RAE-dinov2-wReg-small-ViTXL-n08`](https://huggingface.co/nyu-visionx/RAE-dinov2-wReg-small-ViTXL-n08) | DINOv2-small | 384 x 16 x 16 |
| [`nyu-visionx/RAE-dinov2-wReg-large-ViTXL-n08`](https://huggingface.co/nyu-visionx/RAE-dinov2-wReg-large-ViTXL-n08) | DINOv2-large | 1024 x 16 x 16 |
| [`nyu-visionx/RAE-siglip2-base-p16-i256-ViTXL-n08`](https://huggingface.co/nyu-visionx/RAE-siglip2-base-p16-i256-ViTXL-n08) | SigLIP2-base | 768 x 16 x 16 |
| [`nyu-visionx/RAE-mae-base-p16-ViTXL-n08`](https://huggingface.co/nyu-visionx/RAE-mae-base-p16-ViTXL-n08) | MAE-base | 768 x 16 x 16 |

## 사전 학습된 모델 로드

```python
from diffusers import AutoencoderRAE
model = AutoencoderRAE.from_pretrained(
    "nyu-visionx/RAE-dinov2-wReg-base-ViTXL-n08"
).to("cuda").eval()  # or "mps", "xpu", "cpu"
```

## 실제 이미지의 인코딩 및 디코딩

```python
import torch
from diffusers import AutoencoderRAE
from diffusers.utils import load_image
from torchvision.transforms.functional import to_tensor, to_pil_image
model = AutoencoderRAE.from_pretrained(
    "nyu-visionx/RAE-dinov2-wReg-base-ViTXL-n08"
).to("cuda").eval()  # or "mps", "xpu", "cpu"
image = load_image("https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/cat.png")
image = image.convert("RGB").resize((224, 224))
x = to_tensor(image).unsqueeze(0).to("cuda")  # (1, 3, 224, 224), values in [0, 1]
with torch.no_grad():
    latents = model.encode(x).latent        # (1, 768, 16, 16)
    recon = model.decode(latents).sample     # (1, 3, 256, 256)
recon_image = to_pil_image(recon[0].clamp(0, 1).cpu())
recon_image.save("recon.png")
```

## 잠재 정규화

일부 사전 학습된 체크포인트에는 잠재 공간 정규화를 위한 채널별 `latents_mean` 및 `latents_std` 통계가 포함되어 있습니다. 이러한 통계가 존재하면 `encode`와 `decode`가 각각 정규화와 역정규화를 자동으로 적용합니다.

```python
model = AutoencoderRAE.from_pretrained(
    "nyu-visionx/RAE-dinov2-wReg-base-ViTXL-n08"
).to("cuda").eval()  # or "mps", "xpu", "cpu"
# Latent normalization is handled automatically inside encode/decode
# when the checkpoint config includes latents_mean/latents_std.
with torch.no_grad():
    latents = model.encode(x).latent   # normalized latents
    recon = model.decode(latents).sample
```

## AutoencoderRAE[[diffusers.AutoencoderRAE]]

#### diffusers.AutoencoderRAE[[diffusers.AutoencoderRAE]]

```python
diffusers.AutoencoderRAE(encoder_type: str = 'dinov2', encoder_hidden_size: int = 768, encoder_patch_size: int = 14, encoder_num_hidden_layers: int = 12, decoder_hidden_size: int = 512, decoder_num_hidden_layers: int = 8, decoder_num_attention_heads: int = 16, decoder_intermediate_size: int = 2048, patch_size: int = 16, encoder_input_size: int = 224, image_size: int | None = None, num_channels: int = 3, encoder_norm_mean: list | None = None, encoder_norm_std: list | None = None, latents_mean: typing.Union[list, tuple, torch.Tensor, NoneType] = None, latents_std: typing.Union[list, tuple, torch.Tensor, NoneType] = None, noise_tau: float = 0.0, reshape_to_2d: bool = True, use_encoder_loss: bool = False, scaling_factor: float = 1.0)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/autoencoders/autoencoder_rae.py#L393)

**매개변수:**

encoder_type (`str`, *선택 사항*, 기본값 `"dinov2"`) : 사용할 동결된 인코더의 유형. `"dinov2"`, `"siglip2"`, 또는 `"mae"` 중 하나입니다.
encoder_hidden_size (`int`, *선택 사항*, 기본값 `768`) : 인코더 모델의 숨겨진 크기입니다.
encoder_patch_size (`int`, *선택 사항*, 기본값 `14`) : 인코더 모델의 패치 크기입니다.
encoder_num_hidden_layers (`int`, *선택 사항*, 기본값 `12`) : 인코더 모델의 숨겨진 레이어 수.

patch_size (`int`, *선택 사항*, 기본값 `16`) : Decoder patch size (unpatchify 및 decoder head에 사용됨).
encoder_input_size (`int`, *선택 사항*, 기본값 `224`) : 인코더가 기대하는 입력 크기.
image_size (`int`, *선택 사항*) : 디코더 출력 이미지 크기. `None`인 경우, RAE-main과 마찬가지로 인코더 토큰 수와 `patch_size`에서 유도됩니다: `image_size = patch_size * sqrt(num_patches)`, 여기서 `num_patches = (encoder_input_size // encoder_patch_size) ** 2`입니다.

num_channels (`int`, *선택 사항*, 기본값 `3`) : 입력/출력 채널 수.
encoder_norm_mean (`list`, *선택 사항*, 기본값 `[0.485, 0.456, 0.406]`) : 인코더 입력 정규화를 위한 채널별 평균 (ImageNet 기본값).
encoder_norm_std (`list`, *선택 사항*, 기본값 `[0.229, 0.224, 0.225]`) : 인코더 입력 정규화를 위한 채널별 표준편차 (ImageNet 기본값).
latents_mean (`list` 또는 `tuple`, *선택 사항*) : 잠재 변수 정규화를 위한 선택적 평균 값. Tensor 입력을 허용하며, config 직렬화가 가능한 리스트로 변환됩니다.

latents_std (`list` 또는 `tuple`, *선택 사항*) : 잠재 변수 정규화를 위한 선택적 표준 편차. Tensor 입력을 허용하며 config 직렬화 가능한 리스트로 변환됩니다.
noise_tau (`float`, *선택 사항*, 기본값 `0.0`) : 학습 시 사용할 노이즈 수준(학습 중 latents에 노이즈를 추가합니다).

reshape_to_2d (`bool`, *선택 사항*, 기본값 `True`) : latents를 2D (B, C, H, W) 형식으로 reshape할지 여부.

use_encoder_loss (`bool`, *선택 사항*, 기본값 `False`) : 손실에 인코더 히든 상태를 사용할지 여부(고급 학습용).

이미지를 latent로 인코딩하고 latent를 이미지로 디코딩하는 Representation Autoencoder (RAE) 모델.

이 모델은 학습된 표현으로부터 이미지를 재구성하기 위해 동결된 사전 학습 인코더(DINOv2, SigLIP2, 또는 MAE)와 학습 가능한 ViT 디코더를 사용합니다.

이 모델은 [ModelMixin](/docs/diffusers/main/ko/api/models/overview#diffusers.ModelMixin)에서 상속됩니다. 모든 모델에 대해 구현된 일반적 메서드(다운로드 또는 저장 등)에 대해서는 상위 클래스 문서를 확인하세요.

#### encode[[diffusers.AutoencoderRAE.encode]]

```python
encode(x: Tensor, return_dict: bool = True, generator: typing.Optional[torch.Generator] = None)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/autoencoders/autoencoder_rae.py#L640)

#### decode[[diffusers.AutoencoderRAE.decode]]

```python
decode(z: Tensor, return_dict: bool = True)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/autoencoders/autoencoder_rae.py#L671)

#### forward[[diffusers.AutoencoderRAE.forward]]

```python
forward(sample: Tensor, return_dict: bool = True, generator: typing.Optional[torch.Generator] = None)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/autoencoders/autoencoder_rae.py#L682)

**매개변수:**

sample (`torch.Tensor`) : 입력 샘플.

return_dict (`bool`, *선택 사항*, 기본값 `True`) : 일반 튜플 대신 `DecoderOutput`를 반환할지 여부.
generator (`torch.Generator`, *선택 사항*) : 샘플링을 결정적으로 만들기 위한 [`torch.Generator`](https://pytorch.org/docs/stable/generated/torch.Generator.html)입니다.
**반환값:** `DecoderOutput` 또는 `tuple`
`return_dict`가 True이면 `DecoderOutput`가 반환되고, 그렇지 않으면 일반 `tuple`이 반환됩니다.

## DecoderOutput[[diffusers.models.autoencoders.vae.DecoderOutput]]

#### diffusers.models.autoencoders.vae.DecoderOutput[[diffusers.models.autoencoders.vae.DecoderOutput]]

```python
diffusers.models.autoencoders.vae.DecoderOutput(sample: Tensor, commit_loss: typing.Optional[torch.FloatTensor] = None)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/autoencoders/vae.py#L49)

**매개변수:**

sample (`torch.Tensor`, shape `(batch_size, num_channels, height, width)`) : 모델의 마지막 레이어에서 디코딩된 출력 샘플.

디코딩 메서드의 출력.

Xet Storage Details

Size:: 9.27 kB
Xet hash:: 7c5c8e057fa3856147449fa20a932bf397777c3d9c30c8487f0ea18ffe1d82d1

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

	# AutoencoderRAE

	NYU VISIONx의 Boyang Zheng, Nanye Ma, Shengbang Tong, Saining Xie가 [Diffusion Transformers with Representation Autoencoders](https://huggingface.co/papers/2510.11690)에서 소개한 Representation Autoencoder(RAE) 모델입니다.

	RAE는 동결된 사전 학습된 비전 인코더(DINOv2, SigLIP2 또는 MAE)와 학습 가능한 ViT-MAE 스타일의 디코더를 결합합니다. 2단계 RAE 학습 레시피에서 오토인코더는 1단계(재구성)에서 학습되고, 이후 2단계(생성)에서 생성된 잠재 공간(latent space)에 대해 확산 모델(diffusion model)이 학습됩니다.

	다음 RAE 모델들이 Diffusers에서 릴리스되고 지원됩니다:

	\| 모델 \| 인코더 \| Latent shape (224px 입력) \|
	\|:------\|:--------\|:---------------------------\|
	\| [`nyu-visionx/RAE-dinov2-wReg-base-ViTXL-n08`](https://huggingface.co/nyu-visionx/RAE-dinov2-wReg-base-ViTXL-n08) \| DINOv2-base \| 768 x 16 x 16 \|
	\| [`nyu-visionx/RAE-dinov2-wReg-base-ViTXL-n08-i512`](https://huggingface.co/nyu-visionx/RAE-dinov2-wReg-base-ViTXL-n08-i512) \| DINOv2-base (512px) \| 768 x 32 x 32 \|
	\| [`nyu-visionx/RAE-dinov2-wReg-small-ViTXL-n08`](https://huggingface.co/nyu-visionx/RAE-dinov2-wReg-small-ViTXL-n08) \| DINOv2-small \| 384 x 16 x 16 \|
	\| [`nyu-visionx/RAE-dinov2-wReg-large-ViTXL-n08`](https://huggingface.co/nyu-visionx/RAE-dinov2-wReg-large-ViTXL-n08) \| DINOv2-large \| 1024 x 16 x 16 \|
	\| [`nyu-visionx/RAE-siglip2-base-p16-i256-ViTXL-n08`](https://huggingface.co/nyu-visionx/RAE-siglip2-base-p16-i256-ViTXL-n08) \| SigLIP2-base \| 768 x 16 x 16 \|
	\| [`nyu-visionx/RAE-mae-base-p16-ViTXL-n08`](https://huggingface.co/nyu-visionx/RAE-mae-base-p16-ViTXL-n08) \| MAE-base \| 768 x 16 x 16 \|

	## 사전 학습된 모델 로드

	```python
	from diffusers import AutoencoderRAE

	model = AutoencoderRAE.from_pretrained(
	"nyu-visionx/RAE-dinov2-wReg-base-ViTXL-n08"
	).to("cuda").eval() # or "mps", "xpu", "cpu"
	```

	## 실제 이미지의 인코딩 및 디코딩

	```python
	import torch
	from diffusers import AutoencoderRAE
	from diffusers.utils import load_image
	from torchvision.transforms.functional import to_tensor, to_pil_image

	model = AutoencoderRAE.from_pretrained(
	"nyu-visionx/RAE-dinov2-wReg-base-ViTXL-n08"
	).to("cuda").eval() # or "mps", "xpu", "cpu"

	image = load_image("https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/cat.png")
	image = image.convert("RGB").resize((224, 224))
	x = to_tensor(image).unsqueeze(0).to("cuda") # (1, 3, 224, 224), values in [0, 1]

	with torch.no_grad():
	latents = model.encode(x).latent # (1, 768, 16, 16)
	recon = model.decode(latents).sample # (1, 3, 256, 256)

	recon_image = to_pil_image(recon[0].clamp(0, 1).cpu())
	recon_image.save("recon.png")
	```

	## 잠재 정규화

	일부 사전 학습된 체크포인트에는 잠재 공간 정규화를 위한 채널별 `latents_mean` 및 `latents_std` 통계가 포함되어 있습니다. 이러한 통계가 존재하면 `encode`와 `decode`가 각각 정규화와 역정규화를 자동으로 적용합니다.

	```python
	model = AutoencoderRAE.from_pretrained(
	"nyu-visionx/RAE-dinov2-wReg-base-ViTXL-n08"
	).to("cuda").eval() # or "mps", "xpu", "cpu"

	# Latent normalization is handled automatically inside encode/decode
	# when the checkpoint config includes latents_mean/latents_std.
	with torch.no_grad():
	latents = model.encode(x).latent # normalized latents
	recon = model.decode(latents).sample
	```

	## AutoencoderRAE[[diffusers.AutoencoderRAE]]

	#### diffusers.AutoencoderRAE[[diffusers.AutoencoderRAE]]

	```python
	diffusers.AutoencoderRAE(encoder_type: str = 'dinov2', encoder_hidden_size: int = 768, encoder_patch_size: int = 14, encoder_num_hidden_layers: int = 12, decoder_hidden_size: int = 512, decoder_num_hidden_layers: int = 8, decoder_num_attention_heads: int = 16, decoder_intermediate_size: int = 2048, patch_size: int = 16, encoder_input_size: int = 224, image_size: int \| None = None, num_channels: int = 3, encoder_norm_mean: list \| None = None, encoder_norm_std: list \| None = None, latents_mean: typing.Union[list, tuple, torch.Tensor, NoneType] = None, latents_std: typing.Union[list, tuple, torch.Tensor, NoneType] = None, noise_tau: float = 0.0, reshape_to_2d: bool = True, use_encoder_loss: bool = False, scaling_factor: float = 1.0)
	```

	[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/autoencoders/autoencoder_rae.py#L393)

	매개변수:

	encoder_type (`str`, 선택 사항, 기본값 `"dinov2"`) : 사용할 동결된 인코더의 유형. `"dinov2"`, `"siglip2"`, 또는 `"mae"` 중 하나입니다.

	encoder_hidden_size (`int`, 선택 사항, 기본값 `768`) : 인코더 모델의 숨겨진 크기입니다.

	encoder_patch_size (`int`, 선택 사항, 기본값 `14`) : 인코더 모델의 패치 크기입니다.

	encoder_num_hidden_layers (`int`, 선택 사항, 기본값 `12`) : 인코더 모델의 숨겨진 레이어 수.

	patch_size (`int`, 선택 사항, 기본값 `16`) : Decoder patch size (unpatchify 및 decoder head에 사용됨).

	encoder_input_size (`int`, 선택 사항, 기본값 `224`) : 인코더가 기대하는 입력 크기.

	image_size (`int`, 선택 사항) : 디코더 출력 이미지 크기. `None`인 경우, RAE-main과 마찬가지로 인코더 토큰 수와 `patch_size`에서 유도됩니다: `image_size = patch_size * sqrt(num_patches)`, 여기서 `num_patches = (encoder_input_size // encoder_patch_size) ** 2`입니다.

	num_channels (`int`, 선택 사항, 기본값 `3`) : 입력/출력 채널 수.

	encoder_norm_mean (`list`, 선택 사항, 기본값 `[0.485, 0.456, 0.406]`) : 인코더 입력 정규화를 위한 채널별 평균 (ImageNet 기본값).

	encoder_norm_std (`list`, 선택 사항, 기본값 `[0.229, 0.224, 0.225]`) : 인코더 입력 정규화를 위한 채널별 표준편차 (ImageNet 기본값).

	latents_mean (`list` 또는 `tuple`, 선택 사항) : 잠재 변수 정규화를 위한 선택적 평균 값. Tensor 입력을 허용하며, config 직렬화가 가능한 리스트로 변환됩니다.

	latents_std (`list` 또는 `tuple`, 선택 사항) : 잠재 변수 정규화를 위한 선택적 표준 편차. Tensor 입력을 허용하며 config 직렬화 가능한 리스트로 변환됩니다.

	noise_tau (`float`, 선택 사항, 기본값 `0.0`) : 학습 시 사용할 노이즈 수준(학습 중 latents에 노이즈를 추가합니다).

	reshape_to_2d (`bool`, 선택 사항, 기본값 `True`) : latents를 2D (B, C, H, W) 형식으로 reshape할지 여부.

	use_encoder_loss (`bool`, 선택 사항, 기본값 `False`) : 손실에 인코더 히든 상태를 사용할지 여부(고급 학습용).

	이미지를 latent로 인코딩하고 latent를 이미지로 디코딩하는 Representation Autoencoder (RAE) 모델.

	이 모델은 학습된 표현으로부터 이미지를 재구성하기 위해 동결된 사전 학습 인코더(DINOv2, SigLIP2, 또는 MAE)와 학습 가능한 ViT 디코더를 사용합니다.

	이 모델은 [ModelMixin](/docs/diffusers/main/ko/api/models/overview#diffusers.ModelMixin)에서 상속됩니다. 모든 모델에 대해 구현된 일반적 메서드(다운로드 또는 저장 등)에 대해서는 상위 클래스 문서를 확인하세요.

	#### encode[[diffusers.AutoencoderRAE.encode]]

	```python
	encode(x: Tensor, return_dict: bool = True, generator: typing.Optional[torch.Generator] = None)
	```

	[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/autoencoders/autoencoder_rae.py#L640)

	#### decode[[diffusers.AutoencoderRAE.decode]]

	```python
	decode(z: Tensor, return_dict: bool = True)
	```

	[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/autoencoders/autoencoder_rae.py#L671)

	#### forward[[diffusers.AutoencoderRAE.forward]]

	```python
	forward(sample: Tensor, return_dict: bool = True, generator: typing.Optional[torch.Generator] = None)
	```

	[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/autoencoders/autoencoder_rae.py#L682)

	매개변수:

	sample (`torch.Tensor`) : 입력 샘플.

	return_dict (`bool`, 선택 사항, 기본값 `True`) : 일반 튜플 대신 `DecoderOutput`를 반환할지 여부.

	generator (`torch.Generator`, 선택 사항) : 샘플링을 결정적으로 만들기 위한 [`torch.Generator`](https://pytorch.org/docs/stable/generated/torch.Generator.html)입니다.

	반환값: `DecoderOutput` 또는 `tuple`

	`return_dict`가 True이면 `DecoderOutput`가 반환되고, 그렇지 않으면 일반 `tuple`이 반환됩니다.

	## DecoderOutput[[diffusers.models.autoencoders.vae.DecoderOutput]]

	#### diffusers.models.autoencoders.vae.DecoderOutput[[diffusers.models.autoencoders.vae.DecoderOutput]]

	```python
	diffusers.models.autoencoders.vae.DecoderOutput(sample: Tensor, commit_loss: typing.Optional[torch.FloatTensor] = None)
	```

	[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/autoencoders/vae.py#L49)

	매개변수:

	sample (`torch.Tensor`, shape `(batch_size, num_channels, height, width)`) : 모델의 마지막 레이어에서 디코딩된 출력 샘플.

	디코딩 메서드의 출력.