Crea tu ChatGPT local para documentos con RAGFlow para sysadmins

hace 4 meses

¿Te imaginas poder implementar tu propio sistema de inteligencia artificial que funcione completamente en local, sin depender de servidores externos ni de plataformas de terceros? Con RAGFlow, esto es una realidad. Este motor de Retrieval-Augmented Generation (RAG) te permite gestionar, indexar y buscar información en tus documentos de manera eficiente y segura. Si eres sysadmin o simplemente te interesa la tecnología, esta guía te llevará a través de los principales aspectos para que puedas configurar y utilizar RAGFlow en tu propia infraestructura.

Con un enfoque en la privacidad y la funcionalidad, RAGFlow se presenta como una solución poderosa para aquellos que buscan herramientas robustas de búsqueda y generación de texto. A continuación, exploraremos en detalle cómo desplegarlo, configurarlo y optimizar su uso.

Índice
  1. 1) ¿Qué es un motor RAG y por qué elegir RAGFlow?
  2. 2) Requisitos y arquitectura para RAGFlow
  3. 3) Despliegue rápido con Docker (CPU)
  4. 4) Flujo básico en la interfaz de usuario (5 minutos)
  5. 5) Configuración y tuning del sistema
  6. 6) Seguridad y operación efectiva
  7. 7) ARM64 y construcción de imagen propia
  8. 8) LLMs 100 % locales (sin OpenAI)
  9. 9) Playbook de evaluación (precisión ≠ demo)
  10. 10) Troubleshooting rápido
  11. 11) Casos de uso listos en 1 tarde
  12. 12) Checklist de producción
  13. 13) Preguntas frecuentes

1) ¿Qué es un motor RAG y por qué elegir RAGFlow?

El concepto de RAG combina la búsqueda de información con la generación de texto. Esto significa que, en lugar de que un modelo de lenguaje (LLM) "invente" respuestas, recupera fragmentos relevantes de tus documentos, los cita y genera un resumen coherente.

RAGFlow aporta características adicionales que lo hacen destacar:

  • DeepDoc: Análisis avanzado del diseño de documentos en formatos como PDF y DOCX que contienen tablas e imágenes.
  • Chunking templatable: Permite una segmentación de texto ajustable y visualizable para facilitar la comprensión.
  • Citas trazables: Ayuda a minimizar las "alucinaciones" o información incorrecta generada por el modelo.
  • Agentes predefinidos: Incluye herramientas para orquestar flujos de trabajo visualmente mediante arrastrar y soltar.
  • Soporte multimodal: Capacidad para manejar diferentes tipos de datos, incluyendo imágenes y búsquedas en internet.
  • Text-to-SQL: Facilita consultas en bases de datos mediante lenguaje natural.
  • APIs sencillas: Permite integrar RAGFlow fácilmente en tus aplicaciones o SaaS.

Para un sysadmin, lo más relevante es que RAGFlow permite mantener tus datos en casa, sin depender de la nube, evitando licencias y garantizando observabilidad en el pipeline.

2) Requisitos y arquitectura para RAGFlow

Antes de comenzar con la instalación, es fundamental conocer los requisitos mínimos que tu sistema debe cumplir:

  • CPU: Mínimo 4 vCPU.
  • RAM: Mínimo 16 GB.
  • Disco: Al menos 50 GB de espacio libre.
  • Docker: Debes tener Docker ≥ 24 y Docker Compose ≥ 2.26.1.
  • Configuración de sistema: Asegúrate de que vm.max_map_count ≥ 262144 esté establecido (requerido por Elasticsearch).
  • Opcional: gVisor, si planeas usar el ejecutor de código en un ambiente sandbox.

En cuanto a las ediciones de imagen, hay varias opciones disponibles para x86_64:

  • infiniflow/ragflow:v0.21.0 (≈9 GB): Incluye modelos de embedding.
  • infiniflow/ragflow:v0.21.0-slim (≈2 GB): No incluye embeddings, ideal si usas servicios externos.
  • nightly / nightly-slim: Versiones de última hora con características nuevas.

Ten en cuenta que para ARM64 no hay imágenes oficiales, pero puedes construir la tuya propia (ver sección 7).

3) Despliegue rápido con Docker (CPU)

Para desplegar RAGFlow en tu máquina o servidor, sigue estos pasos:

  1. Ajusta el parámetro vm.max_map_count:
sudo sysctl -w vm.max_map_count=262144
echo 'vm.max_map_count=262144' | sudo tee -a /etc/sysctl.conf
  1. Clona el repositorio y accede a la carpeta de Docker:
git clone https://github.com/infiniflow/ragflow.git
cd ragflow/docker
  1. Arranca la imagen “slim” para CPU:
docker compose -f docker-compose.yml up -d
# Si tienes GPU y CUDA: docker compose -f docker-compose-gpu.yml up -d
  1. Verifica los logs del servidor:
