프로덕션 환경에서 LLM을 사용하는 모든 팀은 동일한 문제에 직면합니다. 모든 요청에 GPT-4가 필요한 것은 아니지만, 어떤 요청에 실제로 그것이 필요한지 미리 알 수 없다는 점입니다. "2+2는 무엇인가요?"라고 묻는 사용자와 "이 재귀적 async Rust 함수에서 버그를 찾아주세요"라고 묻는 사용자 모두 동일한 /v1/chat/completions 엔드포인트에 접속합니다. 두 요청 모두를 GPT-4o로 라우팅하면 산술 연산에 대해 100만 토큰당 15달러를 지불하게 됩니다. 반대로 두 요청 모두를 로컬 모델로 라우팅하면 복잡한 작업에서 품질이 무너집니다.

NeuralUCB Router가 이 문제를 해결합니다. 이는 NeuralUCB Multi-Armed Bandit (MAB) 알고리즘을 사용하여 92% 이상의 품질을 유지하면서 요청을 가장 저렴한 모델로 동적으로 라우팅하는 프로덕션 품질의 OpenAI 호환 API 프록시입니다. NEO를 사용하여 자율적으로 구축되었습니다.

문제 (The Problem)

단순한 해결책들은 모두 실패합니다:

항상 GPT-4o 사용: 10만 개의 쿼리에 대해 월 1,500달러가 소요되며, 그 중 대부분은 단순한 작업에 낭비됩니다.

항상 저렴한 모델 또는 로컬 모델 사용: 어려운 추론, 코드, 수학 작업에서 품질이 급격히 저하됩니다.

하드코딩된 if/else 규칙: 취약합니다. 모든 쿼리 유형을 열거할 수 없으며, 규칙이 적응하지 못합니다.

무작위 라우팅 (Random routing): 학습이 없습니다. 영구적으로 최적화되지 않은 상태로 남으며, 실제로 무엇이 효과적인지 무시합니다.

분류기 (Classifier) 미세 조정: 레이블이 지정된 데이터, 오프라인 학습, 별도의 배포, 수동 업데이트가 필요합니다.

근본적인 문제는 라우팅이 불확실성 하에서의 순차적 의사결정 문제 (Sequential decision problem)라는 점입니다. 각 쿼리는 서로 다르며, 적절한 모델은 부분적으로만 관찰할 수 있는 컨텍스트에 따라 달라지고, 사용 패턴이 변화함에 따라 지속적으로 학습해야 합니다.

해결책: NeuralUCB Bandit 라우팅 (The Solution: NeuralUCB Bandit Routing)

NeuralUCB Router는 LLM 선택을 광고 경매, 임상 시험, 추천 시스템에서 사용되는 것과 동일한 문제 유형인 멀티 암드 밴딧 (Multi-Armed Bandit, MAB) 문제로 정의합니다. 각 LLM은 하나의 "arm (팔)"이며, 각 요청은 하나의 "round (라운드)"입니다. 목표는 시간이 지남에 따라 누적 보상 (품질을 비용으로 나눈 값)을 최대화하는 것입니다.

분류기 (Classifier)는 "이 쿼리 → GPT-4 사용"과 같이 알려주는 라벨링된 학습 데이터가 필요합니다. 반면, 밴딧 (Bandit)은 모델을 시도하고 그 결과를 관찰함으로써 스스로 학습 신호를 생성합니다. 이는 사전 라벨링된 데이터셋 없이 실제 트래픽으로부터 온라인 (online) 방식으로 학습합니다.

각 들어오는 요청에 대해 NeuralUCB가 작동하는 방식:

1. 컨텍스트 특징 (context features) 추출
   [query_length, token_entropy, is_code, is_math,
    time_of_day, session_cost, recent_quality, ...]
...

UCB 보너스 (UCB bonus)가 핵심 통찰입니다. 많이 시도되지 않은 모델은 불확실성 (uncertainty)이 높으며, 이는 높은 탐색 보너스 (exploration bonus)를 의미하고, 모델의 실제 가치가 알려질 때까지 더 많은 선택을 받게 됩니다. 모델의 특성이 잘 파악되면 보너스는 줄어들고 MLP (Multi-Layer Perceptron) 예측이 지배적이 됩니다.

수렴 후 (~500개 요청 후) 발생하는 현상:

단순 사실 쿼리          →  로컬 Ollama/Llama3    (무료,   ~98%의 경우)
코드 생성               →  GPT-4o-mini            ($0.0006, ~87%의 경우)
복잡한 추론/디버깅      →  GPT-4o                 ($0.015,  ~71%의 경우)
...

결과: 항상 GPT-4o를 사용할 때와 비교하여 평균 품질 8.9/10을 유지하면서도 비용을 88% 절감했습니다.

비용 절감 (Cost Savings)

주요 기능 (Key Features)

