RAGFlow es un motor RAG (Retrieval-Augmented Generation) y de agentes 100 % open source que puedes ejecutar en local (sin exfiltrar datos) para consultar, razonar y citar información de PDF/DOCX/HTML/imágenes/tablas y fuentes estructuradas. Se despliega con Docker Compose, indexa en Elasticsearch (o Infinity) y orquesta embeddings + re-ranking + LLM con una UI de flujos y APIs. Para equipos de sistemas y aplicaciones, esto habilita buscadores corporativos, asistentes de soporte, copilots de producto o text-to-SQL, manteniendo gobernanza, coste y latencia bajo control.
El objetivo de esta guía es operar RAGFlow: arquitectura, despliegue, hardening, tuning de búsqueda, integración con LLM locales, observabilidad, runbooks y gotchas en real.
1) Arquitectura operativa (qué piezas vas a manejar)
- RAGFlow Server (API/UI, flow engine y agentes).
- Motor de documentos: Elasticsearch por defecto (texto + vectores), Infinity como alternativa.
- Almacenamiento de objetos (MinIO opcional en stack de desarrollo).
- Redis/MySQL (servicios base según compose).
- Embeddings: en la imagen full vienen embebidos; en slim dependes de un servicio externo/local.
- LLM: configurable (API OpenAI-compatible). Puedes apuntar a Ollama/LM-Studio/vLLM en tu red.
CPU/RAM: 4 vCPU/16 GB es el mínimo útil; para ingestas grandes y OCR/DeepDoc considera 8–16 vCPU y 32 GB.
ARM64: no hay imágenes oficiales —toca build propia.
2) Despliegue reproducible (con guardrails)
Requisitos previos
# kernel para ES/Infinity
sudo sysctl -w vm.max_map_count=262144
echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf
# Docker/Compose ≥ 24 / 2.26
Lenguaje del código: PHP (php)Arranque (CPU)
git clone https://github.com/infiniflow/ragflow.git
cd ragflow/docker
# Edición slim (≈2 GB, sin embeddings)
docker compose -f docker-compose.yml up -d
# GPU (si tienes CUDA): docker compose -f docker-compose-gpu.yml up -d
docker logs -f ragflow-server
Lenguaje del código: PHP (php)Navega a http://IP (puerto 80 por defecto) y crea el primer usuario.
Selecciona LLM y credenciales
Edita service_conf.yaml.template → user_default_llm y API_KEY.
- LLM local (Ollama con puente OpenAI-compatible, LM-Studio Server o vLLM):
BASE_URL: "http://ollama:11434/v1" API_KEY: "local-key" MODEL: "qwen2.5-7b-instruct" # o el que sirvas - Embeddings: si usas la imagen full (
infiniflow/ragflow:v0.21.0), ya vienen dentro; en slim configura tu endpoint de embeddings o cambia de imagen.
TLS: en producción sitúa RAGFlow detrás de nginx/Traefik con Let’s Encrypt y fuerza HTTPS.
3) Gobierno y seguridad (hardening rápido)
- Superficie expuesta: solo 80/443 (o el puerto tras reverse). Redis/MySQL/ES/Infinity en red interna de Docker.
- Autenticación: activa políticas de contraseña, bloquea registro abierto y aplica 2FA si lo pones en el reverse.
- Aislamiento: usa una VM dedicada o namespace con recursos limitados (
deploy.resourcesen Compose). - Egress: si el entorno debe ser air-gapped, usa LLM + embeddings locales y desactiva búsqueda web.
- Backups: programa snapshots de ES/Infinity + copias de MySQL/Redis y
service_conf.yaml.template. - Logs/retención: reenvía a syslog/ELK/Vector y define políticas RGPD.
4) Pipeline RAG de calidad (evita el “demo-driven development”)
RAGFlow te deja ver y editar el chunking, mezclar BM25 + vectores y aplicar re-ranking. Para que el sistema sea fiable:
- Ingesta:
- Activa DeepDoc para PDFs complejos/escaneados (tablas/imágenes).
- Define plantillas de chunking (título+sección, tamaño 400–800 tokens, overlap 10–20 %).
- Dedup por hash/ID; versiona documentos.
- Recuperación:
- Usa multi-recall: vectores (top-k 20–50) + BM25 (top-k 20) → fused re-ranking.
- Ajusta k según recall/latencia; re-ranking colapsa a 5–8 pasajes.
- Generación:
- Prompt con instrucción de citas y límite de tokens; obliga a responder solo con pasajes citados.
- Evaluación:
- Construye un golden set de 30–50 preguntas reales.
- Mide Exact Match, Groundedness (¿la cita respalda?), latencia y fall-back (sin respuesta).
Ejemplo de prompt guardrail (esquema):
Responde a la pregunta SOLO con información de los pasajes recuperados.
Cita con [n] cada afirmación. Si falta contexto, responde “No consta en las fuentes”.
Lenguaje del código: CSS (css)5) Tuning de búsqueda e indexación
Elasticsearch
- Heap: 50 % de RAM del contenedor (máx. 31 GB).
- Sharding: 1–3 primary según volumen; 0–1 réplica en single-node.
- KNN: habilita dense_vector o HNSW (si tu build lo soporta).
- BM25: usa analizadores por idioma; activa synonyms si procede.
Infinity
- Cambia
DOC_ENGINE=infinityendocker/.envy re-ingesta (el down -v borra datos). - No oficial en arm64 Linux.
Re-ranking
- Actívalo: suele dar +10–20 % de precisión con un overhead aceptable.
6) Integración con tus aplicaciones
- APIs: RAGFlow expone endpoints REST para colecciones, ingesta, chat y deep-search. Intercala una API propia para auditoría, authz por tenant y rate-limit.
- Text-to-SQL: conecta tu warehouse (solo lectura) para consultas naturales sobre tablas documentadas.
- Eventos: registra queries/respuestas/citas (útiles para playback y re-train puntual).
- Multi-tenant: separa por colecciones y namespaces; si necesitas aislamiento duro, otra instancia de RAGFlow/ES.
7) LLM local sin OpenAI
Opciones comunes:
- Ollama + bridge OpenAI (
http://ollama:11434/v1) → modelosqwen2.5-7b/14b,llama-3.1-8b,mistral-7b. - LM Studio Server o vLLM sirviendo un modelo instruct.
- text-generation-webui con compatibilidad OpenAI.
Apunta BASE_URL y API_KEY en service_conf.yaml.template. La edición full ya trae embeddings → todo el pipeline queda local.
Rendimiento: si hay GPU, usa el compose-gpu para DeepDoc/OCR y embeddings; reduce latencia 2–5× en cargas medianas.
8) Observabilidad, SLAs y runbooks
- Métricas: Prometheus + node_exporter; latencia de /api/chat, colas de ingesta, tiempo de OCR, tamaño/estado de índices, heap ES.
- Alertas: ES yellow/red,
vm.max_map_countincorrecto, errores de LLM, cert LE a 15 días de caducidad. - Backups:
- ES/Infinity: snapshot diario (S3 o FS externo) + retención 7/30/90.
- DB/Redis/config: dump diario + cifrado en repositorio fuera de banda.
- Actualizaciones: cambia tag (
v0.21.0 → v0.21.1),docker compose pull && up -d, valida con golden set. - DR: VM limpia → restaura snapshots → reindexación incremental si es necesario. RTO objetivo <60 min (panel/API).
9) Gotchas frecuentes (y cómo salir)
- “Network error” al iniciar → espera a que
ragflow-serverimprima el banner; la primera inicialización puede tardar. - Fallo en OCR/DeepDoc → RAM/GPU insuficientes; usa compose-gpu o reduce lotes de ingesta.
- ES muere → aumenta heap y comprueba
vm.max_map_count; vigila disco (≥20 % libre). - ARM64 → construye imagen propia; re-compila dependencias (no hay image oficial).
- LLM no responde → prueba
curl $BASE_URL/v1/models -H "Authorization: Bearer $API_KEY"; revisa CORS y red. - Latencia alta → baja
top-k, activa re-ranking, cachea respuestas y usa embeddings más pequeños.
10) Checklist para pasar a producción
- TLS obligatorio y reverse proxy con HSTS.
- LLM/embeddings locales o proveedores con DPA y scopes limitados.
- Backups probados y plan de restore documentado.
- Observabilidad (métricas/logs) y alertas definidas.
- Golden set y thresholds de calidad pactados con negocio.
- Política de retención y marcado de datos (confidenciales, PII).
- RBAC por colección/tenant y rate-limit per-token/per-IP.
- Plan de actualización (stagging → prod) y ventana de mantenimiento.
11) ¿Por qué RAGFlow frente a “montarlo a mano”?
- Menos pegamento: tienes flow UI, plantillas de chunking, DeepDoc y agentes listos; no hay que ensamblar Haystack/LangChain + retrievers + OCR + UI desde cero.
- Operable: compose único; tuning claro de ES e inference.
- Citas trazables: reduce la fricción con compliance y audit.
- Local-first: puedes ir air-gapped sin perder funcionalidades clave.
12) Casos reales de admins en 1–2 días
- NOC/Soporte: ingesta de runbooks, KB y post-mortems; agente “Deep Search” con citas y snippets operativos.
- App Owners: text-to-SQL sobre warehouse de producto; auditoría de consultas y lineage de tablas.
- Legal/Compliance: análisis de contratos (OCR) con redlining asistido y extracción de cláusulas.
Conclusión
Para administradores de sistemas y aplicaciones, RAGFlow ofrece lo que necesitábamos: un RAG/Agente robusto, local-first, que se despliega y opera como cualquier servicio serio (TLS, backups, métricas), con citas verificables y multimodalidad de verdad. No sustituye a tu CMDB ni a tu SIEM, pero se convierte en la capa de contexto que faltaba para consultar conocimiento corporativo sin salir de tu perímetro y sin costes opacos por token.
Si ya tienes Docker y un dominio, esta tarde puedes tener “tu ChatGPT para documentos” corriendo en tu red. El resto —tuning, gobierno y SLOs— es terreno conocido para un buen admin.
