Cost & Spend Tracking (한국어)

비용의 의미와 그렇지 않은 것

OmniRoute는 토큰 수에 모델의 요금 단가를 곱하여 모든 완료 요청에 요청별 USD 비용을 할당합니다. 이 수치는 비용 대시보드, omniroute cost / omniroute usage CLI, CSV/JSON 내보내기, API 키별 예산에 사용됩니다.

대시보드의 “비용”은 청구 금액이 아니라 절감액 추적기입니다. OmniRoute는 사용자에게 비용을 청구하지 않습니다. 사용자가 이미 연결한 제공업체(자체 구독, 무료 등급 및 API 키)로 요청을 라우팅할 뿐입니다. 무료 모델에서만 누적된 “$290 총비용”은 유료 API에 대략 $290를 지불하지 않았다는 의미입니다. 이 수치는 동일한 트래픽을 표준 정가로 처리했다면 발생했을 비용의 _추정치_이므로, 사용량이 어디에 집중되는지와 더 저렴하거나 무료인 제공업체로 라우팅하여 얼마나 절약하고 있는지 확인할 수 있습니다.

이러한 설명은 프로젝트 README에도 직접 명시되어 있습니다 (“대시보드의 ’비용’은 청구 금액이 아니라 절감액 추적기입니다”).

이 수치는 추정치이므로 다음 사항이 적용됩니다.

• 각 모델에 대해 OmniRoute가 보유한 가격표에 따라 달라집니다. 가격 정보가 없는 모델은 비용에 0만큼 기여합니다(탐색기에서 “레거시 / 무료” 행으로 표시됨).
• 무료 등급과 구독을 통한 트래픽에도 추정 비용이 계속 누적됩니다. 이는 지불해야 할 금액이 아니라 절약 중인 금액입니다.

---

비용 추정 방식

가격 정보 출처

비용은 다음 우선순위에 따라 결정되는 가격표에서 가져옵니다 (src/lib/pricingSync.ts):

1. 사용자 재정의 — 대시보드 또는 PATCH /api/pricing을 통해 설정한 가격입니다.
2. 동기화된 외부 가격 정보 — 동기화가 활성화된 경우 LiteLLM의 공개 model_prices_and_context_window.json에서 가져옵니다(사용자의 재정의 값을 덮어쓰지 않도록 별도의 pricing_synced 네임스페이스에 저장됨).
3. 하드코딩된 기본값 — OmniRoute에 포함되어 제공됩니다.

외부 가격 정보 동기화는 선택 사항이며 기본적으로 비활성화되어 있습니다. 관련 환경 변수는 .env.example을 참조하세요.

환경 변수	기본값	용도
PRICING_SYNC_ENABLED	false	시작 시 백그라운드 LiteLLM 가격 정보 동기화를 활성화합니다.
PRICING_SYNC_INTERVAL	86400	동기화 간격(초 단위, 기본값은 매일)입니다.
PRICING_SYNC_SOURCES	litellm	쉼표로 구분된 소스 목록입니다(현재는 litellm만 지원됨).

비용 계산 공식

비용은 src/lib/usage/costCalculator.ts의 (computeCostFromPricing / calculateCost)를 사용하여 토큰 수와 백만 토큰당 요금을 기준으로 요청별로 계산됩니다.

• 입력 토큰(캐시 읽기 및 캐시 생성 토큰 제외) × input 요금.
• 캐시 읽기 토큰 × cached 요금(없으면 입력 요금 사용).
• 캐시 생성 토큰 × cache_creation 요금(없으면 입력 요금 사용).
• 출력 토큰 × output 요금.
• 추론 토큰 × reasoning 요금(없으면 출력 요금 사용).

모든 요금은 토큰 1,000,000개당 USD로 해석됩니다. Codex “fast”/“priority” 또는 “flex” 서비스 등급에는 비용 배율(getCodexFastCostMultiplier)이 적용됩니다. 예를 들어 flex는 토큰 비용에 50% 할인이 적용되며, 대시보드에서 flex 절감액으로 표시됩니다.

먼저 모델 이름을 정규화하여(openai/ 또는 accounts/fireworks/models/ 같은 제공업체 경로 접두사 제거) 과거 행도 계속 가격 정보와 일치하도록 합니다.

지출 기록 방식

• 요청별 비용은 응답 후 계산되고 파이어 앤 포겟 방식으로 기록되므로 클라이언트에 지연 시간을 추가하지 않습니다. 공유 할당량 소비는 src/lib/quota/spendRecorder.ts를 통해 다음 이벤트 루프 틱에 예약됩니다.

