커스텀 모델 비용 맵

커스텀 모델 비용 맵 (Custom Model Cost Map)

LiteLLM은 모델 비용 맵(각 모델을 토큰별 요율, 컨텍스트 한도, 기능에 매핑하는 JSON 파일)에서 모든 요청의 가격을 책정해요. 기본적으로 프록시는 시작 시 GitHub에서 최신 맵을 가져오므로, 새 모델의 가격은 LiteLLM을 업그레이드하지 않고도 도착해요. 배포에서 가격이 잘못되었거나 없으면(지역 가격 변형, 협상된 요율, 기본 맵이 아직 담지 못한 아주 새로운 티어) 두 가지 방법으로 고칠 수 있어요: 콘피그의 특정 배포에 가격을 재정의하거나, 전체 맵을 자체 호스팅 사본으로 교체.

출처: 문서

본문

제한된 교정에는 배포별 재정의를 선호하세요. 이는 명명한 배포만 바꾸고, 모든 업스트림 맵 업데이트를 견디며, 파일 호스팅이 필요 없고, 폴백 실패 모드도 없어요. 교정이 너무 많은 모델에 걸쳐 배포별 콘피그가 유지 불가능해질 때만 전체 커스텀 맵을 사용하세요.

옵션 1: 배포별 가격 재정의 (권장) (Option 1: per-deployment pricing overrides)

비용 맵의 어떤 가격 키든 배포의 litellm_params에 직접 설정할 수 있어요. input_cost_per_token_above_{N}k_tokens 형태의 계층형 긴 컨텍스트 키도 포함돼요. 입력 토큰 수가 임계값을 넘으면 LiteLLM은 전체 요청을 그 티어 요율로 청구해요.

예를 들어 기본 맵에 긴 컨텍스트 티어가 없는 지역 가격 변형(예: US Data Zone)으로 청구되는 Azure 배포:

model_list:
  - model_name: gpt-5.6-terra
    litellm_params:
      model: azure/<your-deployment-name>
      api_key: os.environ/AZURE_API_KEY
      api_base: os.environ/AZURE_API_BASE
      input_cost_per_token: 0.0000022        # base rate for your price variant
      output_cost_per_token: 0.0000132
      input_cost_per_token_above_272k_tokens: 0.0000044   # long-context tier
      output_cost_per_token_above_272k_tokens: 0.0000198
      cache_read_input_token_cost: 0.00000022
      cache_read_input_token_cost_above_272k_tokens: 0.00000044

재정의 가능한 키의 전체 세트에는 기본 토큰별 요율, 초당 요율, 캐시 읽기·생성 요율, 그리고 각각의 above_128k, above_200k, above_272k 티어 변형, 추가로 _priority 서비스 티어 변형이 포함돼요. 위 숫자는 예시예요. 실제 요율은 제공자의 가격표에서 가져오세요. 일반적인 재정의 메커니즘은 Custom LLM Pricing 참고.

계층형 가격이 적용되도록 코드 변경은 필요 없어요. 비용 엔진은 해석된 가격이 담고 있는 모든 티어 키를 읽어요.

부분 재정의는 기본 가격으로 폴백하지 않아요 (Partial overrides do not fall back to default pricing)

커스텀 가격 필드를 설정하면 배포가 기본 비용 맵 항목에서 분리돼요. LiteLLM은 그 배포용 독립 가격 항목을 만들고 그것만으로 청구해요. input_cost_per_token을 재정의하지만 input_cost_per_token_above_272k_tokens을 남겨두면 그 배포에는 티어 경계가 전혀 없으므로, 272k 토큰을 넘는 요청은 커스텀 기본 요율로 청구돼요. 설정되지 않은 티어 키는 기본 맵의 티어 가격을 상속하지 않으며, LiteLLM은 기본 요율과 기본 티어 프리미엄을 절대 섞지 않아요.

한 가지 의도된 예외는 캐시 가격이에요. 기본 입력 요율을 재정의할 때 빠진 캐시 필드(cache_read_input_token_cost, cache_creation_input_token_cost, 그리고 그 above_1hr·above_200k 변형)는 백엔드 모델의 기본 항목에서 상속돼 캐시 읽기가 0으로 조용히 청구되지 않게 해요. 상속된 값은 사용자의 가격 변형이 아니라 기본 가격이라는 점을 참고하세요. 그러니 지역·협상 요율표는 캐시 키도 재정의해야 해요.

