고객 사용량

고객 사용량 (Customer Usage)

대시보드에서 직접 최종 사용자 지출을 추적하고 시각화해요. 고객 수준 사용 분석, 지출 로그, 활동 지표를 모니터링해 고객이 LLM 서비스를 어떻게 사용하는지 이해할 수 있어요.

출처: 문서

본문

이 기능은 v1.80.8-stable 이상에서 사용할 수 있어요.

개요 (Overview)

Customer Usage는 API 요청에 ID를 전달해 개별 고객(최종 사용자)의 지출과 사용량을 추적할 수 있게 해줘요. 이를 통해:

고객별 지출 자동 추적
Admin UI에서 고객 수준 사용 분석 보기
고객 ID로 지출 로그와 활동 지표 필터링
고객별 예산 및 요율 제한 설정
고객 사용 패턴과 추세 모니터링

지출 추적 방법 (How to Track Spend)

API 요청에 user 필드를 포함하거나 고객 ID 헤더를 전달해 고객 지출을 추적해요. 고객 ID가 자동으로 추적되고 그 요청의 모든 지출과 연결돼요.

요청 본문 (Request Body)

user 필드에 고객 ID를 포함해 /chat/completions 호출을 하세요:

curl -X POST 'http://0.0.0.0:4000/chat/completions' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ***" \
  --data '{
    "model": "gpt-5.6-luna",
    "user": "customer-123",
    "messages": [
      {
        "role": "user",
        "content": "What is the capital of France?"
      }
    ]
  }'

요청 헤더 (Request Headers)

HTTP 헤더로도 고객 ID를 전달할 수 있어요. 이는 커스텀 헤더를 지원하지만 요청 본문 수정은 허용하지 않는 도구(예: ANTHROPIC_CUSTOM_HEADERS를 쓰는 Claude Code)에 유용해요.

LiteLLM은 다음 표준 헤더를 자동 인식해요 (구성 불필요):

x-litellm-customer-id
x-litellm-end-user-id

curl -X POST 'http://0.0.0.0:4000/chat/completions' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ***" \
  --header 'x-litellm-customer-id: customer-123' \
  --data '{
    "model": "gpt-5.6-luna",
    "messages": [
      {
        "role": "user",
        "content": "What is the capital of France?"
      }
    ]
  }'

Claude Code와 함께 사용하기

Claude Code는 ANTHROPIC_CUSTOM_HEADERS 환경 변수를 통해 커스텀 헤더를 지원해요. 고객 ID를 전달하도록 설정하세요:

export ANTHROPIC_BASE_URL="http://0.0.0.0:4000/v1/messages"
export ANTHROPIC_API_KEY="sk-<your-api-key>"
export ANTHROPIC_CUSTOM_HEADERS="x-litellm-customer-id: my-customer-id"

이제 Claude Code의 모든 요청이 my-customer-id 아래에 지출을 자동 추적해요.

고객 ID는 새 지출과 함께 데이터베이스에 자동 upsert돼요. 고객 ID가 이미 있으면 지출이 증가해요.

OpenWebUI 사용 예시

Open WebUI를 LiteLLM에 연결하고 고객 사용량을 추적하는 자세한 지침은 Open WebUI 튜토리얼 참고.

지출 보기 (How to View Spend)

Admin UI에서 지출 보기

Admin UI에서 Customer Usage 탭으로 이동해 고객 수준 지출 분석을 보세요:

고객 사용량 접근: Admin UI의 Usage 페이지로 가서(PROXY_BASE_URL/ui/?login=success&page=new_usage) Customer Usage 탭을 클릭하세요.
고객 분석 보기: Customer Usage 대시보드는 다음을 제공해요:
- 고객별 총 지출: 모든 고객의 집계 지출 보기
- 일일 지출 추세: 시간에 따른 고객 지출 변화 보기
- 모델 사용 분석: 각 고객이 사용하는 모델 이해
- 활동 지표: 고객별 요청, 토큰, 성공률 추적
고객별 필터링: 필터 드롭다운으로 특정 고객의 지출을 보세요:
- 드롭다운에서 하나 이상의 고객 ID 선택
- 필터링된 분석, 지출 로그, 활동 지표 보기
- 서로 다른 고객 간 지출 비교

사용 사례 (Use Cases)

고객 청구 (Customer Billing)

고객별 지출을 추적해 최종 사용자에게 정확하게 청구:

개별 고객 사용 모니터링
실제 지출 기반 인보이스 생성
고객별 지출 한도 설정

사용 분석 (Usage Analytics)

서로 다른 고객이 서비스를 어떻게 사용하는지 이해:

고가치 고객 식별
사용 패턴 분석
리소스 할당 최적화

Customers / End-User Budgets — 고객 예산 및 요율 제한 설정
Cost Tracking — 비용 추적 및 분석
Billing — 사용량 기반 고객 청구

고객 사용량