Buckets:

hf-doc-build
/

doc

Files

xet

hf-doc-build/doc / diffusers /main /ko /quantization /autoround.md

mishig

about 17 hours ago

preview code

download

raw

7.75 kB

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

Xet Storage Details

Size:: 7.75 kB
Xet hash:: e0e658de21997a99def27fa9b536376ae2869c829682898062f9e143031ce0c7

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

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