Guía Completa para Instalar y Configurar RAGFlow con Docker

Si buscas una manera de conseguir que la inteligencia artificial base sus respuestas en tus propios archivos, RAGFlow es una de las alternativas más completas. Se trata de un motor de generación aumentada por recuperación de código abierto que analiza la estructura de los documentos y proporciona al modelo información relevante para reducir las habituales alucinaciones de los LLM.

Además, puedes instalarlo en tu propia infraestructura para mantener el control sobre tus datos y evitar depender completamente de plataformas externas. Gracias a su arquitectura basada en Docker, permite gestionar la ingesta, la indexación y la creación de asistentes y agentes mediante una interfaz visual.

Requisitos técnicos antes de empezar

Para que el sistema funcione correctamente necesitas un equipo que cumpla unos requisitos mínimos. La gestión de documentos, los motores de búsqueda y la indexación pueden consumir bastantes recursos, especialmente cuando se trabaja con colecciones grandes.

La documentación de RAGFlow establece los siguientes requisitos:

• Procesador x86 con cuatro núcleos o más.
• Al menos 16 GB de memoria RAM.
• Un mínimo de 50 GB de almacenamiento disponible.
• Docker 24.0.0 o posterior.
• Docker Compose 2.26.1 o posterior.
• Python 3.13 o posterior.

Si tienes previsto utilizar el ejecutor de código en modo sandbox para tus agentes, también deberás instalar gVisor para aislar la ejecución y mejorar la seguridad del entorno.

Otro punto importante es la configuración del kernel. Debes asegurarte de que el valor de vm.max_map_count sea igual o superior a 262144. En caso contrario, el motor de documentos puede mostrar errores de memoria o no llegar a iniciarse correctamente.

Puedes comprobar el valor actual mediante:

sysctl vm.max_map_count

Si necesitas modificarlo temporalmente, ejecuta:

sudo sysctl -w vm.max_map_count=262144

Este cambio se perderá después de reiniciar el sistema. Para conservarlo, añade la siguiente línea al archivo /etc/sysctl.conf:

vm.max_map_count=262144

Pasos para desplegar RAGFlow con Docker

Una vez preparado el entorno, el primer paso consiste en clonar el repositorio oficial de RAGFlow desde GitHub:

git clone https://github.com/infiniflow/ragflow.git
cd ragflow/docker

Para evitar incompatibilidades entre los archivos de configuración y la imagen de Docker, es recomendable seleccionar una versión estable publicada en el repositorio. Después podrás iniciar RAGFlow mediante:

docker compose -f docker-compose.yml up -d

Este comando utiliza la CPU para las tareas de DeepDoc. Si dispones de una GPU NVIDIA compatible, añade la siguiente variable al archivo .env antes de arrancar los contenedores:

DEVICE=gpu

Después, utiliza el mismo archivo de Docker Compose:

docker compose -f docker-compose.yml up -d

Para comprobar que el servidor ha arrancado correctamente, revisa los registros del contenedor correspondiente:

docker logs -f docker-ragflow-cpu-1

El nombre exacto del contenedor puede variar dependiendo de la versión y la configuración utilizada. Cuando los registros indiquen que el servidor está funcionando en 0.0.0.0, ya podrás abrir la interfaz.

De forma predeterminada, basta con introducir la dirección IP del servidor en el navegador:

http://IP_DEL_SERVIDOR

El puerto HTTP predeterminado es el 80, por lo que normalmente no es necesario escribirlo. Una vez dentro, accede a Model Providers, selecciona el proveedor que quieras utilizar y configura sus credenciales. RAGFlow permite definir por separado los modelos de chat, embeddings, reconocimiento de imágenes y otras tareas compatibles.

Gestión de documentos y flujo de trabajo

La principal ventaja de RAGFlow se encuentra en la forma en que procesa la información. En lugar de limitarse a dividir el contenido en fragmentos arbitrarios, utiliza diferentes analizadores para interpretar la estructura de documentos, tablas, imágenes y archivos escaneados.

Para empezar, crea un conjunto de datos, sube tus archivos y selecciona una plantilla de fragmentación adecuada. La plataforma admite distintos formatos, incluidos PDF, DOCX, hojas de cálculo, presentaciones, archivos de texto e imágenes.

