Skill: openlark/open-ragflow (version 1.0.0)

--- name: open-ragflow description: RAGFlow open-source Retrieval-Augmented Generation (RAG) engine — deployment, configuration, management, and troubleshooting. --- # Open RAGFlow Open-source RAG engine fusing RAG with Agent capabilities. Full-stack: Python backend (Flask), React/TypeScript frontend, Docker-deployed microservices. ## Use Cases - Deploying or self-hosting RAGFlow via Docker Compose or from source - Configuring RAGFlow (LLM providers, API keys, document engines, ports) - Managing knowledge bases, datasets, documents, agents, and chats via RAGFlow CLI - Understanding RAGFlow architecture (DeepDoc, Agent system, RAG pipeline) - Integrating with RAGFlow REST API - Troubleshooting RAGFlow deployment or runtime issues. ## Quick Reference - **Website**: https://ragflow.io - **Cloud**: https://cloud.ragflow.io - **Docs**: https://ragflow.io/docs/dev/ - **Repo**: https://github.com/infiniflow/ragflow - **Discord**: https://discord.gg/NjYzJD3GM3 - **Docker Hub**: `infiniflow/ragflow` - **License**: Apache 2.0 ## When to Use Which Reference - **Deploying / troubleshooting deployment** → [references/deployment.md](references/deployment.md) - **Understanding architecture / components / data flow** → [references/architecture.md](references/architecture.md) - **Using CLI to manage datasets, agents, models** → [references/cli-reference.md](references/cli-reference.md) ## Prerequisites - CPU >= 4 cores, RAM >= 16 GB, Disk >= 50 GB - Docker >= 24.0.0 & Docker Compose >= v2.26.1 - `vm.max_map_count` >= 262144 (Linux, for Elasticsearch) - gVisor: optional, only needed for the code executor (sandbox) feature ## Docker Deployment (Quick Start) ```bash git clone https://github.com/infiniflow/ragflow.git cd ragflow/docker docker compose -f docker-compose.yml up -d docker logs -f docker-ragflow-cpu-1 # wait for the banner, then login # Open http://YOUR_SERVER_IP in browser ``` Configure LLM API keys in `docker/service_conf.yaml.template` under `user_default_llm`, then restart: ```bash docker compose -f docker-compose.yml up -d ``` ### Chinese Mirror Images If Docker Hub is slow: - Huawei Cloud: `swr.cn-north-4.myhuaweicloud.com/infiniflow/ragflow` - Alibaba Cloud: `registry.cn-hangzhou.aliyuncs.com/infiniflow/ragflow` Set HuggingFace mirror if needed: `HF_ENDPOINT=https://hf-mirror.com` in `docker/.env`. ## Key Configuration Files | File | Scope | |------|-------| | `docker/.env` | Environment variables: `SVR_HTTP_PORT`, `MYSQL_PASSWORD`, `MINIO_PASSWORD`, `DOC_ENGINE`, `RAGFLOW_IMAGE`, `HF_ENDPOINT` | | `docker/service_conf.yaml.template` | Backend services: LLM factory, API keys, embedding/rerank/ASR/TTS models | | `docker/docker-compose.yml` | Full stack orchestration | | `docker/docker-compose-base.yml` | Infrastructure services only (dev mode) | ## Post-Deployment LLM Setup 1. Log in via browser 2. Edit `docker/service_conf.yaml.template`: ```yaml user_default_llm: factory: "OpenAI" # or "DeepSeek", "Gemini", etc. [REDACTED_SECRET]" base_url: "https://api.openai.com/v1/" ``` 3. Run `docker compose -f docker-compose.yml up -d` to apply. ## CLI Quick Reference All CLI commands end with `;`. Full reference: [references/cli-reference.md](references/cli-reference.md). ```bash # Datasets LIST DATASETS; CREATE DATASET 'my_kb' WITH EMBEDDING 'text-embedding-ada-002' PARSER 'pdf'; DROP DATASET 'my_kb'; LIST FILES OF DATASET 'my_kb'; # Documents IMPORT '/path/to/doc.pdf' INTO DATASET 'my_kb'; PARSE DATASET 'my_kb' SYNC; PARSE DATASET 'my_kb' ASYNC; # Search SEARCH 'What is RAG?' ON DATASETS 'my_kb'; # Models CREATE MODEL PROVIDER 'openai' 'sk-...'; SET DEFAULT LLM 'gpt-4'; LIST MODEL PROVIDERS; LIST DEFAULT MODELS; # Agents & Chats LIST AGENTS; LIST CHATS; CREATE CHAT 'my_session'; DROP CHAT 'my_session'; # Connection PING; SHOW CURRENT USER; ``` ## Switching Doc Engine (Elasticsearch → Infinity) ```bash docker compose -f docker/docker-compose.yml down -v # WARNING: clears data # Edit docker/.env: set DOC_ENGINE=infinity docker compose -f docker-compose.yml up -d ``` Infinity is lighter weight but Linux/arm64 is not officially supported. ## Architecture at a Glance ``` Web UI (React+TS+vitejs+shadcn) → Flask API (/api/) → RAG Core (/rag/) + Agent (/agent/) ↓ Infrastructure: MySQL + Elasticsearch/Infinity + Redis + MinIO ``` - **Backend** (`/api/`): Flask blueprints — kb, dialog, document, canvas, file, user - **RAG Core** (`/rag/`): DeepDoc parsing, LLM/embedding/rerank abstractions, chunking, GraphRAG - **Agent** (`/agent/`): Canvas-based workflow builder with components (LLM, Retrieval, Code Executor, MCP, Search, SQL) - **Frontend** (`/web/`): React 18 + TypeScript + Vite See [references/architecture.md](references/architecture.md) for detailed component breakdown. ## Development from Source ```bash git clone https://github.com/infiniflow/ragflow.git && cd ragflow uv sync --python 3.12 && uv run python3 download_deps.py docker compose -f docker/docker-compose-base.yml up -d # Add to /etc/hosts: 127.0.0.1 es01 infinity mysql minio redis sandbox-executor-manager source .venv/bin/activate && export PYTHONPATH=$(pwd) bash docker/launch_backend_service.sh # Separate terminal: cd web && npm install && npm run dev ``` ## Troubleshooting Quick Reference | Problem | Fix | |---------|-----| | `network abnormal` browser error | Wait for Docker logs to show the RAGFlow banner — server is initializing | | Docker pull timeout in China | Use `RAGFLOW_IMAGE` mirrors (Huawei Cloud / Alibaba Cloud) | | HuggingFace unreachable | `export HF_ENDPOINT=https://hf-mirror.com` | | ARM64 platform | Build Docker image from source (no official ARM64 image) | | Port conflict | Change `80:80` to `<PORT>:80` in `docker-compose.yml` | | Elasticsearch exits with 137 | Increase Docker memory allocation | | `vm.max_map_count` too low | `sudo sysctl -w vm.max_map_count=262144` | ## API & SDK - REST API: `http://SERVER_IP/api/` — Swagger docs at `/api/docs` - Python SDK: available in `sdk/python/` - CLI client: `python admin/client/ragflow_cli.py <command>` - Guide: [https://ragflow.io/docs/dev/](https://ragflow.io/docs/dev/)


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)