Ignus Code
Docs
Prompt Cache

Prompt Cache

Economize até 90% em prompts com prefixos repetidos.

O Prompt Cache evita que o modelo reprocesse partes idênticas do prompt a cada requisição. Quando o mesmo prefixo aparece em múltiplas chamadas, apenas os tokens novos são cobrados.

Como funciona

Requisição 1:  [system prompt 500 tokens] + [mensagem 50 tokens]  → cobra 550 tokens
Requisição 2:  [system prompt 500 tokens] + [mensagem 60 tokens]  → cobra ~60 tokens (prefixo em cache)
Requisição 3:  [system prompt 500 tokens] + [mensagem 45 tokens]  → cobra ~45 tokens (prefixo em cache)

O cache é especialmente útil para:

  • System prompts grandes (instruções, personas, regras de negócio)
  • Documentos longos passados como contexto
  • Few-shot examples repetidos em múltiplas chamadas

Provedores com suporte

ProvedorCache automático
Anthropic (Claude)✅ Sim
OpenAI✅ Sim (automático no GPT-4o)
Google (Gemini)✅ Sim
Meta / Mistral / DeepSeek❌ Não

Uso com Anthropic (Claude)

Para ativar o cache no Claude, marque as partes do prompt com cache_control:

cache_anthropic.py
from openai import OpenAI
 
client = OpenAI(
    base_url="https://proxy.ignustec.com.br/v1",
    api_key="sk_ic_xxxxxxxxxxxxxxxxxxxx",
)
 
SYSTEM_PROMPT = """
Você é um especialista jurídico brasileiro com 20 anos de experiência...
[prompt muito longo com 2000+ tokens]
"""
 
# Primeira requisição — cria o cache
response = client.chat.completions.create(
    model="claude-sonnet-4",
    messages=[
        {
            "role": "system",
            "content": [
                {
                    "type": "text",
                    "text": SYSTEM_PROMPT,
                    "cache_control": {"type": "ephemeral"},
                }
            ],
        },
        {"role": "user", "content": "Pergunta 1..."},
    ],
)
 
# Segunda requisição — usa o cache (muito mais barato)
response2 = client.chat.completions.create(
    model="claude-sonnet-4",
    messages=[
        {
            "role": "system",
            "content": [
                {
                    "type": "text",
                    "text": SYSTEM_PROMPT,
                    "cache_control": {"type": "ephemeral"},
                }
            ],
        },
        {"role": "user", "content": "Pergunta 2..."},
    ],
)

Uso com OpenAI

O GPT-4o aplica cache automaticamente para prompts com mais de 1.024 tokens de prefixo comum. Não é necessária nenhuma configuração adicional.

cache_openai.py
# O cache é aplicado automaticamente pelo Ignus Code
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "...system prompt longo..."},
        {"role": "user",   "content": "Pergunta do usuário"},
    ],
)
 
# Verifique tokens em cache no campo usage
print(response.usage.prompt_tokens_details)
# {'cached_tokens': 1024, 'audio_tokens': 0}

Verificar o uso do cache

A resposta inclui informações de cache no campo usage:

{
  "usage": {
    "prompt_tokens": 1100,
    "completion_tokens": 85,
    "total_tokens": 1185,
    "prompt_tokens_details": {
      "cached_tokens": 1024
    }
  }
}

O cache tem validade de 5 minutos para a maioria dos provedores. Para uso eficiente, mantenha o prefixo idêntico entre requisições e envie-as com frequência.

StreamingErros