RAGFlow Administrator & Developer Guide

1. Architecture Overview

1.1 System Architecture

RAGFlow is an open-source Retrieval-Augmented Generation engine built on deep document understanding. The system employs a dual-language architecture that separates concerns across Python and Go runtimes, backed by a React-based frontend and orchestrated through Docker Compose.

The platform ingests documents, parses them with vision-based OCR and layout recognition (DeepDoc), chunks the content intelligently, generates vector embeddings via configurable LLM providers, stores those vectors in a pluggable document engine, and serves retrieval-augmented answers with source citations.

1.2 Dual-Language Design

Python stack handles document processing, RAG pipeline execution, and the primary API server:

Go stack provides a newer API server, admin server, CLI client, and high-performance tokenization:

C++ binding (internal/cpp/): A tokenizer built on DARTS double-array trie, Snowball stemmer, OpenCC (simplified/traditional Chinese conversion), and RE2 regex. Compiled to a static library librag_tokenizer_c_api.a and linked into the Go binary via CGO.

Important

The Go server is a newer addition that runs alongside the Python server. Both share the same MySQL database, Redis cache, MinIO storage, and document engine. The Python server remains the primary runtime for document processing and the task executor pipeline.

1.3 Data Flow

User uploads document
    │
    ▼
API Server (Python/Quart, port 9380)
    │
    ├── Stores raw file → MinIO (object storage)
    ├── Creates task record → MySQL (metadata DB)
    │
    ▼
Task Executor picks up task
    │
    ├── DeepDoc parses document
    │   ├── OCR (PaddleOCR/ONNX)
    │   ├── Layout recognition (ONNX models)
    │   └── Table structure recognition
    │
    ├── Chunking (naive, QA, resume, table, etc.)
    ├── Embedding via configured LLM provider
    │
    ▼
Document Engine stores vectors + text
    (Elasticsearch | OpenSearch | Infinity | OceanBase)
    │
    ▼
User queries → Retrieval → Reranking → LLM generates answer with citations

1.4 Infrastructure Services

All backing services run as Docker containers defined in docker/docker-compose-base.yml:

Docker Compose profiles control which services start:

1.5 Frontend Architecture

The web UI lives in web/ and is built with:

• React 18 with TypeScript
• Vite build system
• Tailwind CSS + Ant Design + Radix UI components
• XYFlow for agent canvas visualization
• i18next with 16 locale files for internationalization
• SPA with client-side routing

2. System Requirements

2.1 Hardware Requirements

Note

Document parsing with DeepDoc's OCR and layout recognition is CPU-intensive. The task executor's ONNX models benefit significantly from additional CPU cores. GPU mode accelerates embedding generation and OCR processing.

2.2 Software Requirements

2.3 Build System

The build.sh script orchestrates the full build:

1. C++ static library: cmake + make produces librag_tokenizer_c_api.a
2. Go binaries: CGO_ENABLED=1 compiles server_main and admin_server, linking the C++ tokenizer

# Full build sequence
./build.sh

2.4 Network Ports

3. Configuration Reference

3.1 Configuration Architecture

RAGFlow uses a layered configuration system:

1. YAML config: conf/service_conf.yaml (primary), overridden by conf/local.service_conf.yaml (gitignored)
2. Environment variables: Override YAML values; sourced from .env for Docker Compose or shell environment
3. Docker Compose .env: Sets container-level variables (docker/.env)
4. Runtime settings: Some values configurable via admin API at runtime

The configuration loader (common/config_utils.py) reads YAML first, then applies environment variable overrides. Sensitive values are automatically masked in log output.

Tip

Create conf/local.service_conf.yaml for local overrides that should not be committed. This file takes precedence over conf/service_conf.yaml for any keys it defines.

3.2 Core Settings (common/settings.py)

3.3 API Server Settings (api/apps/__init__.py)

3.4 LLM Settings (rag/llm/)

3.5 Task Executor Settings (rag/svr/task_executor.py)

3.6 Sandbox Settings

Executor Manager (agent/sandbox/executor_manager/core/):

Warning

The sandbox executor manager container mounts docker.sock from the host. This grants it the ability to create and manage sibling containers. In production, restrict access to the sandbox service and consider network policies to limit container escape risk.

3.7 MCP Server Settings (mcp/server/server.py)

3.8 OCR & Vision Settings (deepdoc/vision/)

3.9 GraphRAG Settings (rag/graphrag/)

3.10 Agent Settings (agent/component/)

3.11 HTTP Client Settings (common/http_client.py)

3.12 Document Parsing Settings

3.13 Chunk Feedback Settings (api/db/services/)

3.14 OceanBase Settings (common/doc_store/)

