Discord RAG Bot

Bot RAG para Discord configurable, capaz de responder preguntas usando una base de conocimiento local con Ollama y ChromaDB, optimizado para hardware modesto.

El proyecto está pensado para que una persona pueda clonarlo, ajustar .env, añadir sus documentos, ejecutar /sync_knowledge y empezar a usar /ai sin tocar el código.

Lo mínimo que tienes que cambiar

Si solo te interesa poner el bot en marcha rápido, esto es lo único que debes modificar después de clonar el repo:

Archivo / Carpeta	Qué cambiar
.env	Copia .env.example a .env y pega tu token de Discord. Opcionalmente puedes definir los modelos que tengas en Ollama mediante variables de entorno (ver sección Configuración)
knowledge_base/	Añadir tus archivos .md o .txt con la información que el bot debe conocer

Todo lo demás (comportamiento del bot, chunking, prompt, etc.) tiene valores por defecto razonables y listos para usar.

Qué hace

El bot responde en Discord a partir de documentos locales en formato .md y .txt.

Flujo básico:

1. Un usuario pregunta con /ai.
2. El bot busca fragmentos relevantes en ChromaDB.
3. Envía esos fragmentos como contexto a un modelo local en Ollama.
4. Devuelve la respuesta en Discord.

No indexa documentos al arrancar. La indexación se hace manualmente con /sync_knowledge.

Qué significa RAG

RAG significa Retrieval-Augmented Generation.

En este proyecto quiere decir que el modelo no responde solo con su conocimiento interno. Primero se recuperan fragmentos de tus documentos locales y después el modelo genera una respuesta usando ese contexto.

Esto permite cambiar el conocimiento del bot modificando archivos, sin reentrenar modelos.

Características

• Slash command /ai para hacer preguntas.
• Slash command /sync_knowledge para reindexar manualmente.
• Base de conocimiento local en archivos .md y .txt.
• ChromaDB como base vectorial persistente.
• Ollama para chat y embeddings locales.
• Modelo de chat y modelo de embeddings configurables por separado.
• Cola simple para procesar una generación pesada a la vez.
• Estados visibles: búsqueda, procesamiento y posición en cola.
• Límite de hilos configurable con num_thread.
• División automática de respuestas largas para Discord.
• Caché simple para preguntas repetidas.
• Sin secretos en el código.
• 100% Contenedorizado: Se ejecuta mediante Docker y Docker Compose, funcionando de forma idéntica en Linux, macOS y Windows.

Estructura

discord-rag-bot/
├─ Dockerfile
├─ docker-compose.yml
├─ pyproject.toml
├─ requirements.txt
├─ .gitignore
├─ .dockerignore
├─ .env.example
├─ config.example.json
├─ README.md
├─ LICENSE
├─ knowledge_base/
│  └─ .gitkeep
└─ src/
   ├─ bot.py
   ├─ config.py
   ├─ indexer.py
   ├─ rag.py
   └─ utils.py

Requisitos

• Docker y Docker Compose instalados en el sistema (ej. Docker Desktop para Windows/macOS, o Docker Engine + Compose plugin para Linux).
• Ollama instalado y funcionando en la máquina host.
• Una cuenta de Discord.
• Un bot creado en el Discord Developer Portal.

El bot usa slash commands, así que no necesita activar el privileged intent de contenido de mensajes.

---

Instalación y Despliegue

1. Clonar el repositorio

git clone https://github.com/samu-tec/discord-rag-bot.git
cd discord-rag-bot

2. Configurar Ollama y descargar modelos

Instala Ollama en la máquina host desde ollama.com/download.

Asegúrate de tener descargados los modelos definidos (por defecto qwen2.5:1.5b y nomic-embed-text):

ollama pull qwen2.5:1.5b
ollama pull nomic-embed-text

Important

Nota para usuarios de Linux: Por defecto, el servicio de Ollama en Linux escucha únicamente en 127.0.0.1 (localhost), por lo que el contenedor Docker no podrá acceder a él. Debes configurar Ollama para que escuche en todas las interfaces:

1. Ejecuta sudo systemctl edit ollama.service.
2. Añade las siguientes líneas en el editor que se abrirá:

   [Service]
   Environment="OLLAMA_HOST=0.0.0.0"

3. Guarda y cierra el archivo.
4. Recarga systemd y reinicia Ollama:

   sudo systemctl daemon-reload
   sudo systemctl restart ollama

