516 lines
19 KiB
Markdown
516 lines
19 KiB
Markdown
# Bitacora de diseño del RAG
|
|
|
|
**Proyecto:** Workspace de tools IA para empresas
|
|
**Modulo:** RAG
|
|
**Ultima actualizacion:** 2026-04-02
|
|
**Ultima modificacion por:** Agente tools IA para potenciar servicios empresariales
|
|
**Estado:** Activa
|
|
|
|
---
|
|
|
|
## Proposito
|
|
|
|
Esta bitacora registra el camino de diseño que estamos siguiendo para construir el RAG.
|
|
|
|
No se limita a guardar decisiones finales. Tambien recoge:
|
|
|
|
- como se llego a una decision
|
|
- por que se prefirio una opcion frente a otra
|
|
- que posibilidades quedan abiertas para mas adelante
|
|
- que vision general da sentido al resto de documentos del modulo
|
|
|
|
Su funcion es servir como panorama vivo del diseño del RAG.
|
|
|
|
---
|
|
|
|
## Vision general actual
|
|
|
|
El RAG que se esta diseñando no busca ser una demo cerrada ni una herramienta pensada solo para este workspace.
|
|
|
|
La intencion es crear una base reutilizable que pueda:
|
|
|
|
- integrarse con proyectos de clientes
|
|
- potenciar agentes y soluciones con IA ya existentes
|
|
- servir tanto para conocimiento empresarial como para desarrollo de software
|
|
- crecer hacia un modelo de servicio consumible por distintas herramientas
|
|
|
|
La carpeta `docs/` del workspace solo se usara como primer caso real de prueba, no como limite conceptual del sistema.
|
|
|
|
Otro criterio ya explicitado es que las decisiones de la v1 deben tomarse como base estable y duradera del sistema. La evolucion futura debe venir por ampliacion de capacidades, no por sustituir continuamente decisiones nucleares ya cerradas.
|
|
|
|
---
|
|
|
|
## Casos de uso principales aceptados
|
|
|
|
### 1. Agente experto en empresa
|
|
|
|
El RAG debe poder ayudar a un agente a atender clientes durante venta, postventa, soporte y seguimiento.
|
|
|
|
Eso implica que el sistema debe poder aportar contexto sobre:
|
|
|
|
- empresa
|
|
- productos
|
|
- servicios
|
|
- formas de trabajo
|
|
- empleados, areas y responsabilidades
|
|
- informacion relevante para atender correctamente al cliente
|
|
|
|
### 2. Agente experto en proyecto o desarrollo
|
|
|
|
El RAG debe poder dar a un agente una vision util de un proyecto para:
|
|
|
|
- iniciar un desarrollo desde cero
|
|
- continuar un proyecto existente
|
|
- retomar proyectos de terceros
|
|
- comprender tecnologia, arquitectura, metodos y estructura interna
|
|
- desarrollar nuevas funcionalidades bien integradas con lo que ya existe
|
|
|
|
---
|
|
|
|
## Decisiones y razonamiento acumulado
|
|
|
|
### El RAG no debe limitarse a pregunta y respuesta
|
|
|
|
**Decision:**
|
|
El sistema no se diseñara solo como `pregunta -> respuesta`.
|
|
|
|
**Por que:**
|
|
- los casos de uso reales requieren dar contexto util a agentes, no solo contestar preguntas
|
|
- en desarrollo y continuidad de proyectos, el mayor valor esta en cargar panorama y contexto rico
|
|
- para atencion al cliente tambien puede ser util devolver contexto y no solo respuesta final
|
|
|
|
**Consecuencia:**
|
|
La salida del RAG debe contemplar al menos recuperacion de contexto, y no solo respuesta sintetizada.
|
|
|
|
---
|
|
|
|
### El RAG debe poder funcionar como servicio
|
|
|
|
**Decision:**
|
|
La base de acceso principal se esta pensando como API o endpoint.
|
|
|
|
**Por que:**
|
|
- facilita que otras apps, agentes y soluciones lo consuman
|
|
- permite pruebas inmediatas desde terminal
|
|
- encaja bien con una futura capa MCP
|
|
- es mas util para integracion que pensarlo primero como libreria interna
|
|
|
|
**Posibilidad abierta:**
|
|
- MCP como forma estandar de conexion a sistemas de IA
|
|
- CLI como capa opcional de uso interno o pruebas
|
|
|
|
**Decision tecnica posterior vinculada a esta direccion:**
|
|
La v1 se orienta a un stack basado en `Node.js + TypeScript + Express + Qdrant`, con API HTTP como base principal y proveedor de embeddings desacoplado.
|
|
|
|
**Matiz importante ya detectado:**
|
|
Desacoplar el proveedor de embeddings no evita que cambiar de modelo obligue normalmente a reindexar el contenido afectado.
|
|
|
|
Lo correcto sera:
|
|
- registrar con que proveedor, modelo y dimensiones se genero cada embedding
|
|
- mantener trazabilidad de la version de indexacion
|
|
- evitar mezclar embeddings de modelos distintos dentro de la misma logica de recuperacion
|
|
|
|
**Decision cerrada posterior:**
|
|
Se adopta `Qwen3 Embedding 8B` como modelo base estable del sistema.
|
|
|
|
**Por que se cierra asi:**
|
|
- el usuario quiere que las decisiones nucleares de la v1 nazcan como base duradera
|
|
- el modelo encaja con recuperacion textual y de codigo
|
|
- ofrece una via realista de arranque ahora y despliegue local despues
|
|
- encaja mejor con la estrategia general del RAG que un modelo puramente comercial y dependiente de proveedor cerrado
|
|
|
|
**Referencia comparativa mantenida:**
|
|
`OpenAI text-embedding-3-large` se conserva como referencia de calidad y comparacion, pero no como decision principal del sistema.
|
|
|
|
---
|
|
|
|
### La arquitectura debe separar entrada y salida
|
|
|
|
**Decision:**
|
|
Se ha aceptado que el RAG tiene al menos dos grandes usos operativos:
|
|
|
|
- entrada de informacion
|
|
- salida de informacion por consulta o recuperacion de contexto
|
|
|
|
**Por que:**
|
|
- ambas tareas son distintas y complementarias
|
|
- ayudan a pensar el sistema con responsabilidades claras
|
|
- permiten dejar preparada una arquitectura robusta y ampliable
|
|
|
|
**Ampliacion ya detectada:**
|
|
Tambien se considera necesario un futuro subsistema de actualizacion del conocimiento.
|
|
|
|
---
|
|
|
|
### Debe existir una via futura para actualizacion y versionado
|
|
|
|
**Decision:**
|
|
Aunque no se implementara de entrada, el sistema debe nacer preparado para manejar contenido cambiante.
|
|
|
|
**Por que:**
|
|
- el conocimiento empresarial y tecnico no es estatico
|
|
- parte de la informacion puede cambiar, quedar obsoleta o dejar de ser valida
|
|
- un RAG robusto no puede asumir que todo lo ingerido vale para siempre
|
|
|
|
**Idea asociada en exploracion:**
|
|
Una inspiracion parecida a git puede ser util para pensar el historico, la vigencia y la actualizacion incremental del conocimiento.
|
|
|
|
---
|
|
|
|
### El modelo no solo participa en la salida, tambien puede participar en la entrada
|
|
|
|
**Decision en formacion:**
|
|
Se deja claro que, cuando hablamos de uso de modelo, no nos referimos solo al modelo que consumira el contexto del RAG en consulta.
|
|
|
|
Tambien se contempla un modelo que participe en el proceso de entrada de informacion al RAG.
|
|
|
|
**Por que:**
|
|
- un modelo puede ayudar a entender documentos de calidad irregular
|
|
- puede identificar tema, estructura y puntos clave
|
|
- puede enriquecer la informacion que entra al sistema antes de indexarla
|
|
|
|
**Criterio adoptado:**
|
|
- no conviene depender desde el inicio de modelos caros para esta fase
|
|
- puede existir mas adelante un modelo fijo y economico dentro del pipeline de ingesta
|
|
- tambien queda abierta una fase posterior con una interfaz interactiva de alimentacion, en la que el usuario pueda elegir un modelo mas potente para procesar mejor ciertas entradas
|
|
|
|
**Direccion que sugiere esta idea:**
|
|
- fase basica: ingesta principalmente mecanica y economica
|
|
- fase posterior: ingesta asistida por modelo
|
|
- fase mas avanzada: ingesta interactiva con eleccion de modelo segun necesidad
|
|
|
|
**Matiz posterior aceptado:**
|
|
La arquitectura debe nacer preparada para recibir parametros que indiquen si la ingesta va en modo basico o en modo enriquecido/interactivo.
|
|
|
|
La idea es que:
|
|
- si no llegan parametros especiales, el sistema opere por defecto de forma mecanica y con su modelo predefinido
|
|
- si llegan parametros desde una interfaz, el sistema pueda cambiar de modelo o recibir directrices y marcado del usuario
|
|
|
|
**Consecuencia positiva de este enfoque:**
|
|
Permite que el sistema crezca hacia una ingesta mas rica sin exigir una reescritura posterior del flujo base.
|
|
|
|
---
|
|
|
|
### Identidad del conocimiento por niveles
|
|
|
|
**Decision:**
|
|
Se ha aceptado una jerarquia de identificacion con tres niveles:
|
|
|
|
- `source_id`
|
|
- `document_id`
|
|
- `chunk_id`
|
|
|
|
**Por que:**
|
|
- no basta con identificar solo la carpeta o fuente global
|
|
- los cambios reales suelen ocurrir a nivel de documento
|
|
- los chunks son unidades de recuperacion, no la identidad principal del conocimiento
|
|
|
|
**Decision relacionada:**
|
|
Los documentos sueltos tambien tendran `source_id` mediante una fuente logica por defecto, evitando valores nulos.
|
|
|
|
**Propuesta concreta ya aceptada como base de trabajo:**
|
|
- `source_id`: `src:<tenant>:<source_kind>:<source_name>`
|
|
- `document_id`: `doc:<source_id>:<document_key>`
|
|
- `chunk_id`: `chk:<document_id>:<chunk_mode>:<chunk_index>`
|
|
|
|
**Por que esta forma parece adecuada:**
|
|
- mantiene legibilidad humana
|
|
- deja espacio para multi-tenant desde ahora sin obligar a usarlo plenamente
|
|
- separa bien fuente, documento y chunk
|
|
- permite distinguir tambien el modo de chunking en el identificador del fragmento
|
|
|
|
**Aclaracion importante sobre `tenant`:**
|
|
En este diseño, `tenant` significa el espacio logico de separacion de datos dentro del servicio RAG.
|
|
|
|
No obliga a que desde el primer dia haya varios clientes activos, pero evita que la arquitectura quede cerrada a un unico contexto.
|
|
|
|
Usar `default` al inicio permite trabajar simple hoy y quedar preparados para mañana.
|
|
|
|
**Hallazgo practico posterior:**
|
|
Una misma coleccion vectorial puede servir varias fuentes distintas siempre que queden bien separadas por identificadores y por alcance de consulta.
|
|
|
|
Ejemplo ya probado:
|
|
- `docs/` del workspace como documentacion global
|
|
- `RAG/docs/` como documentacion propia del modulo RAG
|
|
|
|
La separacion operativa actual se hace por `sourceRef` y `source_id` dentro del `scope` de consulta.
|
|
|
|
Esto demuestra en pequeno el mismo patron que luego servira para separar clientes, proyectos o dominios dentro del mismo sistema.
|
|
|
|
---
|
|
|
|
### Despliegue bien integrado en EasyPanel frente a despliegue manual local
|
|
|
|
**Hallazgo posterior:**
|
|
`webfetch` funciona en `VPS2`, pero su imagen fue construida manualmente en el VPS y luego asociada a EasyPanel por nombre local de imagen.
|
|
|
|
**Problema de ese patron:**
|
|
- funciona operativamente
|
|
- pero no queda totalmente integrado con el flujo esperado de EasyPanel para redeploy y gestion de fuente
|
|
|
|
**Conclusion aplicada a `RAG`:**
|
|
para dejar `RAG` bien integrado, conviene usar el patron esperado por EasyPanel:
|
|
- `App Service`
|
|
- fuente Git con `Dockerfile`, o imagen publicada en registry
|
|
|
|
Esto permitira que el panel pueda redesplegar de forma coherente sin depender de una imagen local construida fuera de su flujo.
|
|
|
|
**Decision complementaria sobre `document_key`:**
|
|
Se adopta como regla base que el documento se identifique por una clave interna normalizada, preferiblemente relativa a la fuente.
|
|
|
|
La idea es:
|
|
- usar rutas relativas cuando existan
|
|
- usar nombres normalizados para documentos sueltos
|
|
- usar referencias estables para fuentes externas o derivadas
|
|
|
|
**Por que esta decision completa bien el esquema:**
|
|
- evita depender de rutas absolutas locales
|
|
- mantiene IDs legibles y estables
|
|
- hace posible tratar con la misma logica archivos, PDFs sueltos, APIs documentales u otras fuentes futuras
|
|
|
|
**Matiz adicional aceptado:**
|
|
`document_key` no sustituye al localizador real del fichero o recurso. Su papel es servir como identidad interna estable dentro del sistema.
|
|
|
|
---
|
|
|
|
### Metadatos minimos aceptados
|
|
|
|
**Decision:**
|
|
Se ha aceptado como base este conjunto:
|
|
|
|
- `source_id`
|
|
- `source_type`
|
|
- `source_path` o `source_ref`
|
|
- `document_id`
|
|
- `chunk_id`
|
|
- `title`
|
|
- `updated_at`
|
|
- `hash`
|
|
- `status`
|
|
- `version`
|
|
- `tags`
|
|
|
|
**Por que:**
|
|
- equilibran simplicidad y preparacion para evolucion
|
|
- permiten trazabilidad
|
|
- preparan el sistema para cambios y actualizaciones futuras
|
|
- evitan tener que rediseñar demasiado pronto el modelo de datos
|
|
|
|
---
|
|
|
|
### Chunking: una sola estrategia como implementacion inicial, pero no como vision final
|
|
|
|
**Decision:**
|
|
Se empezo aceptando una estrategia comun de chunking para la v1 por simplicidad.
|
|
|
|
**Matiz importante posterior:**
|
|
Dado que el RAG tambien servira para desarrollo de software, la vision final no debe quedarse en un unico chunking universal.
|
|
|
|
**Conclusion actual:**
|
|
La arquitectura debe quedar preparada al menos para dos modos:
|
|
|
|
- `documental`
|
|
- `codigo`
|
|
|
|
**Aclaracion importante:**
|
|
El modo `codigo` no se deja de lado como direccion del sistema. Sigue siendo parte del objetivo del RAG por su uso previsto en desarrollo de software.
|
|
|
|
Lo que se prioriza primero es cerrar y construir una v1 documental estable para arrancar antes, sin renunciar a incorporar despues el modo `codigo` sobre una arquitectura ya preparada.
|
|
|
|
**Decision posterior ya implementada:**
|
|
El modo `codigo` ha quedado implementado en la v1 con:
|
|
- soporte de extensiones tecnicas habituales
|
|
- chunking por bloques top-level
|
|
- retrieve filtrable por `mode: codigo`
|
|
- answer con referencias de bloque y rango de lineas cuando aplica
|
|
|
|
**Prueba funcional ya realizada:**
|
|
se ingirio `RAG/src/` y se respondio correctamente a una consulta real sobre como se construye `source_id` en el sistema.
|
|
|
|
**Por que:**
|
|
- documentacion y codigo no se parten ni se recuperan igual de bien
|
|
- un chunking puramente documental podria aprovechar mal el codigo fuente
|
|
- el objetivo del sistema exige servir a ambos mundos
|
|
|
|
**Matiz importante ya asumido:**
|
|
Cambiar de forma relevante la estrategia de chunking en el futuro implicara normalmente reprocessar e indexar de nuevo la informacion afectada.
|
|
|
|
Esto no invalida avanzar con una v1 simple, pero refuerza la idea de elegir una base suficientemente solida desde ahora.
|
|
|
|
**Decision ya cerrada para el modo documental de la v1:**
|
|
- cortar primero por estructura natural
|
|
- subdividir por parrafos cuando haga falta
|
|
- usar corte por longitud solo como ultimo recurso
|
|
- trabajar con una referencia aproximada por caracteres
|
|
- aplicar overlap pequeno y fijo
|
|
|
|
**Valores elegidos para arrancar:**
|
|
- objetivo aproximado: 1500 caracteres
|
|
- maximo aproximado: 2200 caracteres
|
|
- overlap aproximado: 200 caracteres
|
|
|
|
**Por que se cierran ya estos valores:**
|
|
- permiten construir la v1 sin seguir aplazando decisiones basicas
|
|
- mantienen una complejidad baja
|
|
- ofrecen una base razonablemente estable para documentacion normal
|
|
- dejan abierta una futura variante `documental_largo` para libros o contenido tecnico extenso
|
|
|
|
---
|
|
|
|
### Seleccion de modo: enfoque hibrido
|
|
|
|
**Decision:**
|
|
La seleccion del modo debe ser hibrida.
|
|
|
|
**Forma acordada:**
|
|
- el consumidor puede indicar el modo explicitamente
|
|
- si no lo hace, el sistema intenta inferirlo
|
|
|
|
**Por que:**
|
|
- combina control y comodidad
|
|
- evita obligar a multiples interfaces separadas demasiado pronto
|
|
- permite a un agente elegir segun el contenido o dejar que el sistema ayude
|
|
|
|
**Modo base previsto:**
|
|
- `documental`
|
|
- `codigo`
|
|
- `auto`
|
|
|
|
---
|
|
|
|
### La salida del RAG debe contemplar contexto, no solo respuestas
|
|
|
|
**Decision:**
|
|
Se consideran validos al menos estos tipos de salida conceptuales:
|
|
|
|
- `retrieve`
|
|
- `answer`
|
|
- opcion intermedia de contexto mas sintesis
|
|
|
|
**Por que:**
|
|
- el mayor valor para agentes de desarrollo esta en recuperar contexto rico y trazable
|
|
- atencion al cliente puede beneficiarse de contexto mas respuesta sintetizada
|
|
- una salida solo orientada a respuesta dejaría corto el sistema para los usos previstos
|
|
|
|
**Decision posterior ya implementada:**
|
|
`answer` se monta sobre `retrieve`, no como un camino independiente.
|
|
|
|
**Por que:**
|
|
- mantiene una arquitectura mas limpia
|
|
- obliga a que la respuesta final siga dependiendo del contexto recuperado
|
|
- hace visible que mejorar `retrieve` mejora tambien `answer`
|
|
|
|
**Ajuste posterior relevante:**
|
|
`retrieve specific` se ha afinado para preguntas operativas frecuentes mediante subconsultas y reordenacion por intencion.
|
|
|
|
**Efecto visible:**
|
|
mejora respuestas como la consulta de pendientes del workspace, que ahora ya baja a lineas concretas del backlog en lugar de quedarse solo en la descripcion general del documento.
|
|
|
|
---
|
|
|
|
### Retrieve inicial y retrieve especifico
|
|
|
|
**Decision en formacion:**
|
|
Se ve mucho valor en separar:
|
|
|
|
- un `retrieve inicial` o de arranque
|
|
- un `retrieve especifico` para profundizar
|
|
|
|
**Idea del retrieve inicial:**
|
|
Debe comportarse como un mapa del dominio, no como una respuesta en detalle.
|
|
|
|
**Ese mapa deberia incluir:**
|
|
- vision general
|
|
- temas principales
|
|
- puntos criticos
|
|
- estructura o areas
|
|
- referencias para profundizar
|
|
|
|
**Aporte adicional aceptado:**
|
|
Algunas piezas podran marcarse explicitamente como criticas para que el sistema les de prioridad en ese contexto inicial.
|
|
|
|
**Por que:**
|
|
- evita saturar al modelo con demasiado detalle desde el principio
|
|
- da orientacion general al agente
|
|
- permite usar consultas posteriores para profundizar solo donde haga falta
|
|
|
|
**Decision posterior ya estructurada:**
|
|
El `retrieve` inicial queda entendido como un paquete de contexto de arranque con esta estructura base:
|
|
|
|
- `mode`
|
|
- `intent`
|
|
- `summary`
|
|
- `topics`
|
|
- `critical_points`
|
|
- `items`
|
|
- `follow_up_refs`
|
|
- `scope`
|
|
|
|
**Sentido de esta estructura:**
|
|
- combina panorama general y trazabilidad
|
|
- sirve tanto a agentes conversacionales como a agentes de desarrollo
|
|
- permite pasar de una carga inicial de contexto a una profundizacion posterior sin perder el mapa del dominio
|
|
|
|
**Matiz posterior aceptado:**
|
|
El `retrieve`, y en especial el `bootstrap`, debe poder recibir un alcance explicito para cargar solo el contexto de una fuente concreta, por ejemplo un workspace o proyecto determinado.
|
|
|
|
**Decision posterior ya implementada:**
|
|
El `bootstrap` deja de comportarse como una sola busqueda ampliada y pasa a usar varias subconsultas internas para construir un mapa inicial mas util.
|
|
|
|
**Por que:**
|
|
- mejora la cobertura del contexto de arranque
|
|
- recupera mejor documentos base como indice, README, pendientes o historial
|
|
- se ajusta mejor al objetivo de volver rapidamente experto a un agente sobre un workspace o proyecto concreto
|
|
|
|
---
|
|
|
|
## Posibilidades abiertas que siguen vivas
|
|
|
|
- integrar el RAG con MCP como canal de conexion a sistemas de IA
|
|
- potenciar el RAG con Obsidian como posible fuente, capa de organizacion o entorno complementario de conocimiento
|
|
- usarlo como servicio comun para distintos clientes y aplicaciones
|
|
- permitir mejoras del motor que beneficien a todos los consumidores del servicio
|
|
- evolucionar hacia algun tipo de historico o versionado inspirado en ideas parecidas a git
|
|
- introducir estrategias especificas de chunking por tipo de documento o fuente
|
|
- ampliar el modo documental con soporte especializado para PDFs complejos o escaneados mediante OCR si llegara a hacer falta
|
|
- definir memoria base de sesion mas retrieves dinamicos posteriores
|
|
|
|
---
|
|
|
|
### Los PDFs entran en la v1
|
|
|
|
**Decision:**
|
|
Los PDFs no se aplazan. Deben estar soportados desde la primera version del sistema.
|
|
|
|
**Por que:**
|
|
- en entornos reales de empresa y proyectos, mucha informacion relevante llega en PDF
|
|
- dejarlos fuera desde el inicio recortaria demasiado el valor practico de la v1
|
|
- el objetivo del RAG es ser util desde pronto en escenarios reales, no solo con Markdown o texto plano
|
|
|
|
**Matiz importante:**
|
|
El soporte inicial se entiende para PDFs con texto extraible. PDFs escaneados o de mala calidad podran requerir despues una capa adicional de OCR o tratamiento especializado.
|
|
|
|
---
|
|
|
|
## Pendientes inmediatos del diseño
|
|
|
|
1. Definir como se construiran exactamente `source_id`, `document_id` y `chunk_id`.
|
|
2. Definir la estrategia concreta del chunking inicial.
|
|
3. Definir que debe devolver exactamente `retrieve`.
|
|
4. Definir que bloques tendra el `retrieve inicial` tipo mapa de dominio.
|
|
5. Definir como se accedera a los servicios minimos del RAG desde la API.
|
|
6. Definir si la ingesta asistida por modelo estara presente desde la v1 o quedara para la siguiente fase.
|
|
|
|
---
|
|
|
|
## Rol de esta bitacora dentro del modulo
|
|
|
|
Los otros documentos del modulo deben ir recogiendo decisiones concretas por areas.
|
|
|
|
Esta bitacora, en cambio, debe conservar la panoramica del camino seguido:
|
|
|
|
- que se quiere construir
|
|
- para que se quiere construir
|
|
- como se esta razonando el diseño
|
|
- que se decide ahora
|
|
- que se deja abierto para mas adelante
|