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

sync_dev_posts: Creación Automática de Posts y Metadata con Gemini

Este artículo describe la actualización del comando `sync_dev_posts` para sincronizar posts de desarrollo desde archivos Markdown a una base de datos. La nueva versión elimina el encabezado duplicado, usa el slug de la categoría para la estructura de carpetas y crea posts automáticamente si no existen. Además, integra Gemini para generar excerpts y tags automáticamente, mejorando la metadata y la organización del contenido. Aprenderás sobre manipulación de archivos, interacción con bases de datos y el uso de Gemini para tareas de generación de contenido.

sync_dev_posts: Creación Automática de Posts y Metadata con Gemini

El Problema del Encabezado Duplicado

El comando sync_dev_posts sincroniza los archivos .md locales con el contenido de los posts en la base de datos. Hasta ahora copiaba el archivo tal como estaba — incluyendo el encabezado:

# Título del Post

**Héctor Garrido Henríquez**
*Febrero 2026*

*Commit base: `abc1234` (27 de febrero de 2026)*

---

## Primera sección real...

El problema: el título, el autor y la fecha ya viven en la base de datos como campos separados. Sincronizarlos en el content los duplicaba en el frontend — el título aparecía dos veces en la página.

La solución es simple: eliminar todo lo que esté antes (e incluyendo) el primer separador --- antes de sincronizar.

def _strip_header(self, content):
    lines = content.split('\n')
    for i, line in enumerate(lines):
        if line.strip() == '---':
            return '\n'.join(lines[i + 1:]).lstrip('\n')
    return content

El .md en disco queda intacto — el encabezado sigue ahí para que el archivo sea legible como documento independiente. Solo se elimina en memoria antes de comparar y guardar.


La Carpeta Refleja el Slug de la Categoría

Antes, los posts de la serie de desarrollo vivían en docs/posts/desarrollo/. El nombre era arbitrario — no tenía relación con nada en la base de datos.

Ahora la carpeta se llama igual que el slug de la categoría en la DB: docs/posts/rag-blog/. El comando descubre automáticamente qué categorías procesar escaneando las subcarpetas de docs/posts/ y buscando la Category con ese slug:

docs/posts/
└── rag-blog/          ← slug coincide con Category.slug en la DB
    ├── 01-construyendo-blog-django-react.md
    ├── 02-busqueda-semantica-rag-blog.md
    └── ...

Si se añade una nueva categoría de posts en el futuro, basta con crear la carpeta con el slug correcto — el comando la detecta sin necesidad de cambiar código.


Creación Automática de Posts Nuevos

El cambio más relevante: antes el comando solo actualizaba posts existentes. Si el post no existía en la DB, fallaba con [ERROR]. Ahora lo crea directamente.

El título se extrae del primer # heading del .md:

def _extract_title(self, raw_content):
    for line in raw_content.split('\n'):
        if line.startswith('# '):
            return line[2:].strip()
    return None

Para el excerpt inicial (requerido por el modelo), si no se usa --ai-metadata se toma el primer párrafo del contenido:

def _extract_first_paragraph(self, content):
    for block in content.split('\n\n'):
        block = block.strip()
        if block and not block.startswith('#'):
            clean = re.sub(r'[`*_\[\]()#>]', '', block)
            return re.sub(r'\s+', ' ', clean).strip()[:300]
    return ''

El flujo al encontrar un .md sin post en la DB:

try:
    post = Post.objects.get(category=category, series_order=series_num)
    is_new = False
except Post.DoesNotExist:
    is_new = True

if is_new:
    post = Post(
        title=title,
        content=content,
        excerpt=fallback_excerpt,
        category=category,
        series_order=series_num,
        author=superuser,
        is_published=True,
    )
    post.save()  # genera slug automáticamente desde el título

Generación Automática de Excerpt y Tags con Gemini

El flag --ai-metadata activa la generación automática de excerpt y tags para cualquier post (nuevo o existente):

python manage.py sync_dev_posts                          # Preview
python manage.py sync_dev_posts --apply                  # Crear/actualizar
python manage.py sync_dev_posts --ai-metadata --apply    # + excerpt y tags con Gemini
python manage.py sync_dev_posts --ai-metadata --apply --post 21   # Solo el post 21
python manage.py sync_dev_posts --apply --cat rag-blog   # Solo la categoría rag-blog

En lugar de importar el SearchEngine desde la app search (lo que crearía acoplamiento entre apps), el comando replica el patrón REST de search/engine.py directamente. La temperatura es 0.3 — más baja que el chatbot (0.7) porque aquí se quiere output determinista, no creativo.

El prompt pide exclusivamente JSON:

prompt = (
    'Dado el siguiente artículo técnico de blog en español, genera:\n'
    '1. Un excerpt: resumen de 2-3 oraciones, máximo 300 caracteres.\n'
    '2. Una lista de 4-7 tags: palabras clave técnicas.\n\n'
    'Responde EXCLUSIVAMENTE con JSON válido, sin texto adicional ni code fences:\n'
    '{"excerpt": "...", "tags": ["tag1", "tag2"]}\n\n'
    f'Título: {post_title}\n\nContenido:\n{content[:3000]}'
)

Gemini ocasionalmente envuelve el JSON en code fences aunque se le pida que no. El parseo extrae el primer objeto {...} con regex como protección:

json_match = re.search(r'\{.*\}', raw, re.DOTALL)
data = json.loads(json_match.group())

Los tags se aplican con get_or_create por slug y post.tags.set() — reemplaza los existentes en cada ejecución para que el resultado siempre refleje el contenido actual.


Output del Comando

======================================================================
Posts dir: /path/to/docs/posts
Modo: APLICAR
AI metadata: ACTIVADO
======================================================================

── Portafolio RAG (rag-blog/) ──
  [OK]   #19 "De GitHub Copilot a Claude Code" — sin cambios en contenido
  [UPD]  #20 "Pipeline Multi-Ambiente" — 180→210 líneas (+30)
         Generando metadata con Gemini...
         Excerpt: Implementación de un entorno de staging en Cloud Run...
         Tags: Cloud Run, CI/CD, GitHub Actions, staging, Docker
         Contenido actualizado
  [NEW]  #21 "sync_dev_posts: Creación Automática" — no existe, se creará
         Generando metadata con Gemini...
         Excerpt: Evolución del comando sync_dev_posts para crear posts...
         Tags: Django, management command, Gemini, automatización
         Creado con slug: sync-dev-posts-creacion-automatica-posts-gemini

======================================================================
Por crear: 1 | Actualizados: 1 | Sin cambios: 19 | Errores: 0
======================================================================

Integración: Contador Dinámico de Posts en Homepage

El comando sync_dev_posts sincroniza posts desde el filesystem al backend, pero la UI debe reflejar ese cambio sin latencia. En la página de inicio (Home.js), el contador de posts publicados ahora se carga dinámicamente:

React.useEffect(() => {
  let cancelled = false;
  getPosts({ page_size: 1 })
    .then((res) => {
      if (!cancelled && res.data.count != null) setPostCount(res.data.count);
    })
    .catch(() => { /* silencioso */ });
  return () => { cancelled = true; };
}, []);

La clave es usar page_size: 1 — el backend devuelve solo la metadata de paginación (count, next, previous) sin traer el primero de los posts. Esto minimiza el payload y permite mostrar el contador dinámico sin comprometer la latencia de la página inicial.

Mientras se resuelve, se muestra un CircularProgress. El tercer stat card (junto a "Publicaciones WOS" y "Años de experiencia") refleja el total en tiempo real:

┌──────────────┬──────────────┬──────────────┐
│      4       │     10+      │     23       │
│ Publicac. WOS│ Años de exp. │Posts publ.   │
└──────────────┴──────────────┴──────────────┘

Cuando se ejecuta sync_dev_posts --apply en el backend (manual o desde CI/CD), los posts nuevos son inmediatamente accesibles vía API. La UI no necesita ser reconstruida ni redesplegada — solo refrescando el navegador se obtiene el count actualizado.


--parse: Regenerar Metadata sin Sincronizar Contenido

Con el tiempo aparece una necesidad distinta: querer regenerar el excerpt o los tags de posts que ya están en la DB, sin que el contenido del .md haya cambiado. Quizás mejoré el prompt, o simplemente quiero reescribir los excerpts de todos los posts de una categoría de golpe.

Para eso no conviene usar --ai-metadata --apply: ese flag solo actúa al procesar el .md, así que si el contenido no cambió ([OK]), se omite la metadata.

El flag --parse resuelve esto. Ignora completamente los archivos .md y trabaja directamente sobre los posts ya almacenados en la DB:

python manage.py sync_dev_posts --parse --apply --cat rag-blog   # Regenera metadata de toda la categoría
python manage.py sync_dev_posts --parse --apply --post 9         # Solo el post series_order=9
python manage.py sync_dev_posts --parse --cat rag-blog           # Preview sin guardar

El método _run_parse_mode() itera Post.objects.public() con los filtros de --cat y --post, llama a _generate_metadata() sobre el content almacenado, y guarda excerpt y tags si el flag --apply está activo:

def _run_parse_mode(self, options):
    qs = Post.objects.public().select_related('category').prefetch_related('tags')
    if only_cat:
        qs = qs.filter(category__slug=only_cat)
    if only_post is not None:
        qs = qs.filter(series_order=only_post)

    for post in qs.order_by('category__slug', 'series_order'):
        excerpt, tags = self._generate_metadata(post.content, post.title)
        if apply:
            if excerpt:
                post.excerpt = excerpt
                post.save(update_fields=['excerpt'])
            if tags:
                self._apply_tags(post, tags)
        time.sleep(1)  # Evitar rate limiting entre llamadas

La pausa de 1 segundo entre posts es importante: Gemini en el tier gratuito tiene límites de RPM estrictos y sin la pausa el tercer o cuarto post empieza a recibir 429s.


Desconexión de Signal Durante --apply

Hay un problema sutil que descubrí cuando empecé a sincronizar muchos posts de golpe: cada post.save() dispara la signal reindex_and_invalidate_on_post_save, que lanza un hilo daemon para regenerar embeddings llamando a Vertex AI.

Con 20 posts sincronizados, eso es 20 llamadas paralelas a Vertex AI compitiendo por quota al mismo tiempo que el propio comando llama a Gemini para generar metadata. El resultado es una mezcla de logs ilegible y rate limits en cascada.

La solución es desconectar la signal antes de empezar y reconectarla al terminar:

def handle(self, *args, **options):
    if options['apply']:
        from django.db.models.signals import post_save
        from search.signals import reindex_and_invalidate_on_post_save
        post_save.disconnect(reindex_and_invalidate_on_post_save, sender=Post)
        self.stdout.write('[INFO] Signal de re-indexación desconectada.')

    try:
        self._run(options)
    finally:
        if options['apply']:
            post_save.connect(reindex_and_invalidate_on_post_save, sender=Post)

El try/finally garantiza que la signal se reconecte aunque el comando falle a mitad. El usuario puede ejecutar python manage.py index_posts manualmente al terminar para actualizar los embeddings de los posts que cambiaron.


Mejoras al Prompt de Metadata

El prompt inicial de _generate_metadata() pedía "2-3 oraciones, máximo 300 caracteres". Eso produce excerpts demasiado cortos para ser útiles en un listado de posts — apenas un titular ligeramente expandido.

El prompt actual pide más riqueza informativa:

prompt = (
    'Dado el siguiente artículo técnico de blog en español, genera:\n'
    '1. Un excerpt: descripción de 4-6 oraciones en español que explique qué problema '
    'resuelve el artículo, qué tecnologías usa y qué aprenderá el lector. '
    'Debe ser informativo y específico, entre 400 y 600 caracteres.\n'
    '2. Una lista de 4-7 tags: palabras clave técnicas (español o inglés según '
    'el término más común en la industria).\n\n'
    'Responde EXCLUSIVAMENTE con JSON válido, sin texto adicional ni code fences:\n'
    '{"excerpt": "...", "tags": ["tag1", "tag2"]}\n\n'
    f'Título: {post_title}\n\nContenido:\n{content[:5000]}'
)

Cambios clave: - 4-6 oraciones en lugar de 2-3. - 400-600 caracteres como rango objetivo en lugar de máximo 300. - El prompt especifica explícitamente qué información incluir: problema, tecnologías, aprendizaje. - El contexto pasado al modelo sube de content[:3000] a content[:5000].


Errores de Vertex AI Más Visibles

La versión inicial de _call_vertex() manejaba los errores pero los hacía difíciles de seguir en logs con muchos posts. Los cambios recientes mejoran la observabilidad:

Identificación del modelo y número de intento en cada línea:

self.stdout.write(self.style.WARNING(
    f'  [{model_id}][intento {attempt}] {response.status_code}'
))

Sleeps diferenciados por tipo de error:

elif response.status_code == 429:
    time.sleep(5)   # Rate limit: esperar más
elif response.status_code in (500, 502, 503, 504):
    time.sleep(2)   # Error transitorio: reintento rápido

El 429 merece más espera porque es explícito: el servidor dice "estás superando el límite". Un 5xx es transitorio — el servidor puede estar sobrecargado momentáneamente y recuperarse en segundos.


Cuándo Usar Cada Modo

Comando Cuándo usarlo
sync_dev_posts Verificar qué cambiaría sin tocar nada
sync_dev_posts --apply Crear posts nuevos + actualizar contenido
sync_dev_posts --ai-metadata --apply Todo lo anterior + excerpt y tags con Gemini
sync_dev_posts --parse --apply Regenerar metadata de todos los posts desde DB
sync_dev_posts --parse --apply --cat rag-blog Solo la categoría rag-blog
sync_dev_posts --apply --post N Solo el post con series_order=N
sync_dev_posts --apply --cat slug Solo la categoría con ese slug
sync_dev_posts --fix-links --apply Corregir links de navegación en los .md