RAGFlow User Guide

RAGFlow is an open-source Retrieval-Augmented Generation (RAG) engine built on deep document understanding. It combines intelligent document parsing — including OCR, layout recognition, and table structure extraction — with a visual agent builder, 80+ LLM integrations, and 30+ data source connectors to let you build grounded, hallucination-reduced AI applications over your own data.

Key features:

• Deep document parsing with DeepDoc (OCR, layout recognition, table structure recognition), MinerU, Docling, and PaddleOCR
• Multiple chunking strategies — Naive, QA, Manual, Table, Paper, Book, Laws, Presentation, One, Knowledge Graph, Tag, Email, and more
• Visual agent/workflow builder (Canvas) with 30+ drag-and-drop component types
• 80+ LLM provider integrations — OpenAI, Anthropic, Google, DeepSeek, Ollama, vLLM, and many more
• 30+ data source connectors — Confluence, Google Drive, Gmail, Jira, Slack, GitHub, S3, and others
• GraphRAG knowledge graph construction and semantic search
• MCP (Model Context Protocol) server for tool-based AI integration
• Python SDK and HTTP API for programmatic access

1. Quick Start

Get RAGFlow running in under five minutes with Docker Compose.

1.1 Prerequisites

Tip

RAGFlow ships everything in containers — you do not need Python, Node.js, Elasticsearch, or MySQL installed on your host. Docker handles all dependencies.

1.2 Clone and Start

git clone https://github.com/infiniflow/ragflow.git
cd ragflow/docker
docker compose -f docker-compose.yml --profile cpu --profile elasticsearch up -d

Expected output:

[+] Running 6/6
 ✔ Container ragflow-mysql       Started
 ✔ Container ragflow-minio       Started
 ✔ Container ragflow-redis       Started
 ✔ Container ragflow-es01        Started
 ✔ Container ragflow-ragflow     Started

1.3 Verify It Is Running

Wait approximately 60–90 seconds for all services to initialize, then check:

docker compose ps

All containers should show Up (healthy) or running. Once healthy, open your browser to:

http://localhost:9380

You will see the RAGFlow login/registration page.

1.4 Create Your Account

1. Click Sign Up (registration is enabled by default via REGISTER_ENABLED=1).
2. Enter your email, username, and password.
3. Log in with your new credentials.

1.5 What to Try Next

2. Installation

2.1 System Requirements

Important

Elasticsearch requires the vm.max_map_count kernel parameter set to at least 262144. On Linux, run sudo sysctl -w vm.max_map_count=262144 and add it to /etc/sysctl.conf for persistence. Without this, Elasticsearch will fail to start.

Warning

RAGFlow containers use significant memory. With Elasticsearch, expect 8–12 GB baseline usage. On machines with exactly 16 GB, close other heavy applications before starting.

2.2 Docker Compose — CPU Deployment

This is the default and most common deployment method.

Step 1: Clone the repository.

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

Step 2: Review and customize the .env file.

cp .env .env.backup  # optional safety copy

Key variables in .env:

Step 3: Start with CPU + Elasticsearch profiles.

docker compose -f docker-compose.yml --profile cpu --profile elasticsearch up -d

Step 4: Verify all services are healthy.

docker compose ps
docker logs ragflow-ragflow 2>&1 | tail -20

Look for a log line indicating the server is listening on port 9380.

2.3 GPU Deployment

For GPU-accelerated embedding and inference:

Prerequisites: Install the NVIDIA Container Toolkit and verify:

nvidia-smi
docker run --rm --gpus all nvidia/cuda:12.0-base nvidia-smi

Start with GPU profile:

docker compose -f docker-compose.yml --profile gpu --profile elasticsearch up -d

To use Text Embeddings Inference (TEI) with GPU:

docker compose -f docker-compose.yml --profile gpu --profile elasticsearch --profile tei-gpu up -d

Set the TEI model in .env:

TEI_MODEL=BAAI/bge-large-en-v1.5
TEI_PORT=8012

2.4 Alternative Document Engines

RAGFlow supports multiple document engines. Choose one via Docker Compose profiles:

Example with OpenSearch:

docker compose -f docker-compose.yml --profile cpu --profile opensearch up -d

Set the corresponding password variable in .env:

OPENSEARCH_PASSWORD=your_secure_password

And configure the DOC_ENGINE in service_conf.yaml or via the DOC_ENGINE environment variable:

DOC_ENGINE=opensearch

2.5 Enabling Optional Services

Code Sandbox (for the Code agent component):

docker compose -f docker-compose.yml --profile cpu --profile elasticsearch --profile sandbox up -d

Sandbox settings in .env:

SANDBOX_EXECUTOR_MANAGER_POOL_SIZE=3
SANDBOX_MAX_MEMORY=256m
SANDBOX_TIMEOUT=10s

Kibana (Elasticsearch monitoring dashboard):

docker compose -f docker-compose.yml --profile cpu --profile elasticsearch --profile kibana up -d

MCP Server (Model Context Protocol):

Add --enable-mcpserver to the RAGFlow entrypoint, or enable it in your compose override.

Admin Server:

Add --enable-adminserver to the entrypoint to expose the admin API on port 9381.

2.6 Building from Source

For development or custom builds:

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

Download dependencies:

python download_deps.py

For users in China, use mirror sources:

python download_deps.py --china-mirrors

Build the Docker image:

docker build -t infiniflow/ragflow:dev .

Then update docker-compose.yml to use your local image tag and start normally.

2.7 Superuser Initialization

To create the initial superuser account (useful for fresh deployments or when registration is disabled):

docker exec -it ragflow-ragflow python ragflow_server.py --init-superuser

Or pass --init-superuser as an entrypoint flag in your Docker Compose configuration.

2.8 Entrypoint Flags Reference

The RAGFlow container entrypoint (docker/entrypoint.sh) accepts these flags:

2.9 Post-Installation Verification

Run through this checklist after installation:

1. All containers healthy:

   docker compose ps
   

2. Web UI accessible:

   http://localhost:9380
   

3. API responding:

   curl http://localhost:9380/v1/system/status
   

4. System config endpoint:

   curl http://localhost:9380/v1/system/config
   

5. MinIO console accessible (for storage inspection):

   http://localhost:9001
   

   Login with MINIO_USER / MINIO_PASSWORD from your .env.

2.10 Installation Troubleshooting

Problem: Elasticsearch fails to start with "max virtual memory areas" error. Cause: vm.max_map_count too low. Solution:

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

Problem: Container ragflow-ragflow exits immediately. Cause: Missing or corrupted configuration, insufficient memory, or port conflict. Solution: Check logs with docker logs ragflow-ragflow. Verify .env values. Ensure port 9380 is free: ss -tlnp | grep 9380.

Problem: docker compose command not found. Cause: Docker Compose v1 (docker-compose) installed instead of v2. Solution: Install Docker Compose v2 plugin: sudo apt install docker-compose-plugin.

Problem: Permission denied errors on Linux. Cause: Current user not in the docker group. Solution: sudo usermod -aG docker $USER && newgrp docker.

Problem: Port 9380 already in use. Cause: Another service occupies the port. Solution: Change SVR_HTTP_PORT in .env to another port (e.g., 9480), then restart.

Problem: MySQL container fails with "InnoDB: Unable to lock" error. Cause: Stale lock files from a previous unclean shutdown. Solution: docker compose down -v to remove volumes, then docker compose up -d (this destroys data — back up first).

Problem: Images pull very slowly or fail. Cause: Docker Hub rate limits or network issues. Solution: Use a Docker mirror registry, or authenticate with Docker Hub: docker login.

Problem: MinIO reports "drive not found" or storage errors. Cause: Volume mount misconfiguration. Solution: Verify the Docker volume paths in docker-compose.yml. Ensure the host directory exists and has correct permissions.