3.15 Infinity Settings (common/doc_store/)

3.16 Superuser Settings (api/db/init_data.py)

Caution

The default superuser credentials are [email removed] / admin. Change these immediately after first deployment. Use the --init-superuser entrypoint flag or the reset-password CLI command to update credentials.

3.17 Logging Settings (common/log_utils.py)

Log levels can also be adjusted at runtime via the admin API (PUT /log_levels).

3.18 Data Source Connector Settings (common/data_source/config.py)

Global connector settings:

Confluence:

Google Drive / Gmail:

Jira:

Slack:

Discord:

Notion:

Dropbox:

Box:

GitHub / Bitbucket:

Airtable:

Asana:

IMAP (Email):

WebDAV:

RDBMS:

DingTalk:

Zendesk:

Web Connector:

Firecrawl:

3.19 Azure Storage Settings (rag/utils/)

3.20 Miscellaneous Settings

3.21 YAML Configuration (conf/service_conf.yaml)

The primary YAML configuration file contains structured settings for all backing services. Key sections:

# Database
mysql:
  host: mysql
  port: 3306
  user: root
  password: ...
  database: ragflow

# Redis
redis:
  host: redis
  port: 6379
  password: ...

# MinIO
minio:
  host: minio:9000
  access_key: ...
  secret_key: ...

# Elasticsearch
es:
  host: es01:9200
  scheme: http

# Storage
storage:
  type: MINIO

Local overrides go in conf/local.service_conf.yaml. The Go stack reads the same YAML via internal/server/config.go.

4. Deployment & Scaling

4.1 Docker Compose Deployment

The standard deployment uses Docker Compose with profile selection:

# Default deployment with Elasticsearch (CPU mode)
docker compose --profile cpu --profile elasticsearch up -d

# GPU mode with OpenSearch
docker compose --profile gpu --profile opensearch up -d

# With Infinity vector database
docker compose --profile cpu --profile infinity up -d

# With OceanBase
docker compose --profile cpu --profile oceanbase up -d

# Enable sandbox for agent code execution
docker compose --profile cpu --profile elasticsearch --profile sandbox up -d

# Enable TEI for local embeddings
docker compose --profile cpu --profile elasticsearch --profile tei-cpu up -d

4.2 Entrypoint Configuration

The Docker entrypoint (docker/entrypoint.sh) starts nginx + ragflow_server (Python) + task executors + data source sync. Control startup behavior with flags:

# Example: Run with 4 task executors, MCP server enabled, admin server enabled
docker run ... ragflow --workers=4 --enable-mcpserver --enable-adminserver

4.3 Scaling Task Executors

Task executors are the document processing workers. Scale them based on document processing load:

# Run 4 workers in a single container
docker compose up -d  # with --workers=4 in the entrypoint command

# Or run separate worker containers with range-based IDs
# Container 1: workers 0-3
docker run ... ragflow --disable-webserver --consumer-no-beg=0 --consumer-no-end=3

# Container 2: workers 4-7
docker run ... ragflow --disable-webserver --consumer-no-beg=4 --consumer-no-end=7

Tip

Separate the API server from task executors in production. Run one container with --disable-taskexecutor for the API and dedicated containers with --disable-webserver for workers. This isolates document processing load from API responsiveness.

4.4 Kubernetes Deployment (Helm)

RAGFlow provides a Helm chart in helm/ with 13 templates:

# Install with default values
helm install ragflow ./helm

# Install with custom values
helm install ragflow ./helm -f custom-values.yaml

# Upgrade
helm upgrade ragflow ./helm -f custom-values.yaml

The Helm chart includes templates for:

Key values.yaml sections cover replica counts, resource limits, image tags, persistence, ingress rules, and all backing service connection strings.

4.5 Document Engine Selection

Choose the document engine based on your scale and requirements:

Switch engines by setting DOC_ENGINE in .env and activating the corresponding Docker Compose profile.

4.6 nginx Configuration

The bundled nginx (docker/nginx/) serves as a reverse proxy:

• Routes /v1/ API requests to the Python API server (port 9380)
• Serves the React frontend static files
• Handles WebSocket upgrades for SSE streaming
• Applies upload size limits and proxy timeouts

5. Operations

5.1 Superuser Management

Initialize superuser on first boot:

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

Reset password via CLI:

# Using the built-in management command
python -m api.utils.commands reset-password \
  --email [email removed] \
  --new-password NEW_PASSWORD \
  --password-confirm NEW_PASSWORD

Reset email:

python -m api.utils.commands reset-email \
  --email [email removed] \
  --new-email [email removed] \
  --email-confirm [email removed]

5.2 RAGFlow CLI

