# AutoRound

[AutoRound](https://github.com/intel/auto-round)는 고급 양자화 툴킷입니다. 부호-경사 하강(sign-gradient descent)을 활용하고 광범위한 하드웨어 호환성을 제공하여, 최소한의 튜닝으로 초저 비트 폭(2~4비트)에서도 높은 정확도를 달성합니다. 자세한 내용은 [SignRoundV1](https://arxiv.org/pdf/2309.05516) 및 [SignRoundV2](https://arxiv.org/abs/2512.04746) 논문을 참고하세요.

`auto-round`(버전 ≥ 0.13.0) 설치:

```bash
pip install "auto-round>=0.13.0"
```

더 빠른 CUDA 추론을 위해 Marlin 커널을 사용하려면 `gptqmodel`을 설치하세요:

```bash
pip install "gptqmodel>=5.8.0"
```

## 양자화된 모델 로드

`AutoRoundConfig`를 [from_pretrained()](/docs/diffusers/main/ko/api/models/overview#diffusers.ModelMixin.from_pretrained)에 전달하여 사전 양자화된 AutoRound 모델을 로드합니다. 이 메서드는 [Accelerate](https://hf.co/docs/accelerate/index)를 통해 로드되고 `torch.nn.Linear` 레이어를 가진 모든 모델에서 작동합니다.

[PipelineQuantizationConfig](/docs/diffusers/main/ko/api/quantization#diffusers.PipelineQuantizationConfig)를 사용하여 파이프라인의 특정 구성 요소를 양자화할 수 있습니다:

```python
import torch
from diffusers import DiffusionPipeline, PipelineQuantizationConfig, AutoRoundConfig

pipeline_quant_config = PipelineQuantizationConfig(
    quant_mapping={"transformer": AutoRoundConfig(backend="auto")}
)
pipe = DiffusionPipeline.from_pretrained(
    "INCModel/Z-Image-W4A16-AutoRound",
    quantization_config=pipeline_quant_config,
    dtype=torch.bfloat16,
    device_map="cuda",  # or "mps", "xpu", "cpu"
)

image = pipe("a cat holding a sign that says hello").images[0]
image.save("output.png")
```

또는 양자화된 모델 구성 요소를 직접 로드합니다:

```python
import torch
from diffusers import ZImageTransformer2DModel, ZImagePipeline, AutoRoundConfig

model_id = "INCModel/Z-Image-W4A16-AutoRound"

quantization_config = AutoRoundConfig(backend="auto")
transformer = ZImageTransformer2DModel.from_pretrained(
    model_id,
    subfolder="transformer",
    quantization_config=quantization_config,
    dtype=torch.bfloat16,
    device_map="cuda",  # or "mps", "xpu", "cpu"
)

pipe = ZImagePipeline.from_pretrained(
    model_id,
    transformer=transformer,
    dtype=torch.bfloat16,
    device_map="cuda",
)

image = pipe("a cat holding a sign that says hello").images[0]
image.save("output.png")
```

> [!NOTE]
> Diffusers의 AutoRound는 *사전 양자화*된 모델만 로드하는 것을 지원합니다. 모델을 처음부터 양자화하려면 [AutoRound CLI 또는 Python API](https://github.com/intel/auto-round)를 직접 사용하고, 그 결과를 Diffusers로 로드하세요.

## torch.compile

AutoRound은 더 빠른 추론을 위해 [`torch.compile`](../optimization/fp16#torchcompile)과 호환됩니다. 더 나은 성능을 위해 양자화된 transformer(DiT)를 컴파일할 수 있습니다:

```python
import torch
from diffusers import DiffusionPipeline, PipelineQuantizationConfig, AutoRoundConfig

pipeline_quant_config = PipelineQuantizationConfig(
    quant_mapping={"transformer": AutoRoundConfig(backend="auto")}
)
pipe = DiffusionPipeline.from_pretrained(
    "INCModel/Z-Image-W4A16-AutoRound",
    quantization_config=pipeline_quant_config,
    dtype=torch.bfloat16,
    device_map="cuda",  # or "mps", "xpu", "cpu"
)

pipe.transformer = torch.compile(pipe.transformer, mode="default", fullgraph=False)
```

## 백엔드

AutoRound은 Weight-only 양자화 모델에 대해 여러 추론 백엔드를 지원합니다. 백엔드는 forward pass 동안 dequantization을 처리하는 커널을 제어합니다. `AutoRoundConfig`의 `backend` 매개변수를 설정하여 하나를 선택합니다:

| 백엔드 | 값 | 장치 | 요구 사항 | The input is a single word "Notes".

참고 |
|---------|-------|--------|--------------|-------|
| **Auto** | `"auto"` | 모두 | — | 기본값. 사용 가능한 최적의 백엔드를 자동으로 선택합니다. |
| **PyTorch** | `"torch"` | CPU / CUDA | — | 순수 PyTorch 구현. 가장 넓은 호환성. |
| **Triton** | `"tritonv2"` | CUDA | `triton` | GPU 추론을 위한 Triton 기반 커널. |
| **ExllamaV2** | `"exllamav2"` | CUDA | `gptqmodel>=5.8.0` | ExllamaV2 커널을 통한 뛰어난 CUDA 성능. |
| **Marlin** | `"marlin"` | CUDA | `gptqmodel>=5.8.0` | Marlin 커널을 통해 최적의 CUDA 성능을 제공합니다. |

```python
from diffusers import AutoRoundConfig

# Auto-select (default)
config = AutoRoundConfig()

# Explicit Triton backend for CUDA
config = AutoRoundConfig(backend="tritonv2")

# Marlin backend for best CUDA performance (requires gptqmodel>=5.8.0)
config = AutoRoundConfig(backend="marlin")

# ExllamaV2 backend for good CUDA performance (requires gptqmodel>=5.8.0)
config = AutoRoundConfig(backend="exllamav2")

# PyTorch backend for CPU/CUDA inference
config = AutoRoundConfig(backend="torch")
```

## 저장 및 로드

AutoRound은 모델을 양자화하기 위해 데이터 보정이 필요합니다. 이는 Diffusers 외부에서 [AutoRound 라이브러리](https://github.com/intel/auto-round)를 직접 사용하여 수행됩니다:

```python
from auto_round import AutoRound

autoround = AutoRound(
    "Tongyi-MAI/Z-Image",
    scheme="W4A16",  # W4G128 symmetric
    enable_torch_compile=True,
    num_inference_steps=3,
    guidance_scale=7.5,
    dataset="coco2014",
)
autoround.quantize_and_save("Z-Image-W4A16-AutoRound")
```

교정 옵션에 대한 자세한 내용은 [AutoRound 문서](https://github.com/intel/auto-round)를 참조하세요.

```python
import torch
from diffusers import ZImageTransformer2DModel, ZImagePipeline

model_id = "INCModel/Z-Image-W4A16-AutoRound"

# The inference backend will be automatically selected.
pipe = ZImagePipeline.from_pretrained(
    model_id,
    dtype=torch.bfloat16,
    device_map="cuda",  # or "mps", "xpu", "cpu"
)

image = pipe("a cat holding a sign that says hello").images[0]
image.save("output.png")
```

### 지원되는 양자화 스킴

AutoRound은 여러 Schemes를 지원합니다:

- **W4A16**(bits:4,group_size:128,sym:True,act_bits:16)
- **W8A16**(bits:8,group_size:128,sym:True,act_bits:16)
- **W3A16**(bits:3,group_size:128,sym:True,act_bits:16)
- **W2A16**(bits:2,group_size:128,sym:True,act_bits:16)
- **GGUF:Q4_K_M**(llamacpp에서 제공하는 모든 Q*_K, Q*_0, Q*_1이 지원됩니다)
- **NVFP4**(실험적 기능, `llm_compressor` 형식으로 내보내는 것을 권장합니다. data_type nvfp4,act_data_type nvfp4,static_global_scale,group_size 16)
- **MXFP4**(**연구용 기능, 실제 커널 없음**, 표준 MXFP4, data_type mxfp,act_data_type mxfp,bits 4, act_bits 4, group_size 32)
- **MXINT4**(**연구용 기능, 실제 커널 없음**, Standard MXINT4, data_type mxint,act_data_type mxint,bits 4, act_bits 4, group_size 32)
- **MXFP4_RCEIL**(**연구용 기능, 실제 커널 없음**, NVIDIA의 변형, data_type mxfp, act_data_type mxfp_rceil, bits 4, act_bits 4, group_size 32)
- **MXFP8**(**연구용 기능, 실제 커널 없음**, data_type mxfp,act_data_type mxfp_rceil,group_size 32)
- **FPW8A16**(**연구용 기능, 실제 커널 없음**, data_type fp8,group_size 0->per tensor )
- **FP8_STATIC**(**연구용 기능, 실제 커널 없음**, data_type:fp8,act_data_type:fp8,group_size -1 ->채널별, act_group_size=0->텐서별)

또한, `group_size`, `bits`, `sym` 등 원하는 여러 설정을 수정할 수 있지만, 실제 커널이 없을 수 있습니다.

## 리소스

- [Hub의 사전 양자화 AutoRound 모델](https://huggingface.co/models?search=autoround)