Caching

Como o Caching Funciona

Toda requisicao que passa pelo gateway Floopy e verificada contra o cache antes de chegar ao provedor de LLM. Quando ocorre um cache hit, a resposta armazenada e retornada imediatamente — nenhum token e consumido e a latencia cai para milissegundos de um digito.

O caching e aplicado automaticamente com base na sua configuracao. Voce nao precisa alterar o codigo da sua aplicacao.

Niveis de Cache

O Floopy usa tres niveis de caching, verificados em ordem:

Exact Cache

O primeiro nivel realiza uma busca direta no Redis. Se a requisicao recebida for identica byte a byte a uma requisicao anterior (mesmo modelo, mensagens e parametros), a resposta em cache e retornada instantaneamente. Este e o nivel mais rapido com o menor overhead.

As entradas do exact cache expiram com base em um TTL configuravel. Este nivel esta disponivel em todos os planos.

Semantic Cache

Quando o exact cache nao encontra correspondencia, o Floopy verifica o semantic cache. Seu prompt e convertido em um embedding vetorial e comparado com prompts anteriores armazenados no banco de dados vetorial. Se um prompt armazenado for similar o suficiente — acima do limite de similaridade configurado — sua resposta e retornada.

Isso significa que pequenas reformulacoes da mesma pergunta (“Qual e a capital da Franca?” vs. “Me diga a capital da Franca”) podem ser servidas do cache em vez de chamar o provedor novamente.

Advanced Cache

O nivel avancado adiciona agrupamento por contagem de mensagens e pontuacao de similaridade com reconhecimento de tokens. As requisicoes sao agrupadas pelo comprimento da conversa antes da comparacao de similaridade, o que melhora a precisao de correspondencia para conversas com multiplos turnos e reduz falsos positivos.

O advanced cache esta disponivel no plano Pro e superiores.

Fluxo de Decisao do Cache

O diagrama a seguir mostra o caminho completo de decisao para toda requisicao com caching habilitado:

graph TD
    A[Request with Floopy-Cache-Enabled: true] --> B[Normalize Prompt]
    B --> C[Exact Cache Lookup in Redis]
    C -->|Hit + Bucket Full| D[Return Random Cached Response]
    C -->|Hit + Bucket Not Full| E[Continue to Provider, Store Additional Response]
    C -->|Miss| F[Semantic Cache Lookup in Qdrant]
    F -->|Hit above threshold| D
    F -->|Miss| G{floopy-cache-advanced: true?}
    G -->|Yes| H[Advanced Cache: Embedding + Bucketed Search]
    H -->|Hit| D
    H -->|Miss| I[Continue to Provider]
    G -->|No| I
    I --> J[Provider Response]
    J --> K[Store in Cache Async]

O prompt e primeiro normalizado — espacos em branco sao removidos, e quaisquer chaves listadas em Floopy-Cache-Ignore-Keys sao removidas do corpo da requisicao antes de computar a chave de cache. Isso garante que campos irrelevantes como timestamps ou IDs de requisicao nao causem cache misses.

Bucket Max Size

Quando Floopy-Cache-Bucket-Max-Size e definido (ex.: 3), cada chave de cache pode armazenar multiplas respostas distintas em vez de apenas uma. Isso proporciona variedade de respostas enquanto ainda economiza custos — particularmente util para prompts criativos ou nao-deterministicos onde voce deseja saidas diversas.

A logica de bucketing funciona da seguinte forma:

• Bucket nao cheio — Se o bucket tem menos respostas do que o tamanho maximo configurado, a requisicao continua para o provedor normalmente. A nova resposta e adicionada ao bucket junto com as respostas em cache existentes.
• Bucket cheio — Se o bucket ja contem o numero maximo de respostas, uma resposta aleatoria e selecionada do bucket e retornada imediatamente. Nenhuma chamada ao provedor e feita, economizando tanto custo quanto latencia.

