시맨틱 자동 라우터

시맨틱 자동 라우터 (Semantic Auto Router, deprecated)

Deprecated

시맨틱 Auto Router는 Auto Routing으로 대체됐어요. Auto Routing은 시맨틱 키워드 매칭, complexity 스코어링, 적응형 라우팅을 단일 auto_router/complexity_router로 통합해요. 새 배포는 거기서 시작하세요. 시맨틱 라우터 페이지는 기존 콘피그를 위해 보존됐어요.

LiteLLM은 사용자가 정의한 규칙에 따라 요청에 가장 적합한 모델을 자동으로 선택할 수 있어요.

출처: 문서

본문

LiteLLM Python SDK

자동 라우팅을 사용하면 입력 콘텐츠에 따라 요청에 가장 적합한 모델을 자동으로 선택하는 라우팅 규칙을 정의할 수 있어요. 다양한 유형의 쿼리를 특화된 모델로 보내야 할 때 유용해요.

설정 (Setup)

라우터 콘피그 파일(예: router.json)을 생성하세요:

{
    "encoder_type": "openai",
    "encoder_name": "text-embedding-3-large",
    "routes": [
        {
            "name": "litellm-gpt-4.1",
            "utterances": [
                "litellm is great"
            ],
            "description": "positive affirmation",
            "function_schemas": null,
            "llm": null,
            "score_threshold": 0.5,
            "metadata": {}
        },
        {
            "name": "litellm-claude-35",
            "utterances": [
                "how to code a program in [language]"
            ],
            "description": "coding assistant",
            "function_schemas": null,
            "llm": null,
            "score_threshold": 0.5,
            "metadata": {}
        }
    ]
}

자동 라우팅 모델로 Router를 구성하세요:

from litellm import Router
import os

router = Router(
    model_list=[
        # 라우팅용 임베딩 모델
        {
            "model_name": "custom-text-embedding-model",
            "litellm_params": {
                "model": "text-embedding-3-large",
                "api_key": os.getenv("OPENAI_API_KEY"),
            },
        },
        # 대상 모델
        {
            "model_name": "litellm-gpt-4.1",
            "litellm_params": {
                "model": "gpt-5.6-terra",
            },
            "model_info": {"id": "openai-id"},
        },
        {
            "model_name": "litellm-claude-35",
            "litellm_params": {
                "model": "claude-sonnet-5",
            },
            "model_info": {"id": "claude-id"},
        },
        # Auto router 구성
        {
            "model_name": "auto_router1",
            "litellm_params": {
                "model": "auto_router/auto_router_1",
                "auto_router_config_path": "router.json",
                "auto_router_default_model": "gpt-5.6-luna",
                "auto_router_embedding_model": "custom-text-embedding-model",
            },
        },
    ],
)

사용법 (Usage)

구성 후 자동 라우터 모델 이름으로 호출해 사용하세요:

# 이 요청은 utterance 매칭에 따라 gpt-5.6-terra로 라우팅됨
response = await router.acompletion(
    model="auto_router1",
    messages=[{"role": "user", "content": "litellm is great"}],
)
# 이 요청은 코딩 쿼리에 대해 claude-sonnet-5로 라우팅됨
response = await router.acompletion(
    model="auto_router1",
    messages=[{"role": "user", "content": "how to code a program in python"}],
)

구성 파라미터 (Configuration Parameters)

auto_router_config_path: router.json 콘피그 파일 경로
auto_router_default_model: 일치하는 라우트가 없을 때의 폴백 모델
auto_router_embedding_model: utterances와 매칭할 임베딩 생성에 사용되는 모델

라우터 콘피그 스키마 (Router Configuration Schema)

router.json 파일은 다음 구조를 지원해요:

encoder_type: 인코더 유형 (예: "openai")
encoder_name: 임베딩 모델 이름
routes: 다음 속성을 가진 라우팅 규칙 배열:
- name: 대상 모델 이름 (model_list의 모델과 일치해야 함)
- utterances: 매칭할 예시 문구/패턴
- description: 라우트의 사람이 읽을 수 있는 설명
- score_threshold: 이 라우트를 트리거할 최소 유사도 점수 (0.0-1.0)
- metadata: 라우트의 추가 메타데이터

LiteLLM 프록시 서버

설정 (Setup)

LiteLLM UI로 이동해 Models+Endpoints > Add Model > Auto Router 탭으로 가세요.

다음 필수 필드를 구성하세요:

Auto Router Name - 개발자가 LiteLLM에 LLM API 요청을 보낼 때 사용할 모델 이름
Default Model - 일치하는 라우트가 없을 때 사용되는 폴백 모델 (예: "gpt-5.6-luna"로 설정하면, 일치하지 않는 요청은 gpt-5.6-luna로 라우팅됨)
Embedding Model - 입력 메시지의 임베딩을 생성하는 데 사용되는 모델. 이 임베딩들은 입력을 라우트에 정의된 utterances와 시맨틱 매칭하는 데 사용됨

라우트 구성 (Route Configuration)

Add Route를 클릭해 새 라우팅 규칙을 생성하세요. 각 라우트는 대상 모델을 결정하기 위해 입력 메시지와 매칭되는 utterances로 구성돼요.

각 라우트를 다음으로 구성하세요:

Utterances - 이 라우트를 트리거할 예시 문구. 대괄호 안에 변수용 플레이스홀더를 사용하세요:

["how to code a program in [language]",
"can you explain this [language] code",
"can you explain this [language] script",
"can you convert this [language] code to [target_language]"]

Description - 이 라우트가 처리하는 내용의 사람이 읽을 수 있는 설명
Score Threshold - 이 라우트를 트리거하는 데 필요한 최소 유사도 점수 (0.0-1.0)

사용법 (Usage)

추가한 후 개발자는 LLM API 요청의 model 필드에서 model=auto_router1을 선택해야 해요.

OpenAI Python v1.0.0+

import openai
client = openai.OpenAI(
    api_key="sk-<your-litellm-api-key>", # replace with your LiteLLM API key
    base_url="http://localhost:4000")
# 이 요청은 콘텐츠에 따라 자동 라우팅됨
response = client.chat.completions.create(
    model="auto_router1",
    messages=[
        {
            "role": "user",
            "content": "how to code a program in python"
        }
    ])
print(response)

Curl 요청

curl -X POST http://localhost:4000/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ***" \
-d '{
    "model": "auto_router1",
    "messages": [{"role": "user", "content": "how to code a program in python"}]
}'

동작 방식 (How It Works)

요청이 들어오면 LiteLLM은 입력 메시지에 대한 임베딩을 생성해요.
이 임베딩을 모든 라우트에 정의된 모든 utterances와 동시에 비교해요.
유사도 점수가 가장 높은 라우트를 식별해요. 그 점수가 해당 라우트의 정의된 임계값을 초과하면 요청은 그 모델로 라우팅돼요. (라우터는 첫 번째 일치에서 멈추지 않고 전역 최대 점수를 선택하므로, 콘피그에서 라우트의 순서는 어떤 라우트가 선택되는지에 영향을 주지 않아요.)
어떤 라우트의 최대 점수도 임계값을 충족하지 못하면 요청은 기본 모델로 가요.