CloudZero

LiteLLM 提供與 CloudZero 的 AnyCost API 整合，讓您可以將 LLM 使用資料匯出到 CloudZero 進行成本追蹤分析。

總覽

屬性	詳細資訊
說明	將 LiteLLM 使用資料匯出到 CloudZero AnyCost API，以進行成本追蹤與分析
callback name	cloudzero
支援的操作	• 自動每小時資料匯出 • 手動資料匯出 • 乾跑測試 • 成本與 token 使用追蹤
資料格式	具備正確資源標記的 CloudZero Billing Format (CBF)
匯出頻率	每小時（可透過 CLOUDZERO_EXPORT_INTERVAL_MINUTES 設定）

環境變數

變數	必填	說明	範例
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

設定

端到端影片導覽

此影片會逐步說明如何設定 LiteLLM 與 CloudZero 整合，並在 CloudZero 中檢視 LiteLLM 匯出的使用資料。

步驟 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 整合

將 CloudZero callback 加入您的 LiteLLM 設定 YAML 檔案：

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 Proxy

使用以下設定啟動您的 LiteLLM proxy：

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

在 UI 上設定

1. 點選「Settings」

2. 點選「Logging & Alerts」

3. 點選「CloudZero Cost Tracking」

4. 點選「Add CloudZero Integration」

5. 輸入您的 CloudZero API 金鑰。

6. 輸入您的 CloudZero 連線 ID。

7. 點選「Create」

8. 使用「Run Dry Run Simulation」測試您的負載

10. 點選「Export Data Now」以匯出到 CLoudZero

測試您的設定

乾跑匯出

呼叫乾跑端點，以在不將資料傳送到 CloudZero 的情況下測試您的 CloudZero 設定。此端點不會將任何資料傳送到 CloudZero，但會回傳將被匯出的資料。

curl -X POST "http://localhost:4000/cloudzero/dry-run" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LITELLM_API_KEY" \
  -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
    }
  }
}

手動匯出

呼叫匯出端點，立即將資料傳送到 CloudZero。我們建議設定較小的 limit 來測試匯出。這只會將最後 10 筆記錄匯出到 CloudZero。注意：Cloudzero 可能需要最多 15 分鐘來處理已匯出的資料。

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

預期回應：

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

資料匯出詳細資訊

自動匯出排程

• 頻率：每 60 分鐘一次（可透過 CLOUDZERO_EXPORT_INTERVAL_MINUTES 設定）
• 資料處理：LiteLLM 會自動每小時處理並匯出使用資料
• CloudZero 處理：CloudZero 通常需要 10-15 分鐘來處理來自 LiteLLM 的資料

資料格式

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"
}

資源標記

LiteLLM 會自動建立資源標籤以進行成本歸屬：

• 提供者標記：openai、anthropic、azure 等
• 模型標記：特定模型名稱，例如 gpt-5.6-terra、claude-sonnet-5
• 團隊/使用者標記：用於成本分配的團隊 ID 與使用者 ID
• Token 明細：分別追蹤 prompt 與 completion tokens
• 使用指標：每個請求消耗的總 token 數

進階設定

自訂匯出頻率

變更匯出頻率（不建議低於 60 分鐘）：

export CLOUDZERO_EXPORT_INTERVAL_MINUTES=120  # Export every 2 hours

自訂時間範圍匯出

匯出特定時間範圍的資料：

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

疑難排解

常見問題

1. 缺少憑證錯誤

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

   解決方案：請確保已設定兩個環境變數，且值有效。

2. 連線問題

   • 確認您的 CloudZero API 金鑰有效
   • 檢查連線 ID 是否存在於您的 CloudZero 帳戶中
   • 確保您的 proxy 可透過網際網路存取 CloudZero 的 API

3. CloudZero 中沒有資料

   • CloudZero 可能需要 10-15 分鐘來處理資料
   • 檢查您的 LiteLLM proxy 是否正在產生使用資料
   • 使用乾跑端點確認資料格式是否正確

相關連結

• CloudZero 文件
• CloudZero AnyCost API