Salt la conținutul principal
Română— Alege o limbă
Meniu

Rapoarte avansate de consum

Lecția 10 din 14 Actualizată 29 iulie 2026 Dezvoltator
Pe această pagină
  1. Elaborarea rapoartelor de consum
  2. Raport comparativ lunar
  3. Detectarea anomaliilor
  4. Defalcare pe modele
  5. Raport săptămânal automatizat
  6. Granularitate și performanță
  7. Puncte cheie

Elaborarea rapoartelor de consum

Datele de consum pe care nimeni nu le consultă sunt inutile. Un raport este util doar dacă răspunde la o întrebare concretă, iar acestea se reduc la trei: consumul crește, s-a produs ceva anormal și unde se duc banii.

Următoarele trei secțiuni abordează aceste întrebări în această ordine. Fiecare generează o valoare pe care puteți acționa, nu doar un grafic în plus.

Raport comparativ lunar

Consumul are sens doar prin comparație. 400 $ pe lună nu este nici bine, nici rău în termeni absoluți: ceea contează este dacă această sumă urmează unei luni de 200 $ sau uneia de 600 $. Contextualizați întotdeauna variațiile cu ceea ce știți despre activitate: o creștere de 40% după lansarea unei funcționalități este de așteptat; aceeași creștere fără nicio noutate justifică trecerea la secțiunea următoare.

import requests
import json

MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
TEAM_ID = "team-..."

def get_monthly_usage(year, month):
    """Retrieves total consumption for a given month."""
    next_month = month + 1 if month < 12 else 1
    next_year = year if month < 12 else year + 1

    response = requests.post(
        f"{MANAGEMENT_API}/v1/billing/teams/{TEAM_ID}/usage",
        headers={
            "Authorization": f"Bearer {MGMT_KEY}",
            "Content-Type": "application/json"
        },
        json={
            "analyticsRequest": {
                "timeRange": {
                    "startTime": f"{year}-{month:02d}-01 00:00:00",
                    "endTime": f"{next_year}-{next_month:02d}-01 00:00:00",
                    "timezone": "Europe/Paris"
                },
                "timeUnit": "MONTH",
                "values": [
                    {"name": "tokens", "aggregation": "SUM"},
                    {"name": "requests", "aggregation": "COUNT"}
                ],
                "groupBy": ["model"]
            }
        }
    )
    return response.json()

# Compare March and April 2026
march = get_monthly_usage(2026, 3)
april = get_monthly_usage(2026, 4)

print("=== Comparative Report March vs April 2026 ===")
print(json.dumps(march, indent=2))
print(json.dumps(april, indent=2))

Detectarea anomaliilor

Abaterea standard definește aici „anormalul“ fără a necesita stabilirea unui prag arbitrar: o zi care depășește două abateri standard față de media dumneavoastră se situează în afara tiparului obișnuit, indiferent de volumul activității. Aceasta este metoda care se adaptează automat pe măsură ce activitatea crește, acolo unde un prag monetar devine depășit chiar în luna următoare.

import requests
import statistics

MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
TEAM_ID = "team-..."

# Retrieve daily consumption for the month
response = requests.post(
    f"{MANAGEMENT_API}/v1/billing/teams/{TEAM_ID}/usage",
    headers={
        "Authorization": f"Bearer {MGMT_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "analyticsRequest": {
            "timeRange": {
                "startTime": "2026-03-01 00:00:00",
                "endTime": "2026-04-01 00:00:00",
                "timezone": "Europe/Paris"
            },
            "timeUnit": "DAY",
            "values": [{"name": "tokens", "aggregation": "SUM"}]
        }
    }
)

data = response.json()
daily_values = [point.get("value", 0) for point in data.get("dataPoints", [])]