The Go-based CLI (ragflow_cli) provides an interactive REPL and single-command execution:

# Interactive admin mode
./ragflow_cli -h 127.0.0.1 -p 9381 --admin

# Interactive user mode with config file
./ragflow_cli -f rf.yml

# Single command execution
./ragflow_cli -h 127.0.0.1 -p 9381 --admin -w admin "list users"

CLI arguments:

CLI config file (rf.yml):

host: "127.0.0.1:9380"
api_token: "ragflow-xxxxxxxxxxxx"
user_name: "[email removed]"
password: "password"

5.3 Health Checks

5.4 Backup and Recovery

MySQL metadata:

# Backup
docker exec mysql mysqldump -u root -p ragflow > ragflow_backup.sql

# Restore
docker exec -i mysql mysql -u root -p ragflow < ragflow_backup.sql

MinIO object storage:

# Use mc (MinIO client) for backup
mc mirror minio/ragflow /backup/minio-ragflow/

Elasticsearch indices:

# Create snapshot repository
curl -X PUT "localhost:9200/_snapshot/backup" -H 'Content-Type: application/json' -d '{
  "type": "fs",
  "settings": { "location": "/usr/share/elasticsearch/backup" }
}'

# Create snapshot
curl -X PUT "localhost:9200/_snapshot/backup/snapshot_1"

5.5 Log Management

RAGFlow logs are written to stdout/stderr by default (Docker-captured). Key log sources:

Runtime log level adjustment:

# Get current log levels (admin API)
curl -X GET http://localhost:9381/log_levels

# Set log level
curl -X PUT http://localhost:9381/log_levels \
  -H 'Content-Type: application/json' \
  -d '{"logger": "root", "level": "DEBUG"}'

5.6 Monitoring with Kibana

Enable the Kibana profile for Elasticsearch monitoring:

docker compose --profile elasticsearch --profile kibana up -d

Access Kibana at http://localhost:5601. Use it to monitor index health, shard allocation, query performance, and document counts.

6. Performance

6.1 Task Executor Tuning

6.2 OCR Optimization

6.3 Elasticsearch Tuning

For production Elasticsearch deployments:

# docker-compose override
es01:
  environment:
    - "ES_JAVA_OPTS=-Xms4g -Xmx4g"
    - "discovery.type=single-node"
    - "xpack.security.enabled=false"
  ulimits:
    memlock:
      soft: -1
      hard: -1

Key index settings to consider:

• Increase number_of_replicas for read scaling
• Adjust refresh_interval for write-heavy workloads (e.g., during bulk ingestion, set to 30s)
• Configure merge.scheduler.max_thread_count based on available I/O

6.4 Redis Cache Strategy

Redis is configured with maxmemory 128mb and allkeys-lru eviction. For larger deployments:

• Increase maxmemory proportionally with active user count
• Monitor eviction rates via INFO stats
• Consider Redis Cluster for horizontal scaling

6.5 Thread Pool Configuration

The global thread pool (THREAD_POOL_MAX_WORKERS=128) handles async operations across the Python stack. Adjust based on:

• Number of concurrent API requests
• Task executor parallelism
• Data source sync concurrency

6.6 LLM Call Optimization

7. Security

7.1 Authentication Architecture

RAGFlow supports multiple authentication methods:

OAuth2/OIDC configuration structure:

# OIDC (auto-discovery)
{
    "type": "oidc",
    "issuer": "https://your-idp.com/oidc",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "redirect_uri": "https://your-ragflow.com/v1/user/oauth/callback/<channel>"
}

# OAuth2 (manual endpoints)
{
    "type": "oauth2",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "authorization_url": "https://your-idp.com/oauth/authorize",
    "token_url": "https://your-idp.com/oauth/token",
    "userinfo_url": "https://your-idp.com/oauth/userinfo",
    "redirect_uri": "https://your-ragflow.com/v1/user/oauth/callback/<channel>"
}

Warning

