Sistema RAG (Retrieval-Augmented Generation)

Un stack completo de servicios para implementar un sistema RAG utilizando Docker Compose. Este proyecto proporciona una infraestructura robusta para el procesamiento de documentos, búsqueda vectorial y generación de respuestas asistidas por IA.

🏗️ Arquitectura del Sistema

Este stack incluye los siguientes servicios:

🤖 IA y Procesamiento

Ollama - Servidor de modelos de lenguaje local (con soporte CPU/GPU)
Qdrant - Base de datos vectorial para búsqueda semántica

🔄 Automatización y Orquestación

n8n - Plataforma de automatización de workflows
PostgreSQL - Base de datos principal para n8n

💾 Almacenamiento y Cache

Redis - Cache en memoria y almacén de datos
MongoDB - Base de datos NoSQL para documentos
Neo4j - Base de datos de grafos para relaciones complejas y análisis de conexiones

🔐 Autenticación

Keycloak - Servidor de gestión de identidad y acceso

🛠️ Herramientas de Administración

Mongo Express - Interfaz web para MongoDB

🚀 Inicio Rápido

Prerrequisitos

Docker y Docker Compose instalados
Al menos 8GB de RAM disponible
(Opcional) GPU NVIDIA para aceleración

Configuración de Variables de Entorno

Método 1: Uso del archivo de ejemplo (Recomendado)

# Copia el archivo de ejemplo
cp env.example .env

# Edita el archivo según tus necesidades
nano .env  # o usa tu editor preferido

El archivo env.example incluye:

✅ Todas las variables necesarias con documentación detallada
🔧 Configuraciones opcionales para personalización avanzada
📝 Instrucciones claras para cada sección
🛡️ Placeholders seguros que debes reemplazar

Método 2: Configuración mínima manual

Si prefieres crear el archivo .env manualmente:

# PostgreSQL
POSTGRES_USER=n8n_user
POSTGRES_PASSWORD=tu_password_seguro
POSTGRES_DB=n8n

# n8n (OBLIGATORIO)
N8N_ENCRYPTION_KEY=tu_clave_de_encriptacion_muy_larga_y_segura
N8N_USER_MANAGEMENT_JWT_SECRET=tu_jwt_secret_muy_largo_y_seguro

Generación de claves seguras

# Generar claves de encriptación seguras
openssl rand -hex 32

Ejecución

Opción 1: Scripts automatizados (Recomendado)

# Hacer los scripts ejecutables (solo la primera vez)
chmod +x start-cpu.sh start-gpu.sh stop.sh

# Para sistemas con CPU únicamente
./start-cpu.sh

# Para sistemas con GPU NVIDIA
./start-gpu.sh

# Para iniciar sin Ollama (usando LLMs externos)
./start-no-ollama.sh

# Para detener los servicios
./stop.sh

Opción 2: Docker Compose manual

# Para sistemas con CPU únicamente
docker-compose --profile cpu up -d

# Para sistemas con GPU NVIDIA
docker-compose --profile gpu-nvidia up -d

📋 Servicios y Puertos

Servicio	Puerto	URL	Credenciales
n8n	5678	http://localhost:5678	admin / Test@132
Qdrant	6333	http://localhost:6333	-
Redis	6379, 8001	http://localhost:8001	-
MongoDB	27017	-	mongoadmin / secret123
Mongo Express	8081	http://localhost:8081	mongoadmin / secret123
Neo4j	7474, 7687	http://localhost:7474	neo4j / test1234
Ollama	11434	http://localhost:11434	-
Keycloak	8080	http://localhost:8080	admin / admin123

🔧 Configuración Detallada

Modelos de Ollama

El sistema descarga automáticamente el modelo llama3.1. Para agregar más modelos:

# Ejecutar dentro del contenedor ollama
docker exec -it ollama ollama pull <nombre_del_modelo>

n8n Workflows

Los workflows se importan automáticamente desde ./n8n/backup/workflows
Las credenciales se importan desde ./n8n/backup/credentials
Los archivos compartidos se almacenan en ./shared

Qdrant

Qdrant está configurado para almacenar vectores y realizar búsquedas semánticas. La API REST está disponible en el puerto 6333.

