LiteLLM을 홈랩에 적용하기: 단일 프록시로 모든 모델 및 워터폴 라우팅 구현

LiteLLM은 폴백 체인(fallback chains), 로드 밸런싱, 비용 제어를 통해 로컬 및 원격 LLM 전반에 걸쳐 사용자의 홈랩을 유연한 AI 게이트웨이로 변모시킵니다.

문제점: 홈랩 내 LLM 엔드포인트의 파편화(Sprawl)

홈랩 AI 생태계가 성장함에 따라, 엔드포인트 관리가 매우 어려워집니다.

LiteLLM 이전: 단편적인 접근 방식

• Ollama: http://homelab:11434 - qwen2.5-coder:14b, deepseek-r1:14b용

• Llama.cpp server: http://homelab:8080 - 특화된 GGUF 모델용

• Text Generation WebUI: http://homelab:7860 - 실험적인 모델용

• OpenAI API: https://api.openai.com/v1 - 로컬 환경만으로는 부족할 때 GPT-4 사용용

• Anthropic API: https://api.anthropic.com - Claude 접근용

• Groq API: https://api.groq.com - 빠른 추론(inference)용

• 각각 필요: 서로 다른 API 키, 서로 다른 엔드포인트, 서로 다른 SDK

• 단일 엔드포인트(Single endpoint): 모든 애플리케이션이 http://homelab:4000/v1/%5C*에 접속합니다.

• OpenAI 호환성: 모든 OpenAI SDK 또는 래퍼와 작동합니다.

• 모델 추상화(Model abstraction): "gpt-4o-mini"가 로컬 또는 원격으로 라우팅될 수 있습니다.

• 자동 폴백(Automatic fallback): 먼저 로컬을 시도하고, 그다음 유료 API를 사용합니다.

• 로드 밸런싱(Load balancing): 여러 Ollama 인스턴스에 요청을 분산합니다.

• 사용량 추적(Usage tracking): 내장된 토큰 카운팅 및 비용 추정 기능을 제공합니다.

• 속도 제한(Rate limiting): 모델별 또는 전역적인 요청 제한이 가능합니다.

• 재시도 로직(Retry logic): 지터(jitter)가 적용된 지수 백오프(exponential backoff)를 사용합니다.

핵심 LiteLLM 개념: 모델, 제공자(Providers), 및 라우팅(Routing)

구성 요소 이해하기:

제공자(Providers): 마법이 일어나는 곳

로컬 제공자 (Homelab 거주)

• ollama: Ollama API와 통신합니다 (대부분의 경우 권장).
• llama_cpp: llama.cpp 서버에 직접 연결합니다.
• vllm: 높은 처리량(high-throughput) 서빙을 위해 사용됩니다 (설정이 더 복잡함).
• tgi: Hugging Face의 Text Generation Inference를 사용합니다.
• sagemaker: 로컬 SageMaker 엔드포인트를 위한 것입니다.
• bedrock: AWS Bedrock 로컬 에뮬레이터입니다.
• vertex_ai: Google Vertex AI 로컬 환경을 지원합니다.
• azure_ai: Azure AI Studio 로컬 환경을 지원합니다.

원격 제공자 (클라우드/API 기반)

• openai: OpenAI API (GPT-3.5, GPT-4 등).
• anthropic: Anthropic API (Claude 계열).
• groq: Groq LPU 추론 엔진입니다.
• cohere: Cohere API를 사용합니다.
• mistralai: Mistral AI API를 사용합니다.
• ali_bailian: Alibaba Cloud BaiLian을 사용합니다.
• volcengine: ByteDance VolcEngine을 사용합니다.
• predibase: Predibase 미세 조정 모델을 사용합니다.
• replicate: Replicate 모델 호스팅 서비스를 이용합니다.
• huggingface: Hugging Face Inference API를 사용합니다.
• azure: Azure OpenAI Service를 사용합니다.
• aws: Amazon Bedrock을 사용합니다.

라우팅 전략: LiteLLM이 요청을 어디로 보낼지 결정하는 방법

순차 목록 (Simple List) (첫 번째 작동하는 것부터 시도)

model_list:
  - model_name: ollama_qwen
    litellm_provider: ollama
...