재정의 블록을 배포의 완전한 요율표로 취급하세요: 기본 입력·출력 요율, 긴 컨텍스트 티어 키, 캐시 키. 부분 재정의는 정확히 비싼 요청에서 조용히 과소 청구해요.

옵션 2: 자체 비용 맵 서빙 (Option 2: serve your own cost map)

프록시를 자체 맵 사본으로 지정하세요:

export LITELLM_MODEL_COST_MAP_URL="https://your-host.example.com/model_prices.json"

맵은 시작 시 5초 타임아웃으로 한 번 가져오므로, 변수는 프록시 시작 전에 설정해야 하고 변경에는 재시작이 필요해요. URL은 HTTP(S)여야 해요. file:// 경로는 지원되지 않아요. 완전 오프라인으로 실행하려면 대신 LITELLM_LOCAL_MODEL_COST_MAP=True를 설정하세요. 이는 가져오기를 건너뛰고 패키지에 번들된 백업 맵(litellm/model_prices_and_context_window_backup.json)을 사용하는데, 이 파일은 자체 이미지에서 덮어쓸 수 있어요.

전체 업스트림 파일에서 시작 (Start from the full upstream file)

커스텀 맵은 항상 완전한 model_prices_and_context_window.json의 포크로 만들어 수정 사항을 편집하세요. 모델만 담은 작은 파일은 거부돼요. 가져온 맵은 최소 50개의 모델 항목과 번들 백업 항목 수의 절반 이상을 포함해야 해요. 아니면 LiteLLM이 버려요. 두 임계값은 MODEL_COST_MAP_MIN_MODEL_COUNT와 MODEL_COST_MAP_MAX_SHRINK_RATIO로 조정 가능하지만, 손상된 맵이 검증을 통과하는 위험을 받아들일 때만 그래요.

폴백 의미론: 모니터링하세요 (Fallback semantics: monitor them)

가져오기가 실패하거나, 타임아웃되거나, 파일이 검증에 실패해도 프록시는 크래시하지 않아요. 경고를 기록하고 조용히 번들 백업 맵으로 폴백하는데, 이는 요청이 그 백업이 담고 있는 가격으로 청구된다는 뜻이에요. 프로덕션 배포에서는 이게 주의해야 할 실패 모드예요. pod 시작 시의 일시적 네트워크 오류가 모든 가격 교정을 조용히 되돌려버려요.

실제로 어떤 맵이 로드됐는지 admin 엔드포인트로 검증하세요:

curl -s http://localhost:4000/model/cost_map/source \
  -H "Authorization: Bearer $LITEL..._KEY"

응답은 source("remote" 또는 "local"), 시도된 url, 사람이 읽을 수 있는 fallback_reason(성공 시 null), model_count를 보고해요. source가 remote가 아니거나 fallback_reason이 null이 아니면 알림을 보내세요.

프로덕션 체크리스트 (Production checklist)

  • 통제하는 인프라(CDN 뒤의 객체 스토리지 또는 내부 엔드포인트)에 파일을 버전이 있는 아티팩트로 호스팅하고, 모든 프록시 pod에서 5초 안에 도달할 수 있어야 해요.
  • /model/cost_map/source가 폴백을 보고하면 알림을 보내세요.
  • 업스트림 맵과 재동기화 주기를 설정해, 새로 출시된 모델의 가격이 포크 시점에 동결되지 않게 하세요.
  • 가능하면 커스텀 맵을 임시로 취급하세요. 교정을 업스트림 기본 맵에 반영한 다음 포크를 버리세요.

어떤 옵션을 고를까 (Which option to choose)

커스텀 맵은 전체 가격 데이터베이스를 교체해요. 모든 항목의 소유권을 맡고, 재동기화할 때까지 업스트림 가격 업데이트를 받지 못하며, 그 실패 모드(조용한 폴백)는 헬스 체크를 실패시키지 않고 교정을 되돌려요. 배포별 재정의는 그런 위험이 없지만 교정해야 할 배포 수에 선형적으로 확장돼요. 콘피그에서 소수의 배포를 고치고, 포크된 맵 + 모니터링으로 플릿을 고치세요. 두 경우 모두 교정을 업스트림에 기여해 워크어라운드를 폐기할 수 있게 하세요.