rag-service/RAG/docs/STACK_TECNICO_V1.md

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.