[transformers] Hugging Face Transformers, GGUF 추론 속도 향상을 위한 대대적인 리팩토링

2026년 9월 4일수정: 2026년 9월 4일

PR 링크: huggingface/transformers#47779 상태: Merged | 변경: +2087 / -137

들어가며

Hugging Face의 transformers 라이브러리는 다양한 모델 아키텍처와 사전 훈련된 가중치를 지원하며, 자연어 처리 분야의 발전에 크게 기여해왔습니다. 특히, GGUF(GPT-Generated Unified Format)는 GGML의 후속 포맷으로, 모델의 메타데이터와 텐서를 단일 파일에 포함하며 다양한 양자화(quantization) 기법을 지원하여 메모리 사용량을 크게 줄여줍니다. 이는 대규모 언어 모델(LLM)을 로컬 환경이나 엣지 디바이스에서 효율적으로 실행할 수 있게 하는 핵심 요소입니다.

이번 PR(Pull Request)은 transformers 라이브러리에서 GGUF 모델의 추론 성능을 대폭 향상시키기 위한 중요한 리팩토링을 단행했습니다. 기존의 GGUF 로딩 및 처리 방식에서 벗어나, 최신 기능과 최적화된 커널을 활용하여 특히 양자화된 모델의 추론 속도를 개선하는 데 초점을 맞추고 있습니다. 이 글에서는 해당 PR의 주요 변경 사항과 그 의미, 그리고 성능 개선 효과에 대해 자세히 살펴보겠습니다.

코드 분석

이번 PR은 GGUF 지원을 현대화하고 성능을 최적화하기 위해 여러 파일에 걸쳐 광범위한 변경을 포함합니다. 주요 변경 사항은 다음과 같습니다.

1. 문서 구조 변경 (`docs/source/en/_redirects.yml`, `docs/source/en/_toctree.yml`, `docs/source/en/gguf.md`, `docs/source/en/main_classes/quantization.md`, `docs/source/en/quantization/gguf.md`, `docs/source/en/quantization/overview.md`, `docs/source/en/serve-cli/jan.md`)

가장 눈에 띄는 변화 중 하나는 문서 구조의 개편입니다. 기존의 gguf.md 파일이 삭제되고, quantization/gguf.md로 이동 및 재구성되었습니다. 이는 GGUF 지원이 라이브러리의 전반적인 양자화 기능의 일부로 통합되었음을 명확히 합니다.

docs/source/en/_redirects.yml: 기존 gguf 경로를 새로운 quantization/gguf로 리디렉션하도록 수정되었습니다.
docs/source/en/_toctree.yml: 문서 목차에서 gguf 항목이 quantization/gguf로 업데이트되었습니다.
docs/source/en/gguf.md (삭제): 기존 GGUF 관련 문서가 제거되었습니다.
docs/source/en/main_classes/quantization.md: GgufConfig 클래스가 추가되어 GGUF 관련 설정을 위한 문서가 마련되었습니다.
docs/source/en/quantization/gguf.md (신규 생성): GGUF 모델 로딩 방법, Metal(MPS)에서의 llama.cpp 커널 활용, 어텐션 구현, 디퀀타이제이션, 서빙 등 GGUF 관련 상세 내용을 담고 있습니다. 특히, Metal GPU에서 llama.cpp 커널을 직접 사용하여 추론 속도를 높이는 방법과 GgufConfig를 통한 디퀀타이제이션 제어 방법을 설명합니다.
docs/source/en/quantization/overview.md: 양자화 방법 비교 테이블에 GGUF/GGML (llama.cpp) 항목이 업데이트되어, quantization/gguf 문서로 연결됩니다.
docs/source/en/serve-cli/jan.md: transformers serve 명령어에서 GGUF 모델을 지정하는 방식(repo:file.gguf)이 명확해졌습니다.

이러한 문서 변경은 GGUF 지원의 구조적 개선과 사용 편의성 증대를 반영합니다.

2. GGUF 로딩 및 처리 로직 개선 (`src/transformers/integrations/gguf/` 디렉토리)

이 PR의 핵심은 GGUF 모델의 로딩 및 추론 방식을 최적화하는 것입니다. 이를 위해 src/transformers/integrations/gguf/ 아래에 새로운 모듈들이 도입되었습니다.

