Router: 로드밸런싱·폴백·재시도 개념

여러 LLM 배포를 하나의 앱에서 골고루 쓰고 싶거나, 한 배포가 죽었을 때 자동으로 다른 배포로 넘기고 싶다면 Router가 그 일을 대신해 줍니다. SDK에서 직접 쓰는 Router는 애플리케이션 레벨에서 동작하고, Proxy Server까지 가면 게이트웨이에서 동일한 로직을 서버 단위로 제공해요. 이 문서는 그 개념을 잡는 데 초점을 맞출게요.

출처: 공식문서 - Router: Load Balancing

Router가 하는 일

LiteLLM의 Router는 크게 세 가지를 관리합니다.

로드밸런싱 — 여러 배포(예: Azure/OpenAI)에 걸쳐 요청을 분산해요.
중요 요청 우선 처리(큐잉) — 중요한 요청이 실패하지 않도록 우선순위를 둬요.
기본 신뢰성 로직 — 여러 배포/프로바이더에 걸친 쿨다운(cooldown), 폴백, 타임아웃, 재시도(고정·지수 백오프)를 처리해요.

운영(production)에서는 Redis를 써서 쿨다운 상태와 사용량(tpm/rpm)을 추적할 수 있습니다.

model_name과 배포 목록

Router에 모델 배포 목록을 넘길 때, 각 항목은 겉으로 드러나는 별칭과 실제 모델을 분리해요.

model_name — 클라이언트가 요청에 쓰는 별칭(alias) 이에요. 같은 model_name을 가진 배포끼리 로드밸런싱됩니다.
litellm_params — 실제 호출에 쓰는 파라미터예요. model(실제 모델명), api_key, api_base, api_version 등을 담습니다.

예를 들어 gpt-5.6-luna라는 별칭 아래 Azure 배포와 OpenAI 배포를 두면, 클라이언트는 model="gpt-5.6-luna"로만 요청하면 됩니다. Router가 그 배포들 중 하나를 골라 실제 모델로 호출하죠.

from litellm import Router

model_list = [  # 모델 배포 목록
    {
        "model_name": "gpt-5.6-luna",        # 별칭: 같은 alias끼리 로드밸런싱
        "litellm_params": {                   # 실제 호출 파라미터
            "model": "azure/chatgpt-v-2",     # 실제 모델명
            "api_key": os.getenv("AZURE_API_KEY"),
            "api_version": os.getenv("AZURE_API_VERSION"),
            "api_base": os.getenv("AZURE_API_BASE")
        }
    },
    {
        "model_name": "gpt-5.6-luna",
        "litellm_params": {
            "model": "gpt-5.6-luna",          # 같은 별칭, OpenAI 배포
            "api_key": os.getenv("OPENAI_API_KEY")
        }
    },
]

router = Router(model_list=model_list)

# model="gpt-5.6-luna" 요청은 model_name이 같은 배포를 골라 호출
response = await router.acompletion(
    model="gpt-5.6-luna",
    messages=[{"role": "user", "content": "Hey, how's it going?"}]
)

라우팅 전략

Router는 여러 라우팅 전략을 제공합니다. 운영에서는 기본값인 simple-shuffle을 가장 권장해요. 성능이 가장 좋고 지연 오버헤드가 최소라서입니다. 전략은 배포 선택의 기준이 달라져요.

simple-shuffle(기본, 권장) — 가장 좋은 성능, 최소 지연 오버헤드.
Rate-Limit Aware v2(비동기) — 제시된 분당 요청수(rpm)나 분당 토큰수(tpm) 를 기반으로 배포를 고릅니다. rpm/tpm이 없으면 랜덤으로 선택하고, weight 파라미터로 배포별 가중치를 줄 수 있어요.
Latency-Based — 지연 기반.
Least-Busy, 커스텀 전략, Lowest Cost 등 — 상황에 맞는 특화 전략도 있어요.

더 알아보기

게이트웨이 안에서 Router가 요청 흐름의 어느 단계에 있는지 보고 싶다면 프록시 요청 수명 문서를 보세요.
게이트웨이(서버) 레벨에서 로드밸런싱을 하려면 Proxy Server 문서를 참고하세요.
Redis 기반 쿨다운·사용량 추적은 Production 배포 문서의 인프라 설명과 이어집니다.