CloudZero

CloudZero

LiteLLM은 CloudZero의 AnyCost API와 통합을 제공해서 LLM 사용 데이터를 비용 추적·분석용으로 CloudZero에 내보낼 수 있어요.

출처: 문서

본문

개요 (Overview)

속성	세부
설명	비용 추적·분석을 위해 LiteLLM 사용 데이터를 CloudZero AnyCost API로 내보내기
콜백 이름	cloudzero
지원 작업	• 자동 시간별 데이터 내보내기 • 수동 데이터 내보내기 • 드라이런 테스트 • 비용 및 토큰 사용 추적
데이터 형식	적절한 리소스 태깅을 포함한 CloudZero Billing Format (CBF)
내보내기 빈도	시간별(CLOUDZERO_EXPORT_INTERVAL_MINUTES로 설정 가능)

환경 변수 (Environment Variables)

변수	필수	설명	예시
CLOUDZERO_API_KEY	예	CloudZero API 키	cz_api_xxxxxxxxxx
CLOUDZERO_CONNECTION_ID	예	데이터 제출용 CloudZero 연결 ID	conn_xxxxxxxxxx
CLOUDZERO_TIMEZONE	아니오	날짜 처리용 타임존(기본: UTC)	America/New_York
CLOUDZERO_EXPORT_INTERVAL_MINUTES	아니오	내보내기 빈도(분, 기본: 60)	60

설정 (Setup)

1단계: 환경 변수 구성

환경에 CloudZero 자격 증명을 설정해 주세요.

export CLOUDZERO_API_KEY="cz_api_xxxxxxxxxx"
export CLOUDZERO_CONNECTION_ID="conn_xxxxxxxxxx"
export CLOUDZERO_TIMEZONE="UTC"  # Optional, defaults to UTC

2단계: CloudZero 통합 활성화

LiteLLM 구성 YAML 파일에 CloudZero 콜백을 추가해 주세요.

model_list:
  - model_name: gpt-5.6-terra
    litellm_params:
      model: openai/gpt-5.6-terra
      api_key: sk-xxxxxxx

litellm_settings:
  callbacks: ["cloudzero"]  # Enable CloudZero integration

3단계: LiteLLM 프록시 시작

구성으로 LiteLLM 프록시를 시작해 주세요.

litellm --config /path/to/config.yaml

UI로 설정 (Setup on UI)

1. "Settings" 클릭
2. "Logging & Alerts" 클릭
3. "CloudZero Cost Tracking" 클릭
4. "Add CloudZero Integration" 클릭
5. CloudZero API Key 입력
6. CloudZero Connection ID 입력
7. "Create" 클릭
8. "Run Dry Run Simulation"으로 페이로드 테스트
9. "Export Data Now"를 클릭해 CloudZero로 내보내기

설정 테스트 (Testing Your Setup)

드라이런 내보내기 (Dry Run Export)

드라이런 엔드포인트를 호출해 CloudZero로 데이터를 보내지 않고도 CloudZero 구성을 테스트할 수 있어요. 이 엔드포인트는 CloudZero로 데이터를 보내지 않지만 내보낼 데이터를 반환해요.

curl -X POST "http://localhost:4000/cloudzero/dry-run" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{
    "limit": 10
  }' | jq

예상 응답:

{
  "message": "CloudZero dry run export completed successfully.",
  "status": "success",
  "dry_run_data": {
    "usage_data": [...],
    "cbf_data": [...],
    "summary": {
      "total_cost": 0.05,
      "total_tokens": 1250,
      "total_records": 10
    }
  }
}

수동 내보내기 (Manual Export)

내보내기 엔드포인트를 호출해 데이터를 즉시 CloudZero로 보내요. 테스트하려면 작은 limit를 설정하는 것을 권장해요. 이는 마지막 10개 레코드만 CloudZero로 내보내요. 참고: CloudZero가 내보낸 데이터를 처리하는 데 최대 15분 걸릴 수 있어요.

curl -X POST "http://localhost:4000/cloudzero/export" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{
    "limit": 10
  }' | jq

예상 응답:

{
  "message": "CloudZero export completed successfully",
  "status": "success"
}

데이터 내보내기 세부 (Data Export Details)

자동 내보내기 일정 (Automatic Export Schedule)

• 빈도: 60분마다(CLOUDZERO_EXPORT_INTERVAL_MINUTES로 설정 가능)
• 데이터 처리: LiteLLM이 사용 데이터를 자동으로 매시간 처리·내보내기
• CloudZero 처리: CloudZero는 LiteLLM 데이터를 처리하는 데 보통 10~15분 걸림

데이터 형식 (Data Format)

LiteLLM은 다음 구조로 CloudZero Billing Format (CBF) 데이터를 내보내요:

{
  "time/usage_start": "2024-01-15T14:00:00Z",
  "cost/cost": 0.0008,
  "usage/amount": 150,
  "usage/units": "tokens",
  "resource/id": "czrn:litellm:openai:cross-region:team-123:llm-usage:gpt-5.6-terra",
  "resource/service": "litellm",
  "resource/account": "team-123",
  "resource/region": "cross-region",
  "resource/usage_family": "llm-usage",
  "resource/tag:provider": "openai",
  "resource/tag:model": "gpt-5.6-terra",
  "resource/tag:prompt_tokens": "100",
  "resource/tag:completion_tokens": "50"
}

리소스 태깅 (Resource Tagging)

LiteLLM은 비용 귀속을 위해 자동으로 리소스 태그를 만든다:

• 프로바이더 태그: openai, anthropic, azure 등
• 모델 태그: gpt-5.6-terra, claude-sonnet-5 같은 특정 모델 이름
• 팀/사용자 태그: 비용 할당을 위한 팀 ID와 사용자 ID
• 토큰 분할: 프롬프트와 완성 토큰의 별도 추적
• 사용 메트릭: 요청당 소비된 총 토큰

고급 구성 (Advanced Configuration)

사용자 지정 내보내기 빈도 (Custom Export Frequency)

내보내기 빈도를 변경해요(60분 미만은 권장하지 않음):

export CLOUDZERO_EXPORT_INTERVAL_MINUTES=120  # Export every 2 hours

사용자 지정 시간 범위 내보내기 (Custom Time Range Export)

특정 시간 범위의 데이터를 내보내요:

curl -X POST "http://localhost:4000/cloudzero/export" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{
    "start_time_utc": "2024-01-15T00:00:00Z",
    "end_time_utc": "2024-01-15T23:59:59Z",
    "operation": "replace_hourly"
  }' | jq

문제 해결 (Troubleshooting)

일반적인 문제 (Common Issues)

1. 자격 증명 누락 오류

CloudZero configuration missing. Please set CLOUDZERO_API_KEY and CLOUDZERO_CONNECTION_ID environment variables.

해결책: 두 환경 변수가 유효한 값으로 설정되어 있는지 확인하세요.

2. 연결 문제
   • CloudZero API 키가 유효한지 확인
   • CloudZero 계정에 연결 ID가 존재하는지 확인
   • 프록시가 CloudZero API에 도달할 인터넷 접근이 있는지 확인
3. CloudZero에 데이터 없음
   • CloudZero가 데이터를 처리하는 데 10~15분 걸릴 수 있음
   • LiteLLM 프록시가 사용 데이터를 생성하고 있는지 확인
   • 드라이런 엔드포인트로 데이터가 올바르게 포맷되는지 확인

관련 링크 (Related Links)

• CloudZero Documentation
• CloudZero AnyCost API

더 알아보기 (Learn more)

• CloudZero — 비용 관리 플랫폼
• AnyCost API — AnyCost API 참조