LiteLLM 통합 게이트웨이의 5가지 핵심 개념 이해: 신규 사용자를 위한 AI 에이전트 인프라 가이드

OpenAI의 GPT, Anthropic의 Claude, Google의 Gemini를 프로젝트에 동시에 사용하면서, 모델마다 제각각인 SDK와 API 형식, 그리고 서로 다른 에러 처리 방식 때문에 골치 아팠던 적 있으신가요? 모델 하나만 바꿔도 코드 전체를 수정해야 하는 상황 말이죠.

이런 고민을 해결해 주는 것이 바로 LiteLLM입니다. 간단히 말해, LiteLLM은 AI 대규모 언어 모델을 위한 '만능 번역기'입니다. 여러분은 단 하나의 호출 방식(OpenAI 형식)만 익히면, LiteLLM이 알아서 100여 개 모델 업체의 각기 다른 API 형식으로 변환해 줍니다.

핵심 가치: 이 글을 읽고 나면 LiteLLM이 무엇인지, 왜 AI 에이전트 프레임워크들이 이를 필수로 사용하는지, 그리고 5분 만에 시작하는 방법을 완벽히 이해하게 될 것입니다.

LiteLLM이란 무엇인가: 5가지 핵심 개념

본격적으로 사용하기 전에, LiteLLM의 5가지 핵심 개념을 가장 쉬운 방식으로 이해해 봅시다. 이 개념들만 확실히 잡으면 이후 작업은 일사천리입니다.

LiteLLM은 어떤 고충을 해결할까요?

LiteLLM이 없는 세상을 상상해 보세요.

OpenAI 호출:

from openai import OpenAI
client = OpenAI(api_key="sk-xxx")
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "안녕하세요"}]
)

Anthropic 호출:

import anthropic
client = anthropic.Anthropic(api_key="sk-ant-xxx")
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,  # Anthropic은 필수 지정
    messages=[{"role": "user", "content": "안녕하세요"}]
)

Google Gemini 호출:

import google.generativeai as genai
genai.configure(api_key="AIza-xxx")
model = genai.GenerativeModel("gemini-2.0-flash")
response = model.generate_content("안녕하세요")

보이시나요? 모델 3개에 SDK 3개, 작성법도 3가지입니다. 프로젝트에서 모델을 교체해야 한다면 코드 곳곳에 if provider == "openai"... elif provider == "anthropic"... 같은 조건문이 가득하게 될 겁니다.

LiteLLM을 사용하면:

import litellm

# OpenAI 호출
response = litellm.completion(model="gpt-4o", messages=[{"role": "user", "content": "안녕하세요"}])

# Anthropic 호출 — 동일한 작성법
response = litellm.completion(model="anthropic/claude-sonnet-4-6", messages=[{"role": "user", "content": "안녕하세요"}])

# Gemini 호출 — 역시 동일한 작성법
response = litellm.completion(model="gemini/gemini-2.0-flash", messages=[{"role": "user", "content": "안녕하세요"}])

litellm.completion() 하나면 충분합니다. model 파라미터만 바꾸면 되죠. LiteLLM이 내부적으로 형식 변환, 파라미터 조정, 응답 표준화를 자동으로 처리합니다.

🎯 기술 제안: LiteLLM의 통합 인터페이스 철학은 APIYI(apiyi.com)와 유사합니다. 둘 다 하나의 인터페이스로 여러 모델을 호출할 수 있죠. 차이점은 LiteLLM은 오픈소스 기반의 직접 배포형 솔루션이고, APIYI는 별도의 배포가 필요 없는 관리형 서비스라는 점입니다. 팀의 기술 역량에 맞춰 적절한 방식을 선택해 보세요.

LiteLLM 두 가지 사용 모드 상세 가이드

LiteLLM은 다양한 환경에 맞춰 사용할 수 있도록 두 가지 모드를 제공합니다. 이 두 모드의 차이점을 이해하는 것이 올바른 사용 방식을 선택하는 핵심입니다.

모드 1: Python SDK (경량형)

Python 코드에서 litellm 패키지를 직접 임포트하여 함수 호출하듯 간편하게 사용할 수 있습니다.

적합한 상황:

• 개인 개발자
• 순수 Python 프로젝트
• 빠른 프로토타입 검증
• 별도의 팀 관리 기능이 필요 없는 경우

설치:

pip install litellm

기본 사용법:

import litellm
import os

# API 키 설정 (환경 변수 사용)
os.environ["OPENAI_API_KEY"] = "sk-당신의키"
os.environ["ANTHROPIC_API_KEY"] = "sk-ant-당신의키"

# 원하는 모델 호출
response = litellm.completion(
    model="gpt-4o",
    messages=[{"role": "user", "content": "API 게이트웨이가 무엇인지 설명해줘"}]
)

