Cache de respuestas

AI Gateway puede guardar respuestas completas en Redis y reutilizarlas para solicitudes idénticas, sin contactar al proveedor. Está desactivado por defecto y el cliente debe habilitarlo en cada solicitud.

Para conocer la reutilización de solicitudes del proveedor y los contadores de tokens, consulta Prompt caching del proveedor.

Habilitar por solicitud

Envía los headers de cache en la solicitud de inferencia:

curl -X POST $BASE/v1/chat/completions \
  -H "Authorization: Bearer sk-..." \
  -H "x-unified-cache: true" -H "x-unified-cache-ttl: 600" \
  -H "content-type: application/json" -d '{
    "model": "general",
    "messages": [{ "role": "user", "content": "Capital of France?" }]
  }'

La primera llamada es un cache miss: el proveedor genera la respuesta y AI Gateway la almacena. Las llamadas idénticas dentro del TTL son cache hits atendidos desde Redis. Cada hit se registra en gateway_operations con cache_hit = true y costo cero.

Cómo se define el alcance de las entradas

• Por virtual key. El espacio de nombres de la cache es la identificación de la virtual key, por lo que una clave nunca ve las respuestas almacenadas en cache de otra clave.
• La master key nunca se almacena en cache. El tráfico del operador siempre va al proveedor, incluso con el header configurado; esto evita que las llamadas administrativas y de prueba contaminen las cachés de los clientes.
• Por solicitud exacta. La clave se deriva del tipo de llamada, el espacio de nombres y un hash de la solicitud canonical, por lo que cualquier cambio en el mensaje, el modelo o los parámetros es una entrada diferente.
• Límite de tamaño. Las respuestas de más de 512 KB, como lotes grandes de embeddings, se entregan normalmente pero no se guardan en cache. Su reutilización no compensa el uso de memoria de Redis.
• Sin streaming, herramientas ni estado persistido. Una solicitud solo es elegible si no usa streaming, herramientas ni estado del servidor. Por ejemplo, una llamada a /v1/responses con store: true queda excluida. Tampoco se guardan respuestas a entradas multimodales: el contenido de una URL puede cambiar y los archivos base64 producen claves de cache demasiado grandes. Consulta Streaming y Entradas de contenido.
• Un hit es gratis. Se registra con cost: null y nunca toca los contadores de gasto o TPM de la virtual key; consulta Contabilidad de costos.

Invalidar

Los operadores pueden borrar las entradas almacenadas en cache con la master key:

# Everything
DELETE /admin/cache

# Narrow by call type and/or namespace (a virtual key id)
DELETE /admin/cache?callType=chat&namespace=<virtual-key-id>

Ambos filtros son opcionales; omitirlos amplíal alcance del borrado. La respuesta indica cuántas entradas se eliminaron. Las entradas también caducan al cumplirse su TTL.

Cuándo usarlo

Úsalo para prompts deterministas o de baja temperatura, consultas repetidas de embeddings, reintentos idempotentes y endpoints con muchas lecturas repetidas. Para contenido personalizado o cuando cada generación deba ser nueva, omite el header de cache.