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

Cache Automático da API

Aula 9 de 14 Atualizada a 29 de julho de 2026 Avancado
Nesta página
  1. O cache como alavanca de redução de custos
  2. Como funciona o cache
  3. O cabeçalho x-grok-conv-id
  4. Verificar a eficiência do cache
  5. Pontos-chave

O cache como alavanca de redução de custos

O cache automático tem o maior impacto na sua fatura, para melhor ou para pior. Com muitos fornecedores, é necessário declará-lo explicitamente no pedido, marcar os blocos a reter e gerir o seu ciclo de vida. A xAI adotou uma abordagem diferente: o cache aplica-se automaticamente a todos os pedidos, sem parâmetros nem anotações. Não precisa de ativar nada, mas tem tudo a ganhar ao compreender o que o desencadeia, pois um prompt mal estruturado nunca beneficia dele e paga o preço total sobre toda a sua entrada.

5–7×
Mais barato na entrada em cache
$0.20
Por M em cache no grok-4.3
UUID
Cabeçalho x-grok-conv-id
Auto
Ativação sem configuração

Como funciona o cache

O cache opera sobre os tokens de entrada e apenas sobre estes: a geração da resposta é sempre faturada à tarifa standard. Quando o início do seu prompt reproduz exatamente o início de um prompt processado anteriormente, a parte idêntica é servida a partir do cache à tarifa reduzida, e apenas a nova parte é faturada à tarifa standard.

Três famílias de aplicações beneficiam imediatamente. Em primeiro lugar, uma conversa: o prompt do sistema e todas as trocas anteriores são rigorosamente idênticos de uma chamada para a outra, mudando apenas a última pergunta, pelo que a taxa de cache aumenta naturalmente à medida que a troca se prolonga. Em seguida, um prompt de contexto fixo — um contrato, um manual técnico, um repositório de produtos seguido de uma pergunta variável — vê o seu bloco de documentos colocado em cache a partir da segunda chamada. Por fim, um pipeline RAG mantém instruções de sistema constantes; apenas o contexto recuperado muda e, se o colocar após as instruções, o prefixo permanece colocável em cache.

Na grelha de preços da xAI, a diferença é considerável. No grok-4.3 e no grok-4.20-0309, um milhão de tokens de entrada em cache custa $0.20 contra $1.25 à tarifa standard. No grok-4.5, o mesmo milhão fica por $0.30 em vez de $2.00. Por outras palavras, um prefixo estável de 5.000 tokens reutilizado mil vezes por dia custa-lhe cinco a sete vezes menos do que um prompt reconstruído a cada chamada — para um resultado estritamente idêntico.

O cabeçalho x-grok-conv-id

Para ajudar a infraestrutura a associar pedidos que pertencem ao mesmo contexto, a API aceita um cabeçalho dedicado:

curl -X POST "https://api.x.ai/v1/chat/completions" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "x-grok-conv-id: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.20",
    "messages": [...]
  }'

O cabeçalho x-grok-conv-id espera um UUID v4. A regra de utilização é simples: um identificador por conversa ou fluxo de processamento, reutilizado para todas as chamadas que dele façam parte. Isto sinaliza que estes pedidos estão ligados, o que aumenta a probabilidade de reutilização do cache. O erro comum é gerar o UUID no momento da chamada em vez da abertura da sessão — cada turno recebe então um identificador diferente e o benefício desaparece. Gere-o uma vez, guarde-o com o estado da conversa:

import uuid

# Um UUID por conversa
conv_id = str(uuid.uuid4())

# Utilize o mesmo UUID para todos os turnos da conversa
headers = {
    "Authorization": f"Bearer {api_key}",
    "x-grok-conv-id": conv_id,
    "Content-Type": "application/json"
}

Verificar a eficiência do cache

Nada supera a medição. O campo cached_tokens no objeto usage, abordado na lição anterior, indica-lhe exatamente o que foi servido a partir do cache:

{
  "usage": {
    "prompt_tokens": 5000,
    "cached_tokens": 4200,
    "completion_tokens": 300
  }
}

Aqui, 4.200 tokens de 5.000 provêm do cache, uma taxa de 84%; apenas 800 tokens foram faturados à tarifa standard. Habitue-se a verificar esta razão numa amostra de pedidos reais após cada implementação: se vir uma taxa próxima de zero numa aplicação conversacional, algo varia no início do prompt, e a próxima lição mostrar-lhe-á o quê.

Pontos-chave

  • O cache é automático: não é necessária configuração
  • Utilize o cabeçalho x-grok-conv-id com um UUID v4 para agrupar pedidos ligados
  • O campo cached_tokens no objeto usage indica o número de tokens servidos a partir do cache
  • A entrada em cache custa 5 a 7 vezes menos: $0.20/M no grok-4.3, $0.30/M no grok-4.5
  • Quanto mais estável for o seu prompt no início da sequência, maior será a taxa de cache