Cache de Prompt do Claude

curl https://aihubmix.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: AIHUBMIX_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "stream": true,
    "model": "claude-opus-4-20250514",
    "max_tokens": 20000,
    "system": [
      {
        "type": "text",
        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style."
      },
      {
        "type": "text",
        "text": "Pride and Prejudice by Jane Austen... [Place complete text content here]",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "thinking": {
      "type": "enabled",
      "budget_tokens": 16000
    },
    "messages": [
      {
        "role": "user",
        "content": "Analyze the major themes in Pride and Prejudice."
      }
    ]
  }'

import os
import anthropic

client = anthropic.Anthropic(
    api_key="sk-***", # Replace with the key you generated in AiHubMix
    base_url="https://aihubmix.com"
)

# Streaming response with caching
with client.messages.stream(
    model="claude-opus-4-20250514",
    max_tokens=20000,
    system=[
        {
            "type": "text",
            "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
        },
        {
            "type": "text",
            "text": "<the entire contents of 'Pride and Prejudice'>",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    thinking={
        "type": "enabled",
        "budget_tokens": 16000
    },
    messages=[
        {"role": "user", "content": "Analyze the major themes in 'Pride and Prejudice'."}
    ]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

# Non-streaming response
message = client.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=20000,
    system=[
        {
            "type": "text",
            "text": "You are an AI assistant tasked with analyzing literary works."
        },
        {
            "type": "text",
            "text": "<the entire contents of 'Pride and Prejudice'>",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[
        {"role": "user", "content": "Analyze the major themes in 'Pride and Prejudice'."}
    ]
)
print(message.content)

import requests

url = "https://aihubmix.com/v1/messages"
headers = {
    "content-type": "application/json",
    "x-api-key": "sk-***", # Replace with the key you generated in AiHubMix
    "anthropic-version": "2023-06-01"
}
data = {
    "stream": True,
    "model": "claude-opus-4-20250514",
    "max_tokens": 20000,
    "system": [
        {
            "type": "text",
            "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
        },
        {
            "type": "text",
            "text": "<the entire contents of 'Pride and Prejudice'>",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "thinking": {
        "type": "enabled",
        "budget_tokens": 16000
    },
    "messages": [{"role": "user", "content": "Analyze the major themes in 'Pride and Prejudice'."}]
}

response = requests.post(url, headers=headers, json=data, stream=True)

# Check response status
if response.status_code == 200:
    # Process the streaming response
    for line in response.iter_lines():
        if line:
            print(line.decode('utf-8'))
else:
    print(f"Error: {response.status_code}, {response.text}")

{"cache_creation_input_tokens":188086,"cache_read_input_tokens":0,"input_tokens":21,"output_tokens":393}
{"cache_creation_input_tokens":0,"cache_read_input_tokens":188086,"input_tokens":21,"output_tokens":393}

​

Como funciona o cache de prompt

1. O sistema verifica se um prefixo de prompt, até um ponto de quebra de cache especificado, já está cacheado de uma consulta recente.
2. Se encontrado, ele usa a versão cacheada, reduzindo o tempo de processamento e os custos.
3. Caso contrário, processa o prompt completo e cacheia o prefixo assim que a resposta começa. Isso é especialmente útil para:

• Prompts com muitos exemplos
• Grandes quantidades de contexto ou informações de background
• Tarefas repetitivas com instruções consistentes
• Conversas longas com múltiplos turnos

​

Erro comum: escrever no cache mas “só escrever, nunca ler”

​

❌ Forma errada: colocar a pergunta que muda a cada turno antes do ponto de quebra

{
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "请总结这份资料的核心观点。" },                          // ← 每轮会变,却放在断点前
        { "type": "text", "text": "<大文档>", "cache_control": { "type": "ephemeral" } }   // 断点
      ]
    }
  ]
}

​

✅ Forma correta: documento grande primeiro + ponto de quebra + pergunta no final

{
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "<固定不变的大文档/参考资料，≥4096 token>", "cache_control": { "type": "ephemeral" } },  // 断点;前缀恒定
        { "type": "text", "text": "请总结这份资料的核心观点。" }                                                          // ← 每轮变化的问题,放在断点之后
      ]
    }
  ]
}