Neo4j

Neo4j proporciona capacidades de base de datos de grafos para el sistema RAG, permitiendo:

Modelado de relaciones entre documentos, entidades y conceptos
Análisis de conexiones para mejorar la recuperación de información
Grafos de conocimiento para contexto enriquecido
Consultas Cypher para navegación compleja de relaciones

Casos de uso en RAG:

Mapeo de relaciones entre documentos
Análisis de dependencias de conceptos
Navegación de entidades relacionadas
Construcción de grafos de conocimiento dinámicos

Acceso:

Interfaz web: http://localhost:7474
Puerto Bolt: 7687 (para drivers y aplicaciones)
Credenciales: neo4j / test1234

📁 Estructura de Directorios

RAG/
├── docker-compose.yml          # Configuración principal
├── env.example                # Archivo de ejemplo para variables de entorno
├── start-cpu.sh               # Script para iniciar con perfil CPU
├── start-gpu.sh               # Script para iniciar con perfil GPU
├── start-no-ollama.sh         # Script para iniciar sin Ollama
├── stop.sh                    # Script para detener servicios
├── fix-docker.sh              # Script para solucionar problemas de Docker
├── .env                       # Variables de entorno (copiar de env.example)
├── n8n/
│   └── backup/                # Backups de workflows y credenciales
│       ├── workflows/
│       └── credentials/
├── shared/                    # Archivos compartidos entre servicios
└── keycloak_data/            # Datos de Keycloak

🛠️ Scripts de Gestión

Scripts Automatizados

Los scripts incluidos proporcionan una experiencia más amigable y automatizan tareas comunes:

`start-cpu.sh` - Inicio con CPU

✅ Verificación automática de Docker y dependencias
🔧 Creación automática de archivo .env con valores seguros
📁 Preparación de directorios necesarios
📊 Información del sistema y recursos disponibles
⏳ Verificación del estado de los servicios
📋 Lista completa de URLs y credenciales

`start-gpu.sh` - Inicio con GPU NVIDIA

🎯 Verificación de GPUs y drivers NVIDIA
🔍 Detección automática de VRAM disponible
⚡ Configuración optimizada para aceleración GPU
📈 Monitoreo del uso de GPU en Ollama
🛡️ Validaciones de seguridad antes del inicio

`start-no-ollama.sh` - Inicio sin Ollama

🚫 Excluye todos los servicios de Ollama (CPU y GPU)
🌐 Ideal para usar LLMs externos (OpenAI, Claude, Gemini)
⚡ Inicio más rápido y menor uso de recursos
🔧 Todos los demás servicios del stack disponibles
💡 Opción para agregar Ollama posteriormente

`stop.sh` - Gestión de parada

🛑 Múltiples opciones de parada (normal, completa, con limpieza)
📊 Visualización del estado actual de servicios
💾 Gestión segura de volúmenes y datos
⚠️ Confirmaciones para operaciones destructivas

Uso de los Scripts

# Primera ejecución - hacer ejecutables
chmod +x *.sh

# Iniciar con CPU
./start-cpu.sh

# Iniciar con GPU NVIDIA
./start-gpu.sh

# Iniciar sin Ollama (para LLMs externos)
./start-no-ollama.sh

# Detener servicios (con opciones interactivas)
./stop.sh

¿Cuál Script Usar?

Script	Cuándo Usarlo	Servicios Incluidos	Recursos
`start-cpu.sh`	Desarrollo completo con LLM local	Todos + Ollama CPU	RAM: 8-16GB
`start-gpu.sh`	Producción con aceleración GPU	Todos + Ollama GPU	RAM: 8GB + GPU
`start-no-ollama.sh`	APIs externas o desarrollo ligero	Sin Ollama	RAM: 4-8GB

Casos de uso para `start-no-ollama.sh`:

🌐 APIs externas: OpenAI, Anthropic Claude, Google Gemini
⚡ Desarrollo rápido: Testing sin esperar descarga de modelos
💻 Recursos limitados: Máquinas con poca RAM o sin GPU
🔧 Servicios específicos: Solo necesitas n8n, Qdrant, etc.
🧪 Testing: Probar configuraciones sin LLM local

