RAGFlow is an open-source Retrieval-Augmented Generation (RAG) engine that combines deep document understanding with conversational AI capabilities. This document provides a technical overview of RAGFlow's architecture, core components, and deployment model.
Coverage: This page introduces RAGFlow's system design, technology stack, and major subsystems. For detailed deployment instructions, see Getting Started and Deployment. For LLM integration specifics, see LLM Integration System. For document processing details, see Document Processing Pipeline. For agent/workflow capabilities, see Agent and Workflow System.
What RAGFlow is: A production-ready RAG platform that parses complex documents (PDF, DOCX, Excel, PPT), chunks them intelligently using multiple strategies, generates embeddings, stores them in hybrid vector/keyword indexes, and provides conversational interfaces with grounded citations. It also includes a visual agent workflow system (Canvas) for building multi-step AI applications.
Sources: README.md73-75 docs/quickstart.mdx13-20
RAGFlow is architected as a multi-layer system with five primary layers: frontend, API gateway, core services, processing engine, and storage.
Key Architectural Decisions:
| Aspect | Technology | Location | Rationale |
|---|---|---|---|
| API Framework | Quart (async Flask) | ragflow_server.py | Async I/O for concurrent requests |
| Task Processing | Custom task executor | rag/app/task_executor.py | Long-running document parsing jobs |
| Document Store | Pluggable (ES/Infinity/OpenSearch) | rag/utils/*_conn.py | Hybrid vector + keyword search |
| Object Storage | Pluggable (MinIO/S3/OSS) | rag/utils/storage_factory.py | Scalable file storage |
| Frontend | React + Vite | web/ | Modern SPA with hot reload |
| Multi-tenancy | Tenant ID isolation | api/db/db_models.py | Per-tenant indexes and data |
Sources: README.md137-141 docker/docker-compose.yml rag/app/ragflow_server.py rag/app/task_executor.py
RAGFlow deploys as a collection of Docker containers orchestrated via docker-compose.yml. The following diagram maps service names to their runtime characteristics:
Service Selection: The DOC_ENGINE environment variable (elasticsearch, infinity, or opensearch) in docker/.env controls which document engine profile activates. Only one runs at a time via Docker Compose profiles.
Sources: docker/docker-compose.yml docker/.env13-28 docker/README.md13-21
RAGFlow has two primary Python entry points:
| Entry Point | File | Purpose | Port |
|---|---|---|---|
| API Server | rag/app/ragflow_server.py | HTTP API via Quart framework | 9380 |
| Task Executor | rag/app/task_executor.py | Background document processing | N/A |
Both processes share the same configuration from conf/service_conf.yaml and connect to the same backing services (MySQL, Redis, document engine, object storage).
Configuration Loading: At startup, conf/service_conf.yaml is generated from docker/service_conf.yaml.template by substituting environment variables. The rag/settings.py module loads this YAML and provides a global ragflow.settings singleton.
Sources: docker/launch_backend_service.sh rag/settings.py docker/service_conf.yaml.template
Key Dependencies (from pyproject.toml):
| Library | Purpose | Version Constraint |
|---|---|---|
quart | Async web framework | ~=0.19.8 |
peewee | ORM for MySQL | ^3.17.6 |
elasticsearch | Document engine client | ~=8.11.0 |
infinity-sdk | Infinity DB client | ~=0.5.1 |
redis | Cache client | ~=5.2.0 |
boto3 | S3-compatible storage | ^1.35.50 |
langfuse | LLM observability | ^2.53.3 |
Sources: pyproject.toml rag/app/ragflow_server.py api/db/db_models.py
Build Output: Vite compiles web/src/ to web/dist/, which Nginx serves as static assets from the ragflow container.
Internationalization: 12 languages supported via web/src/locales/*.ts files (English, Simplified Chinese, Traditional Chinese, Japanese, Korean, Indonesian, Portuguese).
Sources: web/package.json web/vite.config.ts web/src/locales/
RAGFlow uses a multi-engine storage architecture with pluggable backends:
Index Organization: Each tenant has dedicated Elasticsearch/Infinity indexes (ragflow_{tenant_id}) partitioned by knowledge base ID (kb_id field). This enables efficient tenant isolation and KB deletion.
Vector Fields: Embeddings stored as q_{size}_vec fields (e.g., q_512_vec for 512-dimensional vectors) with HNSW indexing for fast approximate nearest neighbor search.
Sources: rag/utils/doc_store_conn.py rag/utils/es_conn.py rag/utils/infinity_conn.py rag/utils/storage_factory.py api/db/db_models.py
Storage backends are selected via environment variables in docker/.env:
| Variable | Values | Effect |
|---|---|---|
DOC_ENGINE | elasticsearch, infinity, opensearch | Selects document engine |
STORAGE_IMPL | OSS, S3, (blank for MinIO) | Selects object storage |
MYSQL_HOST, MYSQL_PORT | Hostname, port | MySQL connection |
REDIS_HOST, REDIS_PORT | Hostname, port | Redis connection |
Factory Pattern: rag/utils/storage_factory.py:get_storage_impl() inspects settings.STORAGE_IMPL and returns the appropriate storage client. Document engine selection occurs in rag/utils/doc_store_conn.py:DocStoreConnection.conn().
Sources: docker/.env13-20 rag/utils/storage_factory.py rag/utils/doc_store_conn.py
Critical Code Paths:
api/apps/file_app.py:upload() → rag/utils/storage_factory.py → api/db/db_models.py:Document.save()api/apps/file_app.py:run() → api/db/db_models.py:Task.insert() → Redis queuerag/app/task_executor.py:build() → rag/raptor.py:pdf() → deepdoc/parser/rag/svr/chunk_service.py:chunk() → rag/nlp/{naive,table,qa,book,paper,laws}.pyrag/svr/embedding_service.py:embed_batch() → rag/llm/chat_model.py:EmbeddingModelrag/svr/chunk_service.py:save_chunks() → rag/utils/es_conn.py:insert()api/apps/dialog_app.py:completion() → rag/svr/retrieval_service.py:search() → rag/utils/es_conn.py:search()Sources: api/apps/file_app.py rag/app/task_executor.py rag/raptor.py rag/svr/chunk_service.py rag/svr/embedding_service.py api/apps/dialog_app.py
RAGFlow implements multi-tenancy at multiple layers:
| Layer | Isolation Mechanism | Implementation |
|---|---|---|
| Database | tenant_id column | api/db/db_models.py - all models have tenant_id |
| Document Index | Index per tenant | ragflow_{tenant_id} in Elasticsearch/Infinity |
| Object Storage | Prefix per tenant | {tenant_id}/{doc_id}/{file_name} path structure |
| API Access | JWT token | api/db/services/user_service.py:get_authenticated_user() |
| LLM Config | Tenant-specific | api/db/db_models.py:LLMConfig.tenant_id |
Authentication Flow: User login (api/apps/user_app.py:login()) → JWT generation with user_id → Request middleware extracts user_id → Lookup User.tenant_id → All DB queries filtered by tenant_id.
Tenant Creation: Registration creates both User and Tenant records. The Tenant model (called "kingdom" in legacy code) represents an organization, while User represents individual accounts within a tenant.
Sources: api/db/db_models.py77-91 api/db/services/user_service.py api/apps/user_app.py
RAGFlow's configuration follows a three-tier hierarchy:
Substitution Process: On container startup, docker/entrypoint.sh runs envsubst on service_conf.yaml.template, replacing ${MYSQL_HOST}, ${REDIS_PASSWORD}, etc., with values from docker/.env. The result is written to conf/service_conf.yaml.
Settings Module: rag/settings.py provides a global ragflow.settings object (imported as from rag import settings throughout the codebase) that loads conf/service_conf.yaml and exposes configuration as attributes (e.g., settings.MYSQL, settings.REDIS, settings.DOC_ENGINE).
Sources: docker/.env docker/service_conf.yaml.template docker/entrypoint.sh rag/settings.py
RAGFlow supports three deployment modes:
Target: Single-server deployments or development
Files: docker/docker-compose.yml
Services: All services (ragflow, mysql, redis, minio, doc engine) on one host
Profiles: Use COMPOSE_PROFILES in docker/.env to select document engine and optional services:
elasticsearch or infinity or opensearch (mutually exclusive)tei-cpu or tei-gpu (optional, for local embedding service)sandbox (optional, for code execution)Sources: docker/docker-compose.yml docker/.env28
Target: Local development with external RAGFlow processes
Files: docker/docker-compose-base.yml
Services: Only dependencies (mysql, redis, minio, doc engine) - no ragflow container
Usage: Run docker compose -f docker/docker-compose-base.yml up -d, then start ragflow_server.py and task_executor.py directly via bash docker/launch_backend_service.sh
Sources: docker/docker-compose-base.yml README.md331-336
Target: Multi-node production clusters
Files: helm/ directory (not included in provided files, but mentioned)
Resources: Kubernetes Deployments, Services, ConfigMaps, Secrets
Scaling: Horizontal scaling of API servers and task executors
Sources: README.md137-141 (diagram mentions Helm)
RAGFlow is a layered RAG platform with:
rag/llm/*.py, Langfuse observabilityNext Steps: For specific subsystem details, see:
Sources: README.md73-136 docker/docker-compose.yml rag/app/ragflow_server.py rag/app/task_executor.py api/db/db_models.py web/package.json
Refresh this wiki