Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Relatórios Avançados de Consumo

Aula 10 de 14 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Construção de relatórios de consumo
  2. Relatório mensal comparativo
  3. Deteção de anomalias
  4. Discriminação por modelo
  5. Relatório semanal automatizado
  6. Granularidade e desempenho
  7. Pontos-chave

Construção de relatórios de consumo

Dados de consumo que ninguém consulta são inúteis. Um relatório só tem valor se responder a uma pergunta que realmente se coloca, e essas perguntas resumem-se a três: o consumo está a aumentar? Ocorreu alguma anomalia? Para onde vai o dinheiro?

As três secções seguintes abordam estas questões pela ordem indicada. Cada uma produz um número sobre o qual pode agir, e não apenas mais um gráfico.

Relatório mensal comparativo

O consumo só faz sentido por comparação. 400 $ num mês não é bom nem mau em termos absolutos: o que importa é saber se esse valor sucede a um mês de 200 $ ou a um de 600 $. Contextualize sempre as alterações com o que sabe sobre a atividade — um aumento de 40 % após o lançamento de uma funcionalidade é esperado; o mesmo aumento sem nenhuma novidade justifica a consulta da secção seguinte.

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))

Deteção de anomalias

O desvio-padrão define aqui o que é «anómalo» sem necessidade de estabelecer um limiar arbitrário: um dia que se situe a mais de dois desvios-padrão da sua média foge ao padrão habitual, independentemente do seu volume. Este é o método que se adapta automaticamente à medida que a sua atividade cresce, ao passo que um limiar monetário se torna obsoleto no mês seguinte.

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

Discriminação por modelo

Este é o relatório com maior retorno, porque aponta para ações concretas. O custo total não lhe diz o que fazer; a discriminação por modelo, sim — revela tarefas simples encaminhadas para o modelo mais dispendioso, que constituem as poupanças mais fáceis de concretizar numa fatura de 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"]
    }
  }'

Esta análise pode revelar oportunidades de otimização: se uma grande parte dos seus pedidos utilizar o grok-4.20-0309-reasoning para tarefas simples, a mudança para o grok-4.3 poderá reduzir significativamente os custos.

Relatório semanal automatizado

A entrega automática altera a natureza do exercício: um relatório que tem de ir buscar só é consultado depois do incidente; um relatório que chega é lido antecipadamente. A periodicidade semanal é a adequada para o consumo de API — frequente o suficiente para detetar desvios antes da fatura, mas espaçada o bastante para que continue a abri-lo.

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

Granularidade e desempenho

Escolha da granularidade adequada

Caso de utilizaçãoGranularidade recomendada
Relatório mensalMONTH
Acompanhamento diárioDAY
Análise de picosHOUR ou QUARTER_HOUR
Depuração em tempo realMINUTE
Análise detalhada de incidentesSECOND

Quanto mais fina for a granularidade, maior será o volume de dados devolvido: ao longo de um mês, a granularidade SECOND produz milhões de pontos, com o correspondente impacto no tempo de resposta e no consumo de memória. A regra prática consiste em escolher a granularidade em função da duração do fenómeno que procura detetar — um pico de alguns minutos é invisível com granularidade MONTH e fica diluído no ruído com granularidade SECOND.

Pontos-chave

  • Combine SUM (total), COUNT (contagem) e groupBy: ["model"] para obter relatórios completos
  • A deteção de anomalias com desvio-padrão identifica dias de sobreconsumo
  • A discriminação por modelo revela oportunidades de otimização de custos
  • Adapte a granularidade temporal ao caso de utilização: MONTH para relatórios, HOUR para depuração
  • Automatize os relatórios semanais para manter o consumo sob vigilância