LiteLLM 태그 예산 설정

LiteLLM 태그 예산 설정 (Setting Tag Budgets)

팀 단위로 나누기엔 애매한 비용, 예를 들어 "이번 달 마케팅 부서가 쓴 LLM 비용"처럼 부서·프로젝트·고객별로 예산을 관리하고 싶을 때 태그가 유용합니다. 태그는 요청에 붙이는 라벨로, 같은 태그의 지출을 합산하고 상한을 걸 수 있어요. 여러 비용 센터가 한 계정을 같이 쓰는 조직에 잘 맞습니다.

출처: 공식문서 - Setting Tag Budgets

사전 준비

• Postgres 데이터베이스(Supabase, Neon 등)가 필요합니다.

태그란 무엇인가

태그는 LLM 요청에 붙이는 라벨로, 카테고리별로 지출을 추적·제한하는 데 씁니다.

흔한 사용 사례:

• 비용 센터 추적: LLM 비용을 부서·사업부에 배분 (예: "engineering", "marketing", "customer-support")
• 프로젝트 기반 예산: 프로젝트·이니셔티브별 예산 설정 (예: "project-alpha", "chatbot-v2")
• 고객 귀속: 고객·클라이언트별 지출 추적 (예: "customer-acme", "customer-techcorp")
• 기능 모니터링: 특정 기능 비용 모니터링 (예: "feature-chat", "feature-summarization")

태그는 요청마다(metadata 또는 x-litellm-tags 헤더) 설정하거나, 가상 키에 붙여 그 키의 모든 요청이 태그와 그 예산 제한을 자동으로 상속하게 할 수 있습니다.

태그 예산 설정하기

1. 예산이 있는 태그 만들기

비용 센터·프로젝트·예산 카테고리를 대표하는 태그를 만들고, max_budget(허용 달러 값)과 budget_duration(예산 초기화 주기)을 지정합니다.

예: Engineering 부서에 월 $500 예산 태그 만들기

curl -X POST 'http://0.0.0.0:4000/tag/new' \
     -H 'Authorization: Bearer sk-1234' \
     -H 'Content-Type: application/json' \
     -d '{
            "name": "engineering", 
            "description": "Engineering department cost center",
            "max_budget": 500.0, 
            "budget_duration": "30d"
        }' 

요청 바디 파라미터:

응답:

{
  "name": "engineering",
  "description": "Engineering department cost center",
  "max_budget": 500.0,
  "budget_duration": "30d",
  "budget_reset_at": "2025-11-10T00:00:00Z",
  "created_at": "2025-10-11T00:00:00Z"
}  

Admin UI에서는 Tag Management 페이지에서 Create New Tag로 만들 수 있습니다.

budget_duration 가능한 값:

2. 태그를 API 키에 연결 (권장)

가상 키를 만들거나 갱신할 때 태그를 붙이면, 그 키로 하는 모든 요청이 태그를 자동으로 상속하고, 클라이언트가 매 요청에 metadata.tags를 넘기지 않아도 Proxy가 태그 예산을 강제합니다.

curl -X POST 'http://0.0.0.0:4000/key/generate' \
     -H 'Authorization: Bearer sk-1234' \
     -H 'Content-Type: application/json' \
     -d '{
            "tags": ["engineering"]
        }'

또는 키 metadata 아래에 태그를 둘 수도 있습니다.

curl -X POST 'http://0.0.0.0:4000/key/generate' \
     -H 'Authorization: Bearer sk-1234' \
     -H 'Content-Type: application/json' \
     -d '{
            "metadata": {
              "tags": ["engineering"]
            }
        }'

Admin UI에서는 Virtual Keys → Create Key(또는 키 편집)에서 Tags 필드에 태그를 선택합니다.

3. 요청에서 태그 쓰기 (선택)

키에 태그를 붙이지 않았다면, 각 요청의 metadata 필드(또는 x-litellm-tags 헤더)에 태그를 추가합니다.

import openai

client = openai.OpenAI(
    api_key="sk-1234",  # Your LiteLLM proxy key
    base_url="http://0.0.0.0:4000"
)

response = client.chat.completions.create(
    model="gpt-5.6-terra",
    messages=[{"role": "user", "content": "Hello"}],
    extra_body={
        "metadata": {
            "tags": ["engineering"]
        }
    }
)

4. 테스트하기

2단계의 가상 키로 태그 예산이 초과될 때까지 요청을 보냅니다. 태그가 키에 이미 있으면 metadata.tags를 넘길 필요가 없습니다.

예산을 초과하면 아래와 같은 응답을 보게 됩니다.

{
  "error": {
    "message": "Budget has been exceeded! Tag=engineering Current cost: 505.50, Max budget: 500.0",
    "type": "budget_exceeded",
    "param": null,
    "code": "400"
  }
}

태그 관리하기

태그 정보 조회:

curl -X POST 'http://0.0.0.0:4000/tag/info' \
     -H 'Authorization: Bearer sk-1234' \
     -H 'Content-Type: application/json' \
     -d '{
           "names": ["engineering", "marketing"]
         }'

응답에는 태그별 spend, max_budget, budget_reset_at 등이 담깁니다.

태그 예산 갱신:

curl -X POST 'http://0.0.0.0:4000/tag/update' \
     -H 'Authorization: Bearer sk-1234' \
     -H 'Content-Type: application/json' \
     -d '{
           "name": "engineering",
           "max_budget": 750.0,
           "budget_duration": "30d"
         }'

태그 삭제:

curl -X POST 'http://0.0.0.0:4000/tag/delete' \
     -H 'Authorization: Bearer sk-1234' \
     -H 'Content-Type: application/json' \
     -d '{
           "name": "engineering"
         }'

요청당 여러 태그

한 요청에 여러 태그를 적용해 비용을 동시에 여러 차원으로 추적할 수 있습니다. 예를 들어 비용 센터와 특정 프로젝트를 함께 추적합니다.

response = client.chat.completions.create(
    model="gpt-5.6-terra",
    messages=[{"role": "user", "content": "Hello"}],
    extra_body={
        "metadata": {
            "tags": ["engineering", "project-alpha", "customer-acme"]
        }
    }
)

예산 강제: 태그 중 하나라도 예산을 초과하면 요청이 거부됩니다.

더 알아보기

• Setting Team Budgets (팀 예산)
• Spend Tracking (지출 추적)
• Budget Reset Times and Timezones (예산 초기화 시각·타임존)