src/transformers/integrations/gguf/dequant.py: GGUF 모델을 디퀀타이즈(dequantize)하는 로직을 담당합니다. 리뷰어 ArthurZucker는 이 부분이 다른 라이브러리에서 가져온 코드를 활용하여 검토 부담을 줄였다고 언급했습니다. 또한, 기존의 fp32로 강제 디퀀타이즈하는 방식 대신, update_dtype 함수를 통해 지정된 dtype으로 디퀀타이즈하도록 개선되었습니다.

# Before (Implicit fp32 dequantization)
# model = AutoModelForCausalLM.from_pretrained(model_id, gguf_file=filename)

# After (Explicit dequantization control with 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
)

src/transformers/integrations/gguf/gguf_config_mapping.py: 모델 아키텍처에 따른 GGUF 설정을 매핑하는 로직을 담당합니다. ArthurZucker는 이 부분을 Qwen 독립적으로 만들 수 있을 가능성을 언급했지만, 현재 접근 방식도 좋다고 평가했습니다.
src/transformers/integrations/gguf/gguf_conversion_mapping.py: GGUF 변환 관련 로직을 처리합니다. ArthurZucker는 이 부분을 WeightConverter를 사용하도록 개선할 수 있는지 질문했으며, 이후 수정이 이루어졌습니다. 이는 기존의 커스텀 텐서 프로세서를 대체하고 WeightConverter를 활용하여 통합성을 높이려는 시도로 보입니다.
src/transformers/integrations/gguf/kernels.py: Metal(MPS) 환경에서 llama.cpp 커널을 활용하기 위한 인터페이스를 제공합니다. 이는 특히 양자화된 선형 계층(quantized linear layers)의 연산을 가속화하는 데 중요한 역할을 합니다.
```
# Example usage for attention kernel
model = AutoModelForCausalLM.from_pretrained(
    model_id, gguf_file=filename, attn_implementation="transformers-community/ggml-attn"
)
```
src/transformers/integrations/gguf/reader.py: GGUF 파일 자체를 읽는 로직을 개선했습니다. ArthurZucker는 이 방식이 네이티브 리더의 주요 문제를 해결했다고 긍정적으로 평가했습니다.
src/transformers/integrations/gguf/utils.py: GGUF 관련 유틸리티 함수들을 포함합니다. ArthurZucker는 이 모듈의 존재를 몰랐으며, quantization 모듈 대신 이곳에 위치한 것에 대해 약간의 의문을 표했지만, 전반적으로는 긍정적인 반응을 보였습니다.

3. 양자화기 통합 (`src/transformers/quantizers/quantizer_gguf.py`)

GGUF 관련 양자화 로직을 transformers의 양자화 프레임워크에 통합했습니다. ArthurZucker는 이 부분이 GGUF 포맷을 저장하는 기능까지 포함하는지 질문했으며, 이에 대해 SunMarc는 transformers에서 GGUF 포맷으로 저장하는 기능은 의도하지 않으며, 대신 디퀀타이즈된 모델을 저장할 수 있도록 model._weight_conversions = None 설정을 통해 처리했다고 답변했습니다.

4. 모델 로딩 및 추론 로직 수정 (`src/transformers/modeling_utils.py`, `src/transformers/tokenization_utils_tokenizers.py`)

src/transformers/modeling_utils.py: GGUF 모델 로딩 시 dtype을 올바르게 설정하는 로직이 update_dtype 함수 내에서 처리되도록 수정되었습니다. ArthurZucker는 이 부분이 기존 PR과 관련 있는지, 그리고 일반 양자화와 동일한 경로를 따를 수 있는지 질문했으나, SunMarc는 GGUF의 특성상 동일한 경로를 따르기 어렵지만 코드를 정리했다고 답했습니다.
src/transformers/tokenization_utils_tokenizers.py: 토크나이저 관련 로직도 일부 수정되었습니다. ArthurZucker는 이 변경을 긍정적으로 평가했습니다.

왜 이게 좋은가?

이번 PR은 GGUF 모델의 추론 성능을 향상시키기 위한 여러 가지 중요한 개선을 포함하고 있습니다.

최적화된 커널 활용: Metal(MPS) 환경에서 llama.cpp에서 제공하는 최적화된 커널(예: 어텐션, 양자화된 선형 계층)을 직접 활용함으로써, 특히 양자화된 모델의 추론 속도를 크게 향상시킵니다. 이는 GPU 연산의 효율성을 극대화합니다.

