vLLM 서빙 완전 가이드: FastAPI·Kubernetes·RAG 결합으로 초저비용 고속 배포

vLLM 서빙은 대규모 언어모델(LLM)을 더 빠르고 더 싸게 제공하기 위한 최적의 선택입니다. 본 글은 vLLM 서빙을 중심으로 FastAPI와 Kubernetes를 결합해 프로덕션 환경에 배포하고, RAG·캐시·모니터링까지 묶어 엔드투엔드 아키텍처를 만드는 방법을 담았습니다.

vLLM 서빙으로 지연·비용을 줄이는 법을 단계별로 설명합니다. FastAPI 게이트웨이, vLLM 런타임 설정, 양자화·배칭·스펙큘러티브 디코딩, 쿠버네티스 오토스케일, 프롬프트/결과/임베딩 캐시, RAG 결합, 프로메테우스 모니터링과 롤백 전략까지 실제 운영에 필요한 구성요소를 예제 코드와 함께 정리했습니다.

1. 왜 vLLM 서빙인가

핵심 요약: vLLM 서빙은 PagedAttention·Continuous Batching으로 처리량을 극대화한다.

vLLM 서빙은 모델 메모리를 효율적으로 관리하는 PagedAttention과 요청을 묶어 처리하는 Continuous Batching을 통해 동일 GPU에서 더 많은 동시 요청을 처리합니다. 덕분에 토큰/초(TPS)와 비용/건이 개선되며, 스펙큘러티브 디코딩과 결합하면 응답 체감 속도가 크게 좋아집니다. 또한 OpenAI 호환 API를 제공해 기존 클라이언트 수정 없이 붙이기 좋습니다.

2. 아키텍처 개요(FastAPI·vLLM·RAG)

핵심 요약: 게이트웨이-FastAPI가 린트·라이트 레이트리밋·캐시·관찰성을 담당한다.

클라이언트: 웹/백엔드 서비스에서 HTTP/WS로 요청.
FastAPI 게이트웨이: 인증, 레이트리밋, 프롬프트/결과 캐시, A/B 라우팅.
vLLM 서빙: 텍스트 생성 엔진. GPU Pod로 배치.
RAG 서비스: 임베딩/검색/리랭킹을 담당(FAISS/Milvus/OpenSearch 등).
모니터링: Prometheus + Grafana 대시보드, Loki 로그.

Client → FastAPI(GW) → vLLM(Generate)
                ↘ RAG(Search/Rerank)

3. vLLM 서빙 설치·기본 설정(배칭·KV·스케줄러)

핵심 요약: 모델 적재·배칭·토큰 한도를 먼저 고정하고, 나중에 미세 튜닝.

3.1 Dockerfile 예시

