스마트 라우팅

celon/auto — 난이도 기반 자동 라우팅

model: "celon/auto"로 요청하면 규칙 기반 분류기(LLM 호출 없음, CPU <5ms)가 난이도 점수를 0–1 범위로 산출합니다. 점수는 아래 특징의 가중합입니다.

점수 → 티어 매핑 (기본 balanced 다이얼 기준): score ≥ 0.62 → Tier 1, score ≥ 0.30 → Tier 2, 그 미만은 Tier 3입니다. 산출된 점수는 응답 메타의 classifier_score로 확인할 수 있습니다.

인텐트 다이얼

같은 분류기라도 워크로드마다 원하는 트레이드오프가 다릅니다. celon.dial(요청 단위) 또는 키의 라우팅 정책(routing.dial)으로 4가지 프리셋 중 하나를 고릅니다. 적용된 다이얼은 응답 메타 dial과 x-celon-dial 헤더로 확인합니다.

목적 라우터 — 목적은 모델 이름으로

다이얼을 직접 고르는 대신, 목적 라우터 id를 모델 문자열로 지정할 수 있습니다. 코딩 워크로드에는 celon/code, 품질이 무조건 중요하면 celon/quality(항상 프론티어), 속도가 생명이면 celon/nitro(실측 처리량 랭킹), 비용이 최우선이면 celon/floor(실시간 최저가 랭킹) — 전부 가상 모델 id라 어떤 OpenAI SDK에서도 model 문자열 하나로 적용됩니다.

절감 목표 라우팅

celon.anchor(품질 상한)와 celon.savings_target(목표 절감률, 0–0.8 범위)을 함께 지정하면, 라우터가 목표 절감률에 수렴하도록 하향 라우팅 강도를 자동 보정합니다. 예: 0.4는 “항상 앵커만 썼을 때 대비 40% 절감”이 목표입니다.

{
  "model": "celon/auto",
  "messages": [{ "role": "user", "content": "이번 분기 지표를 요약해줘" }],
  "celon": {
    "anchor": "anthropic/claude-fable-5",
    "savings_target": 0.4
  }
}

피드백 루프는 사용 원장(usage ledger) 기반입니다 — 키의 실제 과금 기록에서 실현 절감률(앵커 baseline 대비)을 집계해, 목표에 못 미치면 하향 라우팅을 더 공격적으로, 목표를 넘어서면 더 보수적으로 되돌립니다. 추정치가 아니라 원장에 남은 실현 값이 기준이므로 캐시 히트·폴백 비용까지 그대로 반영됩니다.

4단계 제약 인지 파이프라인

celon/auto의 라우팅 결정은 난이도 점수 하나가 아니라, 요청의 제약을 순서대로 반영하는 4단계 파이프라인으로 이뤄집니다. 각 단계의 판정은 응답 메타 pipeline 배열에 트레이스로 남습니다.

3단계 티어

티어별 모델은 fallback 순서대로 나열됩니다 — 첫 모델이 실패하면 다음 모델로 자동 전환됩니다. 가격은 $/1M 토큰 (input / output) 기준입니다.

동적 가격 추적

위 가격표는 스냅샷입니다. 실제 과금 단가는 LiteLLM·OpenRouter 가격 피드에서 주기적으로 동기화되며(기본 6시간), 변경 이력은 model_pricing 이력 테이블에 기록됩니다. 현재 단가는 GET /admin/pricing으로 조회하고, POST /admin/pricing/refresh로 즉시 재동기화하거나, PUT /admin/pricing/override로 특정 모델의 단가를 수동 고정할 수 있습니다.

명시적 모델 지정

카탈로그 id는 vendor/model 형식입니다 — 예: anthropic/claude-fable-5, openai/gpt-5.2, deepseek/deepseek-v3.2. 전체 목록은 GET /v1/models로 조회합니다. 모델을 명시하면 분류기를 거치지 않고 그대로 전달되며(classifier_score: null), 카탈로그에 없는 id는 404 model_not_found로 거부됩니다. 명시 모델 요청에서는 celon.tier 힌트가 무시됩니다.

요청별 celon 옵션

요청 본문의 celon 객체로 라우팅·캐시 동작을 요청 단위로 제어할 수 있습니다. 모든 필드는 선택 사항입니다.

{
  "model": "celon/auto",
  "messages": [{ "role": "user", "content": "핵심 API를 설계해줘" }],
  "celon": {
    "dial": "strict-quality",
    "anchor": "anthropic/claude-fable-5",
    "savings_target": 0.3,
    "session_id": "conv_8f2a91",
    "context_compression": true,
    "no_cache": true,
    "fallbacks": ["meta-llama/llama-4-maverick", "deepseek/deepseek-v3.2"]
  }
}

Fallback 체인의 동작

• 재시도 조건 — 업스트림이 429 또는 5xx를 반환하거나 네트워크/타임아웃 오류가 나면 다음 후보로 자동 전환합니다. 그 외 4xx는 즉시 실패합니다.
• 전환 순서 — 같은 모델의 대체 프로바이더(altProviders, 예: DeepInfra → Novita)를 먼저 시도한 뒤, 다음 후보 모델로 넘어갑니다.
• 추적 — 시도한 경로는 응답 메타의 attempts 배열과 x-celon-attempts 헤더에 기록됩니다.
• 전부 실패 시 — 502 upstream_unavailable로 응답합니다.
• 예산 다운그레이드 — 키 예산 초과 + downgrade 정책이면 celon/auto 요청이 Tier 3로 강제됩니다. 거버넌스 참조.

응답 메타데이터

모든 응답에는 라우팅 결과가 본문 celon 필드와 x-celon-* 헤더로 붙습니다.

{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "model": "meta-llama/llama-4-maverick",
  "choices": [ … ],
  "usage": { "prompt_tokens": 21, "completion_tokens": 96, "total_tokens": 117 },
  "celon": {
    "model": "meta-llama/llama-4-maverick",
    "provider": "deepinfra",
    "tier": 2,
    "classifier_score": 0.41,
    "cache_hit": null,
    "cost_usd": 0.000122,
    "saved_usd": 0.003886,
    "latency_ms": 842,
    "pii_masked": 0,
    "attempts": [],
    "dial": "balanced",
    "sticky": true,
    "pipeline": ["modality:pass", "context:fit", "sticky:hit", "difficulty:0.41→tier2"],
    "guardrails": { "mode": "mask", "findings": 0, "blocked": false }
  }
}

스트리밍에서는 비용을 미리 알 수 없으므로 시작 시 x-celon-model · x-celon-tier · x-celon-dial · x-celon-sticky · x-celon-attempts만 헤더로 나가고, 스트림의 마지막 데이터 청크(choices: [])에 usage와 celon 메타 전체가 담긴 뒤 data: [DONE]이 옵니다.