GGUF

GGUF은 GGML로 추론을 수행하기 위한 모델을 저장하는 단일 파일 형식으로, 모델 메타데이터와 텐서를 포함합니다. 다양한 양자화 데이터 유형을 지원하여(양자화 유형 표 참조) 상당한 양의 메모리를 절약할 수 있습니다.

GGUF 모델 로드

kernels를 설치하지 않으면 로드 시 패킹된 경로가 전체 dequantization으로 폴백됩니다.

pip install kernels

Hub 커널 ggml-org/ggml-quantization이 사용 가능한 경우, 가중치는 패킹된 상태로 유지됩니다. 해당 커널이 존재하면 로더는 기본적으로 MPS를 사용하며, matmul 연산을 패킹된 블록에서 직접 수행합니다. 커널이 사용 불가능한 경우, 모델은 로드 시점에 역양자화됩니다.

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가 작동합니다.

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 path는 현재 Qwen3.5와 Qwen3.5 MoE를 지원합니다. Packed loads는 MPS에서 더 빠르기 때문에 자동으로 float32를 사용합니다. 다른 dtype을 설정하면 로더가 경고를 반환합니다. 다른 아키텍처는 legacy loader를 통해 처리됩니다.

Attention

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

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

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

양자화 해제

Dequantizing은 로드 시점에 모든 가중치를 복원하여 일반적인 dense 모델을 반환합니다. 빠르고 압축된 경로가 적용되지 않는 경우의 기본 대안으로 사용됩니다. GgufConfig를 통해 명시적으로 요청할 수도 있습니다.

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를 통해 로드됩니다.

레거시 로더는 Llama, Mistral, Qwen2, Qwen2Moe, Phi3, Bloom, Falcon, StableLM, GPT2, Starcoder2 및 기타 모델을 지원합니다.

서빙

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

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