• API 키 지출은 SpendBatchWriter에 의해 버퍼링되고 배치 단위로 플러시됩니다(기본 플러시 간격 60초, 버퍼 항목 1,000개). 다음 변수를 통해 조정할 수 있습니다.

  환경 변수	기본값	용도
  OMNIROUTE_SPEND_FLUSH_INTERVAL_MS	60000	플러시 간격(밀리초)입니다.
  OMNIROUTE_SPEND_MAX_BUFFER_SIZE	1000	플러시 전까지 버퍼링할 최대 항목 수입니다.

대시보드의 비용 수치는 저장된 행별 금액에서 읽어오는 것이 아니라, 분석 엔드포인트가 실행될 때마다 토큰 수와 현재 가격표를 사용하여 즉석에서 다시 계산됩니다. 따라서 잘못된 가격을 수정하고 다시 동기화하면 과거 비용 추정치도 소급하여 업데이트됩니다.

---

대시보드: 비용 페이지

비용 페이지는 /dashboard/costs (src/app/(dashboard)/dashboard/costs/)에 있습니다. 기본 화면은 비용 개요 탭 (src/app/(dashboard)/dashboard/costs/CostOverviewTab.tsx)이며, GET /api/usage/analytics에서 모든 데이터를 불러옵니다.

표시되는 내용:

• 지출 타일 — 오늘(1일), 7일, 30일 및 선택한 기간의 예상 지출입니다. 기간 선택기: 7d, 30d, 90d, all.
• 주요 지표 — 기간 내 요청 수, 활성 제공자 수, 활성 모델 수, 요청당 평균 비용입니다.
• 비용 탐색기 — 제공자, 모델, API 키, 계정 또는 서비스 티어별로 그룹화된 정렬 및 필터링 가능한 테이블로, 비용, 요청 수, 토큰 수, 요청당 평균 비용 및 전체 대비 비율(%)을 표시합니다.
• 토큰 사용량 — 전체 / 입력 / 출력 토큰 및 입력:출력 비율입니다.
• 라우팅 효율성 — 폴백 횟수, 폴백 비율 및 요청 모델 적용률입니다.
• 월간 예측 — 최근 일평균을 기반으로 월말 지출을 예측합니다.
• 기간 비교 — 기간의 전반부와 후반부 사이의 변화율(%)입니다.
• 차트 — 일별 비용 추이, 제공자 비중(원형), 상위 제공자, 상위 모델, API 키별 비용, 계정별 비용, 주간 사용 패턴 및 활동 히트맵입니다.
• 내보내기 — 현재 기간의 데이터를 CSV 또는 JSON으로 다운로드합니다(비용 데이터가 0이 아닌 경우 버튼이 표시됨).

가격이 책정된 트래픽이 없는 경우 절감액 추적기 모델을 반영하여 행에 $0 대신 “레거시 / 무료” 레이블이 표시됩니다.

관련 비용 하위 페이지

비용 영역에는 다음 페이지도 있습니다(모두 /dashboard/costs/ 아래에 위치):

• 가격 (/dashboard/costs/pricing) — 모델별 가격을 확인하고 재정의합니다(공유 가격 탭을 렌더링).
• 예산 (/dashboard/costs/budget) — 범위별 지출 한도를 설정합니다(공유 예산 탭을 렌더링).
• 할당량 공유 (/dashboard/costs/quota-share) — 공유 할당량 풀 및 소진율 보기입니다.

---

API 엔드포인트

별도 언급이 없는 한, 다음 엔드포인트는 모두 관리 인증(requireManagementAuth를 통한 루프백/JWT)이 필요합니다.

사용량 및 비용 분석

메서드	엔드포인트	용도
GET	/api/usage/analytics	전체 비용/사용량 분석: 요약, 일별 추이, 제공자/모델/API 키/계정/티어별 데이터. 쿼리: range, startDate, endDate, apiKeyIds, presets.
GET	/api/usage/utilization	시간대별 제공자별 할당량 사용률. 쿼리: range (1h/24h/7d/30d), provider.
GET	/api/usage/history	원시 사용량 기록 행.
GET	/api/usage/call-logs	요청별 호출 로그(모델, 토큰, 비용, 지연 시간, 상태).
GET	/api/usage/quota	제공자 할당량 상태.
GET	/api/usage/proxy-logs	프록시 요청 로그.

예산

메서드	엔드포인트	용도
GET	/api/usage/budget	API 키 하나에 대한 비용 요약 및 예산 확인(apiKeyId 쿼리 매개변수 필수).
POST	/api/usage/budget	API 키의 일간/주간/월간 USD 한도 및 경고 임계값 설정.
GET	/api/usage/budget/bulk	여러 API 키의 예산 요약 일괄 조회.