The OIDC implementation has a known community-reported issue (#14066). Test OIDC flows thoroughly after configuration changes, particularly around token validation and callback handling.

7.2 Admin Authentication

The admin server uses JWT-based session management:

1. Login via POST /login with admin credentials
2. Receive JWT token
3. Include token in subsequent requests

Default credentials: [email removed] / admin. The admin API provides RBAC with:

• Role creation and management (/roles)
• Permission assignment (/roles/:role_name/permission)
• User-role binding (/users/:username/role)

7.3 Field Encryption

Enable field-level encryption for sensitive data at rest:

RAGFLOW_CRYPTO_ENABLED=true
RAGFLOW_CRYPTO_ALGORITHM=aes-256-cbc
RAGFLOW_CRYPTO_KEY=your-32-byte-base64-key

When enabled, designated database fields are encrypted before storage and decrypted on read.

7.4 Network Security

CORS: The Python API server sets Access-Control-Allow-Origin: * by default (common/connection_utils.py). For production, restrict this to your frontend domain.

MySQL TLS: MySQL is configured to require TLS 1.2/1.3 with custom authentication plugin.

Redis: Password-protected via service_conf.yaml. Uses maxmemory with allkeys-lru to prevent OOM.

Caution

The default CORS configuration (Access-Control-Allow-Origin: *) allows any origin to make authenticated API requests. In production deployments, restrict CORS to your specific frontend domain(s).

7.5 Sandbox Security

The sandbox executor provides isolated code execution for agent components:

Sandbox providers:

• Self-managed: Docker-based, runs on the same host. Requires docker.sock mount.
• Aliyun OpenSandbox: Cloud-based alternative. Requires ALIYUN_ACCESS_KEY_ID and ALIYUN_ACCESS_KEY_SECRET.

7.6 API Token Management

API tokens are managed per-user via the admin API:

# Generate API key for a user
POST /admin/users/:username/keys

# List user's API keys
GET /admin/users/:username/keys

# Revoke a specific key
DELETE /admin/users/:username/keys/:token

7.7 Password Security

Passwords are encrypted client-side using RSA before transmission. The server validates password complexity via STRONG_TEST_COUNT (default 8).

7.8 Registration Control

8. Developer Internals

8.1 Module Reference

8.1.1 Root Level (8 files, 23K chars)

Top-level scripts including build.sh, run_tests.py, download_deps.py, and pyproject.toml. The build script orchestrates C++ compilation and Go binary builds.

8.1.2 api/ — Python API Server (5 files, 9K chars)

8.1.3 api/apps/ — API Route Handlers (17 files, 292K chars)

8.1.4 api/apps/services/ — Business Logic Services (5 files, 70K chars)

Service layer between route handlers and database operations.

8.1.5 api/db/ — Database Layer (7 files, 104K chars)

8.1.6 api/db/services/ — Database Services (25 files, 420K chars)

The largest module group by character count. Contains the core business logic for:

8.1.7 api/utils/ — API Utilities (17 files, 117K chars)

8.1.8 api/common/ — API Common (3 files, 4K chars)

Shared constants, error codes, and utility functions for the API layer.

8.1.9 rag/ — RAG Pipeline Core (4 files, 25K chars)

8.1.10 rag/app/ — Document Parsers (15 files, 275K chars)

8.1.11 rag/llm/ — LLM Integration (8 files, 235K chars)

8.1.12 rag/svr/ — Server Processes (4 files, 125K chars)

8.1.13 rag/nlp/ — NLP Utilities (7 files, 112K chars)

Tokenization, query parsing, language detection, and text normalization.

8.1.14 rag/graphrag/ — Graph RAG (5 + 11 files, 66K + 95K chars)

8.1.15 rag/utils/ — RAG Utilities (20 files, 251K chars)

8.1.16 rag/prompts/ — Prompt Templates (3 files, 38K chars)

System prompts for RAG, GraphRAG, and agent components.

8.1.17 rag/advanced_rag/ — Advanced RAG (2 files, 6.5K chars)

Advanced retrieval strategies and RAPTOR hierarchical summarization.

8.1.18 rag/flow/ — Flow Engine (4 files, 13K chars)

Data flow pipeline definitions, chunker abstractions, and parser orchestration.

8.1.19 deepdoc/ — Document Understanding Engine (1 file, 695 chars)

Package root for the DeepDoc document analysis engine.

8.1.20 deepdoc/vision/ — Vision Models (10 files, 138K chars)

8.1.21 deepdoc/parser/ — Document Parsers (16 files, 251K chars)

8.1.22 agent/ — Agent Framework (4 files, 42K chars)

Agent pipeline execution, canvas DSL interpretation, and component orchestration.

8.1.23 agent/component/ — Agent Components (22 files, 184K chars)

8.1.24 agent/templates/ — Agent Templates (25 files, 1MB+)

Pre-built agent DSL templates for common use cases (HR, customer service, research, etc.).

8.1.25 agent/sandbox/ — Sandbox System

8.1.26 agent/plugin/ — Plugin System (4 files, 3K chars)

Embedded plugin framework with LLM tool definitions.

8.1.27 common/ — Shared Utilities (24 files, 115K chars)

8.1.28 common/doc_store/ — Document Store Connectors (7 files, 96K chars)

8.1.29 common/data_source/ — Data Source Connectors (30 files, 475K chars)

8.1.30 internal/ — Go Server Internals (2 files, 5K chars)

Go package root and shared types.

8.1.31 internal/router/ — Go HTTP Router (1 file, 13K chars)

Gin router setup with all API route definitions, middleware, and authentication.

8.1.32 internal/handler/ — Go HTTP Handlers (19 files, 173K chars)

Request handlers for knowledge bases, documents, chunks, chats, search, files, memory, LLM management, and sessions.

8.1.33 internal/service/ — Go Business Logic (19 files, 307K chars)

Service layer with business logic for all Go API operations.

8.1.34 internal/dao/ — Go Data Access (28 files, 143K chars)

Data access objects for MySQL operations via GORM.

8.1.35 internal/entity/ — Go Entity Models (29 files, 86K chars)

Request/response structures and database entity definitions.

8.1.36 internal/admin/ — Go Admin Server (5 files, 96K chars)

Admin router, handlers, middleware, and RBAC enforcement for the Go admin API.

8.1.37 internal/cli/ — Go CLI (17 files, 315K chars)

CLI implementation with the context engine for intelligent command parsing and execution.

8.1.38 internal/cpp/ — C++ Tokenizer (19 files, 238K chars)

High-performance tokenizer with DARTS trie, Snowball stemmer, OpenCC Chinese conversion, and RE2 regex. Compiled to librag_tokenizer_c_api.a.

8.1.39 internal/cache/ — Go Cache Layer (1 file, 25K chars)

Redis-based caching with key management and TTL policies.

8.1.40 internal/engine/ — Go Document Engine (2 + 4 files)

8.1.41 internal/storage/ — Go Storage (6 files, 55K chars)

MinIO and S3-compatible storage operations from the Go stack.

8.1.42 internal/tokenizer/ — Go Tokenizer Binding (2 files, 27K chars)

CGO binding to the C++ tokenizer library.

8.1.43 internal/binding/ — Go C Binding (1 file, 8K chars)

Low-level CGO interface to librag_tokenizer_c_api.a.

8.1.44 internal/common/ — Go Common (5 files, 13K chars)

Shared Go utilities, error handling, and constants.

8.1.45 internal/utility/ — Go Utilities (10 files, 40K chars)

Path resolution, string manipulation, and helper functions.

8.1.46 internal/logger/ — Go Logging (1 file, 4K chars)

Structured logging via Zap with runtime level control.

8.1.47 internal/server/ — Go Server Config (3 files, 37K chars)

Server initialization, configuration loading from YAML and environment, and MinIO/Redis/MySQL connection setup.

8.1.48 memory/ — Memory System

8.1.49 mcp/ — MCP Integration

8.1.50 sdk/python/ — Python SDK (1 file, 674 chars)

SDK package initialization. Full SDK modules in sdk/python/ragflow_sdk/modules/.

8.1.51 conf/ — Configuration (9 files, 252K chars)

8.1.52 helm/ — Kubernetes Charts (2 + 13 files)

Helm chart root (Chart.yaml, values.yaml) plus 13 templates for K8s deployment.

8.1.53 docker/ — Docker Configuration (8 files, 40K chars)

8.1.54 web/ — Frontend (7 files at root level)

8.1.55 cmd/ — Go Entry Points (3 files, 16K chars)

8.1.56 admin/ — Admin System

8.1.57 tools/ — Utility Tools

8.2 Build from Source

# 1. Clone repository
git clone https://github.com/infiniflow/ragflow.git
cd ragflow

# 2. Build C++ tokenizer + Go binaries
./build.sh

# 3. Install Python dependencies
pip install -r requirements.txt

# 4. Build frontend
cd web && npm install && npm run build && cd ..

# 5. Run development server
python api/ragflow_server.py --debug

Build dependencies:

# Ubuntu/Debian
apt-get install cmake g++ libpcre2-dev golang-go

# The build requires:
# - cmake >= 4.0
# - Go >= 1.24 (module requires 1.25)
# - g++ with C++17/C++23 support
# - libpcre2-dev for PCRE2 regex in tokenizer

8.3 Testing Infrastructure

Test runner flags:

Pre-commit hooks: ruff (lint + format), YAML/JSON validation, merge conflict detection.

Playwright E2E configuration:

9. Integration Points

9.1 MCP Server (Model Context Protocol)

RAGFlow exposes its capabilities via MCP for integration with AI assistants:

# Start MCP server (self-host mode)
python -m mcp.server.server \
  --base-url http://127.0.0.1:9380 \
  --host 127.0.0.1 \
  --port 9382 \
  --mode self-host \
  --api-key ragflow-xxxxxxxxxxxx

# Multi-tenant mode
python -m mcp.server.server \
  --mode host \
  --port 9382

MCP server options:

9.2 Python SDK

from ragflow_sdk import RAGFlow

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

# Create knowledge base
kb = rag.create_dataset("my_kb")

# Upload and parse document
doc = kb.upload_document("document.pdf")
doc.parse()

# Query
results = kb.retrieval("What is the architecture?")

9.3 Langfuse Observability

RAGFlow integrates with Langfuse for LLM observability:

# Set Langfuse API key via API
POST /api/v1/langfuse/api_key
{
  "public_key": "pk-...",
  "secret_key": "sk-...",
  "host": "https://cloud.langfuse.com"
}

Note

The Langfuse integration has a known issue (#14204) where start_generation raises an AttributeError in recent Docker images. Monitor the issue tracker for a fix before relying on this feature in production.

9.4 LLM Provider Configuration

RAGFlow supports dozens of LLM providers defined in conf/llm_factories.json. Add providers via the API:

# Set API key for a provider
POST /api/v1/llm/set_api_key
{
  "llm_factory": "OpenAI",
  "api_key": "sk-..."
}

# Add a custom model
POST /api/v1/llm/add_llm
{
  "llm_factory": "OpenAI",
  "model_name": "gpt-4",
  "model_type": "chat"
}

9.5 Webhook Integration

Agent canvases support webhook-based triggers via the Begin node's webhook configuration. Configure via the canvas settings API.

9.6 Evaluation Framework

RAGFlow includes a built-in evaluation framework for measuring retrieval quality:

# Create evaluation dataset
POST /api/v1/evaluation/dataset/create

# Import test cases
POST /api/v1/evaluation/dataset/{id}/case/import

# Run evaluation
POST /api/v1/evaluation/run/start

# Compare runs
POST /api/v1/evaluation/compare

Benchmark tool for standard datasets:

# MS MARCO benchmark
PYTHONPATH=./test uv run -m benchmark retrieval \
  --dataset ms_marco_v1.1 \
  --kb_id <dataset_id>

# TriviaQA benchmark
PYTHONPATH=./test uv run -m benchmark retrieval \
  --dataset trivia_qa \
  --kb_id <dataset_id>

9.7 ES-to-OceanBase Migration

A dedicated migration tool exists in tools/es-to-oceanbase-migration/:

cd tools/es-to-oceanbase-migration
pip install -e .
es-ob-migrate --help

10. API Reference

10.1 Python API Server Endpoints (port 9380)

Canvas / Agent Endpoints

Chunk Endpoints

Connector Endpoints

Document Endpoints

Evaluation Endpoints

Knowledge Base Endpoints

LLM Management Endpoints

Langfuse Endpoints

MCP Server Management Endpoints

User & Auth Endpoints

Tenant Endpoints

System Endpoints

File Conversion Endpoints

Plugin Endpoints

10.2 Go API Server Endpoints (configurable port)

System

User & Auth

Knowledge Base (Go routes)

Documents (Go routes)

Chunks (Go routes)

LLM (Go routes)

Chat & Conversation (Go routes)

Search (Go routes)

Files (Go routes)

Memory (Go routes)

LLM Providers (Go routes)

Session (Go routes)

10.3 Go Admin Server Endpoints (port 9383)

User Management

Role Management

Service Management

Configuration & Variables

Sandbox Management

License Management

Logging

LLM Providers (Admin)

10.4 Python Admin Server Endpoints (port 9381)

11. Troubleshooting

11.1 Deployment Failures

Error: Container fails to start, version upgrade data not inherited

Cause: Known issue (#13713) with v0.24.0 where deployment fails and previous data is lost during upgrade.

Solution: Back up MySQL data and MinIO storage before upgrading. Use docker compose down (without -v) to preserve volumes. Verify volume mounts match between compose versions.

Prevention: Always snapshot volumes before version upgrades.

Error: docker/entrypoint.sh file can't find service_conf.yaml.template

Cause: Issue #6927 -- the entrypoint expects configuration templates that may be missing in certain build configurations.

Solution: Ensure the Docker image was built completely. Verify conf/service_conf.yaml exists in the container. Rebuild the image if necessary.

Prevention: Use official Docker images from the InfiniFlow registry.

Error: Nightly deployment failures

Cause: Issue #14171 -- automated nightly builds fail due to dependency or infrastructure changes.

Solution: Pin dependency versions in production deployments. Use tagged releases rather than nightly builds.

Prevention: Always use stable tagged releases for production.

Error: Latest Docker image not available, minor bugs remain unfixed

Cause: Issue #14193 -- gap between source fixes and Docker image publication.

Solution: Build from source if you need the latest fixes. Monitor the release schedule for updated images.

Prevention: Subscribe to release notifications on the GitHub repository.

11.2 Document Processing Errors

Error: internal server error while chunking: expected string or bytes-like object

Cause: Issue #6990 -- type mismatch during chunking when document content contains unexpected data types.

Solution: Check the source document for corruption. Try a different parser method. Verify the document encoding is UTF-8.

Prevention: Validate documents before upload. Use the naive parser as a fallback.

Error: Error chunking CV with Resume method

Cause: Issue #6933 -- the Resume parser fails on certain CV formats or structures.

Solution: Try the naive parser instead. Check that the CV is in a supported format (PDF preferred). Verify the document is not password-protected.

Prevention: Pre-process CVs to standard PDF format before uploading.

Error: DeepDoc fails on 1000+ page PDFs with poor image quality

Cause: Issue #14196 -- memory and processing limits for very large documents.

Solution: Split large PDFs into smaller chunks before uploading. Increase OCR_GPU_MEM_LIMIT_MB for GPU deployments. Increase worker memory limits.

Prevention: Set document size limits. Process large documents in segments.

Error: MinerU parsed images are obscured/garbled

Cause: Issue #14197 -- MinerU parser produces degraded image output.

Solution: Switch to DeepDoc's native parser. Verify MinerU server configuration. Check image encoding settings.

Prevention: Test parser output quality before bulk processing.

Error: Document parsing stuck or no progress

Cause: Task executor worker may have died without updating status. Worker heartbeat timeout exceeded.

Solution: Check task executor logs. Restart the worker container. Verify WORKER_HEARTBEAT_TIMEOUT (default 120s) is appropriate for your workloads.

Prevention: Monitor worker heartbeats. Set up health checks on executor processes.

11.3 API and Retrieval Issues

Error: Retrieval API returns 110 timeout

Cause: Issue #6998 -- the retrieval operation completes server-side (200 response logged) but the client times out waiting.

Solution: Increase QUART_RESPONSE_TIMEOUT. Optimize Elasticsearch query performance. Check network latency between client and server.

Prevention: Tune Elasticsearch indices. Set appropriate client-side timeouts.

Error: Shared chat links cannot search knowledge base content but editing page works

Cause: Issue #14115 -- shared links may use different authentication contexts that restrict knowledge base access.

Solution: Verify share link permissions. Check that the shared canvas has proper KB bindings.

Prevention: Test shared links after creation. Verify KB access permissions.

Error: Iteration component only processes first element from Code node

Cause: Issue #14142 -- array output from Code nodes not properly iterated in v0.24.0.

Solution: Ensure the Code node output is properly formatted as a JSON array. Check iteration component configuration.

Prevention: Test iteration flows with multi-element arrays before production deployment.

Error: Incorrect time display in API responses

Cause: Issue #6970 -- RFC 1123 format missing timezone information.

Solution: The issue has been addressed in newer versions. Ensure client-side timezone handling accounts for UTC responses.

Prevention: Always parse API timestamps as UTC.

11.4 Authentication Issues

Error: OIDC authorization broken

Cause: Issue #14066 -- OIDC flow fails during token validation or callback processing.

Solution: Verify OIDC configuration matches the identity provider's settings. Check redirect_uri matches exactly. Verify the issuer URL is accessible and .well-known/openid-configuration returns valid data. Check server logs for JWT validation errors.

Prevention: Test OIDC flow in a non-production environment first. Monitor auth logs.

Important

If OIDC is your sole login method, ensure DISABLE_PASSWORD_LOGIN is NOT set until OIDC is fully verified. Keep password login as a fallback during testing.

Error: Login fails after upgrading

Cause: Database schema changes or session token format changes between versions.

Solution: Clear browser cookies. Verify MySQL migrations completed successfully. Use reset-password CLI command if needed.

Prevention: Run database migrations explicitly during upgrades.

11.5 Integration Issues

Error: Langfuse integration broken -- start_generation AttributeError

Cause: Issue #14204 -- incompatible Langfuse SDK version in the Docker image.

Solution: Check the Langfuse SDK version. Pin to a compatible version. Monitor the issue for an official fix.

Prevention: Test Langfuse integration after image updates.

Error: QA mode recalls in knowledge base but not in agent nodes

Cause: Issue #6982 -- agent nodes may use different retrieval parameters than the knowledge base test interface.

Solution: Verify retrieval parameters (similarity threshold, top-k) match between KB settings and agent node configuration. Check that the correct KB is bound to the agent node.

Prevention: Align retrieval parameters across all access paths.

Error: Session crashes during chat

Cause: Issue #6966 -- session state corruption or memory exhaustion during complex conversations.

Solution: Restart the API server. Check memory usage. Clear the session cache in Redis.

Prevention: Monitor Redis memory usage. Set conversation length limits.

Error: Robot returns garbled/weird responses to basic questions

Cause: Issue #6964 -- LLM configuration issue, wrong model selected, or prompt template corruption.

Solution: Verify the chat model is correctly configured. Check the system prompt. Test the model directly via the LLM provider's API.

Prevention: Validate LLM configuration after setup. Use model testing endpoints.

11.6 Elasticsearch Issues

Error: Elasticsearch cluster yellow/red status

Cause: Unassigned replica shards (yellow) or missing primary shards (red).

Solution: For yellow: expected on single-node. Set number_of_replicas: 0 for single-node deployments. For red: check disk space, node health, and recovery status.

Prevention: Monitor disk space. Use Kibana for proactive alerting.

Error: Elasticsearch out of memory

Cause: Heap size too small for index volume.

Solution: Increase ES_JAVA_OPTS heap allocation. Minimum: set to 50% of container memory, not exceeding 31GB.

Prevention: Size Elasticsearch heap according to index volume. Monitor JVM metrics via Kibana.

11.7 MinIO Issues

Error: File upload fails with connection refused

Cause: MinIO container not running or port mismatch.

Solution: Verify MinIO is running: docker ps | grep minio. Check port mapping matches service_conf.yaml. Verify MinIO access keys.

Prevention: Include MinIO in health check monitoring.

Error: Storage full, uploads rejected

Cause: MinIO disk volume exhausted.

Solution: Expand the storage volume. Remove old/unused files. Check for orphaned objects.

Prevention: Monitor disk usage. Set up alerting at 80% capacity.

11.8 Redis Issues

Error: Cache evictions causing performance degradation

Cause: Redis maxmemory (128MB default) too small for the working set.

Solution: Increase maxmemory in the Redis configuration. Monitor evicted_keys metric.

Prevention: Size Redis memory to match your active user count and session volume.

11.9 Sandbox Issues

Error: Sandbox code execution times out

Cause: SANDBOX_TIMEOUT (default 10s) too short for the operation.

Solution: Increase SANDBOX_TIMEOUT. Check that sandbox base images are pre-pulled. Verify Docker daemon responsiveness.

Prevention: Pre-pull sandbox base images. Size timeout to expected workload.

Error: Sandbox container creation fails

Cause: Docker socket not accessible or Docker daemon out of resources.

Solution: Verify docker.sock is mounted. Check Docker daemon logs. Verify container limits haven't been exceeded.

Prevention: Monitor Docker daemon health. Set container cleanup policies.

11.10 OceanBase Issues

Error: DDL timeout during index creation

Cause: OB_DDL_TIMEOUT (default 60s) exceeded for large table operations.

Solution: Increase OB_DDL_TIMEOUT. Check OceanBase server load.

Prevention: Schedule DDL operations during low-traffic periods.

Error: Metadata creation fails

Cause: Issue #14188 -- error during metadata table operations.

Solution: Check OceanBase connection. Verify table schema. Check server logs for the specific SQL error.

Prevention: Test metadata operations in a staging environment.

11.11 MySQL Issues

Error: Connection refused or authentication failure after upgrade

Cause: MySQL 8.0 authentication plugin changes or configuration drift.

Solution: Verify MySQL credentials in service_conf.yaml. Check that the mysql container is healthy. Verify TLS settings match between server and client.

Prevention: Pin MySQL version in docker-compose. Test connectivity after upgrades.

Error: Database migration fails on startup

Cause: Schema version mismatch between application code and database state.

Solution: Check migration logs. Run migrations manually if needed. Verify MySQL user has DDL privileges.

Prevention: Back up the database before upgrades. Review migration scripts in release notes.

11.12 Build Issues

Error: build.sh fails during C++ compilation

Cause: Missing build dependencies (cmake, g++, libpcre2-dev).

Solution: Install required build tools. On Ubuntu: apt-get install cmake g++ libpcre2-dev. Verify cmake version is 4.0+.

Prevention: Use the provided Dockerfile for consistent build environments.

Error: Go binary build fails with CGO errors

Cause: C++ static library not built or not found.

Solution: Run the C++ build step first. Verify librag_tokenizer_c_api.a exists. Ensure CGO_ENABLED=1 is set.

Prevention: Always run the full build.sh sequence.

11.13 GraphRAG Issues

Error: Graph extraction aborts after repeated errors

Cause: GRAPHRAG_MAX_ERRORS (default 3) threshold reached during entity extraction.

Solution: Increase GRAPHRAG_MAX_ERRORS. Check LLM provider connectivity. Verify the document content is suitable for graph extraction.

Prevention: Monitor extraction logs. Ensure LLM provider has sufficient quota.