Cache Automático da API
Nesta página
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.
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-idcom um UUID v4 para agrupar pedidos ligados - O campo
cached_tokensno objetousageindica 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