​

Comparação real (claude-opus-4-6, com alguns segundos de intervalo entre as duas chamadas)

1. Coloque o bloco fixo e grande (documento de referência, contexto longo) bem no início da mensagem user em messages, com o cache_control marcado em seu final, e esse conteúdo não pode mudar nem um caractere;
2. Coloque a pergunta/instrução que muda a cada turno depois do ponto de quebra (após o documento grande na mesma mensagem user, ou em mensagens subsequentes); em conversas de múltiplos turnos, apenas acrescente ao final, sem voltar para modificar mensagens do histórico;
3. Com thinking habilitado, os blocos de thinking dos turnos de assistente anteriores devem ser reenviados sem alteração, caso contrário o prefixo também será quebrado (veja “O que não pode ser cacheado” abaixo);
4. Se um bloco for menor que o limite mínimo de cache (varia de 512 a 4.096 tokens conforme o modelo, veja a seção “Limitações do cache” abaixo), ele não será escrito no cache mesmo marcado com cache_control — isso é comportamento esperado, veja “Limitações do cache” abaixo.

​

Preços

• Tokens de escrita de cache de 5 minutos são 1,25 vezes o preço base dos tokens de entrada
• Tokens de escrita de cache de 1 hora são 2 vezes o preço base dos tokens de entrada
• Tokens de leitura de cache são 0,1 vezes o preço base dos tokens de entrada
• Tokens regulares de entrada e saída são cobrados às taxas padrão da plataforma

​

Como implementar o cache de prompt

​

Modelos suportados

​

Cache automático (cache_control de nível superior)

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "cache_control": {"type": "ephemeral"},
  "system": "You are an AI assistant tasked with analyzing literary works.",
  "messages": [
    {"role": "user", "content": "Analyze the major themes in Pride and Prejudice."}
  ]
}

​

Estruturando seu prompt

​

Limitações do cache

• “ephemeral”: Vida útil padrão de 5 minutos
• Cache de 1 hora: Defina "ttl": "1h" em cache_control, para cenários que requerem duração de cache mais longa

​

Duração de cache de 1 hora

curl https://aihubmix.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: AIHUBMIX_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-20250514",
    "system": [
      {
        "type": "text",
        "text": "Long-term instructions...",
        "cache_control": {
          "type": "ephemeral",
          "ttl": "1h"
        }
      }
    ],
    "messages": [...]
  }'

{
  "cache_control": {
    "type": "ephemeral",
    "ttl": "5m" | "1h"
  }
}

​

Quando usar cache de 1 hora

• Processamento em lote: Processar grandes volumes de requisições com prefixos comuns
• Sessões de longa duração: Conversas que requerem manutenção de contexto por períodos prolongados
• Análise de documentos grandes: Múltiplos tipos diferentes de análise no mesmo documento
• Q&A em codebase: Múltiplas consultas no mesmo codebase por períodos prolongados

​

Misturando diferentes TTLs

{
  "system": [
    {
      "type": "text", 
      "text": "Long-term instructions...",
      "cache_control": {
        "type": "ephemeral",
        "ttl": "1h"
      }
    },
    {
      "type": "text",
      "text": "Short-term context...", 
      "cache_control": {
        "type": "ephemeral",
        "ttl": "5m"
      }
    }
  ]
}

​

O que pode ser cacheado

• Ferramentas: Definições de ferramentas no array tools
• Mensagens de sistema: Blocos de conteúdo no array system
• Mensagens: Blocos de conteúdo no array messages.content, tanto para turnos de usuário quanto de assistente
• Imagens & Documentos: Blocos de conteúdo no array messages.content, em turnos de usuário
• Uso de ferramentas e resultados de ferramentas: Blocos de conteúdo no array messages.content, em turnos de usuário e assistente

​

O que não pode ser cacheado