벤치마크 결과: PR 설명에 따르면, M2 Max (Metal) 환경에서 unsloth/Qwen3.5-4B-GGUF 모델을 사용할 때, 최적화된 커널을 적용한 경우 초당 토큰 생성 속도(tok/s)가 크게 향상되었습니다.

     ┌──────────────────────────┬──────────────────────────────────┬─────────┬──────────────┐
    │         runtime          │            checkpoint            │ memory  │    tok/s     │
    ├──────────────────────────┼──────────────────────────────────┼─────────┼──────────────┤
    │ transformers generate()  │ Qwen3.5-4B-Q4_K_M.gguf + kernels │ 3.31 GB │ 76.33 ± 0.38 │
    ├──────────────────────────┼──────────────────────────────────┼─────────┼──────────────┤
    │ transformers generate()  │ Qwen3.5-4B-BF16.gguf             │ 9.88 GB │ 29.23 ± 0.36 │
    ├──────────────────────────┼──────────────────────────────────┼─────────┼──────────────┤
    │ llama-bench tg128        │ Qwen3.5-4B-Q4_K_M.gguf           │ 2.54 GB │ 72.32 ± 0.48 │
    └──────────────────────────┴──────────────────────────────────┴─────────┴──────────────

위 표에서 볼 수 있듯이, Qwen3.5-4B-Q4_K_M.gguf 모델에 최적화된 커널(+ kernels)을 적용했을 때 76.33 tok/s를 기록하여, BF16 모델(29.23 tok/s)보다 훨씬 빠르며, llama-bench 결과와도 유사한 성능을 보여줍니다.

WeightConverter 활용: 기존의 커스텀 텐서 프로세서 대신 WeightConverter를 사용하여 모델 변환 로직을 통합했습니다. 이는 코드의 재사용성을 높이고 유지보수를 용이하게 합니다.
양자화 모델 로딩 지원: 이전에는 GGUF 모델을 로드할 때 기본적으로 디퀀타이즈(dequantize)했지만, 이제는 양자화된 상태 그대로 로딩하는 것을 지원합니다. 이는 메모리 사용량을 줄이고, 특히 양자화된 모델에 최적화된 커널을 사용할 때 성능 이점을 극대화합니다.
유연한 디퀀타이제이션 제어: GgufConfig를 통해 사용자가 명시적으로 디퀀타이즈 여부를 제어할 수 있게 되었습니다. 이는 특정 환경이나 요구사항에 맞춰 모델 로딩 방식을 조절할 수 있는 유연성을 제공합니다. 리뷰어 BowenBao의 질문에 대해 SunMarc는 하드웨어가 지원되지 않거나 사용자가 원할 경우 이전의 디퀀타이즈 동작으로 폴백(fallback)할 수 있다고 설명했습니다.
코드 구조 개선 및 가독성 향상: 새로운 디렉토리 구조와 모듈 분리를 통해 GGUF 관련 코드가 더 체계적으로 관리되고 가독성이 향상되었습니다. 리뷰어들의 긍정적인 피드백은 이러한 개선을 뒷받침합니다.

일반적 교훈: 이 PR은 라이브러리가 특정 파일 포맷(GGUF)에 대한 지원을 강화할 때, 단순히 포맷을 읽는 것을 넘어 해당 포맷에 최적화된 외부 라이브러리(llama.cpp)의 커널을 통합하고, 최신 하드웨어 기능(Metal GPU)을 활용하는 것이 얼마나 중요한지를 보여줍니다. 또한, 명확한 문서화와 유연한 설정 옵션 제공은 사용자 경험을 크게 향상시킬 수 있습니다.

결론

Hugging Face transformers 라이브러리의 이번 GGUF 리팩토링은 추론 성능 향상에 크게 기여할 것으로 기대됩니다. 최적화된 커널의 통합, WeightConverter 활용, 유연한 로딩 옵션 제공 등은 GGUF 모델을 사용하는 개발자들에게 더 빠르고 효율적인 경험을 선사할 것입니다. 특히 Metal GPU 환경에서의 성능 개선은 해당 하드웨어를 사용하는 사용자들에게 반가운 소식입니다. 앞으로 더 많은 모델과 하드웨어에 대한 지원이 확대될 것으로 예상됩니다.

참고 자료

⚠️ 알림: 이 분석은 AI가 실제 코드 diff를 기반으로 작성했습니다.

PR Analysis 의 다른글

이전글 [vllm] vLLM의 Fast Start: CUDA IPC를 활용한 모델 가중치 제로 카피 로딩
현재글 : [transformers] Hugging Face Transformers, GGUF 추론 속도 향상을 위한 대대적인 리팩토링
다음글 [flashinfer] [FlashInfer] Blackwell 아키텍처를 위한 Warp Level Split-K BF16 GEMM 최적화 분석