Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

Analitika naudojimo

Paskaita 9 iš 14 Atnaujinta 2026 m. liepos 29 d. Kūrėjas
Šiame puslapyje
  1. Suprask savo API vartojimą
  2. Analizės galinis taškas
  3. Užklausos parametrai
  4. Praktiniai pavyzdžiai
  5. Svarbiausi punktai

Suprask savo API vartojimą

Naudojimo skydelis xAI konsolėje Sąskaita faktūra nurodo, kiek išleidai; šis galinis taškas paaiškina kodėl. Tai skirtumas tarp stebėjimo ir veiksmo: vartojimas suskirstomas pagal modelį, laikotarpį ir tavo pasirinktą granuliariumą, leidžiantis susieti šuolį su konkrečiu modelu konkrečiu laiku.

Jo sintaksė turtingesnė nei kitų Valdymo API dalių – trys parametrų blokai derinimui, – tačiau viskas susiveda į tris klausimus: kokiu laikotarpiu, kokiu granuliariumu ir koks matas. Šioje pamokoje juos nagrinėsime būtent tokia tvarka. Tai leidžia analizuoti vartojimą pagal modelį, laikotarpį ir skirtingus laiko granuliariumus – esminius duomenis kaštams optimizuoti ir infrastruktūrai parinkti.

7
Laiko vienetai
9
Agregacijos
POST
HTTP metodas
groupBy
Skaidymas pagal modelį

Analizės galinis taškas

Naudojimo analizė atliekama naudojant POST užklausą:

POST /v1/billing/teams/{teamId}/usage

Užklausos struktūra

{
  "analyticsRequest": {
    "timeRange": {
      "startTime": "2026-03-01 00:00:00",
      "endTime": "2026-04-01 00:00:00",
      "timezone": "UTC"
    },
    "timeUnit": "DAY",
    "values": [
      {"name": "tokens", "aggregation": "SUM"}
    ],
    "groupBy": ["model"]
  }
}

Ši užklausa prašo bendros sunaudotų tokenų sumos per dieną, suskirstytos pagal modelį, 2026 m. kovą UTC laiku. Laikyk tai šablonu: praktiškai iš vienos ataskaitos į kitą keisi tik tris dalykus – laikotarpį, laiko vienetą ir metriką, – o likusi struktūra lieka identiška.

Užklausos parametrai

timeRange

Apibrėžia analizės laikotarpį:

  • startTime : laikotarpio pradžia (formatas YYYY-MM-DD HH:MM:SS)
  • endTime : laikotarpio pabaiga (tas pats formatas)
  • timezone : laiko juosta datų interpretavimui (pvz., UTC, Europe/Paris)

timeUnit

Rezultatų laiko granuliariumas. Galimi variantai:

  • MONTH : mėnesio agregacija
  • CALENDAR_WEEK : kalendorinės savaitės agregacija
  • DAY : dienos agregacija
  • HOUR : valandos agregacija
  • QUARTER_HOUR : ketvirčio valandos agregacija
  • MINUTE : minutės agregacija
  • SECOND : sekundės agregacija

Granuliariumą rinkis pagal tiriamo reiškinio trukmę, o ne pagal analizuojamo laikotarpio ilgį. Mėnesio ataskaita gerai skaitoma naudojant DAY; dešimties minučių šuolis tokiu masteliu visiškai išnyksta ir pasimato tik naudojant QUARTER_HOUR. Per didelis smulkmeningumas taip pat turi kainą – grąžinamų taškų apimtis greitai auga, o kartu didėja ir triukšmas.

values

Agregacijos funkcijos pasirinkimas keičia užduodamą klausimą, ir būtent čia percentiliai nusipelno tavo dėmesio. AVG latencijai suteikia raminantį vidurkį, kurio niekas realiai nepatiria; P99 rodo laukimo laiką, kurį patyrė nesėkmingiausi naudotojai – tie, kurie skundžiasi. Kaštams naudok SUM; našumui – percentilį.

"values": [
  {"name": "tokens", "aggregation": "SUM"},
  {"name": "tokens", "aggregation": "AVG"},
  {"name": "latency", "aggregation": "P99"}
]

Galimos agregacijos funkcijos:

  • SUM : bendra suma
  • AVG : vidurkis
  • MIN : mažiausia reikšmė
  • MAX : didžiausia reikšmė
  • P50 : mediana (50-asis percentilis)
  • P90 : 90-asis percentilis
  • P99 : 99-asis percentilis
  • COUNT : įvykių skaičius
  • COUNT_DISTINCT : unikalių reikšmių skaičius

groupBy

Suskirsto rezultatus pagal dimensiją. Šiuo metu galima grupuoti pagal model, leidžiant matyti atskirą kiekvieno modelio vartojimą (grok-4.20-0309-reasoning, grok-4.3 ir kt.).

Praktiniai pavyzdžiai

Dienos vartojimas einamajam mėnesiui

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-04-01 00:00:00",
        "endTime": "2026-05-01 00:00:00",
        "timezone": "Europe/Paris"
      },
      "timeUnit": "DAY",
      "values": [{"name": "tokens", "aggregation": "SUM"}],
      "groupBy": ["model"]
    }
  }'

Užklausų skaičius per valandą

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-04-03 00:00:00",
        "endTime": "2026-04-04 00:00:00",
        "timezone": "Europe/Paris"
      },
      "timeUnit": "HOUR",
      "values": [{"name": "requests", "aggregation": "COUNT"}],
      "groupBy": ["model"]
    }
  }'

P99 latencija pagal modelį

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-04-01 00:00:00",
        "endTime": "2026-04-04 00:00:00",
        "timezone": "UTC"
      },
      "timeUnit": "DAY",
      "values": [
        {"name": "latency", "aggregation": "P99"},
        {"name": "latency", "aggregation": "AVG"}
      ],
      "groupBy": ["model"]
    }
  }'

Svarbiausi punktai

  • Galinis taškas POST /v1/billing/teams/{teamId}/usage centralizuoja visą analitiką
  • Yra 7 laiko granuliariumai: nuo SECOND iki MONTH
  • 9 agregacijos funkcijos: SUM, AVG, MIN, MAX, P50, P90, P99, COUNT, COUNT_DISTINCT
  • Parametras groupBy: ["model"] suskirsto rezultatus pagal modelį
  • Ataskaitoms, suderintoms su tavo darbo laiku, naudok laiko juostą Europe/Paris