NVIDIA-NeMo/Switchyard

Switchyard lets LLM applications route traffic across models and providers while preserving native OpenAI and Anthropic API compatibility - enabling flexible model selection, benchmarking, and cost/performance optimization.

Switchyard – LLM 호출을 위한 비용 인식 라우팅

무엇인가요 – Switchyard은 하나 이상의 대규모 언어 모델(LLM) 제공자 앞에 위치하는 가벼운 라우팅 계층입니다. 각 요청에 대해 구성 가능한 알고리즘에 따라, 저렴한 "효율적" 모델로 호출을 보내는지, 더 강력하지만 일반적으로 비싼 모델로 보내는지 결정하며, 전체 비용을 낮추면서도 작업 정확도를 유지하려고 합니다.

왜 중요한가요 – 많은 에이전트 중심 워크로드에서 단일 강력한 모델은 대부분의 단계에서 과잉입니다. Switchyard는 어려운 경우만 자동으로 "에스컬레이션"함으로써, 토큰 비용을 13~30% 절감할 수 있으며, 성공률은 소폭 감소하거나 오히려 약간 향상되는 결과를 보였습니다. 이는 Terminal-Bench 2.1 벤치마크에서 입증되었습니다.

핵심 구성 요소 (1.0 미만)

구성 요소	안정성	역할
`switchyard-libsy`	베타	라우팅 알고리즘을 노출하는 순수 Rust 라이브러리. 자체 게이트웨이나 하네스에 통합하여 HTTP 호출, 재시도, 자격 증명을 직접 제어할 수 있습니다.
`switchyard-llm-client`	알파	라이브러리의 중립적 요청/응답 유형과 실제 HTTP LLM API 간의 변환을 도와주는 헬퍼입니다.
`switchyard-runner`	알파	다른 런타임(예: NeMo Relay) 내에서 라우팅 구성 실행을 위한 연결 코드입니다.
`switchyard-server`	데모	OpenAI/Anthropic 엔드포인트를 모방하는 독립형 프록시. 빠른 데모나 평가에 유용합니다.

사용 방법

NeMo Relay 플러그인 – 기존 NeMo Relay 배포에 routes.toml 파일을 로드합니다. 플러그인은 선택된 제공자로의 HTTP 디스패치를 처리하지만, Relay의 일반적인 전송 및 재시도 로직은 유지됩니다.
라이브러리 내장 – Python 패키지(pip install nemo-switchyard)를 설치하거나 Rust 크레이트를 프로젝트에 추가합니다. stage_router(picker="efficient_first", confidence_threshold=0.5)와 같은 라우팅 알고리즘을 구축하고, 모델별 HTTP 클라이언트를 공급하는 run_stream 루프로 제어합니다.
스탠드얼론 프록시 – Rust 바이너리(cargo install switchyard-server)를 설치하고, routes.toml을 간단히 작성하여 타겟 ID를 OpenRouter(또는 어떤 OpenAI 호환 엔드포인트)에 매핑한 후 서버를 시작합니다. OpenAI/Anthropic 클라이언트는 http://localhost:4000을 가리키면 자동으로 라우팅의 이점을 누릴 수 있습니다.

라우팅 알고리즘 (TOML 설정에서 하나 선택)

능력 (llm_classifier) – 첫 번째 요청은 작은 LLM으로 평가됩니다. 작업이 어렵다고 판단되면 호출이 에스컬레이션됩니다.
스테이지 (stage_router) – 도구 생성 응답에 대해 패턴 매칭 또는 판정용 LLM을 적용한 후 모델 전환 여부를 결정합니다.
에스컬레이션 – 저렴한 모델에서 시작하여 결과에 판정용 LLM을 적용합니다. 문제를 감지하면 요청은 강력한 모델로 재전송됩니다.
랜덤 / 어드바이저 / 서브에이전트 인식 / 사용자 정의 – 다양한 실험용 전략.

빠르게 시작하기 (Python 예제)

from switchyard.libsy import LlmResponse, Step
from switchyard.libsy.algorithms import stage_router

algorithm = stage_router(picker="efficient_first", confidence_threshold=0.5)

async def route(request, clients):
    async for step in algorithm.run_stream(request, {
        "efficient": ["fast"],
        "capable":   ["quality"],
    }):
        if isinstance(step, Step.CallModel):
            # 각 후보 모델용 자체 HTTP 클라이언트 호출
            resp = await clients[step.models[0]].call(step.request)
            step.respond(LlmResponse.Agg(resp))
        elif isinstance(step, Step.Done):
            return step.outcome.response

동일한 로직은 Rust에서도 사용 가능. switchyard-libsy 크레이트는 Algorithm::run_stream 반복자를 제공합니다.

성숙도 및 라이선스

프로젝트는 1.0 미만이며, API와 구성 형식은 변경될 수 있으므로 통합 시 버전을 고정해야 합니다.
서버 구성 요소는 데모로 표시되어 있으며, 현재는 프로덕션 사용을 권장하지 않습니다.
라이선스는 Apache 2.0 (NVIDIA Corporation).

더 알아보기

핵심 개념 및 TOML 스키마 – docs/core_concepts.md 및 docs/reference/toml_schema.md
라우팅 알고리즘 세부 정보 – docs/routing_algorithms/…
벤치마크 결과 – README의 "Benchmark Provenance" 표를 참조하세요.
커뮤니티 – GitHub 이슈를 열고, 행동 강령(Code of Conduct)이 제공됩니다.

Switchyard는 기존 LLM 게이트웨이(NeMo Relay, LiteLLM, 또는 커스텀 서버)에 라우팅 계층을 도입하여 에이전트를 재작성하지 않고도 토큰 비용을 절감할 수 있습니다.