3. Lanzar el bot de forma automatizada (Recomendado)

Hemos incluido scripts opcionales que preparan los archivos de configuración y arrancan el bot en Docker Compose con un solo comando.

Note

Sobre las restricciones en macOS/Windows: Dado que estos scripts se ejecutan en tu host local, los sistemas operativos pueden restringir su ejecución inicial por seguridad:

• En macOS: Para dar permisos de ejecución al script antes de poder usarlo, abre la terminal y ejecuta chmod +x start-linux-mac.sh.
• En Windows: Al hacer doble clic en start-windows.bat, Windows SmartScreen puede mostrar una advertencia ("Windows protegió su PC"). Puedes hacer clic en "Más información" y luego en "Ejecutar de todas formas" de manera completamente segura ya que puedes leer el código plano del script.

En Linux / macOS:

./start-linux-mac.sh

En Windows: Haz doble clic en start-windows.bat o ejecútalo en la consola de comandos:

start-windows.bat

4. Lanzar el bot manualmente (Recomendado si prefieres evitar scripts)

Si prefieres no ejecutar scripts locales en tu máquina por seguridad o simplicidad, puedes levantar el bot usando comandos nativos de Docker de forma directa:

1. Crear el archivo .env:
   • Linux/macOS: cp .env.example .env
   • Windows (PowerShell): Copy-Item .env.example .env
   • Windows (CMD): copy .env.example .env
2. Editar el archivo .env para colocar tu token en la línea DISCORD_TOKEN=tu-token-aqui.
3. Crear las carpetas de datos:
   • mkdir knowledge_base chroma_db
4. Iniciar el bot:
   • docker compose up -d --build

• Ver estado del servicio: docker compose ps
• Ver los logs en tiempo real: docker compose logs -f
• Detener el bot: docker compose down

---

Crear el bot en Discord

1. Abrir el portal de desarrolladores

Entra en discord.com/developers/applications.

2. Crear una aplicación

Pulsa New Application, ponle un nombre y crea la aplicación.

3. Crear el usuario bot

Dentro de la aplicación, entra en Bot y crea el bot si todavía no existe.

4. Copiar el token

En la sección Bot, pulsa Reset Token, copia el token nuevo y guárdalo en tu archivo .env.

Trata el token como una contraseña:

• No lo subas a GitHub (el .gitignore ya excluye el .env).
• No lo compartas con nadie.
• Si se filtra, vuelve al portal, haz un Reset Token, actualiza el .env y reinicia el contenedor (docker compose restart).

5. Invitar el bot a tu servidor

En el portal de Discord, ve a OAuth2 o Installation y genera una URL de invitación con estos scopes:

• bot
• applications.commands

Permisos recomendados:

• View Channels
• Send Messages
• Read Message History

Abre la URL generada e invita el bot al servidor donde quieras usarlo.

---

Configuración detallada mediante .env

El bot lee sus configuraciones iniciales por defecto de config.example.json (que se copia internamente como config.json), pero puedes sobrescribir absolutamente cualquier valor de configuración directamente desde tu archivo .env, sin necesidad de modificar ningún archivo JSON.

Variables de Entorno Disponibles

Puedes añadir o descomentar estas variables en tu .env para personalizar el comportamiento del bot:

Configuración de Ollama

