“Tu propio ChatGPT para documentos”, 100 % en local y sin OpenAI: guía práctica de RAGFlow para sysadmins

Por Alan Sonny

X (Twitter) Facebook Pinterest LinkedIn Email WhatsApp

RAGFlow es un motor RAG (Retrieval-Augmented Generation) 100 % open source que orquesta ingesta, indexación semántica, búsqueda, re-ranking, razonamiento y citados verificables sobre tus documentos. Corre en local (sin subir datos a terceros), ofrece UI visual tipo flow para montar agentes y pipelines, y se controla por Docker Compose. Soporta texto + imágenes (analiza PDFs escaneados y layouts complejos), búsquedas web opcionales, text-to-SQL, y workflows agentic (MCP, ejecutor de código en sandbox).

A continuación: qué es, cómo desplegarlo en tu máquina/servidor, cómo integrar LLMs locales, seguridad, rendimiento y troubleshooting.

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

RAG = búsqueda + generación. El LLM no “se lo inventa”: recupera trozos relevantes de tus fuentes, los cita y genera un resumen razonado.
RAGFlow añade:

DeepDoc (análisis de diseño de documentos) para PDF/DOCX con tablas, imágenes y escaneados.
Chunking templatable (explicable, ajustable y visualizable).
Citas trazables (reduce alucinaciones).
Agentes predefinidos y orquestación visual (arrastrar/soltar).
Soporte multimodal en PDFs/Docs e Internet search opcional (Tavily).
Text-to-SQL y consultas multilingües.
APIs sencillas para integrarlo en tu app/SaaS.

Lo importante para un sysadmin: datos en casa, sin dependencia de nube, sin licencias, y observabilidad del pipeline.

2) Requisitos y arquitectura

Requisitos mínimos

CPU ≥ 4 vCPU
RAM ≥ 16 GB
Disco ≥ 50 GB
Docker ≥ 24 y Docker Compose ≥ 2.26.1
vm.max_map_count ≥ 262144 (por Elasticsearch/Infinity)
(Opcional) gVisor si usarás el ejecutor de código del agente

Ediciones de imagen (x86_64)

infiniflow/ragflow:v0.21.0 (≈9 GB) → incluye modelos de embedding
infiniflow/ragflow:v0.21.0-slim (≈2 GB) → sin embeddings (usas externos)
nightly/nightly-slim → bleeding edge

ARM64: no hay imágenes oficiales; puedes construir la tuya (ver §7).

Motores de documentos

Por defecto: Elasticsearch (texto + vectores).
Alternativa: Infinity (cambia una variable; ver §5).

3) Despliegue rápido con Docker (CPU)

Ajusta vm.max_map_count:

sudo sysctl -w vm.max_map_count=262144
echo 'vm.max_map_count=262144' | sudo tee -a /etc/sysctl.conf

Clona y entra en carpeta Docker:

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

Arranca (edición “slim”, CPU):

docker compose -f docker-compose.yml up -d
# GPU (si tienes CUDA): docker compose -f docker-compose-gpu.yml up -d

Verifica logs:

docker logs -f ragflow-server
# Verás el banner "Running on all addresses (0.0.0.0)" al inicializar

Accede a la UI
Navega a http://IP_DEL_SERVIDOR/ (puerto 80 por defecto). Crea cuenta y entra.
Configura LLM por defecto
Edita service_conf.yaml.template (en la ruta Docker) → user_default_llm y API_KEY del proveedor elegido.

Si usas LLM local con API OpenAI-compatible (ej. Ollama-OpenAI, LM Studio server, vLLM en local), pon su endpoint y key.
Si no, puedes usar un proveedor externo (tu clave, tu cuenta).

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

4) Flujo básico en la UI (5 minutos)

Crea una colección y sube documentos (PDF, DOCX, PPTX, XLSX, TXT, imágenes/escaneados, URLs).
Elige plantilla de chunking y deja que DeepDoc analice diseño (tablas, cabeceras, figuras).
Visualiza los chunks (puedes editar/fusionar manualmente).
Indexa (texto + vectores).
Abre el chat/flow, selecciona modelo y agente (p. ej., Deep Search Agent).
Pregunta. Verás respuesta con citas y acceso al pasaje fuente.

Tip: habilita re-ranking en la configuración para mejorar precisión en colecciones grandes.

5) Configuración y tuning

Puertos y variables: revisa docker/.env y docker-compose.yml. Cambia 80:80 por otro puerto si ya usas 80.
LLM y embeddings: service_conf.yaml.template → apunta a tu servidor (OpenAI-compatible) y/o modelos locales.
Motor de documentos: cambiar de Elasticsearch → Infinity: docker compose -f docker/docker-compose.yml down -v # BORRA volúmenes (y datos) # edita docker/.env -> DOC_ENGINE=infinity docker compose -f docker-compose.yml up -d Aviso: Infinity en Linux/arm64 aún no está soportado oficialmente.
GPU: usa docker-compose-gpu.yml para acelerar embeddings y DeepDoc.
Código en sandbox (agente): instala gVisor si quieres habilitar ejecutor de Python/JS aislado.

6) Seguridad y operación

