# GGUF

[GGUF](https://github.com/ggerganov/ggml/blob/master/docs/gguf.md)은 [GGML](https://github.com/ggerganov/ggml)로 추론을 수행하기 위한 모델을 저장하는 단일 파일 형식으로, 모델 메타데이터와 텐서를 포함합니다. 다양한 양자화 데이터 유형을 지원하여([양자화 유형 표](https://hf.co/docs/hub/en/gguf#quantization-types) 참조) 상당한 양의 메모리를 절약할 수 있습니다.

    

## GGUF 모델 로드

[kernels](https://huggingface.co/docs/kernels/index)를 설치하지 않으면 로드 시 패킹된 경로가 전체 [dequantization](#dequantize)으로 폴백됩니다.

```bash
pip install kernels
```

Hub 커널 [ggml-org/ggml-quantization](https://huggingface.co/ggml-org/ggml-quantization)이 사용 가능한 경우 Weights는 packed 상태로 유지됩니다. 해당 커널이 존재하면 로더는 기본적으로 MPS를 사용하며, packed 블록에서 matmul을 직접 실행합니다. 커널이 사용 불가능한 경우 모델은 로드 시 dequantize됩니다.

```py
from transformers import AutoModelForCausalLM, AutoTokenizer

model_id = "unsloth/Qwen3.5-4B-GGUF"
filename = "Qwen3.5-4B-Q4_K_M.gguf"

model = AutoModelForCausalLM.from_pretrained(model_id, gguf_file=filename)
tokenizer = AutoTokenizer.from_pretrained(model_id, gguf_file=filename)
```

Qwen3.5 MoE에도 동일한 load가 작동합니다.

```py
moe_model_id = "unsloth/Qwen3.5-35B-A3B-GGUF"
moe_filename = "Qwen3.5-35B-A3B-Q4_K_M.gguf"

moe_model = AutoModelForCausalLM.from_pretrained(moe_model_id, gguf_file=moe_filename)
moe_tokenizer = AutoTokenizer.from_pretrained(moe_model_id, gguf_file=moe_filename)
```

Packed 경로는 현재 Qwen3.5와 Qwen3.5 MoE를 지원합니다. Packed 로드는 MPS에서 더 빠르기 때문에 자동으로 float32를 사용합니다. 다른 `dtype`을 설정하면 로더가 경고를 반환합니다. 다른 아키텍처는 레거시 로더를 통해 처리됩니다.

## Attention

MPS에서 커널이 설치된 경우, GGUF 파일을 로드할 때 [ggml-attn](https://huggingface.co/kernels/ggml-org/ggml-attn)이 기본 attention으로 사용됩니다. 이는 llama.cpp가 decode와 prefill에 사용하는 것과 동일한 flash-attention 커널입니다. 커널을 가져올 수 없는 경우, 모델은 기존 attention 구현을 유지합니다. `attn_implementation`을 전달하면(예: `"sdpa"`) 항상 우선 적용됩니다.

명시적으로 전달할 수도 있습니다:

```py
model = AutoModelForCausalLM.from_pretrained(
    model_id, gguf_file=filename, attn_implementation="ggml-org/ggml-attn"
)
```

## 양자화 해제

Dequantizing은 로드 시점에 모든 가중치를 해제하여 일반적인 dense 모델을 반환합니다. 빠르고 압축된 경로가 적용되지 않는 경우의 폴백으로 사용됩니다. [GgufConfig](/docs/transformers/v5.23.0/ko/main_classes/quantization#transformers.GgufConfig)를 사용하여 명시적으로 요청할 수도 있습니다.

```py
import torch

from transformers import AutoModelForCausalLM, GgufConfig

quantization_config = GgufConfig(dequantize=True)
model = AutoModelForCausalLM.from_pretrained(
    model_id, gguf_file=filename, quantization_config=quantization_config, dtype=torch.bfloat16
)
```

`dtype`로 전달한 값에 해당하는 일반 dense 모델을 얻습니다.

Qwen3.5와 Qwen3.5 MoE를 제외한 다른 아키텍처는 항상 dequantize하는 legacy loader를 통해 로드됩니다.

> [!TIP]
> 레거시 로더는 Llama, Mistral, Qwen2, Qwen2Moe, Phi3, Bloom, Falcon, StableLM, GPT2, Starcoder2 및 [기타 모델](https://github.com/huggingface/transformers/blob/main/src/transformers/integrations/ggml.py)을 지원합니다.

## 서빙

[transformers serve](../serve-cli/serving)는 저장소의 각 `.gguf` 파일을 개별 모델로 나열합니다. 저장소에는 여러 양자화 버전이 포함되어 있으므로 로드할 버전을 식별하기 위해 GGUF 모델의 이름은 `<repo>:<file>.gguf` 형식입니다. 요청에서도 동일한 방식으로 이름을 지정합니다.

```shell
transformers serve unsloth/Qwen3.5-4B-GGUF:Qwen3.5-4B-Q4_K_M.gguf
```