print(response.choices[0].message.content)

모드 2: Proxy Server (엔터프라이즈급 게이트웨이)

독립적인 서버로 실행되며, 외부에는 OpenAI와 호환되는 HTTP 인터페이스를 제공합니다. HTTP 요청을 보낼 수 있는 모든 프로그래밍 언어나 도구에서 사용할 수 있습니다.

적합한 상황:

• 팀 단위 협업
• 다국어 프로젝트 (Java, Go, Node.js 등)
• 비용 추적 및 예산 관리가 필요한 경우
• 팀별로 가상 키를 할당해야 하는 경우
• AI 에이전트 프레임워크 연동

설치 및 실행:

# 설치
pip install 'litellm[proxy]'

# 설정 파일로 실행
litellm --config config.yaml --port 4000

# 또는 Docker 사용
docker run -p 4000:4000 \
  -e OPENAI_API_KEY=sk-xxx \
  ghcr.io/berriai/litellm:main-latest

실행 후, 어떤 애플리케이션이든 OpenAI를 호출하는 것과 동일한 방식으로 사용할 수 있습니다.

from openai import OpenAI

# base_url을 LiteLLM Proxy로 지정
client = OpenAI(
    api_key="sk-당신의가상키",
    base_url="http://localhost:4000/v1"
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "안녕하세요"}]
)

LiteLLM SDK vs Proxy 모드 비교

💡 선택 팁: 개인 개발자가 프로토타입을 검증하는 단계라면 SDK 모드로 5분 만에 시작해 보세요. 팀 단위로 사용하거나 운영 환경이라면 Proxy 모드가 훨씬 적합합니다. 물론, 직접 서버를 배포하고 유지 관리하는 것이 번거롭다면 APIYI(apiyi.com)와 같은 관리형 통합 인터페이스 서비스를 사용하여 바로 시작할 수도 있습니다.

LiteLLM 퀵 스타트 가이드

LiteLLM을 처음부터 시작하는 전체 단계를 정리해 드립니다.

LiteLLM SDK 모드 퀵 스타트

1단계: 설치

pip install litellm

2단계: 환경 변수 설정

# macOS / Linux
export OPENAI_API_KEY="sk-당신의키"
export ANTHROPIC_API_KEY="sk-ant-당신의키"

# Windows
set OPENAI_API_KEY=sk-당신의키

3단계: 코드 작성

import litellm

# 기본 호출
response = litellm.completion(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "당신은 기술 어시스턴트입니다."},
        {"role": "user", "content": "LLM 게이트웨이란 무엇인가요?"}
    ],
    temperature=0.7
)

print(response.choices[0].message.content)
print(f"토큰 사용량: {response.usage.total_tokens}")
print(f"예상 비용: ${response._hidden_params.get('response_cost', 'N/A')}")

import litellm
import os

os.environ["OPENAI_API_KEY"] = "sk-당신의키"
os.environ["ANTHROPIC_API_KEY"] = "sk-ant-당신의키"

# Fallback 호출: GPT-4o 실패 시 자동으로 Claude로 전환
response = litellm.completion(
    model="gpt-4o",
    messages=[{"role": "user", "content": "RESTful API를 설명해주세요"}],
    fallbacks=["anthropic/claude-sonnet-4-6"],
    num_retries=2
)

# 스트리밍 출력
stream = litellm.completion(
    model="gpt-4o",
    messages=[{"role": "user", "content": "프로그래밍에 관한 시를 써줘"}],
    stream=True
)

for chunk in stream:
    content = chunk.choices[0].delta.content
    if content:
        print(content, end="", flush=True)

LiteLLM Proxy 모드 퀵 스타트

1단계: 설정 파일 config.yaml 생성

model_list:
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: os.environ/OPENAI_API_KEY

  - model_name: claude-sonnet
    litellm_params:
      model: anthropic/claude-sonnet-4-6
      api_key: os.environ/ANTHROPIC_API_KEY

  - model_name: gemini-flash
    litellm_params:
      model: gemini/gemini-2.0-flash
      api_key: os.environ/GEMINI_API_KEY

litellm_settings:
  drop_params: true
  num_retries: 3

general_settings:
  master_key: sk-my-master-key

2단계: Proxy 실행

litellm --config config.yaml --port 4000

3단계: 표준 OpenAI SDK를 사용한 호출

from openai import OpenAI

client = OpenAI(
    api_key="sk-my-master-key",
    base_url="http://localhost:4000/v1"
)

# GPT-4o 호출 (LiteLLM Proxy 경유)
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "안녕하세요"}]
)
print(response.choices[0].message.content)