로드 밸런싱 (Load Balancing) (요청 분산)

여러 인스턴스에 요청을 분산합니다.

모델 목록:

• model_name: ollama_pool_1
  litellm_provider: ollama
  ...

폴백 체인 (Waterfall Routing)

로컬에서 시작하여 점차 비용이 많이 드는 원격 옵션으로 시도합니다:

model_list:
  # Tier 1: 빠른 로컬 (Ollama)
  - model_name: local_fast
...

배포 옵션: 간단한 것부터 정교한 것까지

홈랩 환경에 LiteLLM을 실행하는 방법:

옵션 1: Docker 컨테이너 (권장)

쉽고, 이식성이 뛰어나며, 격리되어 있습니다:

# LiteLLM용 docker run 명령어
docker run -d \
  --name litellm \
...

옵션 2: 직접 설치 (개발용)

수정하거나 디버깅하려는 경우:

# LiteLLM 직접 설치
pip install litellm

...

옵션 3: Kubernetes Helm Chart (고급 사용자용)

TrueNAS SCALE에서 Kubernetes를 실행하는 경우:

# LiteLLM helm repo 추가
helm repo add litellm https://berriai.github.io/litellm-helm-chart
helm repo update
...

설정 심층 분석: config.yaml 파일

LiteLLM 구성의 주요 섹션 이해하기:

필수 구성 섹션

모델 목록 (구성의 핵심)

사용 가능한 모든 모델과 해당 제공업체를 정의합니다:

# 완전한 config.yaml 예시
model_list:
  # === 로컬 Ollama 모델 ===
...

고급 구성 기능

• 모델 별칭 (Model aliases): 동일한 기본 모델을 가리키는 여러 이름
• 동적 모델 로딩 (Dynamic model loading): 요청 패턴에 따라 모델 로드
• 제공업체별 매개변수 (Providers-specific parameters): 각 백엔드에 특수 플래그 전달
• 입력/출력 변환기 (Input/output transformers): 요청/응답을 실시간으로 수정
• 가드레일 (Guardrails): 안전을 위해 NeMo Guardrails 또는 유사 기능과 통합
• 스트리밍 지원 (Streaming support): 스트리밍 응답 적절하게 처리
• 함수 호출 (Function calling): 제공업체 전반에 걸친 OpenAI 스타일 함수 호출
• 비전 모델 (Vision models): 멀티모달 모델의 이미지 입력 처리

일반적인 홈랩 시나리오를 위한 실용적인 라우팅 패턴

일반적인 사용 사례를 위한 바로 사용할 수 있는 구성:

시나리오 1: 비용 효율적인 개발 어시스턴트

로컬 사용을 최대화하고 유료 API 호출을 최소화합니다:

# development assistant용 config.yaml
model_list:
  # Primary: 코딩 도움을 위한 빠른 로컬 모델
...

시나리오 2: 품질 중심의 콘텐츠 생성

출력 품질을 우선시하고, 초안 작성에 로컬 모델을 사용합니다:

# content generation workflow용 config.yaml
model_list:
  # Drafting: 성능 좋은 로컬 모델 사용
...

시나리오 3: 예산 통제형 프로덕션 서비스

우아한 저하(graceful degradation)와 함께 엄격한 비용 제한을 설정합니다:

# budget-conscious service용 config.yaml
model_list:
  # Local models: 실행에 무료 (하드웨어 투자 후)
...

통합 예시: 애플리케이션에서 LiteLLM 사용하기

코드에서 실제로 LiteLLM을 사용하는 방법:

예제 1: OpenAI SDK를 사용한 Python

가장 일반적인 통합 패턴입니다:

# 공식 OpenAI SDK를 사용한 Python 예시
from openai import OpenAI

...

예제 2: 웹 애플리케이션을 위한 JavaScript/TypeScript

웹 앱에 AI를 통합하는 데 완벽합니다:

// JavaScript/TypeScript 예시
// 공식 OpenAI npm 패키지 사용
import { OpenAI } from "openai";

// LiteLLM 엔드포인트를 위해 설정
const client = new OpenAI({
  baseURL: "http://homelab.local:4000/v1",
  apiKey: "sk-12345" // 비어있지 않은 문자열이면 LiteLLM에서 작동합니다
});