Wayfinder Router: 로컬 및 호스팅된 LLM 간의 쿼리 결정론적 라우팅 (deterministic routing)
요약
Wayfinder Router는 프롬프트의 복잡도를 분석하여 로컬 모델과 클라우드 모델 중 최적의 경로를 결정하는 라우팅 도구입니다. 모델 호출 없이 오프라인 상태에서 마이크로초 단위로 결정론적 라우팅을 수행하여 비용을 절감합니다.
핵심 포인트
- 모델 호출 없이 오프라인에서 프롬프트 복잡도 분석
- 프롬프트 구조와 표현 방식을 기반으로 한 결정론적 라우팅
- 단순 작업은 로컬로, 복잡한 작업은 클라우드로 분산하여 비용 최적화
- 마이크로초 단위의 빠른 결정 속도 제공
Wayfinder는 프롬프트의 구조(길이, 헤딩, 리스트, 코드)와 표현 방식(증명, 수학, 엄격한 제약 조건)을 살펴본 다음, 이를 작은 로컬 모델(local model)로 보낼지 아니면 큰 클라우드 모델(cloud model)로 보낼지를 알려줍니다. Wayfinder는 마이크로초 단위로 결정하며, 오프라인에서 실행되고, 결정을 내리기 위해 다른 모델을 호출하지 않습니다. 즉, API 키도, 네트워크도, 결정을 위한 모델 호출도 필요하지 않습니다. 사용자는 점수와 권장 사항을 받게 되며, 이를 어떻게 활용할지는 사용자의 결정에 달려 있습니다.
저렴한 프롬프트는 로컬에 머물고 어려운 프롬프트는 비싼 모델로 전달되므로, "이것을 요약해줘" 또는 "오타를 수정해줘"와 같은 작업에 최고 등급의 비용을 지불하는 일을 멈출 수 있습니다.
비교 분석
대부분의 라우터(router)는 모델을 호출하여 결정합니다. 즉, 학습된 분류기(classifier), LLM 판사(LLM judge), 또는 호스팅된 API를 사용합니다. 이는 비용을 절감하기 위해 설계된 바로 그 단계에 지연 시간(latency), 비용, 그리고 무작위성(randomness)을 추가합니다. 반면 Wayfinder는 대신 구조와 표현 방식을 읽기 때문에, 결정 비용이 들지 않으며 매번 동일한 결과를 보장합니다.
| 라우터 (router) | 결정 방식 | 모델 호출 여부? | 셀프 호스팅 (self-host) | 보정 (calibrate) |
|---|---|---|---|---|
| Wayfinder | 결정론적 구조 점수 (deterministic structural score) | 아니요 | 예 | 예 |
| ... |
마지막 두 행의 게이트웨이(gateways)(OpenRouter, Bifrost, LiteLLM)는 다른 질문에 답합니다. 즉, 가격, 가용성 및 장애 조치(failover)를 기준으로 *어떤 제공업체(provider)*가 호출을 처리할 것인가에 대한 질문입니다. Wayfinder는 프롬프트가 어떤 티어(tier)에 적합한가에 답합니다. 즉, 난이도에 따라 오프라인에서 결정되는 저렴한 모델 대 비싼 모델의 선택입니다. 이 두 가지는 상호 보완적입니다. Wayfinder를 실행하여 저렴한 모델 대 비싼 모델을 결정하고, 그 아래에서 게이트웨이를 실행하여 제공업체에 도달하십시오.
Wayfinder는 최고의 정확도 수치를 쫓는 것이 아닙니다. Wayfinder가 제공하는 것은 모델 호출 없이 오프라인으로 실행할 수 있으며, 사용자의 트래픽에 맞춰 직접 튜닝할 수 있는 라우팅 결정 (routing decision)입니다. 기본적으로는 프롬프트의 구조 (structure)만을 점수화합니다. 어휘적 단서 (lexical cues; 증명, 수학, 제약 조건 등)를 읽을 수도 있지만, 이러한 기능은 기본적으로 꺼져 있습니다 (off by default). 독립적으로 작성된 프롬프트에 대한 이중 맹검 테스트 (double-blind test) 결과, 어휘적 단서의 성능 향상은 일반화되지 않는 것(보지 못한 어려운 프롬프트의 약 20%를 포착하며, 단순 단어 수 기준점 (word-count baseline)보다 성능이 낮음)으로 나타났기에, 이는 선택 사항 (opt-in)입니다. 사용자의 트래픽 어휘에 맞춰 보정 (calibrate)한 경우에만 해당 가중치를 높이십시오. 난이도가 순수하게 의미론적 (semantic)인 프롬프트(미묘한 코드 스니펫, 평범해 보이는 "100번째 소수는 무엇인가요?" 등)는 구조적 특징이 없으며, 이 경우 의미론적 라우터 (semantic router)가 더 우세할 것입니다. 맹검 테스트에서 입증된 신뢰할 수 있는 부분은 바로 모델 호출 없이 수행되는 결정론적 (deterministic), 밀리초 미만 (sub-millisecond)의 오프라인 라우팅 결정입니다. 벤치마크 (benchmark) (make benchmark)는 정직한 기준점 (baselines) 및 완벽한 오라클 (perfect oracle)과 비교했을 때 어디에서 승리하고 어디에서 패배하는지를 보여줍니다. 등급이 매겨진 수치를 확인하려면 RouterBench 또는 RouterArena를 참조하십시오.
처음 접하시거나 검토 중이신가요? FAQ에서 명확한 답변을 제공합니다. 여기에는 성능이 떨어지는 지점(RouterBench의 짧지만 어려운 항목들에 대해서는 무작위 선택보다 나을 것이 없음)과 그럼에도 불구하고 왜 이를 실행해야 하는지에 대한 이유가 포함되어 있습니다.
데모 체험하기 (키 불필요)
API 키, 모델, 네트워크 연결 없이 라우팅 결정을 직접 확인할 수 있는 두 가지 방법이 있습니다.
터미널에서 — Wayfinder 팔레트 내에서 결정 우선 방식 (decision-first)의 채팅을 경험해 보세요. 터미널 채팅은 기본 설치 시 포함되어 있어 추가할 것이 없으며, uvx를 통해 설치 없이 바로 실행할 수도 있습니다:
uvx wayfinder-router chat --dry-run # 설치 불필요, 키 불필요
# 또는: pip install wayfinder-router && wayfinder-router chat
매 턴마다 라우팅된 위치(● LOCAL / ◆ CLOUD), 구조적 점수(structural score) 및 이유(/why), 그리고 항상 클라우드를 사용할 때 대비 누적 절감액(running savings)이 표시됩니다. /init은 채팅창을 벗어나지 않고 모델을 설정하며, /route · /local · /cloud는 턴을 강제하고, 대화는 세션 간에 유지됩니다 (/threads).
브라우저에서 — 실시간 임계값(threshold) 슬라이더가 포함된 웹 채팅 UI:
pip install "wayfinder-router[gateway]"
wayfinder-router webchat --dry-run
# http://127.0.0.1:8088/demo 가 열립니다
webchat은 serve(gateway 및 그 /demo 페이지; --no-open, --port, --host 0.0.0.0, --dry-run 지원)를 위한 가벼운 런처(launcher)이며, serve는 헤드리스(headless) 명령입니다. 두 인터페이스 모두 모든 메시지에 대해 라우팅 위치(로컬 vs 클라우드), 복잡도 점수(complexity score) 및 이유(기능별 상세 분석), 그리고 항상 클라우드를 사용할 때 대비 절감된 비용을 보여줍니다. 설정이 없으면 둘 다 결정 전용(decision-only) 모드로 동작합니다(웹의 경우 --dry-run, 터미널의 경우 프리뷰 모드). 따라서 별도의 설정 없이도 바로 테스트해 볼 수 있습니다. 실제 응답을 받으려면 wayfinder-router init을 실행하여 [gateway.models]를 구성한 후, wayfinder-router doctor를 실행하여 키가 정상적으로 해결되는지 확인하세요 — Quickstart를 참조하십시오.
모든 OpenAI 호환 API와 작동
Wayfinder는 각 호출을 OpenAI 스타일의 /chat/completions 엔드포인트(endpoint)로 전달합니다. 따라서 사용 중인 제공업체가 이를 지원한다면(대부분 지원합니다), 그대로 작동합니다. 하나의 티어(tier)는 하나의 base_url, 모델 이름, 그리고 요청 시 환경 변수에서 읽어온 키로 구성됩니다. SDK나 제공업체별 코드가 필요하지 않습니다. 무료 로컬 모델을 호스팅된 모델과 결합하거나, 두 개의 클라우드 티어를 실행할 수 있습니다.
<sub…plus Groq, Together, OpenRouter, Fireworks, DeepSeek, 그리고 로컬 서버
(vLLM, LM Studio, llama.cpp) — <strong>+ Bearer 키를 사용하는 모든 OpenAI 호환 엔드포인트</strong></sub>
Quickstart
Wayfinder를 모델 앞에 배치하세요. 귀하의 앱은 계속해서 OpenAI API를 사용하면 되며, 단지 base_url 하나만 변경하면 됩니다.
-
설정을 구성(Scaffold)합니다 —
init명령은 시작용wayfinder-router.toml(키가 필요 없는 로컬 Ollama → Anthropic 클라우드 형태)과.env.example파일을 생성한 후, 귀하의 키를 확인합니다:pip install "wayfinder-router[gateway]" wayfinder-router init # 시작 설정 (하이브리드 프리셋) wayfinder-router init --preset openai # 두 가지 OpenAI 티어 (gpt-4o-mini → gpt-4o)
...
또는 `wayfinder-router.toml`에 두 모델을 직접 작성할 수 있습니다:
```toml
[routing]
threshold = 0.5 # 임계값 미만 -> 로컬, 임계값 이상 -> 클라우드
...
Wayfinder는 비밀 정보를 절대 저장하지 않습니다. 모델이 환경 변수(api_key_env)를 지정하면, 요청 시점에 귀하의 환경(environment)에서 키를 읽어옵니다. 별도로 "설치"할 것은 없으며, 변수를 export하기만 하면 됩니다. 셸(shell)에 원시 키(raw key)를 직접 붙여넣는 것을 피하고 싶으신가요? 선택 사항인 api_key_cmd를 추가하면 Wayfinder가 시작 시점에 귀하의 비밀 저장소(secret store)로부터 해당 변수를 채워줍니다 — op read … (1Password), security … (macOS Keychain), secret-tool … (Linux), pass/gopass, vault kv get …, aws secretsmanager get-secret-value …, bw, doppler, gcloud secrets … 또는 비밀 정보를 출력하는 모든 명령어를 사용할 수 있습니다. 키는 메모리에만 유지되며, 여전히 디스크에는 절대 기록되지 않습니다. wayfinder-router doctor는 이러한 도구 중 귀하가 무엇을 설치했는지 감지하여 정확한 명령줄을 제안합니다.
-
키를 설정한 다음 게이트웨이(gateway)를 실행합니다.
doctor는 시작하기 전에 설정을 재확인하고 각 모델의 키가 해결되는지(✓ set/✗ not set) 확인합니다:export ANTHROPIC_API_KEY=sk-... # 또는 설정에 따라 OPENAI_API_KEY wayfinder-router doctor # 모델별 ✓/✗ 확인 — 각 키가 설정되었는가? wayfinder-router serve --port 8088 -
기존 클라이언트를 해당 게이트웨이로 지정합니다. 코드 변경은 필요 없습니다:
client = openai.OpenAI(base_url="http://localhost:8088/v1", api_key="unused") client.chat.completions.create(model="auto", messages=[{"role": "user", "content": "..."}])
쉬운 프롬프트는 로컬(local)로, 어려운 프롬프트는 클라우드(cloud)로 전송되며, 모든 응답에는 어디로 라우팅되었는지 확인할 수 있도록 x-wayfinder-router-model과 x-wayfinder-router-score가 포함됩니다. 특정 요청에 대해 티어(tier)를 강제하고 싶으신가요? model="local" 또는 "cloud" (prefer-local / prefer-hosted 포함)를 설정하거나, X-Wayfinder-Threshold 헤더를 사용하여 단일 호출의 임계값(cut)을 조정하거나, 채팅 메시지를 /local 또는 /cloud로 시작하면 됩니다 (단일 요청 제어하기 참조).
작동 여부 확인:
curl -s localhost:8088/healthz
# {"status":"ok","models":["cloud","local"]}
...
아직 백엔드(backend)가 없나요? wayfinder-router serve --dry-run을 실행하면 상위 서버(upstream)를 호출하는 대신 라우팅 결정 사항을 응답하므로, 실제 모델을 연결하기 전에 30초 만에 라우팅을 체감해 볼 수 있습니다.
설치 (Install)
| 명령 (command) | 제공 항목 |
|---|---|
pip install wayfinder-router | 스코어러 (scorer), CLI, Python API, 그리고 터미널 채팅 (chat); 스코어러/라이브러리 임포트는 의존성을 가볍게 유지합니다 |
| ... |
작동 원리 (How it works)
Wayfinder는 이미 사용 중인 어떤 OpenAI 호환 클라이언트(OpenAI-compatible client) 뒤에 위치합니다. 해당 클라이언트의 base_url을 게이트웨이(gateway)로 한 번 지정하기만 하면, 그 이후부터는 클라이언트 입장에서 보이지 않습니다. 동일한 클라이언트가 로컬로 라우팅되든 호스팅된 서버로 라우팅되든 요청을 처리합니다.
사용자 클라이언트 (chat app, IDE, agent, 또는 코드)
|
v
...
이에 따라 몇 가지 사항이 뒤따릅니다:
- 전면의 인터페이스는 여러분의 것입니다. 채팅 GUI (Open WebUI, LibreChat), 커스텀 엔드포인트를 사용하는 IDE 어시스턴트 (Cursor, Continue), 에이전트 프레임워크, 또는 OpenAI SDK를 사용하는 여러분만의 코드 등이 해당됩니다. 당장 채팅창이 필요하신가요? Open WebUI를 앞에 두고 게이트웨이를 가리키도록 설정하세요.
- 로컬(Local)과 호스팅(Hosted)은 앱이 아니라 백엔드입니다. 로컬 모델은 단순히 OpenAI의
/v1규격을 따르는 서버 (Ollama, LM Studio, vLLM, llama.cpp)일 뿐이며, 호스팅된 모델도 동일한 형태를 가집니다. 사용자는 UI를 전환할 필요가 없으며, 대개 어떤 모델이 답변했는지조차 알지 못합니다. - 점수는 계산되는 것이지, 제2의 의견을 묻는 것이 아닙니다. 모델에게 프롬프트가 얼마나 어려운지 묻는 방식은 느리고, 비결정론적(non-deterministic)이며, 모델 호출 여부를 결정하기 위해 또 다른 모델 호출 비용을 발생시킵니다. 대신 Wayfinder는 프롬프트를 스캔합니다. 구조(길이, 헤딩, 단계, 링크, 코드, 표)와 문구 내의 난이도 단서(추론 용어, 수학 기호, 제약 조건)를
0.0-1.0값으로 변환하여 여러분의 임계값(threshold)과 비교합니다. 동일한 프롬프트, 동일한 임계값에는 동일한 결과가 나옵니다. 이는 난이도에 대한 대리 지표(proxy)이지 판결이 아니므로, 임계값은 여러분이 직접 조정할 수 있습니다.
키(Keys)는 요청 시점에 환경 변수(environment)에서 읽히며, 설정 파일이나 점수가 매겨진 경로에는 절대 닿지 않습니다.
CLI에서 프롬프트 점수 매기기
echo "Summarise this paragraph in one sentence." | wayfinder-router route -
Recommended Model: local
Complexity Score: 0.00 (mode: tiered)
...
머신 소비자(machine consumers, 즉 에이전트가 이를 읽고 자신의 모델로 라우팅하는 경우)를 위해 --json을 추가하세요:
{
"schema_version": "3",
"score": 0.66,
...
라우팅 설정하기
Wayfinder는 실행 위치에서 상위 디렉토리로 탐색하며 wayfinder-router.toml 파일을 읽습니다. 세 가지 모드가 있으며, 우선순위 순서(classifier > tiers > threshold)에 따라 적용됩니다. 스칼라 점수(scalar-score)인 weights는 이 중 어느 모드에도 적용됩니다.
Binary(기본값)는 단일 절단 지점(single cut)을 가집니다:
[routing]
threshold = 0.6
weights = { word_count = 4.0, list_item_count = 2.5 }
AI 자동 생성 콘텐츠
본 콘텐츠는 HN AI Posts의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기