Problem: NVIDIA GPU not detected in GPU profile. Cause: NVIDIA Container Toolkit not installed or driver mismatch. Solution: Install the toolkit, verify with docker run --rm --gpus all nvidia/cuda:12.0-base nvidia-smi. Check that your driver supports CUDA 12.x.

Problem: Services start but web UI shows blank page. Cause: Nginx not yet ready or frontend assets not built. Solution: Wait 60–120 seconds for full initialization. Check docker logs ragflow-ragflow for nginx startup messages.

Problem: "Connection refused" when accessing API. Cause: RAGFlow server not yet fully started. Solution: The Python server takes 30–90 seconds to initialize after the container starts. Watch logs: docker logs -f ragflow-ragflow.

Problem: service_conf.yaml.template not found (issue #6927). Cause: Missing template file in certain versions. Solution: Pull the latest version of RAGFlow. The template is included in current releases.

3. Configuration

3.1 Environment Variables (.env file)

The primary user-facing configuration is the .env file in the docker/ directory. Changes require restarting containers:

docker compose down
docker compose -f docker-compose.yml --profile cpu --profile elasticsearch up -d

3.2 Common Configuration Scenarios

Change the HTTP port:

SVR_HTTP_PORT=8080

Set a secure MySQL password:

MYSQL_PASSWORD=your_strong_password_here

Switch document engine to OpenSearch:

DOC_ENGINE=opensearch
OPENSEARCH_PASSWORD=your_opensearch_password

Enable user registration (or disable it):

REGISTER_ENABLED=1    # 1 = enabled (default), 0 = disabled

Disable password-based login (useful when using only OAuth):

DISABLE_PASSWORD_LOGIN=true

Configure an HTTP proxy for outbound LLM API calls:

HTTP_CLIENT_PROXY=http://proxy.example.com:8080

Set the compute device:

DEVICE=cpu    # or cuda for GPU

Adjust embedding batch size (increase for faster processing on powerful hardware):

EMBEDDING_BATCH_SIZE=16

Enable document encryption:

RAGFLOW_CRYPTO_ENABLED=true
RAGFLOW_CRYPTO_ALGORITHM=aes-256-cbc

Adjust thread pool size:

THREAD_POOL_MAX_WORKERS=128

Set file upload limits:

MAX_FILE_NUM_PER_USER=0    # 0 = unlimited

Configure the sandbox:

SANDBOX_ENABLED=1
SANDBOX_EXECUTOR_MANAGER_POOL_SIZE=3
SANDBOX_MAX_MEMORY=256m
SANDBOX_TIMEOUT=10s

Set nginx API proxy scheme:

API_PROXY_SCHEME=python    # python, go, or hybrid

3.3 Configuring Chunk Feedback

RAGFlow can learn from user feedback on retrieved chunks to improve future retrieval:

CHUNK_FEEDBACK_ENABLED=true
CHUNK_FEEDBACK_WEIGHTING=relevance

3.4 Logging

Control log verbosity:

LOG_LEVELS=INFO    # DEBUG, INFO, WARNING, ERROR

3.5 Nginx API Routing

The API_PROXY_SCHEME variable controls how nginx routes API traffic:

For most users, the default python scheme is correct.

Note

For advanced configuration (service_conf.yaml internals, database tuning, storage backends, security hardening), see the RAGFlow Admin Guide, Section 3.

4. Core Usage

4.1 Creating a Knowledge Base

A knowledge base is RAGFlow's container for documents. Each knowledge base has its own chunking configuration, embedding model, and retrieval settings.

1. Log in to the RAGFlow web UI at http://localhost:9380.
2. Navigate to Knowledge Base in the left sidebar.
3. Click Create Knowledge Base.
4. Configure:
   • Name: A descriptive name for this collection.
   • Embedding Model: Select from your configured LLM providers (e.g., BAAI/bge-large-en-v1.5, text-embedding-ada-002).
   • Chunk Method: Choose a parsing strategy (see 4.4 Document Parsing Methods).
   • Parser Configuration: Adjust chunk size, overlap, and method-specific settings.
5. Click Save.

Via API:

curl -X POST http://localhost:9380/v1/kb/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Documentation",
    "description": "Internal product docs for Q&A"
  }'

4.2 Uploading Documents

RAGFlow supports PDF, DOCX, XLSX, PPTX, TXT, MD, HTML, CSV, JSON, images (via OCR), and many more formats.

1. Open your knowledge base.
2. Click Upload or drag files into the upload area.
3. Files appear in the document list with status Pending.
4. Select documents and click Parse to begin chunking.

Via API — upload a file:

curl -X POST http://localhost:9380/v1/document/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/document.pdf" \
  -F "kb_id=YOUR_KB_ID"

Via API — upload and parse in one step:

curl -X POST http://localhost:9380/v1/document/upload_and_parse \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/document.pdf" \
  -F "kb_id=YOUR_KB_ID"

Via API — web crawl:

curl -X POST http://localhost:9380/v1/document/web_crawl \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kb_id": "YOUR_KB_ID",
    "url": "https://example.com/docs"
  }'

4.3 Triggering Document Parsing

After upload, documents must be parsed (chunked) before they become searchable.

1. In the knowledge base document list, select one or more documents.
2. Click Run (or Parse).
3. Monitor progress — the status changes from Pending to Processing to Completed.

Via API:

curl -X POST http://localhost:9380/v1/document/run \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "doc_ids": ["DOC_ID_1", "DOC_ID_2"]
  }'

Tip

For large documents (100+ pages), parsing can take several minutes. Increase --workers=N in the entrypoint flags to run more task executors in parallel.

4.4 Document Parsing Methods

RAGFlow offers multiple chunking strategies, each optimized for different document types:

External parsers:

4.5 Managing Chunks

After parsing, you can inspect, edit, and manage individual chunks.

View chunks:

1. Open a knowledge base, click a parsed document, and view its chunks.
2. Each chunk shows its text content and metadata.

Edit a chunk (correct parsing errors):

Via API:

curl -X POST http://localhost:9380/v1/chunk/set \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chunk_id": "CHUNK_ID",
    "content": "Updated chunk text here"
  }'

Create a manual chunk:

curl -X POST http://localhost:9380/v1/chunk/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "doc_id": "DOC_ID",
    "content": "Manually created chunk content"
  }'

Delete chunks:

curl -X POST http://localhost:9380/v1/chunk/rm \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chunk_ids": ["CHUNK_ID_1", "CHUNK_ID_2"]
  }'

Test retrieval (check if your chunks return relevant results):

curl -X POST http://localhost:9380/v1/chunk/retrieval_test \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kb_id": "YOUR_KB_ID",
    "question": "How do I configure the database?"
  }'

4.6 Knowledge Graph (GraphRAG)

RAGFlow can build a knowledge graph from your documents, enabling entity-aware retrieval.

1. Create a knowledge base with the Knowledge Graph chunk method.
2. Upload and parse documents — RAGFlow extracts entities and relationships.
3. View the graph via the UI or API.

View the knowledge graph:

curl -X GET "http://localhost:9380/v1/chunk/knowledge_graph?kb_id=YOUR_KB_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

GraphRAG CLI tools (for development/testing):

# Smoke test
python smoke.py -t TENANT_ID -d DOC_ID

# Search the graph
python search.py -t TENANT_ID -d KB_ID -q "What is the relationship between X and Y?"

Note

GraphRAG requires more processing time than standard chunking. For large document sets, expect significantly longer parse times.

4.7 Configuring LLM Providers

RAGFlow supports 80+ LLM providers. Configure them through the web UI or API.

Via web UI:

1. Go to Settings then Model Providers (or LLM section).
2. Select a provider (e.g., OpenAI, Anthropic, Ollama).
3. Enter your API key and any required configuration.
4. Test the connection.

Via API — set an API key for a factory:

curl -X POST http://localhost:9380/v1/llm/set_api_key \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "llm_factory": "OpenAI",
    "api_key": "sk-..."
  }'

Via API — add a custom LLM:

curl -X POST http://localhost:9380/v1/llm/add_llm \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "llm_factory": "Ollama",
    "model_name": "llama3",
    "api_base": "http://localhost:11434"
  }'

List available model factories:

curl -X GET http://localhost:9380/v1/llm/factories \
  -H "Authorization: Bearer YOUR_API_KEY"

List your configured models:

curl -X GET http://localhost:9380/v1/llm/my_llms \
  -H "Authorization: Bearer YOUR_API_KEY"

Supported providers include (partial list): OpenAI, Azure OpenAI, Anthropic, Google Gemini, DeepSeek, Ollama, vLLM, Hugging Face, Mistral, Cohere, Baichuan, Qwen, Zhipu, MiniMax, Moonshot, Yi, Groq, Together AI, Fireworks, Replicate, Perplexity, and many more.

4.8 Building Agents with Canvas

The Canvas is RAGFlow's visual agent/workflow builder, offering 30+ drag-and-drop components.

Creating an agent:

1. Navigate to Agent in the sidebar.
2. Click Create Agent or select from templates.
3. The Canvas editor opens with a visual graph.
4. Drag components from the panel and connect them.

Available components:

Using templates:

curl -X GET http://localhost:9380/v1/canvas/templates \
  -H "Authorization: Bearer YOUR_API_KEY"

Templates provide pre-built agent workflows for common patterns (customer support, research assistant, etc.).

Save an agent:

curl -X POST http://localhost:9380/v1/canvas/set \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Research Assistant",
    "dsl": { ... }
  }'

Run an agent (chat completion):

curl -X POST http://localhost:9380/v1/canvas/completion \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "CANVAS_ID",
    "messages": [{"role": "user", "content": "Find papers about RAG architectures"}]
  }'

Debug an agent:

curl -X POST http://localhost:9380/v1/canvas/debug \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "CANVAS_ID",
    "messages": [{"role": "user", "content": "test query"}]
  }'

Warning

The Code component requires the sandbox to be enabled (SANDBOX_ENABLED=1 and the sandbox Docker Compose profile). Without it, Code components will fail at runtime.

4.9 Using Data Source Connectors

RAGFlow integrates with 30+ external data sources to automatically sync documents.

Supported connectors:

Create a connector:

curl -X POST http://localhost:9380/v1/connector/set \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Confluence",
    "type": "confluence",
    "config": {
      "url": "https://yourorg.atlassian.net",
      "username": "[email removed]",
      "api_token": "your-token",
      "space_key": "DOC"
    }
  }'

List connectors:

curl -X GET http://localhost:9380/v1/connector/list \
  -H "Authorization: Bearer YOUR_API_KEY"

Resume a paused connector:

curl -X PUT http://localhost:9380/v1/connector/CONNECTOR_ID/resume \
  -H "Authorization: Bearer YOUR_API_KEY"

Rebuild a connector (re-sync all data):

curl -X PUT http://localhost:9380/v1/connector/CONNECTOR_ID/rebuild \
  -H "Authorization: Bearer YOUR_API_KEY"

OAuth-based connectors (Google Drive, Gmail, Box): These require OAuth flow through the web UI. Navigate to the connector setup page, click Authorize, and complete the OAuth consent screen.

4.10 Chat and Conversations

Start a chat session with an agent:

curl -X PUT "http://localhost:9380/v1/canvas/CANVAS_ID/sessions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Chat Session"
  }'

List sessions:

curl -X GET "http://localhost:9380/v1/canvas/CANVAS_ID/sessions" \
  -H "Authorization: Bearer YOUR_API_KEY"

Send a message in a session:

Use the canvas completion endpoint with the session context.

4.11 MCP (Model Context Protocol) Integration

RAGFlow can act as an MCP server, exposing your knowledge bases as tools for MCP-compatible AI clients.

Start the MCP server:

Add --enable-mcpserver to the container entrypoint, or run standalone:

python mcp/server/server.py \
  --base-url http://localhost:9380 \
  --host 0.0.0.0 \
  --port 9382 \
  --mode self-host \
  --api-key YOUR_API_KEY

MCP server options:

Manage MCP server configurations in RAGFlow:

# Create an MCP server config
curl -X POST http://localhost:9380/v1/mcp/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My MCP Server", "config": {...}}'

# List MCP servers
curl -X POST http://localhost:9380/v1/mcp/list \
  -H "Authorization: Bearer YOUR_API_KEY"

# List available tools on an MCP server
curl -X POST http://localhost:9380/v1/mcp/list_tools \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mcp_id": "MCP_SERVER_ID"}'

# Test a tool
curl -X POST http://localhost:9380/v1/mcp/test_tool \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mcp_id": "MCP_SERVER_ID", "tool_name": "search", "arguments": {"query": "test"}}'

# Import/Export MCP configs
curl -X POST http://localhost:9380/v1/mcp/import \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@mcp_config.json"

curl -X POST http://localhost:9380/v1/mcp/export \
  -H "Authorization: Bearer YOUR_API_KEY"

4.12 Evaluation and Benchmarking

RAGFlow includes a built-in evaluation framework for measuring retrieval and generation quality.

Create an evaluation dataset:

curl -X POST http://localhost:9380/v1/evaluation/dataset/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "QA Test Set",
    "description": "Golden QA pairs for testing"
  }'

Run an evaluation:

curl -X POST http://localhost:9380/v1/evaluation/run/start \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dataset_id": "DATASET_ID",
    "kb_id": "KB_ID"
  }'

Get evaluation results:

curl -X GET "http://localhost:9380/v1/evaluation/run/RUN_ID/results" \
  -H "Authorization: Bearer YOUR_API_KEY"

CLI benchmark tool:

python benchmark.py max_docs=100 kb_id=YOUR_KB_ID dataset=my_dataset dataset_path=/path/to/data

4.13 Python SDK

The Python SDK provides a programmatic interface to all RAGFlow features.

Installation:

pip install ragflow-sdk

Basic usage:

from ragflow_sdk import RAGFlow

# Connect to RAGFlow
rag = RAGFlow(api_key="YOUR_API_KEY", base_url="http://localhost:9380")

# Create a knowledge base (dataset)
dataset = rag.create_dataset(name="My Dataset")

# Upload a document
with open("document.pdf", "rb") as f:
    doc = dataset.upload_document(f, name="document.pdf")

# Parse the document
doc.parse()

# List chunks
chunks = doc.list_chunks()
for chunk in chunks:
    print(chunk.content[:100])

# Create a chat session
session = rag.create_session(name="Test Session")

# Ask a question
response = session.chat("What is covered in this document?")
print(response.content)

SDK modules include: datasets, documents, chunks, sessions, agents, and more. The SDK mirrors the HTTP API endpoints documented in Section 4.

4.14 Langfuse Observability Integration

RAGFlow integrates with Langfuse for LLM observability and tracing.

Set up Langfuse:

# Save your Langfuse API key
curl -X POST http://localhost:9380/v1/langfuse/api_key \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "public_key": "pk-...",
    "secret_key": "sk-...",
    "host": "https://cloud.langfuse.com"
  }'

# Check saved config
curl -X GET http://localhost:9380/v1/langfuse/api_key \
  -H "Authorization: Bearer YOUR_API_KEY"

# Remove Langfuse integration
curl -X DELETE http://localhost:9380/v1/langfuse/api_key \
  -H "Authorization: Bearer YOUR_API_KEY"

Important

