Saltar al contenido
hg.Héctor GarridoCiencia de datos · Estadística · Ingeniería de datos
← Volver al blog
Portafolio RAG

Caché Semántico, Signals y las Mil Batallas de las Imágenes en GCS

Este artículo técnico aborda el problema de la lentitud en un chatbot RAG debido a la necesidad de recalcular respuestas a preguntas repetidas. Se presenta `RAGQueryCache`, un caché semántico que utiliza embeddings para identificar preguntas similares y reutilizar respuestas almacenadas, mejorando significativamente el rendimiento. Además, se explica el uso de Django Signals para automatizar la indexación de posts en el motor de búsqueda, evitando errores manuales. Aprenderás sobre caché semántico, embeddings, cosine similarity y Django Signals.

Caché Semántico, Signals y las Mil Batallas de las Imágenes en GCS

El Problema de Rendimiento que No Esperaba

Mi chatbot RAG funcionaba. Podías preguntarle "¿Qué opinas de ARIMA?" y te respondía con fragmentos reales de mis artículos. Pero cada pregunta tomaba entre 3 y 8 segundos:

1. Generar embedding de la query        → ~500ms (Vertex AI API)
2. Buscar posts similares (in-memory)   → ~10ms
3. Construir prompt + contexto          → ~5ms
4. Enviar a Gemini y esperar respuesta  → 2-7 segundos
5. Retornar al frontend                 → ~50ms

El paso 4 era el cuello de botella inevitable: los LLMs son lentos por naturaleza. Pero había un desperdicio gigante: si alguien hacía la misma pregunta dos veces, recalculábamos todo desde cero. Y resulta que la gente hace las mismas preguntas. Mucho.


RAGQueryCache: Un Caché Semántico

La Idea

Un caché convencional usa la query exacta como clave:

# Caché ingenuo
cache = {}
cache["¿Qué es ARIMA?"] = respuesta_anterior

# Esto funciona:
cache.get("¿Qué es ARIMA?")  # ✓ Hit

# Esto NO funciona:
cache.get("¿Qué es el modelo ARIMA?")  # ✗ Miss (diferente string)

Un caché semántico usa el embedding de la query como clave. Si dos preguntas son semánticamente similares (cosine similarity > umbral), se considera un hit:

# Caché semántico
"¿Qué es ARIMA?"           → embedding_1 → respuesta_A
"¿Qué es el modelo ARIMA?" → embedding_2 → cosine_sim(1, 2) = 0.95 → HIT → respuesta_A
"¿Quién es Héctor?"        → embedding_3 → cosine_sim(1, 3) = 0.12 → MISS → recalcular

El Modelo

```python blog_backend/blog/models.py class RAGQueryCache(models.Model): query_hash = models.CharField(max_length=64, unique=True, db_index=True) query_text = models.TextField() query_embedding = models.BinaryField(null=True) answer = models.TextField() sources = models.JSONField(default=list) created_at = models.DateTimeField(auto_now_add=True) hit_count = models.IntegerField(default=0)

class Meta:
    indexes = [
        models.Index(fields=['query_hash']),
        models.Index(fields=['created_at']),
    ]

### Búsqueda en Dos Fases

El caché busca en dos pasos, de más barato a más caro:

```python
@classmethod
def find_cached(cls, query, query_embedding, threshold=0.92):
    # Fase 1: Hash exacto (O(1), instantáneo)
    query_hash = hashlib.sha256(query.strip().lower().encode()).hexdigest()
    exact = cls.objects.filter(query_hash=query_hash).first()
    if exact:
        exact.hit_count += 1
        exact.save(update_fields=['hit_count'])
        return exact

    # Fase 2: Similitud semántica (O(n), pero n es pequeño)
    all_cached = cls.objects.all()
    for cached in all_cached:
        cached_emb = pickle.loads(cached.query_embedding)
        similarity = cosine_similarity(
            query_embedding.reshape(1, -1),
            cached_emb.reshape(1, -1)
        )[0][0]

        if similarity >= threshold:
            cached.hit_count += 1
            cached.save(update_fields=['hit_count'])
            return cached

    return None  # Cache miss

¿Por qué dos fases?

La Fase 1 (hash exacto) cuesta ~0.1ms. Si alguien escribe exactamente la misma pregunta, ni siquiera necesitamos calcular embeddings.

La Fase 2 (similitud semántica) cuesta ~5ms para 100 queries cacheadas. Solo se ejecuta si la Fase 1 falla. El umbral de 0.92 es alto intencionalmente: prefiero un cache miss (y recalcular la respuesta) a devolver una respuesta cacheada que no sea suficientemente relevante.

Impacto en Rendimiento

