Cache de prompt
O Prompt Caching permite armazenar em cache prefixos de prompt reutilizados, reduzindo o consumo de tokens e a latência das respostas.
Como funciona
Quando sua requisição contém um system prompt longo e repetidamente utilizado ou informações de contexto:
- Primeira requisição — Todos os tokens são processados integralmente e o prefixo do prompt é armazenado em cache
- Requisições seguintes — Ao acertar o cache, os tokens em cache não são cobrados novamente
- Expiração do cache — O cache tem um TTL limitado (geralmente 5 a 10 minutos); após a expiração, é necessário recriá-lo
Suporte a cache
Os recursos de modelo do OfoxAI são fornecidos por provedores de nuvem como AWS Bedrock, Azure OpenAI, Google Cloud, Alibaba Cloud e Volcengine. Modelos que suportam Prompt Caching no provedor de nuvem correspondente também são suportados pelo OfoxAI.
O suporte específico de cache de cada modelo depende da documentação oficial do provedor de nuvem. O OfoxAI encaminha os parâmetros de cache de forma transparente — nenhuma configuração adicional é necessária.
Esta página trata do cache automático / implícito (o modelo reutiliza prefixos repetidos em regime best-effort). Se você precisa criar caches ativamente com acertos determinísticos para grandes contextos reutilizados repetidamente, o Gemini também suporta cache explícito — veja Cache explícito do Gemini (cachedContents).
Como usar
Protocolo OpenAI
O Prompt Caching para modelos OpenAI é automático — é ativado quando prefixos de prompt repetidos são detectados:
# System prompt longo será automaticamente armazenado em cache
SYSTEM_PROMPT = """Você é o assistente de suporte técnico da OfoxAI.
Aqui estão as informações do produto que você precisa conhecer:
- OfoxAI é um LLM Gateway que suporta mais de 100 modelos de linguagem
- Suporta os três principais protocolos: OpenAI / Anthropic / Gemini
- ...
(mais informações do produto omitidas)
"""
# Primeira requisição: system prompt é armazenado em cache
response1 = client.chat.completions.create(
model="openai/gpt-6.1-sol",
messages=[
{"role": "system", "content": SYSTEM_PROMPT},
{"role": "user", "content": "Quais modelos o OfoxAI suporta?"}
]
)
# Segunda requisição: cache acertado, mais rápido e mais barato
response2 = client.chat.completions.create(
model="openai/gpt-6.1-sol",
messages=[
{"role": "system", "content": SYSTEM_PROMPT}, # Cache hit
{"role": "user", "content": "Como configurar o Claude Code?"}
]
)Protocolo Anthropic
Modelos Anthropic suportam controle explícito de cache:
import anthropic
client = anthropic.Anthropic(
base_url="https://api.ofox.io/anthropic",
api_key="<Sua OFOXAI_API_KEY>"
)
response = client.messages.create(
model="anthropic/claude-sonnet-5.5",
max_tokens=1024,
system=[{
"type": "text",
"text": "Você é um assistente profissional. Aqui está a documentação do produto...",
"cache_control": {"type": "ephemeral"} # Habilitar cache explicitamente
}],
messages=[{"role": "user", "content": "Resuma as características do produto"}]
)
# Verificar status do cache
print(f"Tokens escritos no cache: {response.usage.cache_creation_input_tokens}")
print(f"Tokens lidos do cache: {response.usage.cache_read_input_tokens}")Economia de custos
Ao acertar o cache, os tokens armazenados são cobrados pelo preço de leitura de cache, que é menor; a proporção de economia varia conforme o modelo. Alguns modelos também cobram a escrita no cache pelo preço de escrita de cache, que pode ser superior ao preço de entrada normal.
Os preços de leitura e de escrita de cache de cada modelo são os indicados na página do modelo correspondente no Catálogo de modelos.
A economia real depende da taxa de acerto do cache e da política de preços de cada provedor de nuvem. Consulte as estatísticas de uso no painel do OfoxAI para mais detalhes.
Boas práticas
- Coloque textos longos no início — System prompt e conteúdo de base de conhecimento que não mudam devem ficar no começo das messages
- Mantenha o prefixo consistente — Apenas prefixos exatamente idênticos resultam em cache hit
- Projete a estrutura do prompt com cuidado — Separe as partes fixas das partes variáveis
# ✅ Bom design: conteúdo fixo primeiro, conteúdo variável depois
messages = [
{"role": "system", "content": LONG_STATIC_PROMPT}, # Pode ser cacheado
{"role": "user", "content": dynamic_question} # Parte variável
]
# ❌ Design ruim: conteúdo variável misturado com conteúdo fixo
messages = [
{"role": "system", "content": f"Today is {date}. {LONG_PROMPT}"} # Muda todo dia, não pode ser cacheado
]Os acertos de cache podem ser verificados no campo usage da resposta da API. Você também pode acompanhar a taxa de cache hit nas estatísticas de uso do painel do OfoxAI.