GGUF

GGUF (GGUF)

GGUF는 llama.cpp 생태계에서 쓰이는 모델 포맷이라, 그 포맷의 모델을 vLLM에서도 직접 돌리고 싶은 분들이 많아요. 실제로 vLLM에서 GGUF를 지원하긴 하는데, 지금은 실험적이고 최적화가 덜 된 상태라는 점을 먼저 짚고 넘어갈게요. 다른 기능과 호환이 안 될 수도 있고, 주로 메모리 사용량을 줄이는 용도로 쓰는 게 현재 권장 사항이에요.

출처: vLLM 공식 문서 — GGUF

플러그인 설치 (Plugin installation)

GGUF 지원은 이제 vLLM 외부의 별도 패키지로 빠져 있어요. GGUF 모델을 서빙하기 전에 먼저 vllm-gguf-plugin을 설치해야 합니다.

uv pip install vllm-gguf-plugin

모델 로딩 (Loading a model)

GGUF 모델을 vLLM으로 띄우려면 HuggingFace에서 repo_id:quant_type 형식으로 바로 불러올 수 있어요. 예를 들어 unsloth/Qwen3-0.6B-GGUF에서 Q4_K_M 양자화 모델을 로딩한다면:

# 토크나이저는 베이스 모델에서 가져오는 걸 권장해요 (GGUF 변환은 느리고 불안정할 수 있어서)
vllm serve unsloth/Qwen3-0.6B-GGUF:Q4_K_M --tokenizer Qwen/Qwen3-0.6B

--tensor-parallel-size 2를 추가하면 GPU 2장으로 텐서 병렬 추론을 켤 수도 있어요.

vllm serve unsloth/Qwen3-0.6B-GGUF:Q4_K_M \
    --tokenizer Qwen/Qwen3-0.6B \
    --tensor-parallel-size 2

로컬에 GGUF 파일을 내려받아 쓰는 방법도 있어요.

wget https://huggingface.co/unsloth/Qwen3-0.6B-GGUF/resolve/main/Qwen3-0.6B-Q4_K_M.gguf
vllm serve ./Qwen3-0.6B-Q4_K_M.gguf --tokenizer Qwen/Qwen3-0.6B

⚠️ GGUF 모델의 토크나이저 대신 베이스 모델의 토크나이저를 쓰는 걸 권장해요. GGUF에서 토크나이저를 변환하는 과정이 시간이 오래 걸리고, 특히 어휘(vocab) 크기가 큰 모델은 불안정하기 때문이죠.

GGUF는 HuggingFace가 메타데이터를 config 파일로 변환해 준다는 전제를 깔아요. HuggingFace가 모델을 지원하지 않으면 config를 직접 만들어서 hf-config-path로 넘길 수 있어요.

# HuggingFace가 모델을 지원하지 않으면 HuggingFace 호환 config 경로를 직접 제공
vllm serve unsloth/Qwen3-0.6B-GGUF:Q4_K_M \
    --tokenizer Qwen/Qwen3-0.6B \
    --hf-config-path Qwen/Qwen3-0.6B

Python API로 직접 쓰기 (LLM entrypoint)

GGUF 모델은 vLLM의 LLM 진입점으로도 바로 쓸 수 있어요. 아래 코드는 chat 메서드에 대화를 넘기는 예시예요.

from vllm import LLM, SamplingParams

# 이 스크립트는 chat 메서드에 입력을 전달하는 방법을 보여줍니다.
conversation = [
    {"role": "system", "content": "You are a helpful assistant"},
    {"role": "user", "content": "Hello"},
    {"role": "assistant", "content": "Hello! How can I assist you today?"},
    {"role": "user", "content": "Write an essay about the importance of higher education."},
]

# sampling params 객체 생성
sampling_params = SamplingParams(temperature=0.8, top_p=0.95)

# repo_id:quant_type 형식으로 LLM 생성
llm = LLM(
    model="unsloth/Qwen3-0.6B-GGUF:Q4_K_M",
    tokenizer="Qwen/Qwen3-0.6B",
)

# 프롬프트에서 텍스트 생성. 출력은 RequestOutput 객체 리스트로,
# 여기에 prompt, 생성된 텍스트, 기타 정보가 담겨 있어요.
outputs = llm.chat(conversation, sampling_params)

for output in outputs:
    prompt = output.prompt
    generated_text = output.outputs[0].text
    print(f"Prompt: {prompt!r}, Generated text: {generated_text!r}")

더 알아보기 (Learn more)

• vLLM 양자화 (Quantization)
• GGUF 플러그인 저장소 (vllm-gguf-plugin)
• LLM Compressor