docker logs -f ragflow-server
# Espera a ver el banner "Running on all addresses (0.0.0.0)" para confirmar que está inicializando
  1. Accede a la interfaz de usuario (UI): Navega a http://IP_DEL_SERVIDOR/ (puerto 80 por defecto). Crea tu cuenta y entra.
  2. Configura el LLM por defecto: Edita el archivo service_conf.yaml.template en la ruta Docker, configurando user_default_llm y API_KEY de tu proveedor elegido.
  • Si usas un LLM local compatible con OpenAI (como Ollama-OpenAI o vLLM), introduce su endpoint y key.
  • Si prefieres un proveedor externo, asegúrate de tener tu clave y cuenta en orden.

La imagen completa ya incluye embeddings locales; la versión “slim” requerirá servicios externos o la configuración de modelos locales.

4) Flujo básico en la interfaz de usuario (5 minutos)

El proceso para comenzar a usar RAGFlow es sencillo. Aquí te explicamos el flujo básico:

  1. Crea una colección y sube tus documentos en formatos como PDF, DOCX, PPTX, XLSX, TXT, imágenes o incluso URLs.
  2. Selecciona una plantilla de chunking y permite que DeepDoc analice el diseño de tus documentos.
  3. Visualiza los chunks generados, con la opción de editar o fusionar manualmente los segmentos según sea necesario.
  4. Indexa la información, combinando texto y vectores.
  5. Accede al chat/flow, elige tu modelo y agente (como el Deep Search Agent).
  6. Formula una pregunta y obtén una respuesta que incluye citas y acceso al pasaje fuente correspondiente.

Consejo: Habilita la opción de re-ranking en la configuración para mejorar la precisión en colecciones extensas.

5) Configuración y tuning del sistema

Para optimizar el rendimiento de RAGFlow, considera los siguientes aspectos de configuración:

  • Puertos y variables: Verifica los archivos docker/.env y docker-compose.yml. Cambia 80:80 si ya lo estás utilizando.
  • LLM y embeddings: Configura el archivo service_conf.yaml.template apuntando a tu servidor local o a modelos disponibles.
  • Motor de documentos: Si deseas cambiar de Elasticsearch a Infinity, puedes hacerlo, pero ten en cuenta que se borrarán los volúmenes. Consulta la sección 5 para más detalles.
  • GPU: Si cuentas con una GPU, utiliza docker-compose-gpu.yml para acelerar el proceso de embedding y DeepDoc.
  • Ejecutar código en sandbox: Si deseas habilitar un ejecutor de Python/JS aislado, considera instalar gVisor.

6) Seguridad y operación efectiva

La seguridad es un aspecto crucial al desplegar RAGFlow. Aquí hay algunas recomendaciones:

  • Aislamiento: Ejecuta RAGFlow en un host dedicado o máquina virtual, y expón solo los puertos necesarios (80/443) detrás de un reverse proxy con TLS.
  • Uso de TLS: Implementa un servidor como nginx, Traefik o Caddy y asegúrate de obtener un certificado de Let’s Encrypt.
  • Control de salidas: En entornos sensibles, considera bloquear salidas a internet, ya que RAGFlow funciona con LLM y embeddings locales.
  • Backups: Realiza respaldos de volúmenes de Elasticsearch, MySQL, MinIO (si lo usas) y configuraciones regularmente.
  • Recursos: Para colecciones grandes, aumenta el JVM heap de Elasticsearch y la memoria de la GPU; utiliza docker stats o herramientas como Prometheus para monitorizar.
  • Actualizaciones: Cambia la tag en docker/.env (por ejemplo, de v0.21.0 a v0.21.1) y ejecuta los comandos necesarios para actualizar.

Privacidad

  • Por defecto, todos los datos permanecen en tus volúmenes. Si decides agregar búsqueda web o un LLM externo, evalúa la huella de datos y los registros generados.

7) ARM64 y construcción de imagen propia

Si utilizas un sistema ARM64 (como Raspberry Pi o Graviton), sigue estos pasos para construir tu propia imagen de RAGFlow:

Slim (sin embeddings, ≈2 GB)

git clone https://github.com/infiniflow/ragflow.git
cd ragflow
docker build --platform linux/amd64 --build-arg LIGHTEN=1 -f Dockerfile -t infiniflow/ragflow:nightly-slim .

Full (con embeddings, ≈9 GB)

git clone https://github.com/infiniflow/ragflow.git
cd ragflow
docker build --platform linux/amd64 -f Dockerfile -t infiniflow/ragflow:nightly .

Nota: Las builds oficiales están diseñadas para x86_64. En ARM64 será necesario adaptar o compilar dependencias adecuadamente.

8) LLMs 100 % locales (sin OpenAI)

Una de las grandes ventajas de RAGFlow es la posibilidad de configurar LLMs completamente locales. Aquí algunas opciones típicas:

  • Ollama: Compatible con OpenAI, lo que permite integrar plugins y puentes. Ejemplo: http://ollama:11434/v1
  • LM Studio Server: Otra opción válida junto con vLLM y OpenWebUI, todos con APIs compatibles.
  • Text-generation-webui: Puedes utilizar esta opción con extensiones de compatibilidad.

