지출 추적용 요청 태그

지출 추적용 요청 태그 (Request Tags for Spend Tracking)

환경, AWS 계정, 또는 원하는 커스텀 라벨별로 지출을 추적할 수 있도록 모델 배포에 태그를 추가할 수 있어요. 태그는 LiteLLM 지출 로그의 request_tags 필드에 나타나요.

요구 사항: Virtual Keys와 데이터베이스가 설정되어 있어야 해요. Virtual Keys 설정 문서를 참고해 주세요.

출처: 문서

본문

설정 구성 (Config Setup)

config.yaml의 모델 배포에 태그를 설정해요:

model_list:
  - model_name: gpt-5.6-terra
    litellm_params:
      model: azure/gpt-4-prod
      api_key: os.environ/AZURE_PROD_API_KEY
      api_base: https://prod.openai.azure.com/
      tags: ["AWS_IAM_PROD"]  # 👈 Tag for production

  - model_name: gpt-4-dev
    litellm_params:
      model: azure/gpt-4-dev
      api_key: os.environ/AZURE_DEV_API_KEY
      api_base: https://dev.openai.azure.com/
      tags: ["AWS_IAM_DEV"]  # 👈 Tag for development

요청 만들기 (Make Request)

옵션 1: 설정 태그 사용 (자동)

요청은 모델만 지정하면 되고, 태그는 설정에서 자동으로 적용돼요:

curl -X POST 'http://0.0.0.0:4000/chat/completions' \
  -H "Authorization: Bearer ***" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

옵션 2: `x-litellm-tags` 헤더 사용

x-litellm-tags 헤더에 쉼표로 구분된 문자열로 태그를 동적으로 전달할 수 있어요:

curl -X POST 'http://0.0.0.0:4000/chat/completions' \
  -H "Authorization: Bearer ***" \
  -H 'Content-Type: application/json' \
  -H 'x-litellm-tags: team-api,production,us-east-1' \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

형식: 쉼표로 구분된 문자열 (공백은 자동으로 제거돼요): "tag1,tag2,tag3"

옵션 3: 요청 본문의 `tags` 사용

요청 본문에 태그를 직접 전달할 수 있어요. 두 형식을 모두 지원해요:

직접 tags 필드:

curl -X POST 'http://0.0.0.0:4000/chat/completions' \
  -H "Authorization: Bearer ***" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [{"role": "user", "content": "Hello"}],
    "tags": ["team-api", "production", "us-east-1"]
  }'

metadata 중첩:

curl -X POST 'http://0.0.0.0:4000/chat/completions' \
  -H "Authorization: Bearer ***" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [{"role": "user", "content": "Hello"}],
    "metadata": {
      "tags": ["team-api", "production", "us-east-1"]
    }
  }'

tags 필드는 문자열 배열이어야 해요.

참고: 헤더나 요청 본문으로 태그를 제공하면 모델 배포에 설정된 태그를 재정의해요. 헤더와 본문 태그가 모두 제공되면 본문 태그가 우선해요.

키나 팀에 태그 설정하기

API 키나 팀 수준에서도 기본 태그를 설정할 수 있어요:

키에 설정:

curl -L -X POST 'http://0.0.0.0:4000/key/generate' \
  -H "Authorization: Bearer ***" \
  -H 'Content-Type: application/json' \
  -d '{
    "metadata": {
      "tags": ["customer-acme", "tier-premium"]
    }
  }'

팀에 설정:

curl -L -X POST 'http://0.0.0.0:4000/team/new' \
  -H "Authorization: Bearer ***" \
  -H 'Content-Type: application/json' \
  -d '{
    "metadata": {
      "tags": ["team-engineering", "department-ai"]
    }
  }'

고급: 커스텀 헤더 추적

config에 추가해 원하는 커스텀 헤더로 지출을 추적할 수 있어요:

litellm_settings:
  extra_spend_tag_headers:
    - "x-custom-header"
    - "x-customer-id"

User-Agent 추적 비활성화:

litellm_settings:
  disable_add_user_agent_to_request_tags: true

지출 로그 (Spend Logs)

모델 설정의 태그는 LiteLLM_SpendLogs에 나타나요:

{
  "request_id": "chatcmpl-abc123",
  "request_tags": ["AWS_IAM_PROD"],
  "spend": 0.002,
  "model": "gpt-5.6-terra"
}

지출 추적 개요 (Spend Tracking Overview) — 태그로 지출을 추적하는 전체 튜토리얼
태그 예산 (Tag Budgets) — 태그별 예산 한도 설정
Virtual Keys 설정 — 태그 추적에 필요

지출 추적용 요청 태그