cURL을 사용하여 직접 호출할 수도 있습니다:

curl http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer sk-my-master-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

🚀 빠른 시작: LiteLLM Proxy는 서버와 API 키를 직접 관리해야 합니다. 배포 없이 통합 인터페이스를 바로 사용하고 싶다면 APIYI(apiyi.com)를 확인해 보세요. 인프라 구축 없이도 100개 이상의 모델을 OpenAI 호환 형식으로 바로 호출할 수 있습니다.

AI 에이전트에서 LiteLLM의 핵심 역할

많은 초보자가 궁금해하는 점입니다. 왜 거의 모든 주류 AI 에이전트 프레임워크가 LiteLLM을 지원하거나 권장할까요?

AI 에이전트에 LiteLLM이 필요한 이유

AI 에이전트는 작업을 수행할 때 다음과 같은 기능이 자주 필요합니다:

1. 다양한 모델 호출: 간단한 작업은 저렴한 소형 모델로, 복잡한 추론은 대규모 언어 모델로 처리
2. 자동 장애 조치(Fallback): 주력 모델의 속도 제한이나 서버 다운 시 자동으로 예비 모델로 전환
3. 비용 제어: 여러 에이전트가 동시에 실행될 때 토큰 비용을 통합 추적하고 제한
4. 팀 협업: 여러 개발자의 에이전트가 API 리소스 풀을 공유

LiteLLM은 이러한 요구사항을 완벽하게 해결합니다. 에이전트와 모델 사이의 '스케줄링 센터' 역할을 수행하는 것이죠.

LiteLLM과 주요 AI 에이전트 프레임워크 통합

다중 에이전트 시스템에서의 LiteLLM 일반적인 아키텍처

다중 에이전트 시스템에서 LiteLLM Proxy는 보통 다음과 같이 작동합니다:

1. 기획 에이전트 → Claude Opus 호출 (고성능 추론 모델)
2. 실행 에이전트 → GPT-4o 호출 (성능 균형)
3. 검증 에이전트 → GPT-4o-mini 호출 (빠르고 저렴한 비용)
4. 요약 에이전트 → Gemini Flash 호출 (대규모 컨텍스트 윈도우)

모든 에이전트는 동일한 LiteLLM Proxy 엔드포인트를 통해 호출되며, Proxy가 자동으로 올바른 백엔드 모델로 라우팅합니다. 관리자는 대시보드를 통해 모든 에이전트의 토큰 사용량과 비용을 한눈에 확인할 수 있습니다.

🎯 기술 제안: 프로덕션 환경의 다중 에이전트 시스템에서 LiteLLM Proxy를 사용하려면 비용 추적 및 캐싱 기능을 위해 PostgreSQL과 Redis가 필요합니다. 팀 규모가 작거나 추가 인프라를 운영하고 싶지 않다면, APIYI(apiyi.com)를 고려해 보세요. 비용 추적과 사용량 통계가 내장된 통합 인터페이스를 제공하므로 별도의 데이터베이스를 배포할 필요가 없습니다.

LiteLLM 고급 기능 상세 가이드

기본적인 사용법을 익히셨다면, 이제 프로덕션 환경에서 가장 자주 쓰이는 3가지 고급 기능을 살펴볼 차례입니다.

고급 기능 1: 모델 Fallback (장애 조치)

주력 모델에서 속도 제한, 타임아웃 또는 오류가 발생할 때, LiteLLM이 자동으로 예비 모델로 전환하여 서비스 중단을 방지합니다.

SDK에서 Fallback 설정:

response = litellm.completion(
    model="gpt-4o",
    messages=messages,
    fallbacks=["anthropic/claude-sonnet-4-6", "gemini/gemini-2.0-flash"],
    num_retries=2
)

실행 로직: GPT-4o 우선 시도 → 실패 시 Claude Sonnet 시도 → 다시 실패 시 Gemini Flash 시도.

Proxy에서 Fallback 설정 (config.yaml):

litellm_settings:
  fallbacks:
    - gpt-4o: [claude-sonnet, gemini-flash]
    - claude-sonnet: [gpt-4o, gemini-flash]

고급 기능 2: 로드 밸런싱

하나의 모델 이름에 여러 백엔드 배포를 설정하면, LiteLLM이 요청을 자동으로 분산 처리합니다.

model_list:
  # 동일한 모델명에 두 개의 다른 백엔드 설정
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: os.environ/OPENAI_KEY_1

  - model_name: gpt-4o
    litellm_params:
      model: azure/gpt-4o-deployment
      api_key: os.environ/AZURE_KEY_1
      api_base: https://my-azure.openai.azure.com