Para la configuración en service_conf.yaml.template, asegúrate de ajustar:

  • BASE_URL: URL del servicio local que estás utilizando.
  • API_KEY: Un token de tu elección, aún si el servicio no lo valida.
  • Selecciona el modelo que deseas utilizar, como qwen2.5-7b-instruct o llama-3.1-8b-instruct.

Si utilizas la imagen full, los embeddings ya estarán disponibles localmente, lo que asegura que todo el pipeline funcione en un entorno cerrado.

9) Playbook de evaluación (precisión ≠ demo)

Al evaluar el rendimiento de RAGFlow, considera seguir este playbook para obtener resultados significativos:

  1. Crea un set de oro: Compile entre 30 y 50 preguntas relevantes de tu dominio de trabajo.
  2. Activa las citas y re-ranking; prueba diferentes plantillas de chunking.
  3. Mide la exactitud y groundedness (verifica si la cita respalda la respuesta generada) así como el tiempo de respuesta.
  4. Ajústate a los parámetros de tamaño de chunk, overlap, el número de pasajes recuperados y el modelo de re-ranking.
  5. Repite la evaluación con y sin búsqueda web para analizar el trade-off entre latencia y recall.
  6. Congela la configuración y documenta la versión (puedes usar docker image ls) y la seed del LLM si corresponde.

10) Troubleshooting rápido

Es posible enfrentar algunas dificultades al implementar RAGFlow. Aquí tienes una lista de problemas comunes y sus soluciones:

  • “Error de red” al ingresar por primera vez: Espera a que aparezca el banner "ragflow-server" en los logs; a veces, la inicialización puede tardar unos minutos.
  • Fallo en DeepDoc o embeddings: Asegúrate de que tu sistema tenga suficiente RAM (16–32 GB) si estás utilizando CPU.
  • Elasticsearch se cae: Verifica la configuración de vm.max_map_count, el tamaño del heap y la disponibilidad de espacio en disco.
  • Problemas al arrancar en ARM64: No hay imagen oficial; debes construir la tuya como se describe en la sección 7.
  • Problemas para detectar el LLM local: Realiza una prueba con curl $BASE_URL/v1/models -H "Authorization: Bearer $API_KEY" y revisa la configuración de CORS y puerto.

11) Casos de uso listos en 1 tarde

RAGFlow es versátil y puede adaptarse a diversos escenarios. Aquí algunos casos de uso que puedes implementar rápidamente:

  • Asistente legal: Permite la ingesta de contratos y la segmentación de información por secciones. Utiliza un agente que permite consultas como “ask-and-cite” para tiempos y cláusulas específicas.
  • Buscador corporativo: Indexa documentación de wikis, Confluence o Google Docs, y combina multi-recall con re-ranking. También puedes crear una API para búsqueda web interna.
  • Helpdesk: Integra manuales junto con históricos de consultas; configura un agente que ejecute código en un sandbox para generar diagnósticos o fragmentos de código (usando gVisor).
  • Text-to-SQL: Conecta RAGFlow a tu warehouse para permitir consultas en lenguaje natural, limitadas a permisos de solo lectura.

12) Checklist de producción

Antes de llevar RAGFlow a un entorno de producción, asegúrate de que sigues este checklist:

  • Implementa TLS detrás de un reverse proxy (puedes usar Let’s Encrypt para renovación automática).
  • Configura backups diarios de índices, objetos, bases de datos y configuraciones.
  • Utiliza herramientas de monitorización de contenedores (como Prometheus o Node exporter).
  • Centraliza los logs (considera usar Vector o ELK) y establece políticas de rotación.
  • Controla el egress si no deseas tener acceso a web search o recursos externos.
  • Asegúrate de que los LLM y embeddings locales están verificados y funcionando correctamente.
  • Realiza pruebas de recuperación para asegurar que puedes restaurar el sistema en un entorno de prueba.
  • Documenta las versiones de imágenes y flujos de trabajo utilizando IaC.

13) Preguntas frecuentes

¿Puedo usar RAGFlow sin Internet?
Sí, con un LLM y embeddings locales (utilizando la imagen full), puedes operar en un entorno air-gapped.

¿Soporta imágenes y tablas en PDFs?
Sí, RAGFlow utiliza DeepDoc y modelos multimodales para analizar imágenes dentro de documentos PDF y DOCX.

¿Qué pasa si quiero cambiar de Elasticsearch a Infinity?
Es posible, pero debes tener en cuenta que se eliminarán volúmenes si usas down -v. Planifica exportar e importar datos según sea necesario.

¿Consume mucha RAM?
Para conjuntos de datos medianos, entre 16-32 GB es razonable. Para colecciones más grandes, considera aumentar los recursos y evaluar el uso de GPU.

¿Puedo extenderlo o automatizar procesos?
Sí, expone APIs y la UI visual facilita la creación de agentes y flujos sin necesidad de codificación. También puedes desplegar RAGFlow desde código para propósitos de desarrollo.

Para más información y recursos adicionales, visita RAGFlow en GitHub.

Deja una respuesta

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *

Subir