# 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

| Requirement | Minimum | Recommended |
|---|---|---|
| Docker | 24.0+ | Latest stable |
| Docker Compose | v2.x | Latest stable |
| RAM | 16 GB | 32 GB+ |
| Disk | 50 GB free | 100 GB+ SSD |
| CPU | 4 cores | 8+ cores |
| OS | Linux (kernel 5.x+), macOS, Windows (WSL2) | Ubuntu 22.04+ |

> [!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

```bash
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:

```bash
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

| Goal | Section |
|---|---|
| Upload your first document and ask questions | [4.1 Creating a Knowledge Base](#41-creating-a-knowledge-base), [4.2 Uploading Documents](#42-uploading-documents) |
| Connect an LLM provider | [4.7 Configuring LLM Providers](#47-configuring-llm-providers) |
| Build an AI agent workflow | [4.8 Building Agents with Canvas](#48-building-agents-with-canvas) |
| Connect external data sources | [4.9 Using Data Source Connectors](#49-using-data-source-connectors) |
| Use the Python SDK | [4.13 Python SDK](#413-python-sdk) |
| Deploy with GPU acceleration | [2.3 GPU Deployment](#23-gpu-deployment) |

---

## 2. Installation

### 2.1 System Requirements

| Component | CPU Deployment | GPU Deployment |
|---|---|---|
| RAM | 16 GB minimum | 16 GB system + GPU VRAM |
| Disk | 50 GB free | 50 GB free |
| Docker | 24.0+ with Compose v2 | 24.0+ with Compose v2 |
| GPU | Not required | NVIDIA with CUDA 12.x drivers |
| NVIDIA Container Toolkit | Not required | Required for GPU profiles |
| Network | Internet access for image pull | Internet access for image pull |

> [!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.

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

**Step 2:** Review and customize the `.env` file.

```bash
cp .env .env.backup  # optional safety copy
```

Key variables in `.env`:

| Variable | Default | Description |
|---|---|---|
| `SVR_HTTP_PORT` | `9380` | RAGFlow HTTP port |
| `MYSQL_PASSWORD` | `infini_rag_flow` | MySQL root password |
| `MINIO_USER` / `MINIO_PASSWORD` | `rag_flow` / `infini_rag_flow` | MinIO credentials |
| `ELASTIC_PASSWORD` | `infini_rag_flow` | Elasticsearch password |
| `REDIS_PASSWORD` | `infini_rag_flow` | Redis password |
| `STACK_VERSION` | `8.11.3` | Elasticsearch version |
| `MEM_LIMIT` | `8073741824` | Memory limit for ES |
| `ES_PORT` | `1200` | Elasticsearch port |
| `MINIO_PORT` | `9000` | MinIO API port |
| `MINIO_CONSOLE_PORT` | `9001` | MinIO console port |
| `REDIS_PORT` | `6379` | Redis port |
| `SANDBOX_EXECUTOR_MANAGER_PORT` | `9385` | Sandbox port |
| `API_PROXY_SCHEME` | `python` | Nginx routing: `python`, `go`, or `hybrid` |

**Step 3:** Start with CPU + Elasticsearch profiles.

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

**Step 4:** Verify all services are healthy.

```bash
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](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) and verify:

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

**Start with GPU profile:**

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

To use Text Embeddings Inference (TEI) with GPU:

```bash
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:

| Engine | Profile | Notes |
|---|---|---|
| Elasticsearch | `elasticsearch` | Default, most mature |
| OpenSearch | `opensearch` | AWS-compatible alternative |
| Infinity | `infinity` | High-performance vector DB |
| OceanBase | `oceanbase` | Distributed SQL+vector |
| SeekDB | `seekdb` | Lightweight option |

Example with OpenSearch:

```bash
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):

```bash
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):

```bash
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:

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

**Download dependencies:**

```bash
python download_deps.py
```

For users in China, use mirror sources:

```bash
python download_deps.py --china-mirrors
```

**Build the Docker image:**

```bash
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):

```bash
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:

| Flag | Description |
|---|---|
| `--disable-webserver` | Disable nginx and ragflow_server |
| `--disable-taskexecutor` | Disable document parsing task executors |
| `--disable-datasync` | Disable data source sync workers |
| `--enable-mcpserver` | Enable MCP server |
| `--enable-adminserver` | Enable admin server (port 9381) |
| `--init-superuser` | Initialize superuser account on startup |
| `--workers=N` | Number of task executor workers (default: 1) |
| `--consumer-no-beg=N` | Task executor range start |
| `--consumer-no-end=N` | Task executor range end |
| `--host-id=STRING` | Unique host identifier |
| `--mcp-host` | MCP server bind host |
| `--mcp-port` | MCP server bind port |
| `--mcp-base-url` | MCP server base URL |
| `--mcp-mode` | MCP mode: `self-host` or `host` |
| `--mcp-host-api-key` | API key for self-host MCP mode |
| `--no-transport-sse-enabled` | Disable SSE transport for MCP |
| `--no-transport-streamable-http-enabled` | Disable streamable HTTP transport for MCP |
| `--no-json-response` | Disable JSON response format for MCP |

### 2.9 Post-Installation Verification

Run through this checklist after installation:

1. **All containers healthy:**
   ```bash
   docker compose ps
   ```

2. **Web UI accessible:**
   ```
   http://localhost:9380
   ```

3. **API responding:**
   ```bash
   curl http://localhost:9380/v1/system/status
   ```

4. **System config endpoint:**
   ```bash
   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:
```bash
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:

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

### 3.2 Common Configuration Scenarios

**Change the HTTP port:**

```env
SVR_HTTP_PORT=8080
```

**Set a secure MySQL password:**

```env
MYSQL_PASSWORD=your_strong_password_here
```

**Switch document engine to OpenSearch:**

```env
DOC_ENGINE=opensearch
OPENSEARCH_PASSWORD=your_opensearch_password
```

**Enable user registration (or disable it):**

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

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

```env
DISABLE_PASSWORD_LOGIN=true
```

**Configure an HTTP proxy** for outbound LLM API calls:

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

**Set the compute device:**

```env
DEVICE=cpu    # or cuda for GPU
```

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

```env
EMBEDDING_BATCH_SIZE=16
```

**Enable document encryption:**

```env
RAGFLOW_CRYPTO_ENABLED=true
RAGFLOW_CRYPTO_ALGORITHM=aes-256-cbc
```

**Adjust thread pool size:**

```env
THREAD_POOL_MAX_WORKERS=128
```

**Set file upload limits:**

```env
MAX_FILE_NUM_PER_USER=0    # 0 = unlimited
```

**Configure the sandbox:**

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

**Set nginx API proxy scheme:**

```env
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:

```env
CHUNK_FEEDBACK_ENABLED=true
CHUNK_FEEDBACK_WEIGHTING=relevance
```

### 3.4 Logging

Control log verbosity:

```env
LOG_LEVELS=INFO    # DEBUG, INFO, WARNING, ERROR
```

### 3.5 Nginx API Routing

The `API_PROXY_SCHEME` variable controls how nginx routes API traffic:

| Value | Behavior |
|---|---|
| `python` | All API traffic to Python (Flask/Quart) backend on port 9380 |
| `go` | All API traffic to Go (Gin) backend |
| `hybrid` | Routes split between Python and Go backends |

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](#44-document-parsing-methods)).
   - **Parser Configuration**: Adjust chunk size, overlap, and method-specific settings.
5. Click **Save**.

**Via API:**

```bash
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:**

```bash
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:**

```bash
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:**

```bash
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:**

```bash
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:

| Method | Best For | Description |
|---|---|---|
| **Naive** | General documents | Standard text splitting with configurable chunk size and overlap |
| **QA** | FAQ-style content | Extracts question-answer pairs as individual chunks |
| **Manual** | Pre-structured docs | Uses document headings/sections as chunk boundaries |
| **Table** | Spreadsheets, CSV | Preserves table structure in chunks |
| **Paper** | Academic papers | Understands paper structure (abstract, sections, references) |
| **Book** | Long-form books | Chapter-aware chunking |
| **Laws** | Legal documents | Article/section-aware chunking |
| **Presentation** | Slides (PPTX) | Slide-by-slide chunking |
| **One** | Short documents | Entire document as a single chunk |
| **Knowledge Graph** | Entity-rich content | Extracts entities and relationships for GraphRAG |
| **Tag** | Labeled content | Tag-based chunking |
| **Email** | Email messages | Email-structure-aware chunking |
| **Title Chunker** | Heading-structured docs | Splits on headings/titles |
| **Token Chunker** | Any text | Fixed token-count chunks |

**External parsers:**

| Parser | Setup | Description |
|---|---|---|
| **DeepDoc** | Built-in | OCR + layout + table recognition (ONNX models) |
| **MinerU** | External service | Advanced PDF parsing |
| **Docling** | `USE_DOCLING=true` | IBM's document understanding |
| **PaddleOCR** | External API | OCR for images and scanned documents |

### 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:

```bash
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:**

```bash
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:**

```bash
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):

```bash
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:**

```bash
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):

```bash
# 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:**

```bash
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:**

```bash
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:**

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

**List your configured models:**

```bash
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:**

| Category | Components |
|---|---|
| **Flow Control** | Begin, Switch, Loop, Iteration, Iteration Start From, Categorize, Variable Assigner, Variable Aggregator |
| **LLM/AI** | Message, Rewrite Question, Extractor, Agent (with tools), MCP tool |
| **Data** | Retrieval, Code, ExeSQL, Parser, Doc Generator, Invoke |
| **Search** | DuckDuckGo, Google, Google Scholar, Bing, Searxng, Tavily, Tavily Extract, Wikipedia, Yahoo Finance, WenCai, PubMed, GitHub, arXiv, Crawler |
| **Communication** | Email, User Fill Up |
| **Text Processing** | List Operations, String Transform, Data Operations, Token Chunker, Title Chunker, Tokenizer |

**Using templates:**

```bash
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:**

```bash
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):**

```bash
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:**

```bash
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:**

| Category | Connectors |
|---|---|
| **Collaboration** | Confluence, Jira, Slack, Discord, Notion, Asana, Airtable, DingTalk AI Table |
| **Cloud Storage** | Google Drive, Dropbox, Box, Azure Blob (SAS + SPN), S3/MinIO |
| **Email** | Gmail, IMAP |
| **Code** | GitHub, Bitbucket |
| **Other** | WebDAV, RDBMS (MySQL/PostgreSQL), Web Crawl, Zendesk, SearXNG |

**Create a connector:**

```bash
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:**

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

**Resume a paused connector:**

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

**Rebuild a connector** (re-sync all data):

```bash
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:**

```bash
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:**

```bash
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:

```bash
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:

| Flag | Description | Default |
|---|---|---|
| `--base-url` | RAGFlow server URL | Required |
| `--host` | Bind host | `0.0.0.0` |
| `--port` | Bind port | `9382` |
| `--mode` | `self-host` (single tenant) or `host` (multi-tenant) | Required |
| `--api-key` | API key (required for `self-host` mode) | — |
| `--transport-sse-enabled` / `--no-transport-sse-enabled` | Enable SSE transport | Enabled |
| `--transport-streamable-http-enabled` / `--no-transport-streamable-http-enabled` | Enable streamable HTTP | Enabled |
| `--json-response` / `--no-json-response` | JSON response format | Enabled |

**Manage MCP server configurations in RAGFlow:**

```bash
# 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:**

```bash
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:**

```bash
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:**

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

**CLI benchmark tool:**

```bash
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:**

```bash
pip install ragflow-sdk
```

**Basic usage:**

```python
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-core-usage).

### 4.14 Langfuse Observability Integration

RAGFlow integrates with Langfuse for LLM observability and tracing.

**Set up Langfuse:**

```bash
# 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:

```bash
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:**

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

**Register:**

```bash
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:**

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

**Get tenant info:**

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

**Reset password (CLI):**

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

**Reset email (CLI):**

```bash
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:

```bash
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:**

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

**Layout recognition:**

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

**Table structure recognition:**

```bash
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:
   ```bash
   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:
   ```bash
   curl -X POST http://localhost:9380/v1/mcp/export \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -o mcp_backup.json
   ```
2. Import on another instance:
   ```bash
   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:
   ```bash
   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:
   ```json
   {
     "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:
   ```bash
   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:
   ```bash
   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:
   ```bash
   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:
   ```env
   DOC_ENGINE=opensearch
   OPENSEARCH_PASSWORD=secure_password
   ```
3. Start with OpenSearch profile:
   ```bash
   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`:
   ```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:
   ```env
   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:
   ```bash
   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:
   ```bash
   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:**

```bash
# 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:
   ```bash
   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:**

```python
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:
```bash
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](#48-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.

---

_Generated May 2026 from infiniflow/ragflow at 6712b50. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._