Transformers에서 llama.cpp 양자화 모델 실행 지원 추가

transformers에서 GGUF 모델을 효율적으로 실행하는 기능을 추가합니다. 이제 익숙한 transformers API를 통해 노트북 메모리에 맞는 크기의 체크포인트를 사용할 수 있습니다. Hub에서 원하는 GGUF 파일을 선택하고 from_pretrained로 로드한 다음, 자체 장치에서 생성을 시작할 수 있습니다. AI 모델을 노트북에서 실행하는 것이 훨씬 쉬워졌으며, llama.cpp가 그 핵심적인 역할을 해왔습니다. 이 추론 엔진은 Ollama, LM Studio, Jan과 같은 로컬 AI 도구에 동력을 공급합니다. MLX와 같은 프로젝트와 함께, 로컬 추론이 일상적인 사용을 위한 실용적인 선택지가 되도록 하는 데 도움을 주었습니다.

로컬 AI가 어떤 느낌인지 최근 예시:

여기가 현재 저희의 위치입니다. 그리고 솔직히 말해서 꽤 마법적이라고 느껴집니다 🧙♀️

— Julien Chaumond (@julien_c) 2026년 4월 24일

MacBook Pro에서 Llama.cpp를 통해 Pi 코딩 에이전트 내부에서 실행되는 Qwen3.6 27B

@huggingface 코드베이스의 사소하지 않은 작업에 대해, 이것은 Claude의 최신 Opus에 근접한 느낌입니다… pic.twitter.com/lsIxLoUneU

GGUF는 llama.cpp 팀이 개발한 로컬 추론을 위한 널리 사용되는 형식입니다. 이 팀은 또한 ggml-org 아래 Hub에서 양자화된 체크포인트를 공유합니다. Unsloth, LM Studio Community, bartowski와 같은 퍼블리셔들도 다양한 양자화 수준의 즉시 사용 가능한 GGUF 체크포인트를 제공하므로, 사용자는 자신의 장치에 맞는 버전을 선택할 수 있습니다. GGUF 모델은 백만 번 이상 다운로드되었습니다.

저희도 transformers를 통해 이러한 모델을 로컬에서 실행하는 것을 더 쉽게 만들고 싶었습니다. 호환성은 모델이 사용하기에 쾌적해야 의미가 있습니다. llama.cpp에 근접한 성능을 구현하기 위해, kernels 라이브러리를 통해 그 기반이 되는 ggml 커널을 재사용하고 generate의 오버헤드를 줄이고 있습니다. 초기 초점은 Qwen3.5 아키텍처로 시작하여 Apple Silicon에서의 로컬 추론입니다.

GGUF는 토크나이저 정보와 선택적 채팅 템플릿을 포함하여 모델 가중치와 메타데이터를 하나의 파일에 패키징합니다. 다양한 양자화(quantization) 레벨을 지원하여 정밀도 일부를 포기하는 대신 더 작은 메모리 공간을 확보할 수 있게 합니다. 예를 들어, Q4_K_M은 텐서의 정밀도를 혼합하며, 대부분 4비트 가중치를 사용하면서 민감한 텐서는 높은 정밀도로 유지합니다.

Unsloth의 Qwen3.5-4B 모델 파일 크기가 양자화에 따라 어떻게 변하는지 살펴보겠습니다:

저희는 Q4_K_M으로 시작하여, 메모리가 더 많이 확보된다면 Q5_K_M 또는 Q6_K를 시도해 보시기를 권장합니다. 더 공격적인 양자화는 대형 모델이 들어갈 수 있도록 돕지만, 품질의 상충 관계(tradeoff)는 모델과 작업에 따라 달라집니다. 실제로 모델에게 수행시키고 싶은 작업으로 평가해 보세요. Hub의 GGUF 문서를 참조하시면 사용 가능한 양자화 유형을 확인할 수 있습니다.

시작하려면 다음이 필요합니다:

Apple Silicon Mac. 게시된 ggml-quantization 커널 빌드에서 지원하는 PyTorch 버전, 보통 최신 두 개의 PyTorch 릴리스입니다. 최신 버전의 transformers (현재는 main 브랜치, 다음 릴리스까지) 및 호환되는 버전의 kernels.

pip install -U "git+https://github.com/huggingface/transformers.git" kernels

GGUF 모델을 로드하려면, Hub의 model_id와 파일 이름을 from_pretrained 함수에 gguf_file 인수로 전달하면 됩니다.

추가적인 설정은 필요하지 않습니다: 가중치가 Metal에 패킹된 상태로 유지되면, transformers는 자동으로 호환되는 ggml/Metal 레이어 커널을 로드하고 어텐션 구현으로 ggml-org/ggml-attn을 사용합니다. 만약 해당 커널을 가져올 수 없다면, 경고와 함께 모델은 `

그것이 유일한 GGUF 전용 단계입니다. 그 이후의 모든 것은 표준 transformers API를 따릅니다:

messages = [{"role": "user", "content": "하늘이 파란 이유를 몇 문장으로 설명해 주세요."}]
inputs = tokenizer.apply_chat_template(
messages,
...

호환 가능한 양자화 커널(quantization kernel)이 없으면, 로더는 모델을 역양자화(dequantizing)하고 더 많은 메모리를 사용합니다.

또한 transformers serve를 사용하여 동일한 체크포인트로 사용할 수 있습니다. 이는 OpenAI와 호환되는 API를 노출합니다:

pip install -U "transformers[serving] @ git+https://github.com/huggingface/transformers.git" kernels
transformers serve "unsloth/Qwen3.5-4B-GGUF:Qwen3.5-4B-Q4_K_M.gguf"

모델 인자(argument)는 콜론(:) 앞에 허브 리포지토리(unsloth/Qwen3.5-4B-GGUF)를, 뒤에 로드할 파일을 지정합니다 (Qwen3.5-4B-Q4_K_M.gguf). 이렇게 하면 여러 개가 포함될 수 있는 리포지토리에서 특정 양자화 버전을 선택하게 됩니다.

채팅 템플릿이 추론(thinking)을 지원하는 모델의 경우, --reasoning off를 추가하여 건너뛰거나 --reasoning on를 추가하여 활성화할 수 있습니다. 기본값인 --reasoning auto는 채팅 템플릿의 기본값을 따릅니다. 자세한 내용은 추론 옵션(reasoning options)을 참조하십시오.

Jan이나 Pi와 같은 클라이언트에 연결하려면, 다음 설정을 사용하여 사용자 지정 OpenAI 호환 제공업체(provider)를 추가할 수 있습니다:

transformers는 Mac에서 모델을 실행하고, 클라이언트는 대화 인터페이스를 제공합니다. 동일한 엔드포인트(endpoint)는 이 API를 지원하는 다른 클라이언트에서도 사용될 수 있습니다.

로컬 추론 성능에 대한 참고 자료는 llama.cpp입니다. 아래 비교는 세 가지 GGUF 체크포인트, 즉 작은 밀집 모델(small dense model), 더 큰 밀집 모델(larger dense model), 그리고 전문가 혼합 모델(mixture-of-experts model)에 초점을 맞추고 있습니다.

llama.cpp 열은 llama-bench 도구(빌드 5f55650a7)에서 가져왔습니다.

, 릴리스 b10200, ggml 0.18.0의 Metal 백엔드에서 실행), llama-bench -m <file> -p 0 -n 128 -r 3으로 실행합니다.

이는 세 번 반복에 걸쳐 디코딩된 토큰 128개에 대한 토큰 생성 속도(tg128)를 보고하며, 프롬프트 처리는 제외됩니다. transformers 열은 generate를 사용하여 12개 토큰의 프롬프트에서 동일한 128개 토큰을 생성하며, 세 번 워밍업된 실행 중 가장 좋은 결과를 사용하고 사전 채우기(prefill)가 포함됩니다.

MacBook Pro M2 Max (32 GB 통합 메모리), macOS 26.6, PyTorch 2.12.1, 커널 0.17.0에 연결된 상태에서 측정되었습니다.

벤치마크 스크립트

import time
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer
...

다른 열의 경우:

llama-bench -hf unsloth/Qwen3.5-4B-GGUF:Q4_K_M -p 0 -n 128 -r 3

transformers는 세 가지 체크포인트 모두에서 llama.cpp와 근접합니다. 이 차트는 위에서 설명한 동일한 측정을 사용하지만, transformers 측정에는 사전 채우기(prefill)가 포함되는 반면 llama-bench는 디코드 전용 처리량(decode-only throughput)을 보고하므로 동일한 벤치마크 조건을 의미하지는 않습니다.

GGML과 llama.cpp가 Hugging Face에 합류했을 때, 우리는 그들의 상호 보완적인 역할을 설명했습니다: llama.cpp는 로컬 추론의 기반을 제공하고, transformers는 모델 정의의 기반을 제공합니다. GGUF 지원은 이 둘을 더 가깝게 만듭니다.

효율적인 로컬 추론이 우선순위인 경우, llama.cpp가 여전히 권장되는 엔진입니다. 전용 런타임, 메모리 관리 및 광범위한 하드웨어 지원이 그 목표를 중심으로 구축되어 있습니다. 이 통합을 통해 개발자는 transformers 내부에서 동일한 GGUF 체크포인트로 작업할 수 있는 편리한 방법을 얻게 됩니다:

Python 및 PyTorch에서 GGUF 실험하기. 후크(hooks)를 사용하여 중간 활성화 값(intermediate activations)을 검사하거나, 모델의 순전파 과정(forward pass)을 수정하고, 익숙한 PyTorch 도구를 사용하여 사용자 지정 레이어(custom layers)를 프로토타이핑할 수 있습니다.GGUF 모델 평가하기. 기존의 transformers 평가 워크플로우를 사용하여 양자화된 체크포인트의 품질을 측정할 수 있습니다.GGUF 변환 검증하기. 개발자인 저희에게는, original 체크포인트를 로드하고 이를 GGUF로 변환한 것을 transformers에서 처리하는 것이 가중치(weights)가 올바르게 변환되었는지, 양자화 오류를 감안하여 확인할 수 있게 해줍니다.새로운 디코딩 아이디어 시도하기. generate에서 사용자 지정 로짓 프로세서(logits processors)와 중지 기준(stopping criteria)을 사용하거나, Python으로 자체 생성 루프(generation loop)를 작성할 수 있습니다.GGUF 체크포인트로부터 파인튜닝하기. 가중치를 역양자화(Dequantize)하고 표준 transformers 학습 워크플로우를 계속 진행합니다.

이 마지막 경우의 경우, GgufConfig(dequantize=True)을 사용하십시오.

import torch
from transformers import AutoModelForCausalLM, GgufConfig
model = AutoModelForCausalLM.from_pretrained(
...

더 큰 기회는 llama.cpp가 지원하지 않는 모델에 ggml의 성능을 가져오는 것입니다.

transformers는 이미 이러한 아키텍처에 대한 PyTorch 구현을 제공합니다. PyTorch에서 사용 가능한 ggml 커널(kernels)과 양자화 방식(quantization schemes)을 통해, 전체 모델을 먼저 llama.cpp로 구현할 필요 없이 지원되는 연산(operations)을 가속화하는 방향으로 작업할 수 있습니다. 이는 특히 전용 llama.cpp 구현이 제공되지 않을 수 있는 새로운 아키텍처, 연구 모델, 사용자 지정 변형(custom variants)에 유용합니다.

이러한 기회는 GGUF 형식 자체를 넘어 확장됩니다. 커널은 텐서(tensors)에 대해 작동하며, 전체 모델이 GGUF 파일에서 제공되어야 할 필요가 없습니다. 동일한 빌딩 블록을 다른 트랜스포머(transformers) 모델 및 로딩 워크플로우에 통합할 수 있습니다. 이는 또한 다른 모달리티로의 경로를 열어줍니다: 컴퓨터 비전 모델, 오디오 모델, 그리고 멀티모달 모델은 먼저 llama.cpp에서 전체 구현이 필요하지 않은 호환 가능한 어텐션(attention), 정규화(normalization), 및 행렬 곱셈 커널을 재사용할 수 있습니다. 각 아키텍처는 여전히 통합과 검증이 필요하며, 여기에 제시된 초기 GGUF 예제들은 텍스트 생성에 초점을 맞추고 있습니다.

또한 모델과 생성 루프를 Python 내에서 유지하면서 얼마나 멀리 갈 수 있는지 보여주고 싶었습니다. 올바른 커널과 효율적인 생성 루프만 있다면, Python과 PyTorch는 강력한 로컬 추론 성능을 제공할 수 있습니다. 커널이 무거운 계산을 처리하는 동안, 생성 루프는 불필요한 동기화(synchronization)를 피함으로써 GPU를 바쁘게 유지합니다.

저희의 초점은 torch.compile을 요구하지 않으면서도 이지(eager) 실행을 빠르게 만드는 것이었습니다.

대화형 사용을 위해, 컴파일 일시 중단이나 입력 형태가 변경될 때 재컴파일 없이 빠르고 꾸준한 토큰 스트림을 원했습니다. 그 작업의 두 가지 주요 부분은 커널과 generate 자체입니다.

커널은 GPU에서 특정 작업을 수행하는 작은 프로그램입니다. PyTorch는 범용적인 구현을 제공하며, 특화된 커널은 더 적은 작업을 수행하거나, 여러 연산을 결합하거나, 저장된 형식으로 양자화된 가중치(quantized weights)를 직접 읽을 수 있습니다.

kernels 라이브러리는 ggml의 Metal 커널에 대한 호환 가능한 빌드를 Hub에서 배포하고 transformers에서 호출할 수 있게 합니다. 이를 통해 별도의 추론 런타임으로 모델을 대체하지 않으면서도 ggml의 작업을 PyTorch 모델로 가져올 수 있습니다.

앞의 네 가지 패키지는 ggml의 커널을 기반으로 구축되었으며, top-k 커널은 MoE 라우팅에서 별도의 병목 현상(bottleneck)을 해결합니다. 이들이 함께 작동하여 생성되는 각 토큰에 필요한 GPU 작업을 줄여줍니다.

레이어 커널들의 기여도를 보여주기 위해, 동일한 패킹된 GGUF 체크포인트를 해당 커널들을 사용했을 때와 사용하지 않았을 때 비교했습니다. 양자화 커널은 두 구성 모두에서 활성화 상태를 유지합니다: 이를 비활성화하면 가중치가 표현되는 방식 자체가 바뀌고 다른 트레이드오프(tradeoff)를 측정하게 됩니다.

더 빠른 커널들은 GPU가 처리할 작업이 있을 때만 도움이 됩니다. 생성 과정 동안, CPU는 GPU 작업을 스케줄링하고 다음 토큰을 생성하는 루프를 제어합니다. GPU로부터 결과를 읽어오는 행위는 CPU가 큐에 대기 중인 작업이 완료될 때까지 기다리도록 강제할 수 있습니다. 매 토큰마다 작은 대기 시간이라도 반복되면 처리량(throughput)이 눈에 띄게 감소할 수 있습니다.

generate 함수에서 두 가지 변경 사항을 통해 이를 해결했으며, 이로 인해 모든 트랜스포머 모델(GGUF 파일을 실행할 때뿐만 아니라)의 성능 개선을 가져옵니다.