Langfuse integration has a known issue (#14204) where the start_generation method may raise an AttributeError in certain versions. Check the RAGFlow GitHub issues for the latest status and workarounds.

4.15 Search

RAGFlow exposes a search endpoint for direct retrieval queries:

curl -X GET "http://localhost:9380/v1/search/KB_ID?q=your+query" \
  -H "Authorization: Bearer YOUR_API_KEY"

4.16 User Account Management

Login:

curl -X POST http://localhost:9380/v1/user/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email removed]", "password": "your_password"}'

Register:

curl -X POST http://localhost:9380/v1/user/register \
  -H "Content-Type: application/json" \
  -d '{"email": "[email removed]", "nickname": "username", "password": "your_password"}'

Get user info:

curl -X GET http://localhost:9380/v1/user/info \
  -H "Authorization: Bearer YOUR_API_KEY"

Get tenant info:

curl -X GET http://localhost:9380/v1/user/tenant_info \
  -H "Authorization: Bearer YOUR_API_KEY"

Reset password (CLI):

docker exec -it ragflow-ragflow python reset-password \
  --email [email removed] \
  --new-password NewPass123 \
  --password-confirm NewPass123

Reset email (CLI):

docker exec -it ragflow-ragflow python reset-email \
  --email [email removed] \
  --new-email [email removed] \
  --email-confirm [email removed]

4.17 File Conversion

Convert files to documents:

curl -X POST http://localhost:9380/v1/file2document/convert \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "FILE_ID",
    "kb_id": "KB_ID"
  }'

4.18 OCR and Layout Tools

RAGFlow includes standalone OCR and layout recognition tools:

OCR processing:

python t_ocr.py --inputs /path/to/images_or_pdfs --output_dir /path/to/output

Layout recognition:

python t_recognizer.py --inputs /path/to/documents --output_dir /path/to/output --threshold 0.5 --mode layout

Table structure recognition:

python t_recognizer.py --inputs /path/to/documents --output_dir /path/to/output --mode table

5. Common Tasks

Recipe 1: Build a Q&A System Over Company Documents

Goal: Create a knowledge base from internal docs, then chat with them.

Prerequisites: RAGFlow running, LLM provider configured.

Steps:

1. Create a knowledge base named "Company Docs" with the Naive chunk method.
2. Upload your PDF/DOCX/MD files.
3. Select all documents and click Parse.
4. Wait for parsing to complete (status: Completed).
5. Navigate to Agent and click Create Agent.
6. Add a Begin component, connect to Retrieval (linked to your KB), then connect to Message.
7. Save and test with a question.

Verify: Ask "What is our vacation policy?" and confirm the answer cites your documents.

If it fails: Check that parsing completed successfully. Verify your LLM provider API key is valid. Try the retrieval test endpoint to isolate retrieval vs. generation issues.

Recipe 2: Set Up Ollama as a Local LLM Provider

Goal: Use locally-running Ollama models with RAGFlow.

Prerequisites: Ollama installed and running (ollama serve), a model pulled (ollama pull llama3).

Steps:

1. In RAGFlow, go to Settings then Model Providers.
2. Select Ollama.
3. Set the API base URL to http://host.docker.internal:11434 (from Docker) or http://YOUR_HOST_IP:11434.
4. Save and test the connection.

Verify: The model appears in your model list and can generate responses.

If it fails: Ensure Ollama is listening on all interfaces (OLLAMA_HOST=0.0.0.0 ollama serve). Check network connectivity from the RAGFlow container: docker exec ragflow-ragflow curl http://host.docker.internal:11434/api/tags.

Recipe 3: Connect Confluence as a Data Source

Goal: Automatically sync Confluence spaces into RAGFlow.

Prerequisites: Confluence Cloud account, API token.

Steps:

1. Generate a Confluence API token at https://id.atlassian.com/manage-profile/security/api-tokens.
2. In RAGFlow, go to Connectors and click Add Connector.
3. Select Confluence.
4. Enter your Confluence URL, username (email), API token, and space key.
5. Configure sync schedule.
6. Save and trigger initial sync.

Verify: Documents from your Confluence space appear in the linked knowledge base.

If it fails: Verify your API token has read access to the space. Check connector logs for authentication errors.

Recipe 4: Parse Academic Papers with the Paper Chunk Method

Goal: Optimally chunk research papers preserving structure.

Prerequisites: RAGFlow running, PDF papers ready.

Steps:

1. Create a knowledge base with chunk method set to Paper.
2. Upload your academic PDFs.
3. Parse the documents.
4. Inspect chunks — they should be organized by paper sections (Abstract, Introduction, Methods, etc.).

Verify: Chunks align with paper sections, not arbitrary text splits.

If it fails: If papers have unusual formatting, try the Naive method with a larger chunk size as fallback.

Recipe 5: Build a Multi-Step Research Agent

Goal: Create an agent that searches the web, retrieves from your KB, and synthesizes.

Prerequisites: RAGFlow running, knowledge base populated, LLM configured.

Steps:

1. Go to Agent and click Create Agent.
2. Add a Begin component.
3. Add a Rewrite Question component (improves query quality).
4. Add a Retrieval component connected to your KB.
5. Add a DuckDuckGo (or Google) search component for web results.
6. Add a Message component that receives both retrieval and search results.
7. Connect: Begin to Rewrite Question, then fork to Retrieval and DuckDuckGo, then merge into Message.
8. Save and test.

Verify: Responses cite both your KB documents and web sources.

If it fails: Ensure the search component has internet access from the container. Check that the Message component's prompt template references both input sources.

Recipe 6: Enable and Use the Code Sandbox

Goal: Allow agents to execute Python code safely.

Prerequisites: Sandbox Docker profile enabled.

Steps:

1. Stop RAGFlow: docker compose down.
2. Start with sandbox profile:

   docker compose -f docker-compose.yml --profile cpu --profile elasticsearch --profile sandbox up -d
   

3. Set SANDBOX_ENABLED=1 in your .env if not already set.
4. In your agent canvas, add a Code component.
5. Write Python code in the component editor.
6. Connect it to your workflow.

Verify: The Code component executes and returns results without errors.

If it fails: Check that the sandbox container is running: docker compose ps | grep sandbox. Review sandbox logs for resource limit errors.

Recipe 7: Export and Import MCP Configurations

Goal: Back up or share your MCP server configurations.

Steps:

1. Export:

   curl -X POST http://localhost:9380/v1/mcp/export \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -o mcp_backup.json
   

2. Import on another instance:

   curl -X POST http://localhost:9380/v1/mcp/import \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -F "file=@mcp_backup.json"
   

Verify: Run POST /v1/mcp/list on both instances and confirm matching configurations.

Recipe 8: Set Up Google Drive Connector with OAuth

Goal: Sync documents from Google Drive into RAGFlow.

Prerequisites: Google Cloud project with Drive API enabled, OAuth credentials configured.

Steps:

1. In RAGFlow, navigate to Connectors, click Add Connector, and select Google Drive.
2. Click Authorize to start the OAuth flow.
3. Sign in with your Google account and grant permissions.
4. Select folders to sync.
5. Configure sync frequency.
6. Save the connector.

Verify: Files from your selected Google Drive folders appear in the linked knowledge base.

If it fails: Ensure your Google Cloud OAuth consent screen is configured correctly. Check that the redirect URI matches your RAGFlow instance URL.

Recipe 9: Use RAGFlow as an MCP Server with Claude Desktop

Goal: Let Claude Desktop access your RAGFlow knowledge bases as tools.

Prerequisites: RAGFlow running with MCP server enabled, Claude Desktop installed.

Steps:

1. Enable the MCP server:

   python mcp/server/server.py \
     --base-url http://localhost:9380 \
     --host 0.0.0.0 \
     --port 9382 \
     --mode self-host \
     --api-key YOUR_API_KEY
   

2. In Claude Desktop's MCP configuration, add:

   {
     "mcpServers": {
       "ragflow": {
         "url": "http://localhost:9382/sse"
       }
     }
   }
   

3. Restart Claude Desktop.

Verify: Claude Desktop shows RAGFlow tools available. Ask a question and confirm it queries your knowledge base.

If it fails: Check that the MCP server port is accessible. Verify SSE transport is enabled (default). Review MCP server logs for connection errors.

Recipe 10: Benchmark Retrieval Quality

Goal: Measure how well your chunking and retrieval perform.

Steps:

1. Create a golden QA dataset:

   curl -X POST http://localhost:9380/v1/evaluation/dataset/create \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"name": "Benchmark QA"}'
   

2. Add question-answer pairs to the dataset.
3. Run the evaluation:

   curl -X POST http://localhost:9380/v1/evaluation/run/start \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"dataset_id": "DATASET_ID", "kb_id": "KB_ID"}'
   

4. Review results:

   curl -X GET "http://localhost:9380/v1/evaluation/run/RUN_ID/results" \
     -H "Authorization: Bearer YOUR_API_KEY"
   

Verify: Results include retrieval precision, recall, and relevance scores.

If it fails: Ensure the knowledge base has been fully parsed before evaluation. Check that the dataset format matches expected schema.

Recipe 11: Switch from Elasticsearch to OpenSearch

Goal: Migrate your document engine.

Prerequisites: Back up your data first.

Steps:

1. Stop RAGFlow: docker compose down.
2. In .env, set:

   DOC_ENGINE=opensearch
   OPENSEARCH_PASSWORD=secure_password
   

3. Start with OpenSearch profile:

   docker compose -f docker-compose.yml --profile cpu --profile opensearch up -d
   

4. Re-parse your documents (the document engine index must be rebuilt).

Verify: curl http://localhost:9380/v1/system/status shows OpenSearch as the active engine.

If it fails: Check OpenSearch container logs. Ensure DOC_ENGINE is correctly set. Verify the OpenSearch password matches.

Recipe 12: Process 1000+ Page Documents

Goal: Handle very large documents without timeouts or failures.

Prerequisites: Sufficient system resources (32 GB+ RAM recommended).

Steps:

1. Increase task executor workers by adding --workers=4 to the entrypoint flags.
2. Increase memory limits in .env:

   MEM_LIMIT=16073741824
   

3. Use the Naive or Manual chunk method with a reasonable chunk size (512–1024 tokens).
4. Upload the large document.
5. Parse and monitor progress via docker logs -f ragflow-ragflow.

Verify: Document completes parsing without errors. All chunks are searchable.

If it fails: Check for DeepDoc errors with 1000+ pages (issue #14196). Consider splitting the document into smaller parts before upload. Monitor memory usage with docker stats.

Recipe 13: Set Up Email Notifications via Agent

Goal: Build an agent that sends email alerts based on document analysis.

Steps:

1. Create an agent in Canvas.
2. Add: Begin, then Retrieval, then Message, then an Email component.
3. Configure the Email component with SMTP settings.
4. Set conditions for when emails should be sent.
5. Save and test.

Verify: An email arrives at the configured recipient address.

Recipe 14: Use RDBMS Connector to Index Database Content

Goal: Sync data from MySQL or PostgreSQL into RAGFlow.

Steps:

1. Go to Connectors, click Add Connector, and select RDBMS.
2. Select database type (MySQL or PostgreSQL).
3. Enter connection details: host, port, database, username, password.
4. Specify tables or SQL queries to sync.
5. Link to a knowledge base.
6. Save and trigger sync.

Verify: Database records appear as documents in your knowledge base.

If it fails: Test database connectivity from the RAGFlow container. Ensure the database user has SELECT permission on the specified tables.

Recipe 15: Enable Document Encryption

Goal: Encrypt documents at rest.

Steps:

1. In .env, set:

   RAGFLOW_CRYPTO_ENABLED=true
   RAGFLOW_CRYPTO_ALGORITHM=aes-256-cbc
   

2. Restart RAGFlow.
3. Newly uploaded documents will be encrypted.

Verify: Check MinIO storage — document blobs should be encrypted.

Warning

Enabling encryption after documents are already stored does not retroactively encrypt existing files. Only new uploads are affected.

Recipe 16: Use the QA Chunk Method for FAQ Documents

Goal: Automatically extract question-answer pairs from FAQ-formatted content.

Steps:

1. Create a knowledge base with chunk method QA.
2. Upload FAQ documents (structured as Q&A pairs).
3. Parse the documents.
4. Inspect chunks — each should be a distinct Q&A pair.

Verify: Retrieval returns precise question-answer matches rather than generic text blocks.

Recipe 17: Build a SQL Query Agent

Goal: Create an agent that converts natural language to SQL and executes it.

Steps:

1. Create an agent in Canvas.
2. Add: Begin, then Message (to understand user intent), then an ExeSQL component.
3. Configure ExeSQL with your database connection.
4. Connect the output back to a Message component for result presentation.
5. Save and test.

Verify: Ask "Show me all orders from last month" and receive a formatted table of results.

If it fails: Ensure the database is accessible from the RAGFlow container. Check SQL permissions.

Recipe 18: Set Up Langfuse for LLM Tracing

Goal: Monitor LLM calls, latency, and costs.

Steps:

1. Sign up at https://cloud.langfuse.com (or self-host).
2. Create a project and get your API keys.
3. Configure in RAGFlow:

   curl -X POST http://localhost:9380/v1/langfuse/api_key \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"public_key": "pk-...", "secret_key": "sk-...", "host": "https://cloud.langfuse.com"}'
   

4. Use RAGFlow normally — traces appear in the Langfuse dashboard.

Verify: Open your Langfuse project dashboard and confirm traces are appearing.

If it fails: Check for issue #14204 (start_generation AttributeError). Verify network access to Langfuse from the container.

Recipe 19: Web Crawl and Index a Documentation Site

Goal: Crawl and index an entire documentation website.

Steps:

1. Create a knowledge base.
2. Use the web crawl API:

   curl -X POST http://localhost:9380/v1/document/web_crawl \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "kb_id": "KB_ID",
       "url": "https://docs.example.com/getting-started"
     }'
   

3. The crawler fetches the page and linked pages.
4. Parse the crawled documents.

Verify: Crawled pages appear as documents in your knowledge base and can be searched.

Recipe 20: Use the Admin CLI for User Management

Goal: Manage users and settings via the command line.

Steps:

# Access admin CLI
docker exec -it ragflow-ragflow python ragflow_cli.py \
  -h localhost -p 9381 -w ADMIN_PASSWORD -t admin

# List users
docker exec -it ragflow-ragflow python ragflow_cli.py \
  -h localhost -p 9381 -w ADMIN_PASSWORD -t admin -u USERNAME list-users

The admin CLI connects to the admin server on port 9381 (must be enabled with --enable-adminserver).

Recipe 21: Use Iteration Components for Batch Processing

Goal: Process a list of items one by one in an agent.

Steps:

1. In Canvas, add a Loop or Iteration component.
2. Connect a data source that produces a list (e.g., Retrieval returning multiple chunks).
3. Add an Iteration Start From component inside the loop.
4. Add processing components (Message, Code, etc.) for each item.
5. Connect the loop output to a Variable Aggregator to collect results.

Verify: Each item is processed individually and results are aggregated.

Caution

Issue #14142 reports that the Iteration component may only process the first element in some configurations. Test thoroughly with multi-element inputs.

Recipe 22: Use the Switch Component for Conditional Logic

Goal: Route agent flow based on conditions.

Steps:

1. In Canvas, add a Switch component after your input.
2. Define conditions (e.g., if the query contains "billing" route to path A, otherwise route to path B).
3. Connect each branch to different processing paths.
4. Merge results downstream.

Verify: Different queries route to the correct branches.

Recipe 23: Set Up Azure Blob Storage as a Data Source

Goal: Index documents from Azure Blob Storage.

Steps:

1. Go to Connectors, click Add Connector, and select Azure Blob.
2. Choose authentication method: SAS token or Service Principal (SPN).
3. Enter connection string, container name, and optional prefix filter.
4. Link to a knowledge base.
5. Save and trigger sync.

Verify: Blobs from the specified container appear as documents.

Recipe 24: Use S3/MinIO as an External Data Source

Goal: Sync documents from an S3-compatible bucket.

Steps:

1. Go to Connectors, click Add Connector, and select S3/MinIO.
2. Enter endpoint URL, access key, secret key, and bucket name.
3. Configure optional prefix filter.
4. Link to a knowledge base.
5. Save and trigger sync.

Verify: Objects from the S3 bucket appear as documents in the knowledge base.

Recipe 25: Scale Task Executors for Faster Parsing

Goal: Parse documents faster with more parallel workers.

Steps:

1. Edit the entrypoint to increase workers:

   --workers=4
   

   Or use the range flags:

   --consumer-no-beg=0 --consumer-no-end=3
   

2. Restart RAGFlow.
3. Upload and parse multiple documents simultaneously.

Verify: Multiple documents parse in parallel. Check with docker logs -f ragflow-ragflow for interleaved worker activity.

If it fails: More workers require more memory. Monitor with docker stats and increase MEM_LIMIT if needed.

Recipe 26: Use the Categorize Component for Intent Classification

Goal: Route user queries to different handlers based on intent.

Steps:

1. In Canvas, add a Categorize component after Begin.
2. Define categories (e.g., "Technical Question", "Billing Inquiry", "General Chat").
3. Provide example queries for each category.
4. Connect each category output to the appropriate processing branch.

Verify: Test queries are classified correctly and routed to the right branch.

Recipe 27: Create a Knowledge Graph from Legal Documents

Goal: Extract entities and relationships from legal texts.

Steps:

1. Create a knowledge base with the Knowledge Graph chunk method.
2. Upload legal documents (contracts, regulations, etc.).
3. Parse the documents.
4. View the graph: relationships between parties, clauses, and obligations are visualized.

Verify: The knowledge graph endpoint returns meaningful entities and edges.

Recipe 28: Monitor RAGFlow with Kibana

Goal: Visualize Elasticsearch health and indexing metrics.

Steps:

1. Start with the Kibana profile:

   docker compose -f docker-compose.yml --profile cpu --profile elasticsearch --profile kibana up -d
   

2. Access Kibana at http://localhost:5601.
3. Log in with elastic / your ELASTIC_PASSWORD.
4. Navigate to Stack Management then Index Management to see RAGFlow indices.

Verify: Kibana shows indices with document counts matching your uploaded documents.

Recipe 29: Use the Extractor Component to Pull Structured Data

Goal: Extract specific fields from unstructured text (dates, names, amounts).

Steps:

1. In Canvas, add an Extractor component.
2. Define the fields to extract (e.g., "invoice_date", "total_amount", "vendor_name").
3. Connect it after a Retrieval or document input component.
4. The Extractor uses the configured LLM to identify and return structured fields.

Verify: The output contains correctly identified field values.

Recipe 30: Bulk Upload via API Script

Goal: Upload hundreds of documents programmatically.

Steps:

import os
import requests

API_URL = "http://localhost:9380"
API_KEY = "YOUR_API_KEY"
KB_ID = "YOUR_KB_ID"

headers = {"Authorization": f"Bearer {API_KEY}"}

doc_dir = "/path/to/documents"
for filename in os.listdir(doc_dir):
    filepath = os.path.join(doc_dir, filename)
    if os.path.isfile(filepath):
        with open(filepath, "rb") as f:
            resp = requests.post(
                f"{API_URL}/v1/document/upload_and_parse",
                headers=headers,
                files={"file": (filename, f)},
                data={"kb_id": KB_ID}
            )
            print(f"{filename}: {resp.status_code} - {resp.json().get('message', 'OK')}")

Verify: All files appear in the knowledge base with status Completed.

If it fails: Check for file size limits. Large files may need individual upload and parse calls with progress monitoring.

6. Troubleshooting

6.1 Installation and Startup

Error: Elasticsearch exits with "max virtual memory areas vm.max_map_count [65530] is too low" Cause: Linux kernel default vm.max_map_count is too low for Elasticsearch. Solution:

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

Prevention: Add to your provisioning scripts or Dockerfile.