• OLLAMA_CHAT_MODEL: El modelo de chat utilizado por Ollama para responder (ej. qwen2.5:1.5b).
• OLLAMA_EMBEDDING_MODEL: El modelo de embeddings para procesar los textos (ej. nomic-embed-text).
• OLLAMA_BASE_URL: Dirección base de Ollama (el bot detecta Docker y la reescribe automáticamente a http://host.docker.internal:11434 si es necesario).
• OLLAMA_TEMPERATURE: Nivel de creatividad de las respuestas (ej. 0.2).
• OLLAMA_NUM_THREAD: Hilos de CPU reservados para Ollama (ej. 3).
• OLLAMA_NUM_PREDICT: Longitud máxima aproximada de la respuesta generada (ej. 850).

Configuración del Bot de Discord

• BOT_ACTIVITY_MESSAGE: Mensaje de estado/actividad del bot (ej. Base de conocimiento local).
• BOT_SPLIT_MESSAGE_LIMIT: Límite de caracteres por mensaje para dividir respuestas largas de Discord (ej. 1900).
• BOT_ENABLE_AUTO_THREADS: Si se establece en true, el bot iniciará de forma automática hilos públicos en Discord por cada consulta de /ai para no saturar el canal general (por defecto false).
• BOT_MAX_HISTORY: Cantidad máxima de intercambios (pregunta y respuesta) retenidos en memoria de chat para permitir preguntas de seguimiento (por defecto 5).

Configuración de Indexación y Búsqueda (RAG)

• KNOWLEDGE_DIR: Carpeta de entrada con tus documentos locales (ej. ./knowledge_base).
• DB_DIR: Carpeta donde se guarda ChromaDB persistentemente (ej. ./chroma_db).
• COLLECTION_NAME: Nombre de la colección interna de ChromaDB.
• RETRIEVAL_ENABLE_HYBRID_SEARCH: Si se establece en true, habilita la búsqueda híbrida (ChromaDB + BM25) para mayor precisión textual de palabras clave específicas (por defecto true).
• RETRIEVAL_SOURCE_URL_MAP: Enlace base opcional (ej. de GitHub o wiki) para transformar los nombres de archivo de las fuentes en hipervínculos clickables en Discord.
• TOP_K: Cantidad de fragmentos relevantes recuperados por consulta (ej. 3).
• CHUNK_SIZE: Tamaño de caracteres de cada fragmento (ej. 1200).
• CHUNK_OVERLAP: Solape de caracteres entre fragmentos continuos (ej. 150).

Prompts del Sistema

• SYSTEM_PROMPT: La instrucción maestra del bot que dicta cómo procesar la información y responder.

---

Añadir documentos

Guarda tus archivos en la carpeta local:

knowledge_base/

Formatos soportados:

• .md y .txt: Leídos directamente como texto plano.
• .pdf: El bot lee y extrae automáticamente todo el texto página por página (útil para manuales o libros).
• .url: Archivo de texto que contiene una dirección web (ej. https://ollama.com/library). Al indexar, el bot descargará el HTML y extraerá el texto limpio de forma automatizada (ideal para blogs, wikis o APIs).

Puedes organizar tus archivos en subcarpetas temáticas. Los archivos de texto plano deben estar guardados con codificación UTF-8.

---

Uso en Discord

1. Sincronizar e indexar documentos

Un administrador de tu servidor de Discord debe ejecutar:

/sync_knowledge

Este comando lee los archivos locales del volumen knowledge_base, los divide en fragmentos, genera los embeddings usando Ollama y regenera la base de vectores ChromaDB.

2. Hacer preguntas al bot

/ai pregunta: ¿Cómo se configura el puerto por defecto?

Si el bot está procesando otra pregunta en ese momento, te informará de tu posición en la cola.

---

Hardware modesto y recomendaciones

El proyecto está diseñado para funcionar en hardware modesto (mini PCs o servidores caseros sin GPU dedicada). La inferencia se ejecuta localmente mediante la CPU.

• Usa modelos de chat de tamaño contenido (ej. qwen2.5:1.5b o similar).
• Mantén top_k bajo (ej. 3). Menos fragmentos resultan en una inferencia mucho más ágil.
• Ajusta num_thread para no ahogar tu CPU. Si tienes 4 núcleos de CPU libres en la máquina host, asignar 3 a Ollama asegura que el sistema operativo y Docker sigan respondiendo de forma fluida.

---

Actualizar el bot

Para actualizar el bot a la última versión disponible en el repositorio de GitHub sin perder tus configuraciones ni bases de datos:

# 1. Parar el contenedor
docker compose down

# 2. Descargar los últimos cambios
git pull

# 3. Levantar reconstruyendo la imagen con las nuevas dependencias
docker compose up -d --build

---

Solución de problemas comunes

El contenedor da un error de conexión con Ollama

• Comprueba que Ollama está activo en la máquina host (ollama list o accediendo a http://localhost:11434 en tu navegador).
• Si estás en Linux, asegúrate de haber seguido el paso de configuración de OLLAMA_HOST=0.0.0.0 y reiniciar el servicio de Ollama.

El bot responde que no hay documentos indexados

• Confirma que has depositado archivos .md o .txt en la carpeta knowledge_base del host.
• Ejecuta /sync_knowledge en tu servidor de Discord y espera a que finalice con un mensaje de éxito.

Los comandos no aparecen en tu servidor

• Asegúrate de haber seleccionado el scope applications.commands al generar la URL de invitación del bot.
• Prueba a reiniciar el contenedor (docker compose restart) para forzar una sincronización del árbol de comandos con Discord.

---

Licencia

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