Sin caché:  Cada query → 3-8 segundos
Con caché:  
  - Hit exacto (hash)     → <10ms    (ahorro: 99.7%)
  - Hit semántico          → ~50ms    (ahorro: 99%)
  - Miss (nueva pregunta)  → 3-8 seg  (sin cambio, pero se cachea para la próxima)

Las preguntas sugeridas del frontend (las 15 chips que muestro en la interfaz) se benefician especialmente: la primera persona que clickea espera 5 segundos, todas las demás obtienen la respuesta instantáneamente.


Django Signals: Auto-Indexación de Posts

El Problema Manual

Cada vez que creaba o editaba un post, tenía que acordarme de ejecutar:

python manage.py index_posts

Si lo olvidaba, el motor de búsqueda no encontraba el post nuevo. Y yo lo olvidaba siempre.

La Solución Automática

El commit e239e46 implementó signals de Django para auto-indexar posts:

```python blog_backend/search/signals.py from django.db.models.signals import post_save from django.dispatch import receiver from blog.models import Post

@receiver(post_save, sender=Post) def auto_index_post(sender, instance, **kwargs): """Auto-generar embedding cuando un post se crea o edita.""" if not instance.is_published or instance.is_internal: return # Solo indexar posts públicos y publicados

from search.engine import RAGEngine
try:
    RAGEngine.index_single_post(instance)
    logger.info(f"Auto-indexed post: {instance.title}")
except Exception as e:
    logger.error(f"Failed to auto-index {instance.title}: {e}")

**¿Por qué `post_save` y no `pre_save`?** Porque necesito que el post ya tenga un `id` asignado por la base de datos. En `pre_save`, el objeto no ha sido guardado aún y si es nuevo, no tiene `id`.

**El import lazy de `RAGEngine`:** Lo hago dentro de la función y no al inicio del archivo para evitar un import circular (`search.engine` → `blog.models` → `search.signals` → `search.engine`).

### Invalidación Selectiva de Caché

El commit `7b68564` agregó algo crucial: cuando un post se edita, **el caché de queries que referenciaron ese post debe invalidarse**:

```python
@receiver(post_save, sender=Post)
def invalidate_cache_for_post(sender, instance, **kwargs):
    """Invalidar caché RAG cuando un post cambia."""
    cached_queries = RAGQueryCache.objects.all()
    for cached in cached_queries:
        sources = cached.sources  # JSONField con los slugs de posts usados
        if any(s.get('slug') == instance.slug for s in sources):
            cached.delete()
            logger.info(f"Invalidated cache for query: {cached.query_text[:50]}")

La lógica: Si el usuario preguntó "¿Qué es ARIMA?" y la respuesta usó el post "modelos-arima-series-tiempo" como fuente, y luego edito ese post, la respuesta cacheada ya no es válida. Necesita regenerarse con el contenido actualizado.

Esto es invalidación selectiva: solo elimino las entradas de caché que usaron el post editado, no todo el caché. Si tengo 100 queries cacheadas y edito 1 post, quizás invalido 5 queries, no las 100.


EmbeddingIndex: Búsqueda Vectorial In-Memory

Del Modelo al Índice

La búsqueda semántica leía los embeddings de la base de datos en cada query:

# ANTES: Query a DB en cada búsqueda
all_embeddings = PostEmbedding.objects.all()
for pe in all_embeddings:
    vec = pickle.loads(pe.embedding_data)  # Deserializar pickle por cada post
    score = cosine_similarity(query_vec, vec)

Para 24 posts, esto significaba 24 queries SQL + 24 deserializaciones de pickle en cada búsqueda. Funciona, pero es ineficiente.

La solución fue un índice in-memory que se carga una vez y se reutiliza:

class EmbeddingIndex:
    """Índice en memoria para búsqueda vectorial rápida."""
    _instance = None
    _embeddings = None  # numpy matrix (n_posts × embedding_dim)
    _post_ids = None    # lista de IDs correspondientes

    @classmethod
    def load(cls):
        """Cargar todos los embeddings en una matriz numpy."""
        all_pe = PostEmbedding.objects.select_related('post').all()

        embeddings = []
        post_ids = []
        for pe in all_pe:
            vec = pe.get_embedding()
            if vec is not None:
                embeddings.append(vec)
                post_ids.append(pe.post_id)

        cls._embeddings = np.vstack(embeddings)  # shape: (n, 768)
        cls._post_ids = post_ids

    @classmethod
    def search(cls, query_embedding, top_k=5):
        """Búsqueda vectorial con numpy (sin DB)."""
        if cls._embeddings is None:
            cls.load()

        # Cosine similarity vectorizada contra TODOS los posts a la vez
        scores = cosine_similarity(
            query_embedding.reshape(1, -1), 
            cls._embeddings
        )[0]

        # Top K por score
        top_indices = np.argsort(scores)[::-1][:top_k]
        return [(cls._post_ids[i], float(scores[i])) for i in top_indices]