Por exemplo, com Floopy-Cache-Bucket-Max-Size: 3, as tres primeiras requisicoes identicas todas vao para o provedor, e cada resposta e armazenada. A partir da quarta requisicao, uma das tres respostas armazenadas e retornada aleatoriamente.

Referencia Rapida de Headers de Cache

Economia de Custo e Latencia

Respostas em cache sao gratuitas — nenhum token e cobrado pelo provedor upstream. Para aplicacoes com consultas repetitivas ou similares, o caching pode reduzir custos em 30-70% dependendo dos padroes de trafego.

A latencia para um cache hit e tipicamente inferior a 10ms, comparada a 500ms-3s para uma chamada ao vivo ao provedor. Essa melhoria e especialmente perceptivel para aplicacoes voltadas ao usuario onde o tempo de resposta importa.

Metricas do Dashboard

A secao de Caching do dashboard fornece visibilidade em tempo real sobre o desempenho do cache:

• Taxa de hit ao longo do tempo — um grafico mostrando a porcentagem de requisicoes servidas do cache, detalhada por nivel.
• Tokens economizados — o numero total de tokens que teriam sido consumidos sem caching.
• Latencia economizada — tempo acumulado economizado ao retornar respostas em cache em vez de chamar o provedor.
• Pares mais cacheados — os pares prompt-resposta mais frequentemente cacheados, para que voce entenda o que impulsiona a eficiencia do seu cache.

Use essas metricas para ajustar seus limites de similaridade e configuracoes de TTL para o melhor equilibrio entre frescor e economia.

Configuracao

Voce pode habilitar e configurar o caching por API key ou no nivel da organizacao em Settings. As opcoes principais incluem:

• Habilitar/desabilitar cada nivel de cache independentemente.
• TTL — por quanto tempo as entradas do exact cache permanecem validas.
• Limite de similaridade — a pontuacao minima de similaridade necessaria para um semantic cache hit (valores mais altos exigem correspondencias mais proximas).

Headers de Controle de Cache

Voce pode controlar o comportamento do caching por requisicao usando headers. Estes sobrescrevem a configuracao padrao da API key ou organizacao.

import { OpenAI } from "openai";

const client = new OpenAI({
  baseURL: "https://api.floopy.ai/v1",
  apiKey: process.env.FLOOPY_API_KEY,
});

const response = await client.chat.completions.create(
  {
    model: "gpt-4o",
    messages: [{ role: "user", content: "What is the capital of France?" }],
  },
  {
    headers: {
      "Floopy-Cache-Enabled": "true",
      "Floopy-Cache-Bucket-Max-Size": "3",
      "Floopy-Cache-Seed": "deterministic-seed-abc",
      "Floopy-Cache-Ignore-Keys": "timestamp,request_id",
      "floopy-cache-advanced": "true",
      "cache-control": "max-age=3600",
    },
  },
);

console.log(response.choices[0].message.content);

from openai import OpenAI
import os

client = OpenAI(
    base_url="https://api.floopy.ai/v1",
    api_key=os.environ["FLOOPY_API_KEY"],
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "What is the capital of France?"}],
    extra_headers={
        "Floopy-Cache-Enabled": "true",
        "Floopy-Cache-Bucket-Max-Size": "3",
        "Floopy-Cache-Seed": "deterministic-seed-abc",
        "Floopy-Cache-Ignore-Keys": "timestamp,request_id",
        "floopy-cache-advanced": "true",
        "cache-control": "max-age=3600",
    },
)

print(response.choices[0].message.content)

curl https://api.floopy.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLOOPY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Floopy-Cache-Enabled: true" \
  -H "Floopy-Cache-Bucket-Max-Size: 3" \
  -H "Floopy-Cache-Seed: deterministic-seed-abc" \
  -H "Floopy-Cache-Ignore-Keys: timestamp,request_id" \
  -H "floopy-cache-advanced: true" \
  -H "cache-control: max-age=3600" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "What is the capital of France?"}]
  }'

Requisitos de Plano