Cache de Prompt do GPT

​

Início rápido

curl https://aihubmix.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -d '{
    "model": "gpt-5.6-sol",
    "prompt_cache_key": "my-app-report-assistant-v1",
    "messages": [
      {
        "role": "system",
        "content": "You are a meticulous assistant for analyzing quarterly financial reports... [coloque aqui instruções longas fixas ou material de referência, ≥1024 tokens]"
      },
      {
        "role": "user",
        "content": "Summarize the key figures in one sentence."
      }
    ]
  }'

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AIHUBMIX_API_KEY"],  # A chave é lida da variável de ambiente
    base_url="https://aihubmix.com/v1",
)

long_context = "You are a meticulous assistant for analyzing quarterly financial reports... [instruções longas fixas ou material de referência, ≥1024 tokens]"

# Duas requisições consecutivas com o mesmo prefixo; a segunda acerta o cache
for i in range(2):
    completion = client.chat.completions.create(
        model="gpt-5.6-sol",
        prompt_cache_key="my-app-report-assistant-v1",
        messages=[
            {"role": "system", "content": long_context},
            {"role": "user", "content": "Summarize the key figures in one sentence."},
        ],
    )
    print(completion.usage.prompt_tokens_details)

// 1ª chamada: sem acerto
"prompt_tokens_details": {"audio_tokens": 0, "cached_tokens": 0}

// 2ª chamada: o prefixo acerta o cache
"prompt_tokens_details": {"audio_tokens": 0, "cached_tokens": 2816}

​

Cobrança do cache

​

Como o cache é ativado automaticamente

1. Quando o prefixo atinge 1.024 tokens e um prefixo em cache idêntico é encontrado, a parte com acerto é cobrada pelo preço de leitura de cache e a latência do primeiro token diminui;
2. Quando nenhum é encontrado, a requisição é processada como entrada regular e o prefixo é escrito no cache (no GPT-5.6 e posteriores, a escrita é cobrada a 1.25x);
3. O acerto exige que o prefixo seja idêntico byte a byte; qualquer alteração em um ponto do prefixo invalida todo o cache a partir daquela posição.

• Instruções de sistema longas e fixas ou grande quantidade de exemplos few-shot
• Material de referência longo citado repetidamente em cenários RAG
• Workflows de agentes com muitas definições de ferramentas (tools)
• Conversas longas de múltiplos turnos em que as mensagens são apenas acrescentadas ao final

​

Parâmetros de cache do GPT-5.6

1. Padrão (modo implicit): mesmo sem nenhum parâmetro de cache, o cache é escrito automaticamente — o sistema define o ponto de quebra automaticamente na posição da mensagem mais recente. No GPT-5.6 e posteriores, as escritas de cache automáticas também são cobradas a 1.25x.
2. Modo implicit + ponto de quebra explícito: além do ponto de quebra automático, é possível definir prompt_cache_breakpoint em um bloco de conteúdo para fixar a fronteira do cache no fim do conteúdo estável; alterações no conteúdo posterior ao ponto de quebra não invalidam o cache do prefixo anterior a ele.
3. Modo explicit: com prompt_cache_options.mode definido como "explicit", apenas os pontos de quebra manuais são usados; se nenhum ponto de quebra for definido, a requisição não usa cache nem gera cobrança de escrita de cache. Texto oficial: “If the conversation contains no explicit breakpoints, the request does not use prompt caching or incur cache-write charges.”

{
  "model": "gpt-5.6-sol",
  "prompt_cache_options": {"mode": "explicit"},
  "messages": [
    {"role": "user", "content": "[conteúdo longo de uso único que não será reutilizado]"}
  ]
}

{
  "model": "gpt-5.6-sol",
  "prompt_cache_key": "my-app-report-assistant-v1",
  "messages": [
    {
      "role": "system",
      "content": [
        {
          "type": "text",
          "text": "[instruções longas fixas ou material de referência, ≥1024 tokens]",
          "prompt_cache_breakpoint": {"mode": "explicit"}
        }
      ]
    },
    {"role": "user", "content": "Summarize the key figures in one sentence."}
  ]
}