Aislamiento: ejecuta en host dedicado o VM; expón solo 80/443 (o el puerto que elijas detrás de un reverse proxy con TLS).
TLS: pon nginx/Traefik/Caddy delante y usa Let’s Encrypt.
Egress: en entornos sensibles, bloquea salidas; RAGFlow funciona con LLM/embeddings locales.
Backups: respalda volúmenes de Elasticsearch/Infinity, MySQL, MinIO (si lo usas), Redis y configs.
Recursos: en colecciones grandes, sube JVM heap de ES y vRAM de GPU; monitoriza con docker stats/Prometheus.
Actualizaciones: cambia la tag en docker/.env (p. ej., v0.21.0 → v0.21.1) y: docker compose pull && docker compose up -d

Privacidad

Por defecto, los datos se quedan en tus volúmenes. Si añades búsqueda web (Tavily) o LLM externo, evalúa huella de datos y logs.

7) ARM64 / construcción de imagen propia

Si estás en ARM64 (RPi, Graviton), construye la imagen:

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 pensadas para x86_64. En ARM64 necesitarás adaptar/forzar plataformas o compilar dependencias.

8) LLMs 100 % locales (sin OpenAI)

RAGFlow permite configurar el “factory” de LLM. Opciones típicas:

Ollama con OpenAI-compatible (plugins/puentes) → http://ollama:11434/v1
LM Studio Server, vLLM, OpenWebUI con API OpenAI-compatible
Text-generation-webui con extensión de compatibilidad

En service_conf.yaml.template:

BASE_URL → URL del servicio local
API_KEY → un token (aunque el servicio no valide)
Selecciona el modelo (p. ej., qwen2.5-7b-instruct, llama-3.1-8b-instruct)

Si usas la imagen full, los embeddings ya son locales; así todo el pipeline queda air-gapped.

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

Crea un golden set de 30–50 preguntas reales de tu dominio.
Activa citas y re-ranking; prueba plantillas de chunking diferentes.
Mide Exactitud y Groundedness (¿la cita respalda la frase?) más Tiempo de respuesta.
Ajusta tamaño de chunk, overlap, número de pasajes recuperados, modelo de re-ranking.
Repite con y sin búsqueda web para ver el trade-off de latencia/recall.
Congela configuración y documenta versión (docker image ls) y seed del LLM si aplica.

10) Troubleshooting rápido

“Network error” al entrar la primera vez → espera a que ragflow-server muestre el banner; a veces tarda unos minutos en inicializar.
Falla DeepDoc/embeddings → asegura GPU compose o suficiente RAM (16–32 GB) si CPU.
ES se cae → revisa vm.max_map_count, tamaño de heap y disco libre.
Arm64 no arranca → no hay imagen oficial; build propia (ver §7).
No ve mi LLM local → testea curl $BASE_URL/v1/models -H "Authorization: Bearer $API_KEY"; revisa CORS/puerto.

11) Casos de uso listos en 1 tarde

Asistente legal: ingesta de contratos, plantillas de chunking por secciones; agente con “ask-and-cite” + tiempos / cláusulas.
Buscador corporativo: indexa wikis/Confluence/Docs; multi-recall + re-ranking; API a buscador web interno.
Helpdesk: manuales + históricos; agente con ejecutor de código en sandbox para generar diagnósticos o snippets (gVisor).
Text-to-SQL: conecta a tu warehouse para consultas naturales (con permisos de solo lectura).

12) Checklist de producción

TLS detrás de reverse proxy (Let’s Encrypt, renovación automática)
Backups diarios de índices, objetos, DB y configs
Monitorización de contenedores (Prometheus/Node exporter)
Logs centralizados (Vector/ELK) y rotación
Egress controlado (si no quieres web search/externos)
LLM/Embeddings locales verificadas
Pruebas de recuperación (restore en entorno stage)
Documentadas versiones de imágenes y flows en IaC

13) Preguntas frecuentes

¿Puedo usarlo sin Internet?
Sí. Con LLM y embeddings locales (imagen full) puedes operar air-gapped.

¿Soporta imágenes/tablas en PDFs?
Sí. RAGFlow usa DeepDoc y modelos multimodales para entender imágenes dentro de PDF/DOCX.

¿Qué pasa si quiero cambiar de Elasticsearch a Infinity?
Se puede, pero borrarás volúmenes si usas down -v. Planifica export/import.

¿Consume mucha RAM?
Con datos medianos, 16–32 GB es razonable. Para colecciones grandes, sube resources y evalúa GPU.

¿Puedo extenderlo/automatizar?
Sí. Expone APIs y la UI visual permite montar agentes/flujos sin código. También puedes desplegarlo desde código para desarrollo.

Cierre

Con RAGFlow puedes montar en tu infraestructura un “ChatGPT para documentos” con citas, multimodalidad y agentes, sin mandar un byte a OpenAI. Para un equipo de sistemas, esto significa control real de datos, costes y SLAs, y la base para construir buscadores internos, copilots corporativos o incluso un SaaS de investigación sobre tus fuentes.
El futuro no es “saber programar prompts”, sino orquestar bien estas piezas para entregar valor. Con esta guía, ya lo tienes listo para arrancar hoy.