로컬 LLM 서버 구축 가이드: vLLM, GGUF, FastAPI로 사내 AI API 만들기

요약: 로컬 LLM을 단순 실행이 아니라 사내 서비스가 호출할 수 있는 AI API 서버로 운영하는 방법을 정리합니다.

대상 독자: LLM 모델을 내부 API, 챗봇, 업무 자동화 서비스에 연결하려는 개발자

핵심 키워드: 로컬 LLM 서버, 사내 AI API, FastAPI, vLLM, LLM 운영

로컬 LLM/RAG 구축 시리즈 바로가기

1. 로컬 LLM 구축 1편: vLLM·GGUF·FastAPI
2. 로컬 LLM 구축 2편: GPU 서버 사양
3. 로컬 LLM 구축 3편: RAG 성능 최적화
4. 로컬 LLM API 서버 구축 심화 (현재 글)
5. LangChain RAG 구축 1편: 문서 파이프라인
6. LangChain RAG 구축 2편: 임베딩·Vector DB

 

로컬 LLM 구축 가이드 (4편)

vLLM + GGUF 기반 모델 서빙 & API 구축 실전 편

이 편에서는 GPU 서버 위에 실제로 모델을 올리고,
vLLM 서버 → FastAPI → 내부 시스템 연동까지 모두 구현합니다.

---

 3편 목차

1. GGUF 모델 다운로드 & 관리 전략
2. vLLM 서버 실행 – GPU 최적화 옵션 세팅
3. FastAPI 기반 모델 API 구축
4. 사내망 시스템 연동 구조 설계
5. 실무에서 반드시 걸리는 문제들 해결법
6. “실전 팁 3개”

---

 1. GGUF 모델 다운로드 & 관리 전략

▶ 어떤 모델을 선택해야 하나?

• 문서 검색 + RAG 목적 → Llama3 8B Instruct GGUF
• 대규모 사내 문서 처리 → Qwen2 7B/14B GGUF
• 국문 응답 품질 우선 → SOLAR Mini / Sophia Korean

▶ 모델 다운로드 예시

wget https://huggingface.co/…/llama-3-8b-instruct.Q4_K_M.gguf
mkdir -p /opt/models/llama3
mv *.gguf /opt/models/llama3

▶ 모델 버전 관리 팁

1. 모델 디렉토리명에 버전 & 날짜 포함
2. 사내망일 경우 모델 ZIP을 내부 NAS에 캐싱
3. 용량이 큰 경우 Q4_K_M 기준으로 운영(품질 대비 효율 best)

---

 2. vLLM 서버 실행 – GPU 성능 극대화 옵션

▶ 기본 실행

python3 -m vllm.entrypoints.openai.api_server \
  --model /opt/models/llama3/llama-3-8b.Q4_K_M.gguf \
  --tensor-parallel-size 1 \
  --gpu-memory-utilization 0.92 \
  --max-num-batched-tokens 4096 \
  --host 0.0.0.0 \
  --port 8001

▶ 옵션 설명

• gpu-memory-utilization=0.92
  → GPU 메모리를 최대한 활용해 처리량 증가
• tensor-parallel-size=1
  → 단일 GPU 환경 기준
• max-num-batched-tokens=4096
  → vLLM의 최대 강점인 Batch Throughput 활용

---

 3. FastAPI 기반 모델 API 구축

▶ FastAPI 코드 예시

from fastapi import FastAPI
import requests

app = FastAPI()

VLLM_URL = "http://localhost:8001/v1/chat/completions"

@app.post("/chat")
def chat(query: str):
    payload = {
        "model": "local-llama3",
        "messages": [{"role": "user", "content": query}]
    }
    response = requests.post(VLLM_URL, json=payload, timeout=60)
    return response.json()

▶ 사내망 적용 팁

• 인증이 필요한 경우 JWT 또는 사내 SSO 연동
• 로그는 Elastic Stack / Grafana Loki로 중앙 수집
• 요청량 많은 경우 Nginx + Gunicorn 로드밸런싱

---

 4. 사내 시스템 연동 구조 예시

사내 웹서비스
     ↓ API 호출
FastAPI (Model Gateway)
     ↓
vLLM 서버
     ↓
GGUF 모델
     ↓
GPU 서버

이 구조가 가장 안정적이며,
FastAPI 레이어에서 권한 관리, 로깅, 요청 필터링을 담당하도록 구성한다.

---

 5. 실무에서 자주 걸리는 문제 해결

문제 원인 해결

GPU 메모리 부족	Q4_K_S, Q5_K 등 너무 큰 모델	Q4_K_M로 다운스케일
응답 느림	Batch 옵션 미사용	--max-num-batched-tokens 증가
FastAPI 타임아웃	vLLM 응답 지연	timeout=120 또는 streaming 활용
모델 품질 낮음	기본 Instruction 모델	RAG + 프롬프트 강화 적용

---

실전 팁 3개

1) 모델 경량화는 품질보다 안정성이 우선

→ 사내 서비스는 장애가 더 위험하다.

2) vLLM 서버와 API 서버 분리하라

→ 장애가 나도 서비스 전체가 죽지 않음.

3) 운영 중에는 반드시 GPU 메모리 사용량을 모니터링

→ 90% 넘으면 OOM 발생 확률 급증.

 

실무 적용 체크리스트

점검 항목운영 기준

API 설계	프롬프트 입력, 응답 형식, 오류 코드를 서비스 계약으로 정리
보안	내부망 접근 제어, 토큰 인증, 요청 로그 마스킹 적용
성능	동시 요청 수, timeout, streaming 응답 기준을 분리
관측성	응답 시간, 토큰 사용량, 실패율을 대시보드로 추적

자주 묻는 질문

로컬 LLM을 API 서버로 만들면 어떤 장점이 있나요?

여러 내부 서비스가 같은 모델을 표준 방식으로 호출할 수 있어 권한, 로그, 장애 대응을 중앙에서 관리하기 쉽습니다.

FastAPI만으로 운영해도 충분한가요?

PoC는 충분하지만 운영 환경에서는 reverse proxy, process manager, GPU 모니터링, 장애 재시작 정책을 함께 구성하는 것이 안전합니다.

사내 AI API에서 가장 먼저 봐야 할 지표는 무엇인가요?

응답 시간, 동시 요청 처리량, 실패율, GPU 메모리 사용량, 사용자별 호출량을 우선 모니터링하는 것이 좋습니다.

함께 읽으면 좋은 글

• 로컬 LLM 구축 1편: vLLM·GGUF·FastAPI
• 로컬 LLM 구축 2편: GPU 서버 사양
• 로컬 LLM 구축 3편: RAG 성능 최적화
• LangChain RAG 구축 1편: 문서 파이프라인
• LangChain RAG 구축 2편: 임베딩·Vector DB

📗 로컬 LLM 구축 시리즈 (전 4편)

1. 1편 — vLLM·GGUF·FastAPI로 사내 AI 서버 만들기
2. 2편 — GPU 서버 사양과 환경 구축
3. 3편 — RAG 성능 최적화와 평가 지표
4. 4편 — vLLM 모델 서빙 & API 구축 심화 (현재 글)