• Cada requisição cria no máximo 4 novas escritas de cache; no modo implicit, o ponto de quebra automático ocupa 1 delas;
• O prefixo anterior ao ponto de quebra ainda precisa atingir 1.024 tokens para ser cacheado;
• Na leitura, o prefixo com correspondência mais longa é escolhido entre os 50 pontos de quebra mais recentes;
• Definir um ponto de quebra em um bloco de conteúdo sem suporte retorna 400 invalid_request_error. Chat Completions suporta blocos text / image_url / input_audio / file / refusal; a Responses API suporta blocos input_text / input_image / input_file.

​

Por que o cache não teve acerto

• Prefixo abaixo de 1.024 tokens: requisições abaixo do comprimento mínimo de cache são processadas como entrada regular;
• Conteúdo variável misturado no prefixo: timestamps, IDs de sessão, variáveis de usuário etc. devem ficar depois do conteúdo fixo; qualquer alteração no prefixo invalida o cache a partir daquele ponto;
• Definições ou ordem de tools alteradas: a lista de ferramentas participa do cálculo do prefixo; definições e ordenação devem ser exatamente iguais;
• Parâmetro detail de imagens inconsistente: detail afeta a tokenização das imagens e precisa permanecer o mesmo;
• Schema de saída estruturada alterado: o JSON Schema de response_format participa do cache como prefixo da mensagem de sistema; mudar o schema muda o prefixo;
• reasoning_effort alterado: listado oficialmente entre as causas comuns de menor taxa de acertos de cache (“Changes to reasoning effort”);
• Período de retenção do cache excedido: antes do GPT-5.6, o cache é limpo após 5–10 minutos de inatividade; no GPT-5.6 e posteriores, é mantido por no mínimo 30 minutos;
• prompt_cache_key ausente (GPT-5.6): sem ele, acertos automáticos ainda podem ocorrer, mas o mecanismo de correspondência mais confiável não é usado.

​

Melhores práticas

• Coloque o conteúdo fixo (instruções de sistema, exemplos, material de referência, definições de ferramentas) no início da requisição e o conteúdo que muda a cada turno no final;
• Defina o mesmo prompt_cache_key estável para o tráfego que compartilha o mesmo prefixo, mantendo o tráfego total de cada key em torno de 15 requisições/minuto; acima disso, divida em mais keys por área de negócio;
• Em conversas de múltiplos turnos, apenas acrescente mensagens ao final, sem modificar mensagens do histórico;
• Mantenha tráfego contínuo para requisições com o mesmo prefixo, reduzindo a limpeza do cache;
• Para requisições longas de uso único cujo prefixo não será reutilizado, use o modo explicit para evitar a cobrança de escrita de cache (GPT-5.6 e posteriores);
• Monitore continuamente os acertos por meio de usage.prompt_tokens_details.cached_tokens.

​

Perguntas Frequentes (FAQ)

​

O cache de prompts do GPT precisa ser ativado manualmente?

​

Como é calculada a taxa de escrita de cache do GPT-5.6? Como evitar taxas de escrita desnecessárias?

​

Por quanto tempo o cache é mantido?

​

Qual é a diferença entre o ponto de quebra explícito do GPT-5.6 e o cache_control do Claude?

​

O cache afeta o conteúdo da saída?

​

Referências oficiais

• Anúncio de lançamento do GPT-5.6: regra de cobrança de escrita de cache a 1.25x e desconto de 90% na leitura
• Guia de cache de prompts: mecanismo, parâmetros, campos de usage e limites
• OpenAI Pricing: preços oficiais de cada modelo
• Documentação do modelo GPT-5.6: janela de contexto e limiar de cobrança de contexto longo