[BETA] 어댑티브 라우터

[BETA] 어댑티브 라우터 (Adaptive Router)

베타 기능이에요. 피드백은 Discord 또는 Slack에서 공유해 주세요.

요구사항: Postgres 데이터베이스가 있는 LiteLLM Proxy. 품질 추정치는 Postgres에 저장되고 시작 시 로드됩니다. 데이터베이스가 없으면 라우터는 동작하지만 재시작 시 학습한 모든 것을 잊어버려요.

싸고 좋은 모델과 비싼 모델이 있다고 상상해 보세요. 저렴한 모델이 충분히 좋을 때는 저렴한 모델을 쓰고, 정말 중요할 때만 비싼 모델을 쓰고 싶은데, 몇 달씩 튜닝할 룰을 하드코딩하고 싶지는 않을 거예요.

어댑티브 라우터는 이를 자동으로 처리합니다. 각 요청 유형(코드, 글쓰기, 분석 등)에 어떤 모델이 가장 잘 수행하는지 추적하고 그에 따라 라우팅하며, 사용자가 제어하는 가중치에 따라 품질과 비용을 균형 맞춰요.

빠른 시작

model_list:
  - model_name: gpt-5.6-terra
    litellm_params:
      model: openai/gpt-5.6-terra
    model_info:
      input_cost_per_token: 0.000002
      adaptive_router_preferences:
        quality_tier: 3        # 1=budget, 2=mid, 3=frontier
        strengths: ["code_generation", "analytical_reasoning"]

  - model_name: gpt-5.6-luna
    litellm_params:
      model: openai/gpt-5.6-luna
    model_info:
      input_cost_per_token: 0.0000002
      adaptive_router_preferences:
        quality_tier: 2
        strengths: ["factual_lookup"]

  - model_name: my-router
    litellm_params:
      model: auto_router/adaptive_router
      adaptive_router_config:
        available_models: ["gpt-5.6-terra", "gpt-5.6-luna"]
        weights:
          quality: 0.7   # raise this if quality complaints; lower if bill too high
          cost: 0.3      # must sum to 1.0 with quality

모델을 어댑티브 라우터의 이름으로 설정해 라우팅하세요:

curl -X POST {{baseURL}}/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{
    "model": "my-router",
    "messages": [
      {"role": "user", "content": "build me a python script that parses CSV"},
      {"role": "assistant", "content": "Here is a script using csv.DictReader..."},
      {"role": "user", "content": "now add error handling for missing files"},
      {"role": "assistant", "content": "Wrap the open() call in a try/except FileNotFoundError..."},
      {"role": "user", "content": "perfect, that worked. thanks!"}
    ]
  }'

응답에는 실제로 어떤 모델이 선택됐는지 알려주는 헤더가 포함돼요:

x-litellm-adaptive-router-model: gpt-5.6-terra

위 예시의 "thanks!" 턴은 만족 신호를 발동시키고, 그것이 밴딧(bandit)을 움직이는 거예요.

출처: 문서

본문

비용 vs 품질 튜닝

가중치는 주요 레버예요:

라우터는 시간이 지나며 학습합니다. 모델당 처음 약 10개 요청 동안은 선언한 등급(tier)에 의존합니다. 그 후에는 실제 성능 데이터가 적용돼요.

요청별 최소 품질 등급 강제

특정 요청이 비용과 무관하게 frontier 모델을 필요로 한다면 이 헤더를 전달하세요:

x-litellm-min-quality-tier: 3

헤더 대신 요청 metadata로 min_quality_tier를 전달할 수도 있어요.

무엇을 학습하나

라우터는 각 요청을 7가지 유형 중 하나로 분류하고 각 모델이 각 유형에서 어떻게 수행하는지 독립적으로 추적합니다. 사실 조회(factual lookup)에는 뛰어나지만 코드에는 약한 모델은, 전반적으로 더 싸더라도 사실 조회 요청은 이기고 코드 요청은 지는 형태예요.

분류기 코드 참고

학습 신호는 Signals: Trajectory Sampling and Triage for Agentic Interactions 문서에서 영감을 받았어요.

현재 상태 확인

GET /adaptive_router/state

관리자 전용이에요. 구성된 어댑티브 라우터마다 하나의 스냅샷을 반환하며(router_name 필드가 각각을 식별), 요청 유형별·모델별 현재 품질 추정치를 담고 있습니다. 어떤 모델이 왜 선택되거나 선택되지 않는지 이해하는 데 유용해요.

{
  "routers": [
    {
      "router_name": "smart-cheap-router",
      "available_models": ["fast", "smart"],
      "weights": { "quality": 0.7, "cost": 0.3 },
      "cells": [
        {
          "request_type": "analytical_reasoning",
          "model": "fast",
          "quality_mean": 0.5,
          "samples": 0
        },
        {
          "request_type": "analytical_reasoning",
          "model": "smart",
          "quality_mean": 0.95,
          "samples": 0
        }
      ]
    }
  ]
}

quality_mean이 핵심 숫자예요: 해당 모델이 그 요청 유형을 얼마나 잘 처리하는지에 대한 라우터의 현재 추정치입니다. samples는 사전(prior)을 움직인 실제 관측 수를 세요 (0에서 시작하며, 콜드 스타트 prior 질량은 제외).

알려진 제한 사항

• 지연 시간(latency)은 점수화되지 않아요. 느린 모델도 품질 + 비용에서 이길 수 있습니다
• 신호는 정규식 기반이고 영어 편향이에요. LLM 판사(judge)는 없습니다
• 셀당 200개 관측의 하드 상한, 아직 decay는 없음
• 세션에 한 번 모델이 선택되면 그 세션의 다른 모델 턴은 학습에 기여하지 않아요

더 알아보기 (Learn more)

• Auto Router
• Reliability - Retries, Fallbacks