router_settings:
  routing_strategy: least-busy  # 부하가 가장 적은 모델 우선
  # 기타 전략: simple-shuffle, latency-based

호출 시 model="gpt-4o"만 지정하면, LiteLLM이 알아서 OpenAI 직연동과 Azure 배포 사이에서 트래픽을 분산합니다.

고급 기능 3: 비용 추적 및 가상 키

가상 키 생성 (Proxy 모드):

curl http://localhost:4000/key/generate \
  -H "Authorization: Bearer sk-master-key" \
  -H "Content-Type: application/json" \
  -d '{
    "max_budget": 50.0,
    "budget_duration": "monthly",
    "models": ["gpt-4o", "claude-sonnet"],
    "metadata": {"user": "developer-01"}
  }'

이렇게 하면 월간 예산이 50달러로 제한되고, GPT-4o와 Claude Sonnet만 호출할 수 있는 가상 키가 생성됩니다.

비용 추적:

LiteLLM은 모델별 가격표를 내장하고 있어 API 호출 시마다 비용을 자동으로 계산합니다. Proxy 관리 대시보드에서 다음을 확인할 수 있습니다:

• 모델별 총 사용 비용
• 사용자/팀별 상세 비용 내역
• 기간별 비용 추이
• 토큰 사용량 통계

💰 비용 최적화: LiteLLM의 비용 추적 기능을 활용하면 어떤 모델 호출이 가장 많은 비용을 차지하는지 쉽게 파악할 수 있습니다. APIYI(apiyi.com)의 가격 경쟁력과 결합하면, 동일한 모델 호출이라도 더 저렴한 가격으로 이용할 수 있어 AI 애플리케이션 운영 비용을 획기적으로 낮출 수 있습니다.

LiteLLM이 지원하는 100개 이상의 모델 Provider 목록

LiteLLM은 매우 방대한 Provider를 지원합니다. 가장 자주 사용되는 카테고리는 다음과 같습니다:

🎯 선택 가이드: 모델 선택은 구체적인 상황에 따라 달라집니다. 어떤 모델을 써야 할지 고민된다면 APIYI(apiyi.com) 플랫폼에서 다양한 모델의 성능을 빠르게 테스트해 보세요. 해당 플랫폼 또한 위 모델 대부분에 대해 OpenAI 호환 인터페이스 호출을 지원합니다.

LiteLLM 자주 묻는 질문(FAQ)

# 스트리밍 예제 코드
stream = litellm.completion(
    model="gpt-4o",
    messages=[{"role": "user", "content": "이야기를 하나 써줘"}],
    stream=True
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

litellm --config /path/to/your/config.yaml

LiteLLM 빠른 의사결정 가이드

현재 상황에 맞춰 가장 적합한 솔루션을 선택하세요:

요약

LiteLLM은 AI 애플리케이션 개발에서 매우 유용한 인프라 도구입니다. 핵심 가치를 한 문장으로 정리하자면, **"OpenAI 형식의 코드 하나로 100개 이상의 모델 제공업체 API를 호출할 수 있다"**는 점입니다.

초보자라면 다음 핵심 사항들을 기억하세요:

1. LiteLLM은 '번역기'입니다: 통일된 형식의 요청을 각 모델의 API 형식으로 변환해 줍니다.
2. 두 가지 모드: SDK(경량 파이썬 패키지)와 Proxy(독립형 게이트웨이 서버) 모드를 지원합니다.
3. 핵심 가치: 통합 인터페이스, Fallback(대체 모델 전환), 로드 밸런싱, 비용 추적 기능을 제공합니다.
4. 에이전트 프레임워크의 표준: LangChain, CrewAI, AutoGen 등 거의 모든 프레임워크가 LiteLLM을 지원합니다.
5. 완전 오픈소스 무료: MIT 라이선스를 따르며, 자체 배포 시 비용이 전혀 들지 않습니다.

만약 LiteLLM Proxy를 직접 배포하고 운영하는 것이 부담스럽다면, APIYI(apiyi.com)와 같은 관리형 통합 인터페이스 서비스를 사용해 보세요. 하나의 API 키로 모든 주요 모델을 호출할 수 있어 배포 및 운영 부담을 덜 수 있습니다.

작성자: APIYI 기술팀
기술 교류: APIYI(apiyi.com)를 방문하여 더 많은 AI 모델 호출 튜토리얼과 기술 지원을 받아보세요.
업데이트 날짜: 2026년 4월
적용 버전: LiteLLM v1.x+

참고 자료:

1. LiteLLM 공식 문서: docs.litellm.ai
2. LiteLLM GitHub 저장소: github.com/BerriAI/litellm
3. LiteLLM 공식 웹사이트: litellm.ai
4. BerriAI 공식 웹사이트: berri.ai