RAGFlow también permite inspeccionar los fragmentos generados, editarlos manualmente y añadir palabras clave. Esta posibilidad resulta útil cuando el analizador no ha interpretado correctamente una tabla, un encabezado o una sección concreta.

Cuando el sistema recupera información para contestar una pregunta, puede incluir citas que conducen hasta los fragmentos originales. Esto mejora la trazabilidad de las respuestas, aunque no garantiza que el modelo quede completamente libre de errores.

Después de procesar los documentos, puedes crear un asistente desde la sección de chat. Entre sus opciones se encuentra la posibilidad de definir qué debe responder cuando no encuentre información suficiente en la base de conocimientos.

Configurar un mensaje como «No encuentro esta información en los documentos disponibles» ayuda a reducir el riesgo de que el modelo improvise una respuesta sin respaldo documental.

Ajustes avanzados y optimización del sistema

Los principales parámetros del despliegue se encuentran en el archivo .env. Desde él puedes modificar elementos como el puerto HTTP, las contraseñas de MySQL y MinIO, el motor de documentos o la utilización de la GPU.

RAGFlow utiliza Elasticsearch como motor predeterminado para almacenar y recuperar texto y vectores. También permite cambiar a Infinity mediante esta variable:

DOC_ENGINE=infinity

Sin embargo, este cambio no conserva automáticamente los datos existentes. El procedimiento oficial requiere detener los contenedores y eliminar sus volúmenes:

docker compose -f docker-compose.yml down -v

El parámetro -v borra los volúmenes de Docker y todos los datos almacenados en ellos. Antes de ejecutar el comando, asegúrate de contar con una copia de seguridad y de que realmente quieres comenzar con una instalación vacía.

Después de establecer DOC_ENGINE=infinity en el archivo .env, puedes volver a iniciar los contenedores:

docker compose -f docker-compose.yml up -d

Las imágenes oficiales de RAGFlow están preparadas para plataformas x86. Si utilizas un procesador ARM64, como determinados equipos con Apple Silicon o servidores con Amazon Graviton, tendrás que construir una imagen compatible siguiendo las instrucciones del proyecto.

Desde la versión 0.22, RAGFlow distribuye únicamente la edición ligera de su imagen. Esta ocupa alrededor de 2 GB y depende de servicios externos o adicionales para proporcionar los modelos de lenguaje y embeddings necesarios.

Si quieres exponer el servicio a Internet, no es recomendable publicar directamente su puerto. Lo más seguro es situar un proxy inverso como Nginx o Traefik delante de RAGFlow, habilitar HTTPS y añadir controles de acceso apropiados.

Integración de modelos locales y privacidad

RAGFlow también puede utilizar modelos ejecutados dentro de tu propia infraestructura. Entre las opciones compatibles se encuentran Ollama, LM Studio y vLLM, aunque la configuración concreta depende del proveedor y de la versión instalada.

En una instalación normal, Ollama puede añadirse desde Settings > Model Providers > Ollama. Allí debes indicar el modelo y la dirección mediante la que RAGFlow podrá acceder al servidor de Ollama.

Si RAGFlow se ejecuta dentro de Docker, recuerda que localhost apunta al propio contenedor. Cuando Ollama está instalado en el sistema anfitrión, tendrás que emplear una dirección accesible desde los contenedores, como la IP del equipo o host.docker.internal cuando esté disponible.

Para mantener los datos dentro de tu red no basta con utilizar un modelo de chat local. También debes comprobar que los modelos de embeddings, reconocimiento de imágenes, re-ranking y cualquier otro servicio conectado se ejecuten localmente. Si alguno depende de una API externa, parte de la información podría salir de tu infraestructura.

La plataforma permite utilizar modelos de re-ranking para volver a ordenar los fragmentos recuperados antes de enviarlos al LLM. Esto puede mejorar la relevancia de las respuestas en determinadas colecciones, aunque el resultado dependerá de los documentos, el modelo seleccionado y la configuración de la búsqueda.

RAGFlow permite convertir una colección de documentos en una base de conocimientos consultable mediante inteligencia artificial. Sus herramientas de análisis, fragmentación, recuperación y trazabilidad ayudan a obtener respuestas mejor fundamentadas, mientras que el despliegue local ofrece un mayor control sobre la infraestructura y el tratamiento de los datos.