로컬에서 Qwen 실행하기

로컬 실행이 필요한 순간

Qwen은 API로 쓰는 것이 가장 빠르지만, 모든 상황에 API가 답은 아닙니다. 사내 문서나 고객 데이터가 외부로 나가면 안 되는 경우, 같은 작업을 대량으로 반복해 호출 비용이 커지는 경우, 모델을 직접 파인튜닝하거나 추론 설정을 세밀하게 바꾸고 싶은 경우에는 로컬 실행이 강력한 선택지가 됩니다.

다만 로컬 실행은 "설치하면 끝"이 아닙니다. 모델 크기, GPU VRAM, 시스템 RAM, CPU 성능, 컨텍스트 길이, 동시 요청 수를 함께 계산해야 합니다. 특히 긴 컨텍스트를 쓰면 모델 가중치 외에도 KV 캐시 메모리가 크게 늘어납니다. 단일 GPU가 부족한 서버에서는 vLLM의 tensor parallel 같은 분산 추론 옵션을 검토해야 합니다.

AI 생성 이미지

어떤 Qwen 모델을 받을까

Qwen 오픈 모델은 공식 Hugging Face와 ModelScope 저장소에서 받는 것을 기본으로 삼는 것이 안전합니다. Qwen3 계열에는 0.6B, 1.7B, 4B, 8B, 14B, 32B 같은 dense 모델과 30B-A3B, 235B-A22B 같은 MoE 모델이 있으며, Instruct와 Thinking 변형도 목적에 맞게 나뉩니다¹.

작은 개인 PC에서는 4B나 8B급부터 시작하는 편이 현실적입니다. 14B 이상은 양자화 여부와 VRAM에 따라 가능성이 달라집니다. 32B 이상이나 대형 MoE 모델은 워크스테이션이나 다중 GPU 서버를 전제로 보는 것이 좋습니다. 일반 질의응답과 업무 자동화는 Instruct 모델이 편하고, 수학·복잡한 추론·고난도 코드 분석은 Thinking 계열이 더 적합합니다.

Transformers로 직접 추론하기

가장 기본적인 Python 실행 흐름은 Transformers를 사용하는 방식입니다. 공식 문서는 Python 3.10 이상, PyTorch 2.6 이상, transformers 4.51 이상을 권장하며, AutoTokenizer와 AutoModelForCausalLM로 모델을 불러온 뒤 채팅 템플릿을 적용하고 model.generate()로 응답을 생성하는 흐름을 제시합니다².

from transformers import AutoTokenizer, AutoModelForCausalLM

model_name = "Qwen/Qwen3-8B"

tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForCausalLM.from_pretrained(
    model_name,
    torch_dtype="auto",
    device_map="auto"
)

messages = [
    {"role": "user", "content": "Qwen을 로컬에서 실행하는 장점을 짧게 설명해줘."}
]

text = tokenizer.apply_chat_template(
    messages,
    tokenize=False,
    add_generation_prompt=True
)
inputs = tokenizer([text], return_tensors="pt").to(model.device)
outputs = model.generate(**inputs, max_new_tokens=1024)
print(tokenizer.decode(outputs[0], skip_special_tokens=True))

이 방식은 실험과 디버깅에 좋습니다. 하지만 여러 사용자가 동시에 호출하는 서비스라면 별도 추론 서버가 필요합니다.

vLLM으로 로컬 API 서버 만들기

운영형 로컬 서버가 필요하면 vLLM이 편합니다. 다음 명령으로 OpenAI 호환 API 서버를 띄울 수 있습니다.

vllm serve Qwen/Qwen3-8B

기본 주소는 http://localhost:8000이며, API 경로는 보통 http://localhost:8000/v1을 사용합니다. --host, --port로 바인딩 주소와 포트를 바꿀 수 있고, ModelScope에서 모델을 받으려면 VLLM_USE_MODELSCOPE=true 환경 변수를 설정할 수 있습니다. 여러 GPU를 묶어야 한다면 --tensor-parallel-size 4처럼 병렬 크기를 지정합니다³.

vllm serve Qwen/Qwen3-8B --host 0.0.0.0 --port 8000 --tensor-parallel-size 2

서버가 뜨면 기존 OpenAI SDK 코드에서 base_url만 로컬 주소로 바꿔 연결할 수 있습니다. 이 장점 때문에 사내 챗봇, RAG 서버, 코드 리뷰 도구에 붙이기 쉽습니다.

GPU가 부족하면 GGUF와 양자화를 쓴다

GPU가 없거나 메모리가 부족하면 GGUF 형식의 양자화 모델을 llama.cpp 또는 Ollama 계열 도구로 실행할 수 있습니다. 예를 들어 공식 Qwen/Qwen3-8B-GGUF 저장소에서 q4_k_m 같은 4-bit 파일을 받아 CPU/RAM 중심 환경에서 실행할 수 있습니다⁴.

huggingface-cli download Qwen/Qwen3-8B-GGUF qwen3-8b-q4_k_m.gguf --local-dir .

4-bit와 8-bit 양자화는 메모리 사용량을 크게 줄여 더 큰 모델을 실행하게 해줍니다. 대신 품질과 속도가 달라질 수 있습니다. 요약이나 초안 작성은 4-bit로 충분할 수 있지만, 정확한 코드 분석이나 복잡한 추론은 BF16/FP16 또는 8-bit 결과와 비교해야 합니다.

로컬 운영 체크리스트

로컬 실행에서는 모델 파일도 운영 자산입니다. 어떤 체크포인트를 썼는지, GGUF 변환 파일은 어디에 저장했는지, 라이선스가 서비스 목적에 맞는지, 업데이트 후 품질이 유지되는지 기록해야 합니다. 가장 큰 모델을 고르는 것보다 중요한 기준은 "내 장비에서 안정적으로, 필요한 품질을, 예측 가능한 속도로 내는가"입니다.

참고

¹Qwen3 공식 저장소

²Qwen Quickstart

³Qwen vLLM 배포 문서

⁴Qwen llama.cpp 실행 문서