• 동적 모델 라우팅 (Dynamic Model Routing): 컨텍스트를 기반으로 각 요청에 가장 적합한 모델을 자동으로 선택합니다.
• 비용 최적화 (Cost Optimization): 요청의 80%를 무료 또는 저렴한 모델로 라우팅하여 API 비용을 75% 이상 절감합니다.
• 품질 유지 (Quality Retention): 복잡한 작업에는 고가의 모델을 사용하여 92% 이상의 품질을 유지합니다.
• OpenAI 호환 (OpenAI-Compatible): OpenAI API (/v1/chat/completions, /v1/models)를 즉시 대체할 수 있습니다.
• 실시간 대시보드 (Real-time Dashboard): 자동 새로고침, 비용 절감 측정기, 라우팅 히트맵(heatmap)을 제공하는 Streamlit 대시보드입니다.
• 다중 백엔드 (Multiple Backends): Ollama (로컬), OpenAI, Anthropic 제공업체를 지원합니다.
• 감사 로그 (Audit Logging): 분석을 위해 CSV/Parquet 내보내기가 가능한 SQLite 감사 로그를 제공합니다.

아키텍처 (Architecture)

┌─────────────────────────────────────────────────────────────────┐
│                    NeuralUCB Router                             │
├─────────────────────────────────────────────────────────────────┤
...

빠른 시작 (Quick Start)

Docker 배포 (Docker Deployment)

# 리포지토리 클론
git clone https://github.com/dakshjain-1616/neuralucb-router.git
cd neuralucb-router
...

로컬 설치 (Local Installation)

# 의존성 설치
pip install -r requirements.txt

...

설정 (Configuration)

configs/example_config.yaml 파일을 수정하세요:

models:
  - name: llama3.2-1b
    provider: ollama
...

밴딧 수렴 (Bandit Convergence)

1,000개 요청에 대한 모델 선택 분포:

밴딧(Bandit)은 복잡한 작업의 품질을 유지하면서 요청의 80%를 무료 모델인 Llama3.2-1b로 라우팅하는 법을 학습합니다.

기술적 세부 사항 (Technical Details)

NeuralUCB 알고리즘 (NeuralUCB Algorithm)

• Architecture (아키텍처): 모델 Arm(arm)당 2-layer MLP (hidden=64, ReLU activation, Sigmoid output)
• UCB Formula (UCB 공식): UCB(model) = f(x; θ_m) + λ * sqrt(gᵀ Z⁻¹ g)
• f(x; θ_m): 모델 m에 대한 MLP 예측값
• g: θ_m에 대한 f의 Gradient (기울기)
• Z: Sherman-Morrison을 통해 업데이트되는 Covariance matrix (공분산 행렬)
• λ: Exploration weight (탐색 가중치)
• Updates (업데이트): Z⁻¹에 대한 Sherman-Morrison rank-1 updates (전체 역행렬 계산 시 O(n³) 대비 O(n²)의 복잡도)

Context Features (문맥 특징, 15차원)

• prompt_length: 정규화된 토큰 수
• task_type: 원-핫 인코딩 [code, math, creative, qa, chat, other]
• avg_token_length: 평균 토큰 길이
• has_system_prompt: 이진 플래그 (Binary flag)
• time_of_day: Sin/cos 인코딩
• latency_ema: 모델별 Exponential Moving Average (지수 이동 평균)

Reward Calculation (보상 계산)

두 가지 모드:

• Embedding Cosine Similarity (임베딩 코사인 유사도): sentence-transformers를 사용하여 응답을 참조값과 비교
• LLM-as-Judge: LLM을 사용하여 품질 점수 산출 (1-5 척도)

Reward (보상) = quality (품질) / cost_per_1k (1k당 비용, 정규화됨)

Testing (테스트)

# 모든 테스트 실행
pytest tests/ -v

...

모든 테스트는 LLM 호출을 Mock (모의) 처리합니다. 테스트를 위해 API 키는 필요하지 않습니다.

Dashboard Features (대시보드 기능)

Auto-refresh (자동 새로고침): 2초마다 업데이트
Cost Savings Meter (비용 절감 계측기): 누적 비용 추적
Model Performance Bar Chart (모델 성능 막대 그래프): 선택 사항 및 평균 보상
Routing Heatmap (라우팅 히트맵): 시간에 따른 라우팅 결정 시각화
Recent Decisions Table (최근 결정 테이블): 지표가 포함된 최근 20개의 라우팅 이벤트

API Endpoints (API 엔드포인트)

Project Structure (프로젝트 구조)

neuralucb-router/
├── router/bandit/
│   ├── neural_ucb.py     # NeuralUCB bandit 알고리즘
...

Export to Hugging Face (Hugging Face로 내보내기)

from hf_export.push_to_hub import export_to_hub

