221 lines
6.7 KiB
Markdown
221 lines
6.7 KiB
Markdown
# Stack tecnico v1
|
|
|
|
**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:** Acordado para v1
|
|
|
|
---
|
|
|
|
## Proposito
|
|
|
|
Definir el stack tecnico minimo con el que se construira la primera version funcional del RAG.
|
|
|
|
Las decisiones tomadas aqui deben entenderse como base estable del sistema, no como elecciones provisionales pensadas para ser sustituidas inmediatamente en una siguiente version.
|
|
|
|
---
|
|
|
|
## Stack acordado
|
|
|
|
### Runtime y lenguaje
|
|
|
|
- `Node.js`
|
|
- `TypeScript`
|
|
|
|
**Por que:**
|
|
- equilibrio entre velocidad de desarrollo y estructura
|
|
- buen encaje con APIs, tools y futuras integraciones
|
|
- facilita evolucion posterior hacia MCP u otras capas de consumo
|
|
|
|
---
|
|
|
|
### Backend HTTP
|
|
|
|
- `Express`
|
|
|
|
**Por que:**
|
|
- simplicidad de arranque
|
|
- ecosistema amplio
|
|
- suficiente para esta v1
|
|
- el rendimiento del framework no es el cuello de botella principal del sistema ahora mismo
|
|
|
|
**Encaje operativo:**
|
|
- compatible con despliegue local y en VPS
|
|
- adecuado para montarlo como servicio en EasyPanel dentro de un contenedor propio
|
|
|
|
---
|
|
|
|
### Vector store
|
|
|
|
- `Qdrant`
|
|
|
|
**Por que:**
|
|
- pensado especificamente para busqueda vectorial
|
|
- mas adecuado para un RAG real que usar solo una base de datos generalista
|
|
- deja una base mejor para evolucion posterior que una solucion demasiado provisional
|
|
|
|
**Matiz:**
|
|
- `SQLite` podria servir como apoyo auxiliar para ciertos metadatos o control local, pero no se toma como nucleo del retrieval vectorial
|
|
- en un escenario con EasyPanel, `Qdrant` encaja bien como servicio separado o contenedor adjunto al servicio principal del RAG
|
|
|
|
---
|
|
|
|
### Embeddings
|
|
|
|
- proveedor desacoplado mediante una interfaz interna del sistema
|
|
|
|
**Por que:**
|
|
- evita atarnos a un unico proveedor desde el inicio
|
|
- permite cambiar por coste, calidad o disponibilidad sin rehacer el nucleo del RAG
|
|
- facilita pruebas comparativas en el futuro
|
|
|
|
**Aclaracion importante:**
|
|
Esto debe entenderse como una capa de abstraccion o adaptador interno para proveedores de embeddings, no como una dependencia directa del resto del sistema hacia un proveedor concreto.
|
|
|
|
**Decision cerrada para la base estable del sistema:**
|
|
- `Qwen3 Embedding 8B`
|
|
|
|
**Por que se elige este modelo:**
|
|
- encaja con el objetivo de que la v1 ya sea una base estable y no una eleccion pensada para cambiar pronto
|
|
- sirve tanto para recuperacion textual como para recuperacion de codigo
|
|
- ofrece capacidades multilingues y manejo de texto largo
|
|
- esta disponible ahora en OpenRouter para poder arrancar
|
|
- puede desplegarse de forma local mas adelante, manteniendo coherencia con la arquitectura deseada
|
|
|
|
**Referencia de comparacion, no decision principal:**
|
|
- `OpenAI text-embedding-3-large` se considera una referencia valida de calidad comercial, pero no se adopta como base del sistema porque no encaja igual de bien con el objetivo de despliegue local futuro
|
|
|
|
**Consecuencia de cambiar de modelo de embeddings:**
|
|
- los vectores generados por modelos distintos no deben mezclarse como si vivieran en el mismo espacio semantico
|
|
- si se cambia de modelo de embeddings, normalmente hay que re-embeddear el contenido afectado
|
|
- esto no obliga a perder trazabilidad si el sistema guarda que modelo y que version genero cada embedding
|
|
|
|
**Criterio de diseño adoptado:**
|
|
- cada embedding debe registrar al menos su `embedding_provider`, `embedding_model` y `embedding_dimensions`
|
|
- el sistema debe poder saber con que modelo fue indexado cada documento o chunk
|
|
- el retrieval debe consultar dentro de un indice o coleccion coherente con el modelo de embeddings usado
|
|
|
|
**Configuracion base prevista:**
|
|
- modelo base: `Qwen3 Embedding 8B`
|
|
- acceso inicial: proveedor externo compatible
|
|
- acceso futuro previsto: despliegue local en red propia manteniendo la misma abstraccion del proveedor
|
|
|
|
**Direccion recomendada:**
|
|
- tratar cada combinacion relevante de proveedor y modelo como una version de indexacion
|
|
- permitir reindexacion controlada cuando se quiera migrar a otro modelo
|
|
- evitar mezclar embeddings de modelos distintos en la misma logica de recuperacion
|
|
|
|
---
|
|
|
|
### Parsing documental
|
|
|
|
Soporte inicial previsto para:
|
|
|
|
- `md`
|
|
- `txt`
|
|
- `pdf`
|
|
- codigo fuente del proyecto
|
|
|
|
**Por que:**
|
|
- cubre documentacion habitual del workspace y de escenarios reales de empresa
|
|
- el soporte de PDF es obligatorio desde la v1
|
|
|
|
**Matiz:**
|
|
- la v1 contempla PDFs con texto extraible
|
|
- OCR para PDFs escaneados o de baja calidad queda como ampliacion futura
|
|
|
|
Extensiones de codigo ya soportadas:
|
|
- `ts`
|
|
- `tsx`
|
|
- `js`
|
|
- `jsx`
|
|
- `mjs`
|
|
- `cjs`
|
|
- `py`
|
|
- `json`
|
|
- `yml`
|
|
- `yaml`
|
|
|
|
---
|
|
|
|
### Chunking y pipeline interno
|
|
|
|
- implementacion propia en TypeScript
|
|
|
|
**Por que:**
|
|
- el comportamiento del chunking forma parte central del diseño del sistema
|
|
- ya se han acordado reglas propias que conviene controlar directamente
|
|
- evita depender demasiado pronto de una abstraccion externa que no siga nuestras decisiones
|
|
|
|
---
|
|
|
|
### Forma de acceso
|
|
|
|
- API HTTP como base principal
|
|
|
|
**Por que:**
|
|
- permite que otras apps, agentes y sistemas consuman el RAG con facilidad
|
|
- permite pruebas inmediatas desde terminal
|
|
- encaja bien con una futura capa MCP
|
|
|
|
Endpoints funcionales actuales:
|
|
- `GET /health`
|
|
- `POST /ingest`
|
|
- `POST /retrieve`
|
|
- `POST /answer`
|
|
|
|
---
|
|
|
|
## Configuracion local de claves
|
|
|
|
Se deja previsto un archivo local `RAG/.env.local` para trabajar claves y configuraciones sensibles sin incluirlas en el repositorio.
|
|
|
|
Uso previsto:
|
|
- `EMBEDDING_API_KEY` para OpenRouter o proveedor compatible
|
|
- credenciales de `Qdrant` si aplican
|
|
- futuras claves de servicios asociados
|
|
|
|
Este archivo esta ignorado por Git.
|
|
|
|
---
|
|
|
|
## Encaje con EasyPanel
|
|
|
|
La estructura tecnica inicial se ha planteado para que el modulo pueda ejecutarse:
|
|
|
|
- en local durante desarrollo
|
|
- en un VPS Debian gestionado desde EasyPanel
|
|
|
|
Direccion operativa recomendada:
|
|
|
|
- un contenedor para la API del RAG
|
|
- un servicio de `Qdrant` separado o adjunto segun convenga
|
|
- variables de entorno gestionadas desde EasyPanel
|
|
|
|
Esto mantiene simple el despliegue y evita acoplar el codigo a una unica maquina o ruta local.
|
|
|
|
---
|
|
|
|
## Direccion general del stack
|
|
|
|
La v1 se construira con una idea clara:
|
|
|
|
- base simple de poner en marcha
|
|
- lo bastante seria para servir en casos reales
|
|
- preparada para evolucionar sin rehacer todo al cambiar proveedor o ampliar capacidades
|
|
|
|
---
|
|
|
|
## Decisiones ya cerradas que condicionan este stack
|
|
|
|
- el RAG se pensara como servicio
|
|
- PDFs entran desde la v1
|
|
- el modo `codigo` sigue siendo parte de la direccion del sistema aunque no sea la primera implementacion
|
|
- la salida del RAG debe servir tambien para contexto, no solo para respuestas finales
|
|
|
|
---
|
|
|
|
## Pendiente inmediato
|
|
|
|
Generar la imagen Docker final del servicio y dejarlo listo para desplegar en EasyPanel.
|