• Blocos de thinking não podem ser cacheados diretamente com cache_control. Não entanto, blocos de thinking PODEM ser cacheados junto com outro conteúdo quando aparecem em turnos anteriores de assistente. Quando cacheados desta forma, eles CONTAM como tokens de entrada quando lidos do cache.
• Sub-blocos de conteúdo (como citações) por si só não podem ser cacheados diretamente. Em vez disso, cacheie o bloco de nível superior.
• Blocos de texto vazios não podem ser cacheados.

​

Rastreando desempenho do cache

• cache_creation_input_tokens: Número de tokens escritos no cache ao criar uma nova entrada.
• cache_read_input_tokens: Número de tokens recuperados do cache para esta requisição.
• input_tokens: Número de tokens de entrada que não foram lidos do cache nem usados para criar um cache.

​

Melhores práticas para cache eficaz

• Cacheie conteúdo estável e reutilizável como instruções de sistema, informações de background, contextos grandes ou definições frequentes de ferramentas.
• Coloque o conteúdo cacheado no início do prompt para melhor desempenho.
• Use pontos de quebra de cache estrategicamente para separar diferentes seções de prefixo cacheáveis.
• Analise regularmente as taxas de acerto do cache e ajuste sua estratégia conforme necessário.
• Para conteúdo de longo prazo, considere usar cache de 1 hora para melhor eficiência de custo.

​

Otimizando para diferentes casos de uso

• Agentes conversacionais: Reduza custo e latência para conversas estendidas, especialmente aquelas com instruções longas ou documentos enviados.
• Assistentes de codificação: Melhore o autocompletar e Q&A em codebase mantendo seções relevantes ou uma versão resumida do codebase no prompt.
• Processamento de documentos grandes: Incorpore material longo completo incluindo imagens em seu prompt sem aumentar a latência de resposta.
• Conjuntos de instruções detalhadas: Compartilhe listas extensivas de instruções, procedimentos e exemplos para ajustar finamente as respostas do Claude. Desenvolvedores frequentemente incluem um exemplo ou dois no prompt, mas com cache de prompt você pode obter desempenho ainda melhor incluindo 20+ exemplos diversificados de respostas de alta qualidade.
• Uso agêntico de ferramentas: Aumente o desempenho para cenários envolvendo múltiplas chamadas de ferramentas e mudanças iterativas de código, onde cada etapa tipicamente requer uma nova chamada de API.
• Converse com livros, papers, documentação, transcrições de podcasts e outros conteúdos longos: Dê vida a qualquer base de conhecimento incorporando o(s) documento(s) inteiro(s) no prompt e deixando os usuários fazerem perguntas.

​

Solucionando problemas comuns

• Garanta que seções cacheadas sejam idênticas e marcadas com cache_control nos mesmos locais em todas as chamadas
• Verifique se as chamadas são feitas dentro da vida útil do cache (5 minutos ou 1 hora)
• Verifique que tool_choice e uso de imagem permanecem consistentes entre chamadas
• Valide que está cacheando pelo menos o número mínimo de tokens
• Embora o sistema tente usar conteúdo previamente cacheado em posições anteriores a um ponto de quebra de cache, você pode usar um parâmetro cache_control adicional para garantir a busca no cache em porções anteriores do prompt, o que pode ser útil para consultas com listas muito longas de blocos de conteúdo

​

Armazenamento e compartilhamento de cache

• Isolamento da Organização: Os caches são isolados entre organizações. Organizações diferentes nunca compartilham caches, mesmo se usarem prompts idênticos.
• Correspondência Exata: Acertos de cache requerem segmentos de prompt 100% idênticos, incluindo todo texto e imagens até e incluindo o bloco marcado com cache_control. O mesmo bloco deve ser marcado com cache_control durante as leituras e criação do cache.
• Geração de Tokens de Saída: O cache de prompt não tem efeito na geração de tokens de saída. A resposta que você recebe será idêntica ao que você obteria se o cache de prompt não fosse usado.

​

Habilitando o cache do Claude em clientes / plataformas

​

Dify (via plugin Aihubmix)

