로컬 배포 완전 플레이북: 하드웨어 점검부터 워크플로 통합까지 7단계
로컬 배포 완전 플레이북
산발적 튜토리얼은 "한 지점"을 다룹니다: Ollama 설치, GGUF 다운로드, 플러그인 설정. 그러나 실제로 매일 쓸 수 있는 로컬 모델을 배포하는 것은 완전한 체인입니다 — 하드웨어가 충분한가, 어떤 모델과 등급인가, 어떤 파일을 받아야 하나, 어떻게 서비스화하고, 어떻게 도구에 연결하고, 문제가 생기면 어떻게 찾을 것인가. 이 플레이북은 7단계로 체인을 걷고 각 단계에 실행 가능한 명령과 "멈추기·전환" 판단 기준을 제시합니다.
30초 요약
7단계: ① 하드웨어 점검(VRAM/RAM/디스크) ② 모델 역산(VRAM으로 규모·등급) ③ GGUF 다운로드 ④ 실행(Ollama 또는 llama.cpp) ⑤ 로컬 엔드포인트 공개 ⑥ 도구 통합(Cursor/Continue/Open WebUI) ⑦ 모니터링과 디버깅. 어느 단계에서든 막히면 판단 기준으로 돌아가세요.
1단계: 하드웨어와 예산 점검
먼저 3가지를 확인하고, 부족하면 목표를 조정합니다:
| 항목 | 최소 | 권장 | 확인 방법 |
|---|---|---|---|
| VRAM | 8GB | 목표 모델에 따라 | nvidia-smi |
| 시스템 RAM | 32GB | 64GB+ | free -g / 시스템 정보 |
| 디스크 | 100GB 여유 | 200GB+ | df -h |
VRAM 계산: 목표 파라미터 수 × 등급별 바이트 계수 + KV cache + 2GB 오버헤드. 완전한 공식과 계산 예시는 VRAM 계산 실전을 참고하세요. 한 줄 요약: 27B는 24GB급, 14B급은 16GB, 4B급은 8GB에서 편안합니다.
디스크가 자주 간과됩니다
27B 모델의 Q4 GGUF만 약 16GB입니다. 여러 등급과 모델을 남겨두면 100GB는 금방 바닥납니다. 모델 캐시(Ollama 기본 홈 디렉터리)는 시스템 드라이브에 있어 꽉 차기 쉽습니다 — 모델 디렉터리를 별도 디스크로 옮길 것을 권장합니다.
2단계: VRAM에서 모델과 등급 역산
예산이 있으면 무엇이 도는지 역으로 찾습니다:
| 예산 VRAM | 권장 대상 | 양자화 등급 |
|---|---|---|
| 8GB | 4B급 전체 / 7-8B Q4 | Q4_K_M |
| 16GB | 14B Q4/Q5, 또는 27B Q3 | Q4_K_M부터 |
| 24GB | 27B Q4/Q5 편안 | Q4_K_M / Q5_K_M |
| 48GB+ | 70B급 Q4, 또는 27B Q8 | 품질 요구에 따라 |
패밀리 선택은 Qwen 모델 선택 가이드, DeepSeek V4 전 라인업, Hunyuan hy4와 A13B을 참고하세요. 등급 트레이드오프는 GGUF 양자화 도구 비교를 참고하세요.
3단계: GGUF 다운로드
HuggingFace에서 대상 모델의 GGUF를 다운로드합니다. 두 가지 방법:
# huggingface-cli로 특정 파일 다운로드(모델 카드에서 실제 파일명 확인)
huggingface-cli download <작성자>/<모델>-GGUF \
<모델>-Q4_K_M.gguf --local-dir ./models
또는 직접 풀을 지원하는 런타임(Ollama가 일부 모델 공식 풀 지원)으로 받습니다. 다운로드 전 모델 카드의 파일 크기를 확인해 나중에 VRAM에 안 맞는다 깨닫는 일을 피하세요.
파일명에서 크기를 추정하지 마세요
같은 모델의 다른 양자화 등급은 크기가 수 배 다릅니다. 다운로드 전 모델 카드에 각 파일의 크기와 최소 하드웨어 요구를 확인하는 것이 가장 시간을 아끼는 단계입니다.
4단계: 실행
경로 A: Ollama(최단 검증)
# 로컬 GGUF를 가리키는 Modelfile 작성
# FROM ./models/<모델>-Q4_K_M.gguf
ollama create mymodel -f Modelfile
ollama run mymodel "한 문장으로 자기소개"
경로 B: llama.cpp(제어와 서비스화)
git clone https://github.com/ggerganov/llama.cpp && cd llama.cpp && make -j
./build/bin/llama-server \
-m ./models/<모델>-Q4_K_M.gguf \
-ngl 35 \
-c 8192 \
--host 127.0.0.1 --port 8080
두 경로의 선택
결과만 확인: Ollama, 명령 한 줄. GPU 레이어, 컨텍스트, 동시성 조정이나 장기 서비스 운용: llama.cpp(llama-server는 OpenAI 호환 API 제공). 둘 다 GGUF를 소비하므로 모델 파일은 호환되고 언제든 전환할 수 있습니다.
5단계: 로컬 엔드포인트 공개
모델을 도구에 연결하려면 장기 실행되는 HTTP 엔드포인트가 필요합니다:
- Ollama: 기본
127.0.0.1:11434를 리슨하고 OpenAI 호환 API 제공 - llama.cpp:
llama-server가 지정 포트를 리슨하고/v1/chat/completions도 호환
엔드포인트 보안 경계
기본은 127.0.0.1 바인딩으로 로컬 전용 접근 — 이것이 올바른 기본입니다. LAN의 다른 기기에서 쓰려면 반드시 바인딩 주소를 바꾸고, 인증 없는 추론 서비스를 네트워크에 노출하는 것을 인지하세요: 방화벽 규칙을 추가하고 신뢰할 수 있는 네트워크에서만 열거나 인증 프록시를 앞에 두세요.
6단계: 도구 통합
로컬 엔드포인트가 동작하면 통합은 "주소를 가리키고 모델을 고르는 것"뿐입니다:
| 도구 | 방식 | 가이드 |
|---|---|---|
| Cursor | Override OpenAI Base URL을 로컬 엔드포인트에 | Cursor 통합 |
| Continue | config 파일에서 apiBase 선언 | Continue 통합 |
| Open WebUI | 연결 설정에서 API Base URL 입력 | Open WebUI 통합 |
| 자체 앱 | OpenAI SDK base_url을 여기로 | 로컬 코딩 워크플로 |
실용 디테일: 에디터 플러그인에는 보통 타임아웃이 있고 로컬 모델 첫 로드에는 시간이 걸립니다 — 타임아웃을 크게 하거나 통합 전에 몇 번 워밍업 요청을 돌리세요.
7단계: 모니터링, 디버깅, 폴백
모니터링: nvidia-smi로 VRAM 피크, llama.cpp 로그로 KV cache 할당과 token/s를 확인합니다.
고정된 디버깅 순서:
- VRAM 부족 → 컨텍스트(
-c)를 줄이거나 등급을 낮추기 - 컨텍스트는 되는데 느림 → RAM 오프로드 레이어를 줄이고 GPU가 실제 사용 중인지 확인
- 출력이 깨지거나 로드 실패 → 엔진 업데이트(MoE 아키텍처는 엔진 버전에 민감)
- 도구 측 오류 → 먼저 curl로 엔드포인트를 직접 때려 엔드포인트 문제인지 도구 설정 문제인지 구분
폴백: 로컬 모델이 주력, 클라우드가 안전망입니다. 로컬이 느리거나 다운되었거나 플래그십 품질이 필요할 때 1회의 폴백 호출로 클라우드 API(EXAIV OpenAI 호환 엔드포인트, ID는 /models 실시간 카탈로그)로 전환하면 개발 루프가 끊기지 않습니다. 비용 트레이드오프는 로컬 계산 비용 모델을 참고하세요.
로컬 투자 멈춰야 할 때
목표 모델이 플래그십 품질을 반드시 하거나, 동시성이 로컬 하드웨어를 초과하거나, 팀에 유지보수 여력이 없다면 로컬은 유일한 답이 아닙니다. 이런 경우 클라우드 API가 더 적습니다. 판단 기준은 "어느 쪽이 더 멋있나"가 아니라 "어떤 방식이 내 사용량·프라이버시 요구·운용 능력에 맞는가"입니다.
FAQ
파이프라인 전체에 시간이 얼마나 걸립니까?
Ollama와 llama.cpp를 동시에 쓸 수 있나요?
로컬 모델은 얼마나 자주 업데이트해야 하나요?
로컬 배포에 인터넷이 필요한가요?
여러 사용자가 쓸 때 주의할 점은?
배포 후 속도가 만족스럽지 않으면?
관련 글
- 로컬 LLM용 GPU 선택 가이드 — 카드 구매 전 필수
- VRAM 계산 실전 — 공식과 실측
- 로컬 계산 비용 모델 — 구매 vs 대여 vs API
- Qwen GGUF 로컬 배포 입문 — 양자화와 배포 기초
- 중국 오픈 웨이트 vs 미국 플래그십 — 로컬과 클라우드 전체 그림