export_to_hub(
...

Comparison (비교)

NEO를 사용하여 이를 구축한 방법

이 프로젝트는 NEO를 사용하여 구축되었습니다. NEO는 AI 모델 평가 (evals), 프롬프트 최적화 (prompt optimization), 그리고 엔드 투 엔드 (end-to-end) AI 파이프라인 개발을 포함한 AI/ML 작업을 위해 코드를 작성하고 솔루션을 구축할 수 있는 완전 자율형 AI 엔지니어링 에이전트입니다.

요구 사항은 NeuralUCB Multi-Armed Bandit (MAB) 알고리즘을 사용하여 문맥 (context)에 따라 LLM 요청을 동적으로 라우팅함으로써, 품질을 유지하면서 비용을 절감하는 프로덕션 품질의 OpenAI 호환 API 프록시를 만드는 것이었습니다. NEO는 이 저장소의 파일들을 계획하고 생성했습니다: Bandit 알고리즘, 문맥 추출 (context extraction) 및 보상 계산 (reward calculation) 모듈, Ollama, OpenAI, Anthropic을 위한 세 가지 백엔드 통합, 미들웨어와 Pydantic 스키마를 포함한 FastAPI 프록시 서버, CSV 및 Parquet 내보내기 기능이 있는 SQLite 감사 로거 (audit logger), Streamlit 대시보드, 3종 테스트 세트 설정, HuggingFace 내보내기 도구, Docker 및 compose 파일, 그리고 설정 시스템입니다.

그 결과, 실제 트래픽으로부터 학습하고, 약 500개의 요청 후에 수렴하며, 요청의 80%를 무료 또는 저렴한 모델로 라우팅하고, 항상 GPT-4o를 사용할 때 발생하는 비용의 12%만으로 8.9/10의 품질을 제공하는 완전히 작동하는 지능형 라우터가 탄생했습니다.

NEO와 함께 이를 사용하는 방법

설정이 필요 없는 OpenAI 프록시로 바로 도입하여 즉시 비용을 절감하세요.
이 라우터는 완전히 OpenAI와 호환되는 /v1/chat/completions 엔드포인트를 노출하므로, OpenAI API를 가리키고 있는 기존의 어떤 애플리케이션이라도 베이스 URL (base URL)만 변경하면 즉시 지능적인 라우팅을 시작할 수 있습니다. 그 설정 한 줄 외에는 코드 변경이 전혀 필요하지 않습니다.

단 하나의 YAML 파일만 편집하여 자신만의 모델을 추가하세요.
Ollama, OpenAI 또는 Anthropic에서 지원하는 모든 제공자(provider)를 이름, 제공자, 기본 URL(base URL), 1K 토큰당 비용과 함께 configs/example_config.yaml에 추가할 수 있습니다. 밴딧(bandit)은 다음 시작 시 이를 인식하고 기존의 팔(arms)과 함께 자동으로 탐색(exploring)을 시작합니다.

감사 로그(audit log)를 사용하여 트래픽이 정확히 어떻게 라우팅되고 있는지 파악하세요.
모든 라우팅 결정은 전체 메트릭(metrics)과 함께 SQLite에 기록됩니다. /v1/router/audit 엔드포인트와 CSV/Parquet 내보내기 기능을 통해 팀은 이 데이터를 모든 분석 도구로 가져와 어떤 모델이 어떤 유형의 쿼리를 처리하고 있는지, 어떤 품질 점수(quality scores)를 생성하고 있는지, 그리고 비용 절감이 실제로 어디에서 발생하는지를 확인할 수 있습니다.

Streamlit 대시보드를 팀을 위한 실시간 비용 모니터링 레이어로 실행하세요.
대시보드는 2초마다 자동으로 새로고침되며 누적 비용 절감액, 모델 선택 분포, 그리고 메트릭이 포함된 최근 20개의 라우팅 결정을 보여줍니다. 이는 별도의 보고 도구를 구축하지 않고도 비기술적 이해관계자(non-technical stakeholders)에게 정보를 제공하는 데 유용합니다.

최종 참고 사항

대부분의 팀은 결국 두 가지 나쁜 균형 상태(bad equilibria) 중 하나에 빠지게 됩니다. 모든 요청에 대해 프런티어 모델(frontier model)에 너무 많은 비용을 지출하거나, 모든 상황에서 저렴한 모델의 저하된 품질을 수용하는 것입니다. NeuralUCB Router는 어떤 요청에 실제로 비싼 모델이 필요한지 학습하고, 그 외의 모든 요청은 이를 처리할 수 있는 가장 저렴한 옵션으로 라우팅함으로써 이 두 상태 사이의 균형을 잡습니다.

코드는 https://github.com/dakshjain-1616/neuralucb-router에서 확인할 수 있습니다.
모델은 HuggingFace의 https://huggingface.co/daksh-neo/neuralucb-router에 업로드되어 있습니다.
pip를 통해 설치하세요: pip install neuralucb-router
또한 VS Code extension 또는 Cursor를 사용하여 IDE에서 NEO로 빌드할 수 있습니다.
Claude Code와 함께 NEO MCP를 사용할 수 있습니다: https://heyneo.com/claude-code