# 🗑️ Flush manual del caché de Qdrant
## 🤔 ¿Qué hago? ¿Cómo lo hago? ¿Y para qué lo hago?
**¿Qué hago?**
Elimino todos los vectores almacenados en la colección Qdrant de klaude-proxy, dejando el caché semántico en estado vacío.
**¿Cómo lo hago?**
Mediante una llamada HTTP DELETE al endpoint `/cache/flush` del proxy, que internamente borra y recrea la colección en Qdrant.
**¿Para qué lo hago?**
Para obtener un estado limpio antes de ejecutar los tests de validación de la caché semántica (v1-v5), o cuando se necesita eliminar respuestas desactualizadas o incorrectas del caché de producción.
---
## ⚠️ Por qué el flush NO se automatiza en los tests
Los tests de la batería semántica (v1-v5) **no ejecutan flush automáticamente** porque:
1. **El caché de Qdrant es datos de producción.** Un flush destruye todas las respuestas cacheadas acumuladas — potencialmente horas o días de inferencias útiles que evitan llamadas a Anthropic.
2. **El coste de un flush es irreversible.** No hay rollback: los vectores eliminados no se pueden recuperar.
3. **Los tests deben validar, no destruir.** La responsabilidad del operador es decidir cuándo se necesita un estado limpio — el test solo informa del estado actual y avisa si podría estar contaminado.
> ℹ️ `validate_variant.sh` sí ejecuta flush automáticamente porque es una herramienta de diagnóstico puntual que opera en aislamiento y limpia tras sí misma.
---
## 🚀 Comando de flush manual
```bash
# Flush básico (API_KEY por defecto: test)
curl -s -X DELETE \
-H "x-api-key: ${API_KEY:-test}" \
http://192.168.1.50:8080/cache/flush
# Con variables de entorno personalizadas
PROXY=http://192.168.1.50:8080
API_KEY=mi-clave
curl -s -X DELETE \
-H "x-api-key: $API_KEY" \
"$PROXY/cache/flush"
```
**Respuesta esperada:**
```json
{
"flushed": true,
"deleted_points": 42,
"collection": "klaude_cache"
}
```
---
## 📋 Cuándo hacer flush manual
| Situación | ¿Flush necesario? |
| --- | --- |
| 🧪 Antes de ejecutar tests v1-v5 por primera vez | ✅ Sí — los tests necesitan caché vacío |
| 🔁 Segunda ejecución del mismo test en el mismo día | ✅ Sí — Q1-Q3 devuelven HIT si el caché está caliente |
| 🚀 Despliegue de nueva versión del proxy | ⚠️ Evaluar — si cambió el modelo de embeddings, los vectores anteriores son incompatibles |
| 🐛 Investigación de falso HIT en producción | ⚠️ Solo si se confirma que la entrada contaminada debe eliminarse |
| 📊 Revisión normal de analytics | ❌ No necesario |
| 🔄 Restart del proxy | ❌ No necesario — el caché persiste en volumen Podman `qdrant-data` |
---
## 🔍 Verificar el estado del caché antes y después
```bash
# Ver cuántos vectores hay en el caché
curl -s http://192.168.1.50:8080/cache/stats
# Respuesta esperada (caché vacío):
# {"collection": "klaude_cache", "vectors_count": 0, "points_count": 0, "status": "green"}
# Respuesta esperada (caché con datos):
# {"collection": "klaude_cache", "vectors_count": 42, "points_count": 42, "status": "green"}
```
---
## 🧪 Flujo recomendado para ejecutar los tests
```bash
# 1. Comprobar estado actual
curl -s http://192.168.1.50:8080/cache/stats
# 2. Si points_count > 0 y quieres estado limpio — flush manual
curl -s -X DELETE -H "x-api-key: test" http://192.168.1.50:8080/cache/flush
# 3. Ejecutar los tests en orden
bash tests/test_cache_semantic.sh # v1 — esperado 9/10 (Q9 edge-case)
bash tests/test_cache_semantic_v2.sh # v2 — esperado 9/10 (Q7 edge-case)
bash tests/test_cache_semantic_v3.sh # v3 — esperado 10/10
bash tests/test_cache_semantic_v4.sh # v4 — esperado 10/10 (código)
bash tests/test_cache_semantic_v5.sh # v5 — esperado 10/10 (errores técnicos)
# Nota: si ejecutas varias baterías seguidas SIN flush intermedio,
# los Q1-Q3 de la segunda batería devolverán HIT porque sus tópicos
# no colisionan entre baterías — solo es un problema si relanzas
# la MISMA batería sin flush.
```
---
## 🔗 Documentos relacionados
- [cache.md](cache.md) — arquitectura y configuración del caché semántico
- [proxy.md](proxy.md) — endpoints del proxy (incluye `/cache/flush` y `/cache/stats`)
- [setup.md](setup.md) — configuración inicial y variables de entorno