La clave: cosine_similarity de scikit-learn opera sobre matrices numpy. En lugar de hacer N comparaciones secuenciales, hace una sola multiplicación de matrices que compara la query contra todos los posts simultáneamente. Esto aprovecha las optimizaciones BLAS/LAPACK del CPU.

Rendimiento:

Antes (DB + pickle loop):  ~15ms para 24 posts
Después (numpy in-memory): ~0.5ms para 24 posts

Para 24 posts la diferencia es pequeña. Para 500 posts, sería 10x más notable.


Las Batallas de Google Cloud Storage

Los commits 84ebe04, 5aec17d, 832c41b, ba3a211, 1f2a142 y 85ee3f1 representan mi pelea con Google Cloud Storage (GCS) para servir imágenes de portada de los artículos.

El Problema Base

En desarrollo local, las imágenes se guardan en media/covers/ y Django las sirve directamente. En producción, necesitas un servicio de storage externo porque Cloud Run no tiene disco persistente.

GCS es la opción natural en GCP. Django tiene un paquete excelente para esto: django-storages[google].

# settings.py
if os.getenv('GS_BUCKET_NAME'):
    STORAGES = {
        'default': {
            'BACKEND': 'storages.backends.gcloud.GoogleCloudStorage',
            'OPTIONS': {
                'bucket_name': os.getenv('GS_BUCKET_NAME'),
                'querystring_auth': False,  # URLs públicas, sin firma
            }
        },
        'staticfiles': {
            'BACKEND': 'whitenoise.storage.CompressedManifestStaticFilesStorage',
        }
    }

Bug #1: STATICFILES_STORAGE conflictivo (85ee3f1)

Django 5 unificó la configuración de storage en un solo diccionario STORAGES. Pero yo tenía ambas configuraciones:

# ANTES (conflicto)
STORAGES = {
    'default': {'BACKEND': 'storages.backends.gcloud.GoogleCloudStorage', ...}
}
STATICFILES_STORAGE = 'whitenoise.storage.CompressedManifestStaticFilesStorage'

Django 5 ignora STATICFILES_STORAGE cuando STORAGES['staticfiles'] existe, pero mi STORAGES no tenía la key staticfiles, así que Django usaba el default (que es StaticFilesStorage sin compresión). El resultado: archivos estáticos sin hash en el nombre, sin compresión, y con problemas de cache-busting.

Bug #2: default_acl incompatible (5aec17d)

GCS tiene dos modos de control de acceso: 1. Fine-grained: Cada archivo tiene su propia ACL (Access Control List) 2. Uniform bucket-level: Todo el bucket tiene la misma política

Mi bucket usaba uniform, pero django-storages intentaba setear ACLs por archivo (default_acl='publicRead'). GCS rechazaba la operación con un error 400.

La solución: eliminar default_acl y confiar en la política del bucket.

Bug #3: Signed URLs innecesarias (1f2a142)

Por defecto, django-storages genera URLs firmadas (con un token temporal en la query string):

https://storage.googleapis.com/mi-bucket/covers/foto.jpg?X-Goog-Signature=abc123...

Estas URLs expiran (por defecto en 1 hora). Perfectas para contenido privado, desastrosas para un blog público: los links en el HTML se rompen después de una hora. Además, Google no puede cachear URLs firmadas en su CDN.

# La solución: desactivar firma
'querystring_auth': False,
# Resultado: https://storage.googleapis.com/mi-bucket/covers/foto.jpg

Bug #4: Cover Images no se guardaban (832c41b)

El admin de Django no mostraba el campo cover_image porque mi ModelAdmin no tenía fieldsets explícitos que lo incluyeran. Django no incluye automáticamente FileField/ImageField en el admin si usas ciertos patrones de configuración.

@admin.register(Post)
class PostAdmin(admin.ModelAdmin):
    fieldsets = (
        ('Contenido', {
            'fields': ('title', 'content', 'excerpt', 'cover_image', 'cover_position')
        }),
        ('Metadata', {
            'fields': ('status', 'visibility', 'tags', 'author')
        }),
    )

cover_position: Control del Punto Focal (ad9ed46)

Después de resolver los bugs de GCS, agregué una feature que quería desde el inicio: controlar dónde se centra la imagen de portada.

Las imágenes de los posts no siempre tienen el sujeto principal centrado. Una foto de un gráfico puede tener el contenido interesante arriba a la derecha. Con cover_position, el autor puede especificar el punto focal:

class Post(models.Model):
    COVER_POSITION_CHOICES = [
        ('center', 'Centro'),
        ('top', 'Arriba'),
        ('bottom', 'Abajo'),
        ('left', 'Izquierda'),
        ('right', 'Derecha'),
    ]
    cover_position = models.CharField(
        max_length=10, 
        choices=COVER_POSITION_CHOICES, 
        default='center'
    )

En el frontend, esto se traduce a object-position de CSS:

<CardMedia
  component="img"
  image={post.cover_image}
  sx={{ objectPosition: post.cover_position || 'center' }}
/>

Índices de Base de Datos y Optimización de Queries

El commit 5c66c84 agregó índices a los campos más consultados:

class Post(models.Model):
    class Meta:
        indexes = [
            models.Index(fields=['status', 'created_at']),
            models.Index(fields=['slug']),
            models.Index(fields=['visibility']),
        ]

¿Por Qué Estos Índices?

status + created_at: La query más frecuente del blog es "posts publicados, ordenados por fecha" (Post.objects.filter(status='published').order_by('-created_at')). Sin índice compuesto, PostgreSQL hace un sequential scan de toda la tabla, luego filtra, luego ordena. Con el índice, va directo a los posts publicados y ya están ordenados.

slug: Cada vista de detalle busca por slug (Post.objects.get(slug=slug)). Sin índice, es un scan. Con índice, es un lookup O(log n).

visibility: Los filtros de contenido privado (visibility='internal') necesitan ser rápidos para no penalizar a los usuarios normales.

reading_time: Propiedad Calculada

También agregué el tiempo estimado de lectura:

@property
def reading_time(self):
    """Minutos estimados de lectura (250 palabras/minuto)."""
    word_count = len(self.content.split())
    return max(1, round(word_count / 250))

250 palabras por minuto es el promedio de lectura de un adulto. La función max(1, ...) asegura que nunca muestre "0 minutos" para posts muy cortos.


Documentación Exhaustiva (cdc5d31)

Este commit creó la carpeta docs/ con 6 documentos pedagógicos que cubren toda la arquitectura. La estructura:

docs/
├── 01-arquitectura.md      # Visión general, stack, decisiones
├── 02-backend-django.md    # Modelos, serializers, views
├── 03-motor-rag.md         # Pipeline completo del RAG
├── 04-frontend-react.md    # Componentes, tema, routing
├── 05-infraestructura.md   # Docker, Cloud Run, GCS
├── 06-guia-desarrollo.md   # Setup local, deploy, troubleshooting
└── README.md               # Índice

Escribir documentación técnica exhaustiva es, paradójicamente, una de las actividades más valiosas y menos glamorosas del desarrollo. Nadie la lee hasta que la necesita desesperadamente. Pero cuando la necesitas y no existe, pierdes horas reconstruyendo el contexto mental del "yo del pasado" que tomó esas decisiones.


Lecciones de Esta Fase

1. El caché semántico es una abstracción poderosa. La idea de usar similitud de embeddings como "igualdad aproximada" se puede aplicar a muchos dominios más allá de un chatbot: deduplicación de tickets de soporte, agrupación de feedback de usuarios, detección de preguntas frecuentes.

2. Los signals de Django son un arma de doble filo. Son perfectos para lógica reactiva ("cuando pasa X, haz Y"). Pero pueden crear acoplamientos invisibles: si un signal falla silenciosamente, el comportamiento del sistema cambia sin que sea obvio dónde está el problema. Siempre loguear los errores en signals.

3. Las integraciones con cloud storage son deceptively complex. GCS, S3, Azure Blob — todos prometen "sube archivos fácil". Pero las combinaciones de ACLs, URLs firmadas, CORS, CDN caching, y las diferencias entre fine-grained y uniform access crean un espacio de configuración enorme donde es fácil perderse.

4. Los índices de base de datos deberían agregarse con las queries, no después. Cada vez que escribes una query frecuente, deberías preguntarte: "¿Esta query tiene un índice?" Es mucho más fácil agregar índices al diseñar el modelo que diagnosticar problemas de rendimiento en producción.

En el siguiente y último artículo: la migración definitiva a Vertex AI como proveedor exclusivo, la deprecación de Ollama/SBERT, y el hardening del frontend para sobrevivir a los cold starts de Cloud Run.


Anterior: Despliegue Full-Stack Serverless en Google Cloud Platform
Siguiente: Vertex AI Exclusivo, Resiliencia y la Última Milla: Paginación

Este artículo es el quinto de la serie "Construyendo un Blog con IA". El código fuente completo está en GitHub.