FROM nvidia/cuda:12.1.0-runtime-ubuntu22.04
RUN apt-get update && apt-get install -y python3 python3-pip && rm -rf /var/lib/apt/lists/*
RUN pip3 install vllm fastapi uvicorn[standard] pydantic[dotenv]
COPY server.py /app/server.py
WORKDIR /app
CMD ["python3", "server.py"]

3.2 vLLM 서버(FastAPI 통합)

# server.py
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from vllm import LLM, SamplingParams

app = FastAPI()
llm = LLM(model="/models/qwen2-7b", tensor_parallel_size=1)

class Req(BaseModel):
    prompt: str
    max_tokens: int = 256
    temperature: float = 0.2

@app.post("/generate")
async def generate(r: Req):
    sp = SamplingParams(max_tokens=r.max_tokens, temperature=r.temperature)
    out = llm.generate([r.prompt], sp)
    return {"text": out[0].outputs[0].text}

3.3 성능 팁

--max-model-len으로 컨텍스트 길이를 통제해 OOM을 방지.
--gpu-memory-utilization을 0.85 수준으로 시작.
Continuous Batching은 기본 활성화, --max-num-batched-tokens로 조절.
Speculative Decoding 사용 시 초안 모델(Draft)을 경량 모델로 선택.

4. FastAPI 게이트웨이와 캐시 전략

핵심 요약: 프롬프트 캐시와 결과 캐시가 vLLM 서빙의 체감 성능을 좌우한다.

4.1 게이트웨이 코드 스케치

from fastapi import FastAPI, Depends
from redis import Redis
import hashlib, json, httpx

app = FastAPI()
redis = Redis(host="redis", port=6379)
VLLM_URL = "http://vllm:8000/generate"

async def k(prompt, t):
    payload = json.dumps({"p":prompt, "t":t}, sort_keys=True).encode()
    return hashlib.sha256(payload).hexdigest()[:16]

@app.post("/chat")
async def chat(prompt: str, temperature: float = 0.2):
    key = "llm:resp:" + await k(prompt, temperature)
    if hit := redis.get(key):
        return {"text": hit.decode(), "cached": True}
    async with httpx.AsyncClient() as c:
        r = await c.post(VLLM_URL, json={"prompt": prompt, "temperature": temperature})
        r.raise_for_status()
    text = r.json()["text"]
    redis.setex(key, 60*60*12, text)  # 12h TTL
    return {"text": text, "cached": False}

4.2 캐시 체크리스트

키에 프롬프트 버전/모델/온도를 포함.
SWR(serve-stale-while-revalidate)로 피크 시간 안정화.
개인화가 있으면 사용자/조직 스코프를 키에 섞기.

5. Kubernetes 배포와 오토스케일링(HPA)

핵심 요약: vLLM 서빙은 GPU Pod, 게이트웨이는 CPU Pod로 분리하고 튜닝한다.

5.1 Deployment 스니펫

apiVersion: apps/v1
kind: Deployment
metadata:
  name: vllm
spec:
  replicas: 1
  template:
    spec:
      containers:
      - name: vllm
        image: yourrepo/vllm:latest
        args: ["--model","/models/qwen2-7b","--max-model-len","8192"]
        resources:
          limits:
            nvidia.com/gpu: 1
          requests:
            cpu: "2"
            memory: "8Gi"
---
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: gateway-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: gateway
  minReplicas: 2
  maxReplicas: 10
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 60

5.2 오토스케일 포인트

게이트웨이는 CPU/메모리 기반 HPA, vLLM 서빙은 큐 길이/토큰 처리량 커스텀 메트릭 권장.
GPU 노드 스케일 아웃은 코스트 임팩트가 커서 예약형 + 버스트형 혼합.

6. RAG 결합: 벡터DB·리랭킹·프롬프트 포맷

핵심 요약: 검색 정확도와 프롬프트 포맷이 vLLM 서빙의 답변 품질을 결정한다.

분할(Chunking): 500~1,000 토큰, 10~20% 오버랩. 표·코드는 별도 청크.
하이브리드 검색: BM25 + 벡터 유사도, 필터(버전/팀/제품) 적용.
리랭킹: 상위 k=50 → k'=5로 크로스 인코더 리랭킹.
프롬프트: "다음 근거만 사용하여 답하고, 출처를 인용"을 고정. JSON 구조화 출력 권장.

7. 모니터링·로깅·비용 최적화

핵심 요약: 토큰·지연·히트율을 한 대시보드에서 본다.

메트릭: 요청수, 입력/출력 토큰, p50/p95 지연, 캐시 히트율, 에러율.
로그: 프롬프트 버전, 모델 파라미터, 실패 스택, 비용 추정.
비용 절감: 양자화(8-bit/4-bit), 초안 모델로 스펙큘러티브 디코딩, 프롬프트/결과 캐시, 임베딩/검색 캐시.
안전: 프롬프트 주입 방어(화이트리스트·거절 템플릿), 툴 호출엔 스키마 검증.

8. 자주 묻는 질문(FAQ)

Q1. vLLM 서빙과 텍스트-전용 모델만 가능한가?

텍스트 생성 중심이지만, 미들웨어로 멀티턴·함수 호출·RAG 결합을 쉽게 구현할 수 있습니다.

Q2. 지연이 갑자기 튀는 이유는?

요청 폭주로 배칭이 비효율적이거나, 긴 컨텍스트가 섞였을 가능성. max-model-len과 큐 제한을 점검하세요.

Q3. 어떤 GPU가 적합한가?

7B~13B는 단일 24~48GB, 34B 이상은 TP/PP 분산이 유리합니다. 양자화로 메모리를 아낄 수 있습니다.

Q4. 상용 API와 비교한 장점은?

데이터 주권과 비용 통제가 장점입니다. 단, 운영 복잡도는 올라가므로 모니터링·가드레일이 필수입니다.

결론

핵심 요약: vLLM 서빙 + 캐시 + RAG + 모니터링이 프로덕션의 네 기둥이다.

vLLM 서빙을 도입하면 같은 GPU로 더 많은 트래픽을 처리하면서 비용을 크게 줄일 수 있습니다. FastAPI 게이트웨이로 캐시·정책·관찰성을 붙이고, Kubernetes로 배포/스케일을 자동화하세요. 여기에 RAG와 프롬프트 표준화를 얹으면 빠르고 신뢰할 수 있는 LLM 제품이 완성됩니다. 작은 모델로 시작해 지표를 수집하며 확장해 보세요.

함께 보면 좋은 글

LLM 함수 호출(Function Calling) 완전 가이드: JSON Schema·툴 사용·에러 복구

LLM 함수 호출(Function Calling) 완전 가이드: JSON Schema·툴 사용·에러 복구 LLM 함수 호출을 올바르게 설계하면 모델이 정확한 구조화 응답을 내고, 외부 API·DB·검색·계산 같은 툴 사용을 안전하게 자

tapyst.com

LLM 캐시 최적화 완전 정복: KV 캐시·프롬프트 캐시·임베딩 캐시로 지연·비용 50% 줄이기

LLM 캐시 최적화 완전 정복: KV 캐시·프롬프트 캐시·임베딩 캐시로 지연·비용 50% 줄이기 LLM 캐시를 제대로 설계하면 응답 지연은 짧아지고, 월 비용은 예측 가능해집니다. 본 글은 LLM 캐시 핵심

tapyst.com

'개발 · IT > IT 트렌드 & 생산성' 카테고리의 다른 글

OpenSearch/Elasticsearch 쿼리 오류 완전 가이드: DSL 사용법·매핑 함정·페이징·집계·성능 튜닝 (0)	2025.09.02
LangGraph 멀티에이전트 워크플로 구축: 설계·패턴·RAG·운영까지 (완전 가이드) (1)	2025.08.30
LLM 캐시 최적화 완전 정복: KV 캐시·프롬프트 캐시·임베딩 캐시로 지연·비용 50% 줄이기 (4)	2025.08.28
프롬프트 주입 방어 완전 가이드: 안전한 RAG·툴 호출을 위한 4계층 보안 아키텍처 (3)	2025.08.27
AI 에이전트 실전 구축 가이드: 2025 워크플로우·도구·운영 전략 (4)	2025.08.26

타이P스트 IT 아카이브

vLLM 서빙 완전 가이드: FastAPI·Kubernetes·RAG 결합으로 초저비용 고속 배포