예산 API의 범위는 API 키(apiKeyId)별로 지정됩니다. GET /api/usage/budget에서 반환되는 한도에는 dailyLimitUsd, weeklyLimitUsd, monthlyLimitUsd, warningThreshold 및 누적 합계(totalCostToday, totalCostMonth, …)가 포함됩니다.

가격

메서드	엔드포인트	용도
GET	/api/pricing	현재 병합된 가격(사용자 + 동기화 + 기본값). 항목별 출처를 확인하려면 ?includeSources=1을 사용합니다.
PATCH	/api/pricing	{ provider: { model: { input, output, cached, … } } }의 가격을 재정의합니다.
DELETE	/api/pricing	가격을 기본값으로 재설정합니다(선택적으로 ?provider=&model=을 사용해 범위 지정).
GET	/api/pricing/defaults	100만 개당 기본 폴백 요율을 표시합니다.
GET	/api/pricing/models	모델을 키로 사용하는 가격 정보입니다.
POST	/api/pricing/sync	외부 소스(LiteLLM)에서 수동 동기화를 시작합니다.
GET	/api/pricing/sync	현재 동기화 상태입니다.
DELETE	/api/pricing/sync	동기화된 모든 가격 데이터를 삭제합니다.

기타 비용 관련 엔드포인트

메서드	엔드포인트	용도
GET	/api/free-tier/summary	무료 모델의 총 토큰, 이번 달 사용량 및 남은 무료 할당량입니다.
GET	/api/quota/pools/[id]/usage	공유 할당량 풀의 사용량입니다.

---

CLI

OmniRoute의 CLI는 비용, 사용량 및 가격 명령어를 제공합니다(bin/cli/commands/registry.mjs에 등록됨).

omniroute cost

/api/usage/analytics에서 집계된 비용 보고서입니다.

omniroute cost                          # 최근 30일, 제공업체별 그룹화
omniroute cost --period 7d              # 최근 7일
omniroute cost --group-by model         # provider | model | combo | api-key | day 기준으로 그룹화
omniroute cost --since 2026-06-01 --until 2026-06-13
omniroute cost --api-key <key> --limit 50

열: 그룹, 요청 수, 입력/출력 토큰, 비용(USD), 전체 대비 비율(%). 마지막에는 총합 행이 출력됩니다(--quiet 또는 --output json을 사용하면 출력되지 않음).

omniroute usage

omniroute usage analytics --period 30d [--provider <id>]   # 제공업체별 비용 요약
omniroute usage logs [--limit 100] [--follow] [--api-key <k>] [--search <q>]
omniroute usage quota [--provider <id>] [--check]
omniroute usage utilization [--api-key <k>]
omniroute usage history [--limit 100]
omniroute usage proxy-logs [--limit 100]

# 예산
omniroute usage budget list
omniroute usage budget get [scope]
omniroute usage budget set <amount> [--scope global] [--period monthly]
omniroute usage budget reset [scope]

omniroute pricing

omniroute pricing list [--provider <p>] [--model &lt;m&gt;] [--limit 200]
omniroute pricing get &lt;model&gt;
omniroute pricing sync [--provider <p>] [--force]   # POST /api/pricing/sync
omniroute pricing diff [--model &lt;m&gt;]
omniroute pricing defaults show
omniroute pricing defaults set [--input <p>] [--output <p>] [--cache-read <p>] [--cache-write <p>]

pricing defaults show는 GET /api/pricing/defaults를 조회합니다. 대신 개별 모델의 가격을 편집하려면 Pricing 대시보드 페이지 또는 PATCH /api/pricing을 사용하세요.

---

문제 해결

• 모든 비용이 $0 / “Legacy / Free”로 표시됩니다. 사용 중인 모델에 가격 항목이 없습니다. 외부 동기화를 활성화하고(PRICING_SYNC_ENABLED=true) omniroute pricing sync를 실행하거나, Pricing 페이지 / PATCH /api/pricing을 통해 가격을 수동으로 설정하세요.
• 과거 모델의 가격이 잘못 책정되었습니다. 가격을 수정하세요(재정의 또는 재동기화). 비용은 분석 데이터를 조회할 때마다 토큰 수를 기준으로 다시 계산되므로 예상치가 소급하여 업데이트됩니다.
• 지출액이 실시간보다 늦게 반영됩니다. 키별 지출액은 일괄 처리됩니다. 더 최신 수치가 필요하면 OMNIROUTE_SPEND_FLUSH_INTERVAL_MS 값을 낮추세요.

---

더 광범위한 대시보드에서 이 기능이 어디에 해당하는지 알아보려면 사용자 가이드와 기능 갤러리를 참조하세요.

---

OmniRoute 소스 코드 (a58000c7685f)