RAG local para el homelab: preguntar a tus manuales, runbooks e inventario sin subirlos a la nube

Esta pieza encaja dentro de la ruta de automatización e IA local. No trata de montar otro chat bonito. Trata de algo bastante más útil: poder preguntarle a tu propia documentación dónde está una cosa, por qué tomaste una decisión o qué pasos seguías cuando un servicio se rompía.

RAG significa Retrieval Augmented Generation. Dicho sin ceremonia: antes de responder, el sistema busca fragmentos relevantes en tus documentos y se los pasa al modelo como contexto. El modelo no “recuerda” tu homelab. Recupera notas, manuales, inventario y runbooks, y luego redacta una respuesta con eso delante.

En un homelab esto tiene mucho sentido, porque la documentación suele estar desperdigada. Un Markdown con la red. Un PDF del SAI. Una nota sobre el NAS. El README de un stack Docker. Un inventario medio actualizado. Capturas de una instalación que hiciste hace meses. Cuando todo funciona, esa dispersión molesta poco. Cuando algo cae, molesta bastante.

Ya he hablado de Ollama como base para IA local y de Open WebUI como interfaz cómoda. Esta guía baja un nivel: qué metería en una base RAG del homelab, cómo la mantendría y qué límites aceptaría desde el primer día.

qué problema resuelve

#

El problema real no es “quiero hablar con mis documentos”. Eso suena muy bien en una demo, pero en casa la pregunta aparece de formas más feas.

¿Qué contenedor dependía de esa base de datos?

¿Dónde apuntaba el DNS interno de Paperless?

¿Qué hice la última vez que un certificado no renovó?

¿Qué servicios puedo apagar si me voy de vacaciones?

¿Qué ruta tengo que restaurar para recuperar las recetas?

Un buscador tradicional ayuda si recuerdas la palabra exacta. Si escribiste “reverse proxy” pero buscas “nginx”, quizá aparece. Si escribiste “certificados” pero buscas “https caducado”, quizá no. La búsqueda semántica aporta justo ahí: encuentra texto por significado, no solo por coincidencia literal.

Ollama documenta los embeddings como vectores numéricos pensados para búsqueda semántica y pipelines RAG. Qdrant y Chroma hacen la parte de almacenar esos vectores y consultarlos. El modelo de chat viene después.

Lo importante es separar las piezas:

• Documentos: tus notas, manuales, inventario y runbooks.
• Troceado: partir cada documento en fragmentos manejables.
• Embeddings: convertir cada fragmento en un vector.
• Base vectorial: guardar vectores con metadatos.
• Recuperación: buscar fragmentos parecidos a la pregunta.
• Respuesta: pasar esos fragmentos al modelo local y pedir una respuesta.

Si una pieza falla, el resultado se degrada. Y casi siempre falla antes el contenido que el modelo.

qué documentos metería

#

Empezaría pequeño. Meter todo el NAS de golpe es la forma más rápida de construir una montaña mediocre.

Para una primera base RAG del homelab pondría esto:

• Inventario de servicios: nombre, función, URL interna genérica, dónde corre, dependencia principal y backup.
• Runbooks cortos: qué hacer si falla DNS, backups, reverse proxy, Home Assistant, Paperless o Vaultwarden.
• Decisiones de arquitectura: por qué elegí Docker Compose en un sitio, Proxmox en otro o una VPN concreta.
• Manuales que sí consulto: SAI, NAS, switch, router, impresora 3D, mini PCs y cualquier equipo que tenga rarezas.
• Ficheros README de stacks importantes.
• Notas de mantenimiento: ventanas de actualización, restauraciones probadas y tareas mensuales.

No metería secretos. Ni tokens, ni claves, ni exports de gestores de contraseñas, ni ficheros .env reales. Un RAG local sigue siendo software que procesa y almacena texto. Que esté en casa reduce exposición, pero no convierte los datos sensibles en confeti inocente.

Tampoco metería logs enormes al principio. Los logs son otro problema. Para investigar logs ya tienes Loki, Grafana, journalctl o lo que uses. Una base RAG de documentación debe responder por contexto operativo, no sustituir a la observabilidad.

formato: Markdown antes que PDFs eternos

#

Los PDFs entran, pero prefiero Markdown para la documentación viva. Es fácil de versionar, fácil de revisar y fácil de trocear. Un README claro suele generar mejores respuestas que un PDF de 80 páginas con tablas raras.

Mi estructura ideal sería algo así:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

docs/
  inventario/
    servicios.md
    maquinas.md
    dependencias.md
  runbooks/
    dns-caido.md
    restaurar-paperless.md
    certificados-https.md
    apagar-vacaciones.md
  decisiones/
    vpn-tailscale-cloudflare.md
    backups-fotos.md
    servicios-familiares.md
  manuales/
    sai-notas.md
    nas-notas.md

No hace falta escribir una enciclopedia. De hecho, cuanto más corta y concreta sea la documentación, mejor responde el sistema. Un runbook de 40 líneas suele valer más que una novela con aspiraciones.