🛠️ Comandos Útiles

Gestión Manual de Contenedores

# Iniciar todos los servicios
docker-compose --profile cpu up -d

# Detener todos los servicios
docker-compose down

# Ver logs de un servicio específico
docker-compose logs -f <nombre_servicio>

# Reiniciar un servicio
docker-compose restart <nombre_servicio>

Backup y Restauración

# Backup de volúmenes
docker-compose exec postgres pg_dump -U $POSTGRES_USER $POSTGRES_DB > backup.sql

# Acceso a Redis CLI
docker-compose exec cache redis-cli

# Acceso a MongoDB
docker-compose exec mongodb mongosh -u mongoadmin -p secret123

# Acceso a Neo4j Cypher Shell
docker-compose exec neo4j cypher-shell -u neo4j -p test1234

# Backup de Neo4j
docker-compose exec neo4j neo4j-admin backup --backup-dir=/data/backup --name=graph.db

🔍 Solución de Problemas

Problemas Comunes

🐳 Problemas de Docker

Error "docker-credential-desktop not found"

# Solución automática
./fix-docker.sh

# O solución manual
rm ~/.docker/config.json
docker login  # Si es necesario

Docker daemon no responde
- Reinicia Docker Desktop completamente
- Verifica que Docker esté completamente iniciado (icono en la barra de tareas)
- Ejecuta: docker system prune -f
Error de memoria insuficiente
- Aumenta la memoria asignada a Docker (mínimo 8GB recomendado)
- Considera ejecutar solo los servicios necesarios

🚀 Problemas de Servicios

Ollama no descarga modelos
- Verifica la conexión a internet
- Revisa los logs: docker-compose logs ollama-pull-llama-cpu
- El primer inicio puede tardar 10-15 minutos
n8n no puede conectar a PostgreSQL
- Verifica que las variables de entorno estén configuradas
- Espera a que PostgreSQL termine de inicializar (puede tardar 2-3 minutos)
- Revisa: docker-compose logs postgres
Neo4j no inicia correctamente
- Verifica que los puertos 7474 y 7687 estén disponibles
- Revisa los logs: docker-compose logs neo4j
- El primer inicio puede tardar varios minutos
Error de autenticación en Neo4j
- Las credenciales por defecto son: neo4j / test1234
- Si cambias la contraseña, actualiza la variable NEO4J_AUTH

🔧 Script de Diagnóstico

Para problemas de Docker, ejecuta el script de diagnóstico:

chmod +x fix-docker.sh
./fix-docker.sh

Este script:

✅ Detecta y soluciona problemas de credenciales
🔄 Intenta iniciar Docker automáticamente
🧹 Limpia recursos no utilizados
📊 Verifica configuración del sistema

Logs y Debugging

# Ver todos los logs
docker-compose logs

# Logs en tiempo real de un servicio
docker-compose logs -f n8n

# Estado de los contenedores
docker-compose ps

🤝 Contribución

Fork el proyecto
Crea una rama para tu feature (git checkout -b feature/nueva-funcionalidad)
Commit tus cambios (git commit -am 'Añade nueva funcionalidad')
Push a la rama (git push origin feature/nueva-funcionalidad)
Crea un Pull Request

📄 Licencia

Este proyecto está bajo la licencia MIT. Ver el archivo LICENSE para más detalles.

🆘 Soporte

Si encuentras algún problema o tienes preguntas:

Revisa la sección de solución de problemas
Busca en los issues existentes
Crea un nuevo issue con detalles del problema

⚡ Nota: Este es un entorno de desarrollo. Para producción, asegúrate de cambiar todas las contraseñas por defecto y configurar adecuadamente la seguridad.

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
.env		.env
.gitattributes		.gitattributes
README.md		README.md
docker-compose.yml		docker-compose.yml
env.example		env.example
fix-docker.sh		fix-docker.sh
start-cpu.sh		start-cpu.sh
start-gpu.sh		start-gpu.sh
start-no-ollama.sh		start-no-ollama.sh
stop.sh		stop.sh

Folders and files

Latest commit

History

Repository files navigation