Error: service_conf.yaml.template not found (GitHub issue #6927) Cause: Missing template file in certain older versions. Solution: Upgrade to the latest RAGFlow version. The template is included in current releases. Prevention: Always use the latest stable release.

Error: Container ragflow-ragflow keeps restarting Cause: Configuration error, missing dependency, or database connection failure. Solution: Examine logs: docker logs ragflow-ragflow 2>&1 | head -100. Common causes: wrong MySQL password, Elasticsearch not ready yet, port conflicts. Prevention: Ensure all dependent services (MySQL, Redis, ES/OS) are healthy before RAGFlow starts. Docker Compose depends_on handles this in most cases.

Error: v0.24.0 deployment failure, no data inheritance (GitHub issue #13713) Cause: Schema changes between versions without proper migration. Solution: Follow the official upgrade guide. Back up MySQL data and Elasticsearch indices before upgrading. Check release notes for breaking changes. Prevention: Always back up before version upgrades.

Error: "Connection refused" on port 9380 after startup Cause: Server initialization takes 30–90 seconds. Solution: Wait and retry. Check docker logs -f ragflow-ragflow for the "serving on" message. Prevention: Add health checks to your monitoring.

Error: Docker Compose reports "no matching manifest for linux/arm64" Cause: Some images may not support ARM architecture natively. Solution: Use --platform linux/amd64 with Docker on ARM hosts, or build from source. Prevention: Check architecture compatibility before deploying.

6.2 Document Parsing

Error: "expected string or bytes-like object" while chunking (GitHub issue #6990) Cause: Document contains unexpected binary data or encoding issues. Solution: Re-upload the document in a different format (e.g., convert DOCX to PDF). Check document encoding. Prevention: Validate document encoding before upload.

Error: Resume chunking fails (GitHub issue #6933) Cause: Interrupted parsing leaves inconsistent state. Solution: Delete the document's chunks and re-parse from scratch. If the document itself is corrupted, re-upload it. Prevention: Avoid stopping containers during active parsing.

Error: DeepDoc fails on 1000+ page documents (GitHub issue #14196) Cause: Memory exhaustion or timeout during OCR/layout processing of very large documents. Solution: Split the document into smaller parts (200–300 pages each). Increase container memory limits. Consider using the Naive chunk method without OCR for text-only PDFs. Prevention: Pre-split large documents before upload.

Error: MinerU parser — parsed images obscured (GitHub issue #14197) Cause: MinerU image extraction produces low-quality or overlapping image regions. Solution: Use DeepDoc parser instead for image-heavy documents. Check MinerU version compatibility. Prevention: Test parser output on sample pages before processing full documents.

Error: Parsing stuck at 0% progress Cause: Task executor not running or unable to claim the job. Solution: Verify task executors are running: docker logs ragflow-ragflow 2>&1 | grep "task_executor". Restart with --workers=1 to ensure at least one executor is active. Check that --disable-taskexecutor is NOT set. Prevention: Monitor task executor logs.

Error: OCR produces garbled or incorrect text Cause: Low-quality scans, unusual fonts, or language not supported by default models. Solution: Use higher-resolution scans (300+ DPI). For non-English documents, ensure appropriate OCR models are loaded. Prevention: Pre-process images to improve contrast and resolution.

Error: Table structure not preserved in chunks Cause: Using Naive chunk method on table-heavy documents. Solution: Switch to the Table chunk method for spreadsheets and table-heavy PDFs. Prevention: Choose the appropriate chunk method for your document type.

6.3 LLM and Retrieval

Error: Retrieval timeout — HTTP 200 but results timeout (GitHub issue #6998) Cause: Elasticsearch query too complex or index too large for available resources. Solution: Increase MEM_LIMIT for Elasticsearch. Reduce chunk count per knowledge base. Optimize query complexity. Prevention: Monitor Elasticsearch heap usage. Keep knowledge bases under 1M chunks for best performance.

Error: LLM returns empty or error responses Cause: Invalid API key, rate limiting, or model not available. Solution: Verify API key in Settings then Model Providers. Check provider-specific rate limits. Ensure the model name is correct. Prevention: Use the LLM test function in the UI before deploying to production agents.

Error: Embedding model fails to load Cause: Model files not downloaded or GPU out of memory. Solution: For local models, ensure they are downloaded. For GPU, check VRAM availability with nvidia-smi. Switch to a smaller embedding model or CPU mode. Prevention: Monitor GPU memory usage.

Error: Retrieval returns irrelevant results Cause: Poor chunking strategy, embedding model mismatch, or insufficient data. Solution: Use the retrieval test endpoint to experiment with different queries. Try a different chunk method. Use a domain-appropriate embedding model. Increase chunk overlap. Prevention: Test retrieval quality with the evaluation framework before deploying.

6.4 Agents and Canvas

Tip

When debugging agent issues, use the Canvas Debug mode (POST /v1/canvas/debug) to see intermediate outputs at each component step.

Error: Code component fails with "sandbox not available" Cause: Sandbox service not running. Solution: Start with the sandbox profile: --profile sandbox. Set SANDBOX_ENABLED=1. Prevention: Always include the sandbox profile if using Code components.

Error: Iteration component only processes first element (GitHub issue #14142) Cause: Bug in certain versions where the iteration loop does not advance. Solution: Check for patches in the latest RAGFlow release. As a workaround, use a Loop component with explicit index tracking. Prevention: Test iteration agents with multi-element inputs before production use.

Error: Agent canvas saves but does not run Cause: Disconnected components or missing required configuration. Solution: Verify all components are connected in the graph. Check that each component has its required fields filled (model selection, knowledge base linkage, etc.). Prevention: Use the Canvas validation feature before saving.

Error: Search components (DuckDuckGo, Google) return no results Cause: Network access blocked from the container, or API key not configured for Google. Solution: Ensure DNS resolution works from the container. For Google, configure API credentials. DuckDuckGo does not require an API key but needs outbound HTTPS access. Prevention: Test network connectivity: docker exec ragflow-ragflow curl -s https://duckduckgo.com.

6.5 Connectors

Error: Confluence connector fails to authenticate Cause: Invalid API token or incorrect URL. Solution: Regenerate the API token. Use the full Confluence URL including the protocol (https://yourorg.atlassian.net). Prevention: Test credentials manually before configuring the connector.

Error: Google Drive OAuth flow returns error Cause: OAuth redirect URI mismatch or consent screen not configured. Solution: Verify the redirect URI in your Google Cloud project matches your RAGFlow instance URL. Ensure the OAuth consent screen is published (not in test mode with limited users). Prevention: Follow the Google OAuth setup guide exactly.

Error: OIDC authorization broken (GitHub issue #14066) Cause: Bug in OIDC integration in certain versions. Solution: Check for patches in the latest release. Fall back to password-based authentication. Prevention: Test OIDC configuration in a staging environment first.

Error: Data source sync connector stuck Cause: Connection timeout, rate limiting from the source, or container restart during sync. Solution: Use the resume endpoint: PUT /v1/connector/{id}/resume. If stuck, rebuild: PUT /v1/connector/{id}/rebuild. Prevention: Monitor connector status regularly.

6.6 MCP Server

Error: MCP server fails to start Cause: Port conflict or missing configuration. Solution: Verify the MCP port is free. Ensure --mcp-base-url points to a reachable RAGFlow instance. Check that the API key is valid for self-host mode. Prevention: Test MCP server connectivity immediately after starting.

Error: MCP tools not appearing in client Cause: Transport mismatch or firewall blocking. Solution: Ensure the client supports the transport protocol (SSE or Streamable HTTP). Check firewall rules allow the MCP port. Verify with curl http://localhost:9382/sse. Prevention: Use the --transport-sse-enabled flag explicitly.

6.7 Performance

Error: High memory usage causing OOM kills Cause: Elasticsearch, MySQL, and RAGFlow competing for memory on a resource-constrained host. Solution: Reduce MEM_LIMIT for Elasticsearch. Use OpenSearch or Infinity which may have lower memory footprints. Add swap space as a safety net. Prevention: Deploy on machines with 32 GB+ RAM for production workloads.

Error: Slow document parsing Cause: Single task executor, large documents, or CPU-only embedding. Solution: Increase --workers=N. Enable GPU for embedding. Use lighter chunk methods (Naive without OCR for text-only PDFs). Prevention: Benchmark with your typical document sizes before setting worker counts.

Error: API responses are slow (>5s) Cause: Overloaded Elasticsearch, large knowledge bases, or insufficient thread pool. Solution: Increase THREAD_POOL_MAX_WORKERS. Scale Elasticsearch resources. Check index health in Kibana. Prevention: Monitor API response times and set up alerts.

6.8 Langfuse Integration

Error: AttributeError: 'NoneType' object has no attribute 'start_generation' (GitHub issue #14204) Cause: Langfuse client initialization or version incompatibility. Solution: Check RAGFlow GitHub issues for the latest fix. As a workaround, remove the Langfuse API key (DELETE /v1/langfuse/api_key) to disable tracing. Prevention: Pin Langfuse SDK versions when deploying.

6.9 Database

Error: MySQL connection refused on startup Cause: MySQL container not yet initialized or incorrect password. Solution: Wait for MySQL to complete initialization (first run creates schemas). Verify MYSQL_PASSWORD matches across .env and service_conf.yaml. Prevention: Use docker compose logs mysql to confirm MySQL readiness before starting RAGFlow.

Error: Redis connection timeout Cause: Redis not started or password mismatch. Solution: Verify Redis is running and REDIS_PASSWORD is consistent. Check REDIS_PORT is not conflicting with another service. Prevention: Include Redis in your health monitoring.

7. FAQ

General

Q: What is RAGFlow? A: RAGFlow is an open-source RAG (Retrieval-Augmented Generation) engine that uses deep document understanding to provide accurate, citation-backed answers from your own data. It combines intelligent document parsing, vector search, and LLM integration.

Q: What makes RAGFlow different from other RAG tools? A: RAGFlow's primary differentiator is its deep document understanding via DeepDoc — it performs OCR, layout recognition, and table structure extraction rather than treating documents as flat text. It also includes a visual agent builder (Canvas) with 30+ components, 30+ data source connectors, and GraphRAG support.

Q: What LLMs does RAGFlow support? A: RAGFlow supports 80+ LLM providers including OpenAI, Anthropic, Google Gemini, DeepSeek, Ollama (local), vLLM, Hugging Face, Mistral, Cohere, Groq, Together AI, and many more. Any OpenAI-compatible API endpoint can be configured.

Q: Is RAGFlow free? A: Yes. RAGFlow is fully open-source under the Apache 2.0 license. There are no usage fees, enterprise tiers, or feature gates in the core product.

Q: What document formats does RAGFlow support? A: PDF, DOCX, XLSX, PPTX, TXT, MD, HTML, CSV, JSON, images (PNG, JPG, TIFF via OCR), emails (EML, MSG), and more. The specific formats depend on the parsing method used.

Q: What version of RAGFlow does this guide cover? A: This guide covers RAGFlow at commit 6712b50, which corresponds to the v0.24.x release line.

Installation

Q: What are the minimum system requirements? A: 16 GB RAM, 4 CPU cores, 50 GB disk, Docker 24.0+ with Compose v2. For GPU acceleration, an NVIDIA GPU with CUDA 12.x drivers and the NVIDIA Container Toolkit.

Q: Can I run RAGFlow without Docker? A: RAGFlow is designed for Docker deployment. Running without Docker requires manually setting up Python, Go, MySQL, MinIO, Redis, and Elasticsearch — this is possible but not officially supported for production use.

Q: How do I upgrade RAGFlow? A: docker compose down, git pull, review release notes for breaking changes, then docker compose up -d. Always back up MySQL and the document engine data before upgrading.

Q: Can I run RAGFlow on macOS? A: Yes, via Docker Desktop for Mac. Ensure Docker Desktop has at least 16 GB of memory allocated in its settings. Performance may be lower than native Linux due to Docker's virtualization layer.

Q: Can I run RAGFlow on Windows? A: Yes, via Docker Desktop with WSL2 backend. Enable WSL2 integration in Docker Desktop settings. Ensure vm.max_map_count is set inside WSL2: wsl -d docker-desktop sysctl -w vm.max_map_count=262144.

Q: How do I deploy RAGFlow with Helm on Kubernetes? A: RAGFlow provides Helm charts in the repository. Customize values.yaml for your cluster, then helm install ragflow ./helm/ragflow. Refer to the chart documentation for cluster-specific configuration.

Q: How much disk space does RAGFlow use? A: The Docker images require approximately 10–15 GB. Data usage depends on your document volume. Elasticsearch indices typically use 2–5x the raw document size. MinIO stores the original files. Plan for at least 50 GB for a small deployment.

Configuration

Q: Where is the main configuration file? A: The primary user-facing configuration is the .env file in the docker/ directory. Advanced configuration lives in service_conf.yaml inside the container.

Q: How do I change the default port? A: Set SVR_HTTP_PORT=NEW_PORT in .env and restart containers.

Q: How do I disable user registration? A: Set REGISTER_ENABLED=0 in your environment. Use --init-superuser to create the admin account.

Q: Can I use RAGFlow behind a reverse proxy? A: Yes. RAGFlow works behind nginx, Traefik, or any reverse proxy. Ensure WebSocket pass-through is configured for streaming responses. Set appropriate X-Forwarded-For and X-Forwarded-Proto headers.

Q: How do I configure SSL/TLS? A: RAGFlow itself serves HTTP. Place a reverse proxy (nginx, Traefik, Caddy) in front with SSL termination. Do not modify the RAGFlow container for SSL.

Q: How do I set an HTTP proxy for LLM API calls? A: Set HTTP_CLIENT_PROXY=http://proxy:port in your environment variables.

Usage

Q: How long does document parsing take? A: It depends on document size, parsing method, and hardware. A 10-page PDF with Naive chunking takes seconds. A 500-page PDF with OCR and layout recognition may take several minutes. GPU acceleration significantly speeds up embedding.

Q: What is the maximum document size? A: There is no hard-coded maximum, but very large documents (1000+ pages) may encounter memory issues (see issue #14196). Splitting large documents into smaller parts is recommended.

Q: Can I use multiple knowledge bases in one agent? A: Yes. The Retrieval component in Canvas can be configured to search across multiple knowledge bases. Add multiple Retrieval components or configure a single one with multiple KB IDs.

Q: What is GraphRAG and when should I use it? A: GraphRAG builds a knowledge graph from your documents, extracting entities and relationships. Use it when your queries involve relationships between concepts (e.g., "Who works with whom?" or "Which regulations apply to this product?"). Standard vector search is better for direct factual questions.

Q: How does the Memory system work? A: RAGFlow maintains conversation context across chat sessions. The memory system stores previous interactions and can reference them in future queries, enabling multi-turn conversations that build on earlier context.

Q: Can I export my data? A: You can export MCP configurations (POST /v1/mcp/export). Document data is stored in MinIO (accessible via the MinIO console at port 9001) and Elasticsearch/OpenSearch indices. Use the respective tools' export capabilities for full backups.

Q: How do I use RAGFlow with my own embedding model? A: Configure a local embedding provider (Ollama, vLLM, or TEI) and register it in RAGFlow's model providers. TEI integration is available via the tei-cpu or tei-gpu Docker Compose profiles.

Q: What is the difference between Naive and Manual chunk methods? A: Naive splits text into fixed-size chunks with overlap. Manual uses document structure (headings, sections) as natural chunk boundaries. Manual produces more semantically coherent chunks but requires well-structured documents.

Agents

Q: How many agent components are available? A: Over 30 components spanning flow control, LLM operations, data retrieval, web search, text processing, and communication. See 4.8 Building Agents with Canvas for the full list.

Q: Can agents call external APIs? A: Yes, via the Code component (requires sandbox), Invoke component, or MCP tool component. The Code component executes arbitrary Python, while Invoke calls HTTP endpoints, and MCP tool connects to MCP-compatible services.

Q: Can I share or export agent configurations? A: Yes. Agents can be exported as JSON via the Canvas API (GET /v1/canvas/get/{id}). Import by using POST /v1/canvas/set with the exported DSL.

Q: What search engines can agents use? A: DuckDuckGo, Google, Google Scholar, Bing, SearXNG, Tavily, Wikipedia, Yahoo Finance, WenCai, PubMed, GitHub, and arXiv. Each has its own component in Canvas.

Q: What is the difference between Loop and Iteration components? A: Both handle repeated processing, but Iteration is designed for processing each element in a list sequentially, while Loop supports more general-purpose repeated execution with custom exit conditions.

Connectors

Q: How often do data source connectors sync? A: Sync frequency is configurable per connector. You can set it to manual-only or configure automatic intervals.

Q: Can I filter which files a connector syncs? A: Yes, most connectors support path prefixes, file type filters, or query-based selection depending on the data source type.

Q: What happens if a connector sync fails mid-way? A: The connector can be resumed (PUT /v1/connector/{id}/resume) to pick up where it left off, or rebuilt (PUT /v1/connector/{id}/rebuild) to re-sync from scratch.

Q: Which OAuth connectors are supported? A: Google Drive, Gmail, and Box use OAuth authentication flows. Other connectors use API keys, tokens, or username/password authentication.

API and SDK

Q: How do I get an API key? A: Log in to RAGFlow, go to your user settings, and generate an API key. For programmatic access, use the login endpoint to obtain a token.

Q: Is there a rate limit on the API? A: RAGFlow does not enforce rate limits by default. This depends on your infrastructure capacity and any reverse proxy configuration.

Q: Does RAGFlow support streaming responses? A: Yes. The Canvas completion endpoint supports streaming via Server-Sent Events (SSE) for real-time token delivery.

Q: Can I use the Go API instead of Python? A: Yes. Set API_PROXY_SCHEME=go or API_PROXY_SCHEME=hybrid in .env to route API traffic to the Go backend. The Go API is under active development and may have different endpoint availability than the Python API.

Q: What Python version does the SDK require? A: The RAGFlow Python SDK supports Python 3.9+. Install it with pip install ragflow-sdk.

Troubleshooting

Q: RAGFlow is slow — how do I improve performance? A: (1) Increase task executor workers (--workers=N). (2) Enable GPU for embedding. (3) Increase Elasticsearch memory (MEM_LIMIT). (4) Use SSD storage. (5) Increase THREAD_POOL_MAX_WORKERS. (6) Consider Infinity as a document engine for higher throughput.

Q: My documents parsed but retrieval returns nothing. A: Verify the knowledge base has chunks: check the document status is "Completed" and chunk count is > 0. Test with the retrieval test endpoint. Ensure the embedding model is the same one used during parsing (changing models after parsing requires re-parsing).

Q: How do I reset my password if I cannot log in? A: Use the CLI: docker exec -it ragflow-ragflow python reset-password --email [email removed] --new-password NewPass --password-confirm NewPass.

Q: How do I check system health? A: curl http://localhost:9380/v1/system/status returns the system status including database connectivity, storage availability, and document engine health.

Q: The web UI shows a blank page after update. A: Clear your browser cache (Ctrl+Shift+Delete). If using a reverse proxy, purge its cache too. Check that the container has fully started by examining logs.

Q: How do I view RAGFlow logs? A: Use docker logs ragflow-ragflow for the main application. For specific services: docker logs ragflow-mysql, docker logs ragflow-es01, etc. Add -f to follow logs in real time.

Q: Can I run RAGFlow on a Raspberry Pi or other ARM device? A: Not recommended. RAGFlow requires significant memory (16 GB minimum) and CPU resources. ARM support depends on Docker image availability for all dependent services.