1. Envolva o prompt a ser cacheado (prompt de sistema fixo / contexto longo) com <cache>…</cache>; o plugin converte automaticamente esse ponto em um ponto de quebra cache_control;
2. Nos parâmetros do modelo, defina o “limite de cache automático para mensagens grandes” como um inteiro positivo: o cache só é realmente escrito quando o conteúdo atinge esse limite de tokens (ainda sujeito à restrição de cache mínimo da seção “Limitações do cache” abaixo: 4096 tokens para Opus 4.5/4.6, Haiku 4.5); definir 0 ou deixar em branco desativa.

​

Cherry Studio

1. Clique na engrenagem à direita do nome do provedor Aihubmix para abrir as “API Settings”:

2. Configure os três itens a seguir, e o cliente injetará automaticamente o cache_control para o Claude com base neles:

• Cache Token Threshold: o ponto de quebra de cache só é injetado quando o conteúdo ultrapassa esse número de tokens (defina um número positivo para ativar, 0 ou em branco para desativar);
• Cache System Message: quando ativado, marca um ponto de quebra de cache na mensagem system (adequado para cachear um prompt de sistema longo e fixo);
• Cache Last N Messages: marca um ponto de quebra de cache nas N mensagens mais recentes (adequado para cache rolante em conversas de múltiplos turnos).

​

Perguntas Frequentes (FAQ)

​

Por que o cache é escrito (cache_creation_input_tokens alto) mas nunca lido (cache_read_input_tokens igual a 0)?

​

Quantos tokens no mínimo o cache precisa?

​

Quanto tempo dura o cache? Dá para mudar para 1 hora?

​

Como habilitar o cache no Dify / Cherry Studio?

​

Suporte em Diferentes Modelos

• O suporte ao Cache de Prompt depende do próprio modelo.
• Se o modelo inerentemente suporta cache sem exigir declarações explícitas de parâmetros, pode ser suportado através de encaminhamento compatível com OpenAI.
• A OpenAI suporta Cache de Prompt por padrão, com ativação automática (prefixo ≥1024 tokens). Nos modelos anteriores ao GPT-5.6, a escrita de cache não tem cobrança adicional e o cache é limpo automaticamente após 5-10 minutos de inatividade; no GPT-5.6 e posteriores, a escrita de cache é cobrada a 1,25 vezes o preço de entrada, a leitura a 0,1 vez, o cache é mantido por no mínimo 30 minutos e há suporte a pontos de quebra de cache explícitos. Detalhes em Cache de Prompt do GPT.
• O Claude requer a declaração nativa cache_control: { type: "ephemeral" }. A taxa de cache é 1,25 vezes o custo padrão de entrada (5 minutos) ou 2 vezes (1 hora), a recuperação de tokens cacheados custa 0,1 vez a taxa normal, com ciclo de vida de 5 minutos ou 1 hora. Detalhes
• Deepseek V3 e R1 suportam cache nativamente. A taxa de cache é igual ao custo padrão de entrada, a recuperação de tokens cacheados custa 0,1 vez a taxa normal. Detalhes
• Suporte a cache implícito do Gemini:
  • Cache Implícito: Habilitado por padrão para todos os modelos Gemini 2.5. Se sua requisição acertar o cache, as economias de custo são aplicadas automaticamente. Esse recurso é efetivo a partir de 8 de maio de 2025. A contagem mínima de tokens de entrada para cache de contexto é 1.024 para Gemini 2.5 Flash e 2.048 para Gemini 2.5 Pro.
  • Dicas para melhorar a taxa de acerto do cache implícito:
    • Tente colocar conteúdo grande e frequentemente reutilizado no início do prompt.
    • Tente enviar requisições com prefixos similares dentro de uma janela curta de tempo.
  • Você pode visualizar o número de tokens com acerto de cache no campo usage_metadata do objeto de resposta.
  • As economias de custo são calculadas com base nos acertos do cache de prefill. Apenas o cache de prefill e o cache de pré-processamento de vídeos do YouTube são elegíveis para cache implícito.