Buckets:

hf-doc-build
/

doc

Files

xet

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

mishig

about 12 hours ago

preview code

download

raw

5.02 kB

# GGUF

GGUF 파일 형식은 일반적으로 [GGML](https://github.com/ggerganov/ggml)을 사용하여 추론하는 모델을 저장하는 데 사용되며, 다양한 블록 단위 양자화 옵션을 지원합니다. Diffusers는 Model 클래스의 `from_single_file` 로딩을 통해 GGUF 형식으로 사전 양자화되어 저장된 체크포인트를 로드하는 것을 지원합니다. 현재 Pipeline을 통한 GGUF 체크포인트 로딩은 지원되지 않습니다.

다음 예제는 [FLUX.1 DEV](https://huggingface.co/black-forest-labs/FLUX.1-dev) transformer 모델을 GGUF Q2_K 양자화 변형으로 로드합니다.
시작하기 전에 환경에 gguf를 설치하세요
```shell
pip install -U gguf
```
GGUF은 단일 파일 형식이므로, `~FromSingleFileMixin.from_single_file`를 사용하여 모델을 로드하고 [GGUFQuantizationConfig](/docs/diffusers/main/ko/api/quantization#diffusers.GGUFQuantizationConfig)를 전달하세요.
GGUF 체크포인트를 사용할 때, 양자화된 가중치는 낮은 메모리 `dtype`(일반적으로 `torch.uint8`)로 유지되며, 모델의 각 모듈이 포워드 패스를 수행할 때마다 동적으로 역양자화되어 설정된 `compute_dtype`으로 캐스트됩니다. `GGUFQuantizationConfig`를 사용하면 `compute_dtype`을 설정할 수 있습니다.
동적 역양자화에 사용되는 함수들은 [compilade](https://github.com/compilade)의 원래 [`numpy`](https://github.com/ggerganov/llama.cpp/blob/master/gguf-py/gguf/quants.py) 구현을 Pytorch로 이식한 [city96](https://github.com/city96/ComfyUI-GGUF)의 훌륭한 작업을 기반으로 합니다.
```python
import torch
from diffusers import FluxPipeline, FluxTransformer2DModel, GGUFQuantizationConfig
ckpt_path = (
    "https://huggingface.co/city96/FLUX.1-dev-gguf/blob/main/flux1-dev-Q2_K.gguf"
)
transformer = FluxTransformer2DModel.from_single_file(
    ckpt_path,
    quantization_config=GGUFQuantizationConfig(compute_dtype=torch.bfloat16),
    dtype=torch.bfloat16,
)
pipe = FluxPipeline.from_pretrained(
    "black-forest-labs/FLUX.1-dev",
    transformer=transformer,
    dtype=torch.bfloat16,
)
pipe.enable_model_cpu_offload()
prompt = "A cat holding a sign that says hello world"
image = pipe(prompt, generator=torch.manual_seed(0)).images[0]
image.save("flux-gguf.png")
```
## GGUF에서 최적화된 CUDA 커널 사용

최적화된 CUDA 커널은 GGUF 양자화 모델 추론을 약 10% 가속화할 수 있습니다. 이 기능은 `torch.cuda.get_device_capability`가 7보다 큰 호환 가능한 GPU와 커널 라이브러리가 필요합니다:

```shell
pip install -U kernels
```

설치 후, 최적화된 커널이 사용 가능한 경우 이를 사용하려면 `DIFFUSERS_GGUF_CUDA_KERNELS=true`를 설정하세요. CUDA 커널은 원래 GGUF 구현과 비교했을 때 미세한 수치적 차이를 유발할 수 있으며, 이로 인해 생성된 이미지에 미묘한 시각적 변이가 발생할 수 있습니다. CUDA 커널 사용을 비활성화하려면 환경 변수 `DIFFUSERS_GGUF_CUDA_KERNELS=false`를 설정하세요.

GGUF 커널은 [`Isotr0py/ggml`](https://huggingface.co/Isotr0py/ggml) 저장소에서 다운로드되며, 해당 저장소의 게시자는 Hub에서 신뢰할 수 있는 커널 게시자가 아닙니다. 이 커널을 로드하면 Hub에서 코드를 다운로드하고 실행하므로, Diffusers에서는 `DIFFUSERS_TRUST_REMOTE_KERNELS=true`를 설정하여 명시적으로 허용하도록 요구합니다. 자세한 내용은 [원격 커널 신뢰](../optimization/attention_backends#trusting-remote-kernels)를 참조하세요.

## 지원되는 양자화 유형

- BF16
- Q4_0
- Q4_1
- Q5_0
- Q5_1
- Q8_0
- Q2_K
- Q3_K
- Q4_K
- Q5_K
- Q6_K

## GGUF로 변환

아래 Space를 사용하여 Diffusers 체크포인트를 추론을 위한 GGUF 형식으로 변환합니다. 변환 실행:

<iframe src="https://diffusers-internal-dev-diffusers-to-gguf.hf.space" frameborder="0" width="850" height="450"
>

```py
import torch
from diffusers import FluxPipeline, FluxTransformer2DModel, GGUFQuantizationConfig
ckpt_path = (
    "https://huggingface.co/sayakpaul/different-lora-from-civitai/blob/main/flux_dev_diffusers-q4_0.gguf"
)
transformer = FluxTransformer2DModel.from_single_file(
    ckpt_path,
    quantization_config=GGUFQuantizationConfig(compute_dtype=torch.bfloat16),
    config="black-forest-labs/FLUX.1-dev",
    subfolder="transformer",
    dtype=torch.bfloat16,
)
pipe = FluxPipeline.from_pretrained(
    "black-forest-labs/FLUX.1-dev",
    transformer=transformer,
    dtype=torch.bfloat16,
)
pipe.enable_model_cpu_offload()
prompt = "A cat holding a sign that says hello world"
image = pipe(prompt, generator=torch.manual_seed(0)).images[0]
image.save("flux-gguf.png")
```

Diffusers 형식의 GGUF 체크포인트를 사용할 때는 모델의 `config` 경로를 반드시 제공해야 합니다. 모델 config가 `subfolder`에 있는 경우, 해당 경로도 지정해야 합니다.

Xet Storage Details

Size:: 5.02 kB
Xet hash:: 67ecbae8c89db931cc9ce99df3057daf80ef47527299571548d22ba417630e32

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

	# GGUF

	GGUF 파일 형식은 일반적으로 [GGML](https://github.com/ggerganov/ggml)을 사용하여 추론하는 모델을 저장하는 데 사용되며, 다양한 블록 단위 양자화 옵션을 지원합니다. Diffusers는 Model 클래스의 `from_single_file` 로딩을 통해 GGUF 형식으로 사전 양자화되어 저장된 체크포인트를 로드하는 것을 지원합니다. 현재 Pipeline을 통한 GGUF 체크포인트 로딩은 지원되지 않습니다.

	다음 예제는 [FLUX.1 DEV](https://huggingface.co/black-forest-labs/FLUX.1-dev) transformer 모델을 GGUF Q2_K 양자화 변형으로 로드합니다.

	시작하기 전에 환경에 gguf를 설치하세요

	```shell
	pip install -U gguf
	```

	GGUF은 단일 파일 형식이므로, `~FromSingleFileMixin.from_single_file`를 사용하여 모델을 로드하고 [GGUFQuantizationConfig](/docs/diffusers/main/ko/api/quantization#diffusers.GGUFQuantizationConfig)를 전달하세요.

	GGUF 체크포인트를 사용할 때, 양자화된 가중치는 낮은 메모리 `dtype`(일반적으로 `torch.uint8`)로 유지되며, 모델의 각 모듈이 포워드 패스를 수행할 때마다 동적으로 역양자화되어 설정된 `compute_dtype`으로 캐스트됩니다. `GGUFQuantizationConfig`를 사용하면 `compute_dtype`을 설정할 수 있습니다.

	동적 역양자화에 사용되는 함수들은 [compilade](https://github.com/compilade)의 원래 [`numpy`](https://github.com/ggerganov/llama.cpp/blob/master/gguf-py/gguf/quants.py) 구현을 Pytorch로 이식한 [city96](https://github.com/city96/ComfyUI-GGUF)의 훌륭한 작업을 기반으로 합니다.

	```python
	import torch

	from diffusers import FluxPipeline, FluxTransformer2DModel, GGUFQuantizationConfig

	ckpt_path = (
	"https://huggingface.co/city96/FLUX.1-dev-gguf/blob/main/flux1-dev-Q2_K.gguf"
	)
	transformer = FluxTransformer2DModel.from_single_file(
	ckpt_path,
	quantization_config=GGUFQuantizationConfig(compute_dtype=torch.bfloat16),
	dtype=torch.bfloat16,
	)
	pipe = FluxPipeline.from_pretrained(
	"black-forest-labs/FLUX.1-dev",
	transformer=transformer,
	dtype=torch.bfloat16,
	)
	pipe.enable_model_cpu_offload()
	prompt = "A cat holding a sign that says hello world"
	image = pipe(prompt, generator=torch.manual_seed(0)).images[0]
	image.save("flux-gguf.png")
	```

	## GGUF에서 최적화된 CUDA 커널 사용

	최적화된 CUDA 커널은 GGUF 양자화 모델 추론을 약 10% 가속화할 수 있습니다. 이 기능은 `torch.cuda.get_device_capability`가 7보다 큰 호환 가능한 GPU와 커널 라이브러리가 필요합니다:

	```shell
	pip install -U kernels
	```

	설치 후, 최적화된 커널이 사용 가능한 경우 이를 사용하려면 `DIFFUSERS_GGUF_CUDA_KERNELS=true`를 설정하세요. CUDA 커널은 원래 GGUF 구현과 비교했을 때 미세한 수치적 차이를 유발할 수 있으며, 이로 인해 생성된 이미지에 미묘한 시각적 변이가 발생할 수 있습니다. CUDA 커널 사용을 비활성화하려면 환경 변수 `DIFFUSERS_GGUF_CUDA_KERNELS=false`를 설정하세요.

	GGUF 커널은 [`Isotr0py/ggml`](https://huggingface.co/Isotr0py/ggml) 저장소에서 다운로드되며, 해당 저장소의 게시자는 Hub에서 신뢰할 수 있는 커널 게시자가 아닙니다. 이 커널을 로드하면 Hub에서 코드를 다운로드하고 실행하므로, Diffusers에서는 `DIFFUSERS_TRUST_REMOTE_KERNELS=true`를 설정하여 명시적으로 허용하도록 요구합니다. 자세한 내용은 [원격 커널 신뢰](../optimization/attention_backends#trusting-remote-kernels)를 참조하세요.

	## 지원되는 양자화 유형

	- BF16
	- Q4_0
	- Q4_1
	- Q5_0
	- Q5_1
	- Q8_0
	- Q2_K
	- Q3_K
	- Q4_K
	- Q5_K
	- Q6_K

	## GGUF로 변환

	아래 Space를 사용하여 Diffusers 체크포인트를 추론을 위한 GGUF 형식으로 변환합니다. 변환 실행:

	<iframe src="https://diffusers-internal-dev-diffusers-to-gguf.hf.space" frameborder="0" width="850" height="450"
	>

	```py
	import torch

	from diffusers import FluxPipeline, FluxTransformer2DModel, GGUFQuantizationConfig

	ckpt_path = (
	"https://huggingface.co/sayakpaul/different-lora-from-civitai/blob/main/flux_dev_diffusers-q4_0.gguf"
	)
	transformer = FluxTransformer2DModel.from_single_file(
	ckpt_path,
	quantization_config=GGUFQuantizationConfig(compute_dtype=torch.bfloat16),
	config="black-forest-labs/FLUX.1-dev",
	subfolder="transformer",
	dtype=torch.bfloat16,
	)
	pipe = FluxPipeline.from_pretrained(
	"black-forest-labs/FLUX.1-dev",
	transformer=transformer,
	dtype=torch.bfloat16,
	)
	pipe.enable_model_cpu_offload()
	prompt = "A cat holding a sign that says hello world"
	image = pipe(prompt, generator=torch.manual_seed(0)).images[0]
	image.save("flux-gguf.png")
	```

	Diffusers 형식의 GGUF 체크포인트를 사용할 때는 모델의 `config` 경로를 반드시 제공해야 합니다. 모델 config가 `subfolder`에 있는 경우, 해당 경로도 지정해야 합니다.