Saltar para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt

Use this file to discover all available pages before exploring further.

​
Visão Geral

Além do cache semântico da plataforma da TokenLab, muitos provedores de IA oferecem seu próprio recurso de cache de prompt. Este é um mecanismo de cache separado que opera no nível do provedor (Anthropic, OpenAI, DeepSeek, etc.).
Dois Tipos de Cache
TipoOndeComo FuncionaCusto
Cache da PlataformaTokenLabCorrespondência por similaridade semântica10% do preço normal
Cache do ProvedorUpstream (Anthropic/OpenAI/etc)Correspondência exata de prefixoTaxas de token com desconto
Estes são mutualmente exclusivos: se houver um hit no cache da plataforma, nenhuma chamada upstream é feita, portanto, o cache do provedor não se aplica.

​
Como Funciona o Cache de Prompt do Provedor

O cache de prompt do provedor armazena a representação processada do prefixo do seu prompt nos servidores do provedor. Quando você envia uma solicitação com o mesmo prefixo, o provedor pode pular o reprocessamento desses tokens.

​
Principais Características

  • Baseado em prefixo: Apenas o início do seu prompt pode ser armazenado em cache
  • Correspondência exata: Requer tokens idênticos (não similaridade semântica)
  • Tempo limitado: As entradas de cache expiram (geralmente entre 5 a 60 minutos)
  • Automático: Nenhuma configuração especial é necessária
Request 1: [System prompt + Context A + Question 1]
           ^^^^^^^^^^^^^^^^^^^^^^^^
           This prefix gets cached

Request 2: [System prompt + Context A + Question 2]
           ^^^^^^^^^^^^^^^^^^^^^^^^
           Cache hit! Only Question 2 is processed

​
Provedores Suportados

ProvedorDesconto de Leitura de CacheCusto de Escrita de CacheTokens Mínimos
Anthropic90% de desconto25% de prêmio1024
OpenAI50% de descontoIgual à entrada1024
DeepSeek90% de descontoIgual à entrada64
Google75% de desconto25% de acréscimo32768
Os descontos são aplicados automaticamente. A TokenLab repassa o preço de cache do provedor para você.

​
Identificando o Uso do Cache

​
Nos Logs de Uso

Seus logs de uso mostram o detalhamento detalhado dos tokens de cache:
CampoDescrição
cacheReadTokensTokens servidos pelo cache do provedor (com desconto)
cacheWriteTokensTokens gravados no cache (para solicitações futuras)
nonCachedPromptTokensTokens processados sem cache

​
Nas Transações

As transações exibem um rótulo de Provider Cache quando o cache upstream foi utilizado:
  • Cache (azul céu): Hit de cache semântico da plataforma - desconto de 90%
  • Provider Cache (azul-petróleo): Hit de cache de prompt upstream - taxas com desconto

​
Exemplo de Cálculo de Custo

Para uma solicitação com 10.000 tokens de entrada para o Claude (Anthropic): Sem cache: 
10,000 tokens × $3.00/1M = $0.030
Com cache do provedor (8.000 em cache + 2.000 novos): 
Cache read:  8,000 tokens × $0.30/1M = $0.0024  (90% off)
Cache write: 2,000 tokens × $3.75/1M = $0.0075
Total: $0.0099 (67% de economia)

​
Melhores Práticas

Coloque seu prompt de sistema e contexto estático no início de suas mensagens. Isso maximiza o potencial de hit do cache.
Envie solicitações com o mesmo prefixo em intervalos próximos para se beneficiar do cache antes que ele expire.
Certifique-se de que seu prefixo passível de cache atenda ao mínimo do provedor (ex: 1024 tokens para Anthropic/OpenAI).
Verifique as estatísticas de uso no seu dashboard para ver as taxas de hit de cache e economia.

​
Cache da Plataforma vs Cache do Provedor

AspectoCache da PlataformaCache do Provedor
CorrespondênciaSimilaridade semânticaCorrespondência exata de prefixo
Custo10% do preço normalTaxas com desconto
LatênciaInstantânea (~1ms)Reduzida (pula o processamento)
ControleConfigurações do dashboardAutomático
EscopoEntre usuários (opcional)Por chave de API

​
Quando Cada Um se Aplica

Request arrives
    │
    ▼
┌─────────────────────┐
│ Platform Cache Hit? │
└─────────────────────┘
    │ Yes              │ No
    ▼                  ▼
┌─────────┐    ┌─────────────────────┐
│ Return  │    │ Call Upstream API   │
│ Cached  │    └─────────────────────┘
│ (10%)  │            │
└─────────┘            ▼
               ┌─────────────────────┐
               │ Provider Cache Hit? │
               └─────────────────────┘
                   │ Yes        │ No
                   ▼            ▼
               Discounted    Full Price
               Token Rate    Token Rate

​
Verificando o Status do Cache

​
Headers de Resposta

X-Cache-Status: HIT           # Hit de cache da plataforma
X-Cache-Status: MISS          # Sem cache da plataforma
X-Upstream-Cache-Read: 8000   # Tokens de leitura de cache do provedor
X-Upstream-Cache-Write: 2000  # Tokens de escrita de cache do provedor

​
API de Uso

Consulte seus logs de uso para ver o detalhamento do cache: 
GET /v1/usage/logs is currently not a public endpoint.
Use X-Cache-Status and X-Upstream-Cache-* response headers, plus the dashboard usage page.
A resposta inclui: 
{
  "promptTokens": 10000,
  "cacheReadTokens": 8000,
  "cacheWriteTokens": 2000,
  "nonCachedPromptTokens": 0,
  "completionTokens": 500,
  "cost": 0.0099
}

​
FAQ

O cache do provedor é automático e não pode ser desativado. No entanto, ele só traz benefícios (custos menores), portanto não há motivo para desativá-lo.
Motivos comuns:
  • O prefixo mudou (mesmo que por um único token)
  • O cache expirou (geralmente entre 5 a 60 minutos)
  • Prefixo muito curto (abaixo do mínimo de tokens)
  • Chave de API diferente utilizada
Sim! Ao usar suas próprias chaves de API (BYOK), o cache do provedor funciona da mesma maneira. O cache está vinculado à sua chave de API upstream.
  1. Use o cache semântico da plataforma para consultas semelhantes repetidas
  2. Estruture os prompts com conteúdo estático primeiro
  3. Mantenha os prompts de sistema consistentes entre as solicitações
  4. Envie solicitações relacionadas em sucessão rápida