La documentación del homelab tiene una propiedad incómoda: se pudre. Cambias una IP, mueves un contenedor, sustituyes un disco, añades un proxy, y el documento sigue mintiendo con mucha tranquilidad. Por eso RAG no arregla la documentación mala. La hace más fácil de consultar, que es distinto.

arquitectura mínima que montaría

#

Para casa, montaría la primera versión con tres piezas:

• Ollama para generar embeddings y responder con un modelo local.
• Chroma o Qdrant como base vectorial.
• Un script pequeño de indexación que lea Markdown y PDFs seleccionados.

Chroma me gusta para empezar porque es muy directo en proyectos pequeños. Qdrant me gusta más si quieres API limpia, filtros por metadatos y una base vectorial que pueda crecer con mejor operación. Ambos tienen documentación oficial decente. La elección no debería bloquear el proyecto.

Si ya usas Open WebUI, puedes empezar con su función de documentos y RAG integrado. Para probar el concepto está bien. Subes documentos, preguntas y ves si te ayuda. Pero para una base de conocimiento mantenible prefiero un pipeline propio, aunque sea simple, porque quiero controlar qué entra, con qué metadatos y cada cuánto se actualiza.

Mi versión mínima tendría metadatos por fragmento:

• source: ruta del documento.
• title: título legible.
• kind: inventario, runbook, manual, decisión o README.
• service: servicio relacionado si aplica.
• updated: fecha de última modificación.

Sin metadatos, las respuestas se vuelven vagas. Con metadatos puedes pedir “busca solo en runbooks” o “dame la fuente exacta”. Eso cambia bastante la utilidad.

cómo trocearía los documentos

#

El troceado parece un detalle técnico y acaba importando mucho. Si haces fragmentos enormes, el buscador recupera bloques con demasiado ruido. Si haces fragmentos diminutos, pierdes contexto.

Para notas del homelab, probaría con fragmentos de 500 a 900 palabras y algo de solape entre fragmentos. En Markdown, también respetaría encabezados. Si un runbook tiene una sección “restauración”, quiero que esa palabra viaje como contexto junto a los pasos.

No haría troceado por líneas fijas. Un documento técnico tiene estructura. Títulos, listas, bloques de código, advertencias. Romperlo a lo bruto puede separar una explicación del comando o de la ruta que le da sentido.

También guardaría siempre la fuente. Una respuesta sin enlace al documento original me parece peligrosa. Si el modelo dice “restaura la base de datos antes que los ficheros”, quiero poder abrir el runbook y comprobarlo. El RAG tiene que acelerar, no convertirse en una autoridad opaca.

actualización: el detalle que decide si vive

#

La primera indexación siempre funciona porque estás motivado. El problema es el mes siguiente.

Yo lo automatizaría así:

• Reindexación diaria de documentos modificados.
• Reindexación completa semanal, por si cambió el script o el modelo de embeddings.
• Registro de errores cuando un PDF no se puede leer.
• Informe corto con documentos añadidos, modificados y eliminados.

No hace falta meter una plataforma enorme. Un cron y un script decente bastan para empezar. Si ya tienes GitOps doméstico para configuraciones, puedes enganchar la indexación al repositorio de documentación. Cada cambio en docs/ dispara una actualización o queda listo para el siguiente cron.

La parte aburrida importa: borrar documentos también. Si eliminas una nota antigua pero sus fragmentos siguen en la base vectorial, el sistema puede recuperar basura caducada. Hay que reconciliar estado, no solo añadir cosas nuevas.

preguntas que sí espero que responda

#

Un RAG local bien montado debería responder cosas como:

• “Qué servicios dependen del NAS?”
• “Cómo recupero Paperless si pierdo la VM?”
• “Qué piezas de la red necesito vivas para que Home Assistant funcione?”
• “Dónde tengo documentado el plan para apagar parte del homelab?”
• “Qué decisiones tomé sobre Tailscale y Cloudflare Tunnel?”
• “Qué backups tienen prueba de restauración reciente?”

También debería poder decir “no lo tengo documentado”. Esa respuesta vale oro. Si preguntas algo importante y no aparece, acabas de encontrar una deuda documental. Mucho mejor descubrirlo un martes tranquilo que durante una caída.

Lo que no le pediría:

• Diagnóstico en tiempo real de logs.
• Respuestas sobre estado actual si no le das datos actuales.
• Secretos.
• Decisiones automáticas sobre producción familiar.
• Cambios en servidores sin revisión humana.

El sistema puede ayudarte a recordar y buscar. No debería sustituir tu criterio cuando toca tocar algo que usa más gente en casa.

seguridad y privacidad

#

RAG local no significa “todo permitido”. La base vectorial guarda representaciones del texto y metadatos. Dependiendo del sistema, también puede guardar el texto original para devolver fuentes. Si indexas una clave API, la has metido en otra base más.

Mis reglas serían:

• No indexar .env, exports de contraseñas ni notas con credenciales.
• Revisar patrones sensibles antes de indexar.
• Mantener la base RAG en la red interna o detrás de VPN.
• No exponer la interfaz directamente a internet.
• Separar documentación operativa de secretos.
• Hacer backup de la documentación original, no solo de la base vectorial.

La base vectorial se puede reconstruir si conservas documentos y script. Lo que importa son las fuentes. Si Chroma o Qdrant se rompen, reindexas. Si pierdes los Markdown donde apuntabas decisiones y runbooks, ahí ya duele más.

modelo local o nube

#

Para embeddings, usaría local siempre que pueda. Ollama tiene modelos de embeddings y su documentación oficial explica el endpoint /api/embed. Para un homelab, generar vectores de Markdown y manuales no exige una GPU enorme. Puede tardar más, pero es una tarea por lotes.

Para responder, depende. Un modelo local de 7B o 12B puede bastar para preguntas concretas si el contexto recuperado es bueno. Si la pregunta exige sintetizar mucho o cruzar varios documentos largos, un modelo local pequeño puede quedarse corto.

Mi enfoque sería híbrido:

• Embeddings locales.
• Búsqueda local.
• Respuestas locales por defecto.
• Opción manual de usar un modelo cloud cuando la tarea sea compleja y el contenido no sea sensible.

Esto no es pureza. Es pragmatismo. Hay días en los que quieres privacidad completa y días en los que quieres calidad. Lo importante es saber qué datos estás enviando y por qué.

un ejemplo práctico

#

Imagina que tienes un documento runbooks/restaurar-paperless.md con estos apartados:

• qué datos protege el servicio
• dónde está la base de datos
• qué volumen guarda documentos
• orden de restauración
• comprobaciones después de levantarlo
• enlaces a backups relacionados

También tienes inventario/servicios.md, donde Paperless aparece con dependencias: PostgreSQL, almacenamiento del NAS, reverse proxy, DNS interno y SMTP para avisos.

Preguntas:

1

Se ha roto Paperless. Qué tengo que restaurar y en qué orden?

Un RAG útil recupera el runbook, el inventario y quizá la decisión donde explicaste por qué separaste documentos y base de datos. El modelo responde con pasos, pero también cita las fuentes. Tú abres el runbook, confirmas que sigue actualizado y ejecutas.

La mejora no está en que el modelo sea brillante. La mejora está en no perder diez minutos buscando “paperless”, “documentos”, “postgres”, “restaurar” y “backup” por cinco sitios distintos.

dónde suele fallar

#

Los fallos más habituales son bastante humanos:

• Documentos antiguos.
• Demasiados documentos irrelevantes.
• Fragmentos mal hechos.
• Fuentes sin metadatos.
• Preguntas demasiado amplias.
• Confianza excesiva en una respuesta bien redactada.

La respuesta puede sonar segura y estar apoyada en una nota vieja. Por eso pondría fecha y fuente en cada respuesta. Si una recomendación sale de un documento modificado hace ocho meses, quiero verlo.

También limitaría el alcance al principio. Nada de “mete todo mi segundo cerebro”. Primero homelab operativo. Luego, si funciona, añades notas de compras de hardware, comparativas o documentación de proyectos.

mantenimiento mínimo

#

Una vez al mes revisaría tres cosas:

• Qué documentos se consultan más.
• Qué preguntas no encuentran respuesta.
• Qué documentos llevan demasiado tiempo sin tocarse.

Esto puede salir de logs sencillos. No necesitas analítica compleja. Basta con ver si el sistema ayuda o si se está convirtiendo en otro panel que nadie abre.

Si una pregunta importante falla, no culparía primero al modelo. Revisaría si existe documentación buena. Muchas veces el RAG solo te enseña que nunca escribiste lo que creías haber escrito.

mi recomendación

#

Montaría RAG local en el homelab si ya tienes documentación mínima y quieres consultarla mejor. No lo montaría como excusa para no documentar.

La secuencia sensata:

1. Escribir inventario y cinco runbooks reales.
2. Versionarlos en Git.
3. Indexarlos con embeddings locales.
4. Probar veinte preguntas concretas.
5. Corregir documentos, no solo prompts.
6. Añadir manuales y decisiones cuando el flujo funcione.

Si ya tienes inventario automático del homelab, esta pieza encaja muy bien. El inventario te dice qué existe. El RAG ayuda a encontrar por qué existe, cómo se mantiene y qué hacer cuando algo se rompe.

fuentes útiles

#

Para montar esto con piezas actuales, miraría primero documentación primaria:

• Embeddings en Ollama
• Endpoint /api/embed de Ollama
• Documentación oficial de Qdrant
• Embedding functions en Chroma

No hace falta usar todas a la vez. Para empezar, elegiría una base vectorial, un modelo de embeddings y un conjunto pequeño de documentos. El éxito no está en el stack. Está en que la respuesta llegue con fuentes, sea comprobable y te quite fricción cuando el homelab decide pedir atención.