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

Campos de Custo nas Respostas

Aula 8 de 14 Atualizada a 29 de julho de 2026 Avancado
Nesta página
  1. Acompanhe Custos em Tempo Real
  2. O Objeto usage
  3. Duas Escalas para o Mesmo Custo
  4. Construa um Rastreador de Custos
  5. Analise a Taxa de Cache
  6. Pontos-chave

Acompanhe Custos em Tempo Real

Cada resposta da API do Grok inclui os detalhes do custo imediato. Muitas equipas descobrem esta informação tarde demais, quando chega a fatura mensal, embora esteja disponível pedido a pedido. Ao aproveitar estes dados desde o início da integração, deteta desvios numa hora após a sua ocorrência: um prompt de sistema que duplicou de tamanho após uma implementação, um ciclo de repetição mal calibrado que repete as mesmas chamadas ou um contexto que ultrapassa um limiar de faturação. Sem este acompanhamento, estes incidentes permanecem invisíveis até à emissão do extrato.

O Objeto usage

Cada resposta inclui um objeto usage que detalha o consumo de tokens e o custo associado:

{
  "usage": {
    "prompt_tokens": 1250,
    "completion_tokens": 340,
    "total_tokens": 1590,
    "cached_tokens": 800,
    "cost_in_usd_ticks": 5000000000,
    "cost_in_nano_usd": 500000000
  }
}

Os quatro campos de contagem lêem-se da seguinte forma.

CampoSignificado
prompt_tokensnúmero de tokens de entrada (o seu prompt completo)
completion_tokensnúmero de tokens de saída (a resposta do modelo)
total_tokenssoma dos tokens de entrada e de saída
cached_tokenstokens de entrada servidos a partir da cache

Um detalhe evita um erro comum: cached_tokens está incluído em prompt_tokens, não somado a este. No exemplo acima, 1.250 tokens entraram no modelo, 800 vieram da cache e apenas 450 foram faturados à taxa total. Se o seu agregador somar ambos os campos, contará em duplicado a parte em cache e inflacionará artificialmente as suas estatísticas de volume.

Duas Escalas para o Mesmo Custo

O custo do pedido é fornecido em duas unidades inteiras. Esta escolha não é arbitrária: expressar frações de cêntimo em números de ponto flutuante introduz erros de arredondamento que se tornam visíveis ao agregar milhões de chamadas. Os inteiros evitam totalmente este problema.

O campo cost_in_usd_ticks conta em “ticks”, com 10 mil milhões de ticks por dólar. O valor 5.000.000.000 no exemplo corresponde, portanto, a 0,50 $, e um milhão de ticks equivale a 0,0001 $. A conversão cabe numa linha:

cost_usd = cost_in_usd_ticks / 10_000_000_000

O campo cost_in_nano_usd conta em nanodólares, com mil milhões de nanodólares por dólar. Os 500.000.000 no exemplo representam o mesmo montante, 0,50 $, e mil nanodólares equivalem a 0,000001 $. A conversão segue a mesma lógica:

cost_usd = cost_in_nano_usd / 1_000_000_000

Ambos os campos descrevem o mesmo montante em escalas diferentes. cost_in_nano_usd é mais intuitivo de manusear, enquanto cost_in_usd_ticks oferece uma precisão ligeiramente superior. Escolha um e mantenha-o consistente em toda a sua cadeia de medição: misturar ambos na mesma agregação é a melhor forma de obter totais inconsistentes.

Construa um Rastreador de Custos

Em produção, um único acumulador é suficiente para transformar estes campos num painel de controlo. A classe abaixo regista cada objeto usage e expõe o custo cumulativo juntamente com a taxa de cache:

class CostTracker:
    def __init__(self):
        self.total_nano_usd = 0
        self.requests = 0
        self.input_tokens = 0
        self.output_tokens = 0
        self.cached_tokens = 0

    def record(self, usage):
        self.total_nano_usd += usage.get("cost_in_nano_usd", 0)
        self.requests += 1
        self.input_tokens += usage.get("prompt_tokens", 0)
        self.output_tokens += usage.get("completion_tokens", 0)
        self.cached_tokens += usage.get("cached_tokens", 0)

    @property
    def total_cost_usd(self):
        return self.total_nano_usd / 1_000_000_000

    @property
    def cache_rate(self):
        if self.input_tokens == 0:
            return 0
        return self.cached_tokens / self.input_tokens

De seguida, associe limiares a total_cost_usd. Um primeiro limiar a 80% do orçamento diário dispara um alerta informativo para a equipa técnica; um segundo a 95% torna-se um alerta crítico que exige decisão humana; aos 100%, a aplicação corta automaticamente os pedidos não críticos — trabalhos em lote, pré-cálculos, enriquecimentos diferidos — e permite apenas o tráfego direto do utilizador. Esta degradação graciosa é preferível a uma paragem súbita do serviço num dia de pico.

Analise a Taxa de Cache

A propriedade cache_rate merece um painel de controlo próprio, pois reflete diretamente a qualidade da estrutura do seu prompt.

Taxa de CacheInterpretação
0 a 20%sem cache eficaz, reveja a estrutura do prompt
20 a 50%cache parcial, verifique a estabilidade dos seus prompts de sistema
50 a 80%boa taxa para conversas
80% ou maisexcelente, típico para prompts longos e estáveis

Uma taxa que cai abruptamente de uma semana para a outra é quase sempre sinal de uma implementação que introduziu uma variável no início do prompt. A próxima lição detalha o mecanismo; por agora, lembre-se de que este valor é um indicador de regressão tão valioso quanto uma taxa de erro.

Preços a partir de 5 de agosto de 2026 — os preços evoluem regularmente: antes de qualquer cálculo orçamental, consulte a tabela de preços atual na página oficial de modelos e preços da xAI.

Pontos-chave

  • Cada resposta da API contém um objeto usage com detalhes de tokens e custo
  • cost_in_usd_ticks: 10 mil milhões de ticks = 1 USD
  • cost_in_nano_usd: 1 mil milhão de nano-USD = 1 USD
  • O campo cached_tokens mede a eficiência da cache
  • Construa um rastreador de custos em produção com alertas de orçamento