Wayfinder Router: deterministic routing of queries between local and hosted LLM

TL;DR Highlight

프롬프트의 복잡도를 모델 호출 없이 오프라인으로 점수화해서 간단한 쿼리는 로컬 모델로, 어려운 쿼리는 유료 모델로 자동 라우팅하는 CLI 도구다. LLM 비용을 줄이면서도 응답 품질을 유지하고 싶은 개발자에게 유용하다.

Who Should Read

로컬 LLM(Ollama 등)과 GPT-4/Claude 같은 유료 API를 함께 쓰면서 비용을 줄이고 싶은 백엔드 개발자나 AI 애플리케이션 개발자. OpenAI-compatible API를 이미 쓰고 있다면 별도 코드 변경 없이 바로 붙일 수 있다.

Core Mechanics

Wayfinder는 프롬프트의 복잡도를 0.0~1.0 사이 점수로 매겨서 간단한 요청은 로컬/소형 모델로, 어려운 요청은 대형 유료 모델로 라우팅한다. '오타 수정해줘' 같은 쉬운 쿼리에 GPT-4 비용을 낭비하지 않는 게 핵심 목표다.
복잡도 점수는 완전히 오프라인으로, 모델 호출 없이 계산한다. 프롬프트의 구조(길이, 헤딩, 리스트, 코드 여부)와 표현(수학 증명, 하드 제약 조건 등)을 규칙 기반으로 분석하기 때문에 API 키도 네트워크도 필요 없다.
라우팅 결정 자체가 서브밀리초(sub-millisecond) 수준으로 빠르고 완전히 결정적(deterministic)이다. 같은 프롬프트를 넣으면 항상 같은 결과가 나오고, 라우팅 단계에서 추가 비용이 전혀 발생하지 않는다.
RouteLLM처럼 학습된 분류기를 쓰거나, NotDiamond/Martian처럼 호스팅된 API를 호출해서 라우팅을 결정하는 다른 라우터들과 달리, Wayfinder는 모델 호출이 없어서 라우팅 단계의 레이턴시와 비용이 0이다.
2티어(로컬/클라우드) 구성뿐 아니라 N티어 사다리 방식으로도 구성할 수 있고, RouteLLM 같은 다른 모델 라우터를 뒤에 붙여서 조합하는 것도 가능하다.
OpenAI-compatible 클라이언트 뒤에 프록시 형태로 배치되기 때문에 기존 코드를 바꾸지 않아도 된다. Docker와 docker-compose 설정 예시도 제공하고 있어서 셀프호스팅이 쉽다.
자체 데이터로 캘리브레이션(복잡도 임계값 조정)이 가능하다. 벤치마크 결과도 제공하고, 어떻게 점수를 매기는지 EXPLAINER.md에 상세히 설명되어 있다.

Evidence

컨텍스트 유지 문제가 가장 큰 실용적 한계로 지적됐다. 한 쿼리는 로컬 모델로, 다음 쿼리는 GPT-4로 보내면 두 모델이 서로 이전 대화 맥락을 모르는 상황이 생기는데, 이걸 어떻게 해결할지에 대한 답이 없다는 지적이 여러 댓글에서 나왔다. 결국 대화형 세션이 아닌 일회성(one-off) 프롬프트에만 실용적이라는 의견이다.
실제로 에이전틱 코딩 환경에서 라우팅을 해봤더니 문제가 생겼다는 경험담도 있었다. 모델을 중간에 바꾸면 이전 모델이 했던 작업의 맥락을 새 모델이 모르기 때문에 리그레션이 발생하거나 환각이 늘어난다는 것. 하네스(harness, AI 코딩 도구의 실행 환경)가 내부적으로 다양한 보상 전략을 쓰는데 동적 라우팅이 이를 방해한다는 구체적인 문제도 언급됐다.
'오타 수정' 같은 간단한 쿼리는 원래 토큰 수도 적어서 비용 절감 효과가 미미하다는 반론이 나왔다. 정작 비용이 많이 드는 건 복잡한 장문 쿼리인데, 그건 어차피 비싼 모델로 보내야 하니 실질적인 절감 효과에 의문을 제기하는 시각이었다.
유사한 로컬/클라우드 라우팅 도구를 별도로 개발 중이라는 댓글도 달렸다(github.com/try-works/role-model). 이 분야에 대한 커뮤니티 관심이 높다는 방증이고, 여러 접근법이 동시에 시도되고 있는 상황이다.
장기적으로는 OS 레벨의 LLM 라우팅 인프라가 필요하다는 흥미로운 비전도 제시됐다. 모바일 데이터처럼 AI 추론을 인프라로 보고, 앱마다 따로 과금하는 게 아니라 OS가 로컬/클라우드 라우팅을 통합 관리해야 한다는 아이디어다.

How to Apply

Ollama로 로컬 모델(예: llama3)을 돌리면서 GPT-4 API도 함께 쓰는 환경이라면, Wayfinder를 두 모델 사이에 프록시로 놓고 복잡도 임계값을 설정하면 된다. 단순 요약, 오타 수정, 짧은 번역은 자동으로 로컬로 가고 복잡한 코드 리뷰나 추론 작업만 GPT-4로 가도록 분리할 수 있다.
대화 맥락이 필요 없는 일회성 쿼리가 많은 배치 처리 파이프라인(예: 문서 분류, 요약 자동화)에 적용하면 가장 효과적이다. 각 문서마다 독립적으로 라우팅되므로 컨텍스트 단절 문제가 없고, 문서 복잡도에 따라 비용을 자동으로 최적화할 수 있다.
자체 프롬프트 데이터셋이 있다면 benchmark 기능을 써서 실제 라우팅 정확도를 측정하고, decisions 디렉토리의 캘리브레이션 설정으로 복잡도 임계값을 튜닝하면 된다. 기본 규칙 기반 점수가 자신의 도메인과 잘 맞는지 먼저 확인하는 게 중요하다.
Docker로 빠르게 테스트하고 싶다면 레포의 docker-compose.example.yml을 복사해서 로컬 모델 엔드포인트와 OpenAI API 키만 넣으면 바로 실행할 수 있다. OpenAI-compatible 클라이언트를 쓰는 기존 코드는 엔드포인트 URL만 Wayfinder로 바꾸면 된다.

Terminology

deterministic routing같은 입력에 항상 같은 출력이 나오는 라우팅 방식. 확률적이지 않아서 결과를 예측하고 디버깅하기 쉽다.

RouteLLMStanford에서 만든 LLM 라우터로, 사용자 선호 데이터로 학습한 분류기가 쿼리를 어느 모델로 보낼지 결정한다. 학습이 필요하고 모델 호출 비용이 발생한다.

하네스(harness)AI 코딩 도구(Cursor, Copilot 등)가 LLM과 상호작용할 때 컨텍스트 관리, 도구 호출, 에러 처리 등을 담당하는 실행 환경 전체를 가리키는 말.

OpenAI-compatibleOpenAI의 API 형식(/v1/chat/completions 등)을 그대로 지원하는 것. 이 형식을 지원하면 OpenAI 클라이언트 라이브러리를 코드 변경 없이 그대로 쓸 수 있다.

N-tier ladder2단계(쉬움/어려움)가 아니라 복잡도 구간을 여러 단계로 나눠서 소형→중형→대형 모델 순으로 단계적으로 라우팅하는 구성 방식.

캘리브레이션(calibration)모델이나 시스템의 판단 기준을 자신의 실제 데이터에 맞게 조정하는 작업. 여기서는 '이 점수 이상이면 어려운 쿼리로 본다'는 임계값을 내 상황에 맞게 튜닝하는 것.