# Cache de respuestas

> Reutiliza respuestas completas en Redis mediante una opción por solicitud.

URL: https://boelabs.com/docs/ai-gateway/caching
Language: Español

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](https://boelabs.com/docs/ai-gateway/provider-prompt-caching).

## Habilitar por solicitud [#enable-it-per-request]

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

| header | Valores | Efecto |
|---|---|---|
| `x-unified-cache` | `true` o `1` | Habilita el caching para esta solicitud. Cualquier otro valor (o ausente) = sin cache. |
| `x-unified-cache-ttl` | segundos | Tiempo de retención de una entrada. Por defecto `300` (5 min), máximo `86400` (24 h). |

```bash
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 [#how-entries-are-scoped]

- **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](https://boelabs.com/docs/ai-gateway/streaming) y [Entradas de contenido](https://boelabs.com/docs/ai-gateway/file-inputs).
- **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](https://boelabs.com/docs/ai-gateway/cost-accounting).

## Invalidar [#invalidate]

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

```bash
# 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 [#when-to-use-it]

Ú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.