if daily_values:
    mean = statistics.mean(daily_values)
    stdev = statistics.stdev(daily_values) if len(daily_values) > 1 else 0
    threshold = mean + 2 * stdev  # Threshold at 2 standard deviations

    for i, val in enumerate(daily_values):
        if val > threshold:
            print(f"Day {i+1}: {val} tokens (anomaly, threshold = {threshold:.0f})")

Defalcare pe modele

Acesta este raportul cu cel mai mare randament, deoarece indică acțiuni concrete. Costul total nu vă spune ce să faceți; defalcarea pe modele, da – aceasta relevă sarcini simple direcționate către modelul cel mai scump, reprezentând economiile cele mai ușor de realizat la factura API.

curl -X POST "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/usage" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "analyticsRequest": {
      "timeRange": {
        "startTime": "2026-03-01 00:00:00",
        "endTime": "2026-04-01 00:00:00",
        "timezone": "UTC"
      },
      "timeUnit": "MONTH",
      "values": [
        {"name": "tokens", "aggregation": "SUM"},
        {"name": "cost", "aggregation": "SUM"}
      ],
      "groupBy": ["model"]
    }
  }'

Această analiză poate revela oportunități de optimizare: dacă o parte importantă a cererilor dumneavoastră utilizează grok-4.20-0309-reasoning pentru sarcini simple, trecerea la grok-4.3 ar putea reduce semnificativ costurile.

Raport săptămânal automatizat

Livarea automată schimbă natura exercițiului: un raport pe care trebuie să îl recuperați este consultat doar după incident, în timp ce un raport care vă parvine este citit preventiv. Frecvența săptămânală este ritmul potrivit pentru consumul API – suficient de frecvent pentru a detecta o deviere înainte de sosirea facturii, dar suficient de distanțat pentru a menține interesul de a-l deschide.

import requests
from datetime import datetime, timedelta

MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
TEAM_ID = "team-..."

# Previous week
end = datetime.now().replace(hour=0, minute=0, second=0, microsecond=0)
start = end - timedelta(days=7)

response = requests.post(
    f"{MANAGEMENT_API}/v1/billing/teams/{TEAM_ID}/usage",
    headers={
        "Authorization": f"Bearer {MGMT_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "analyticsRequest": {
            "timeRange": {
                "startTime": start.strftime("%Y-%m-%d %H:%M:%S"),
                "endTime": end.strftime("%Y-%m-%d %H:%M:%S"),
                "timezone": "Europe/Paris"
            },
            "timeUnit": "DAY",
            "values": [
                {"name": "tokens", "aggregation": "SUM"},
                {"name": "requests", "aggregation": "COUNT"}
            ],
            "groupBy": ["model"]
        }
    }
)

report = response.json()
print(f"=== Weekly Report {start.date()} → {end.date()} ===")

# Format report for email/Slack
# ... send via your preferred notification tool

Granularitate și performanță

Alegerea granularității potrivite

Caz de utilizareGranularitate recomandată
Raport lunarMONTH
Urmărire zilnicăDAY
Analiză a vârfurilor de consumHOUR sau QUARTER_HOUR
Depanare în timp realMINUTE
Analiză detaliată a incidentelorSECOND

Cu cât granularitatea este mai fină, cu atât volumul de date returnat este mai mare: pe o perioadă de o lună, granularitatea SECOND generează milioane de puncte, cu un timp de răspuns și un consum de memorie corespunzătoare. Regula de bază este să alegeți granularitatea în funcție de durata fenomenului căutat: un vârf de câteva minute este invizibil la granularitatea MONTH și se pierde în zgomot la granularitatea SECOND.

Puncte cheie

  • Combinați SUM (total), COUNT (număr) și groupBy: ["model"] pentru rapoarte complete
  • Detectarea anomaliilor prin abaterea standard identifică zilele de supraconsum
  • Defalcarea pe modele relevă oportunități de optimizare a costurilor
  • Adaptați granularitatea temporală la cazului de utilizare: MONTH pentru rapoarte, HOUR pentru depanare
  • Automatizați rapoartele săptămânale pentru a monitoriza consumul