RAGFlow

开源的 RAG 引擎，融合了 RAG 与 Agent 能力。全栈架构：Python 后端（Flask）、React/TypeScript 前端、Docker 部署的微服务。

使用场景

• 通过 Docker Compose 或源码自部署或自托管 RAGFlow
• 配置 RAGFlow（LLM 提供商、API 密钥、文档引擎、端口等）
• 使用 RAGFlow CLI 管理知识库、数据集、文档、Agent 和聊天记录
• 理解 RAGFlow 架构（DeepDoc、Agent 系统、RAG 流水线）
• 与 RAGFlow REST API 集成
• 排查 RAGFlow 部署或运行时问题

快速参考

• 官网: https://ragflow.io
• 云服务: https://cloud.ragflow.io
• 文档: https://ragflow.io/docs/dev/
• 代码仓库: https://github.com/infiniflow/ragflow
• Discord 社区: https://discord.gg/NjYzJD3GM3
• Docker Hub: infiniflow/ragflow
• 许可证: Apache 2.0

何时使用哪种参考文档

• 部署 / 排查部署问题 → [references/deployment.md](references/deployment.md)
• 理解架构 / 组件 / 数据流 → [references/architecture.md](references/architecture.md)
• 使用 CLI 管理数据集、Agent、模型 → [references/cli-reference.md](references/cli-reference.md)

前置条件

• CPU ≥ 4 核，内存 ≥ 16 GB，磁盘空间 ≥ 50 GB
• Docker ≥ 24.0.0 且 Docker Compose ≥ v2.26.1
• Linux 系统需设置 vm.max_map_count ≥ 262144（用于 Elasticsearch）
• gVisor：可选，仅在启用代码执行器（沙箱）功能时需要

Docker 部署（快速开始）

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  # 等待出现启动提示后登录
# 在浏览器中打开 http://YOUR_SERVER_IP

编辑 docker/service_conf.yaml.template 文件，在 user_default_llm 下配置 LLM API 密钥，然后重启：

docker compose -f docker-compose.yml up -d

中文镜像加速

若 Docker Hub 访问缓慢：

• 华为云镜像：swr.cn-north-4.myhuaweicloud.com/infiniflow/ragflow
• 阿里云镜像：registry.cn-hangzhou.aliyuncs.com/infiniflow/ragflow

如需设置 HuggingFace 镜像源，请在 docker/.env 中添加：HF_ENDPOINT=https://hf-mirror.com

关键配置文件

部署后 LLM 配置

1. 通过浏览器登录
2. 编辑 docker/service_conf.yaml.template：

   user_default_llm:
     factory: "OpenAI"   # 或 "DeepSeek"、"Gemini" 等
     api_key: "sk-..."
     base_url: "https://api.openai.com/v1/"

1. 执行以下命令应用更改：

docker compose -f docker-compose.yml up -d

CLI 快速参考

所有 CLI 命令以分号 ; 结尾。完整参考请见：[references/cli-reference.md](references/cli-reference.md)。

# 数据集操作
LIST DATASETS;
CREATE DATASET 'my_kb' WITH EMBEDDING 'text-embedding-ada-002' PARSER 'pdf';
DROP DATASET 'my_kb';
LIST FILES OF DATASET 'my_kb';

# 文档操作
IMPORT '/path/to/doc.pdf' INTO DATASET 'my_kb';
PARSE DATASET 'my_kb' SYNC;
PARSE DATASET 'my_kb' ASYNC;

# 搜索
SEARCH 'What is RAG?' ON DATASETS 'my_kb';

# 模型管理
CREATE MODEL PROVIDER 'openai' 'sk-...';
SET DEFAULT LLM 'gpt-4';
LIST MODEL PROVIDERS;
LIST DEFAULT MODELS;

# Agent 与聊天
LIST AGENTS;
LIST CHATS;
CREATE CHAT 'my_session';
DROP CHAT 'my_session';

# 连接测试
PING;
SHOW CURRENT USER;

切换文档引擎（Elasticsearch → Infinity）

docker compose -f docker/docker-compose.yml down -v  # 警告：会清除数据
# 修改 docker/.env：设置 DOC_ENGINE=infinity
docker compose -f docker-compose.yml up -d

Infinity 更轻量，但目前不支持 Linux/arm64 平台。

架构概览

Web UI (React+TS+vitejs+shadcn) → Flask API (/api/) → RAG Core (/rag/) + Agent (/agent/)
                                                          ↓
基础设施：MySQL + Elasticsearch/Infinity + Redis + MinIO

• 后端 (/api/)：Flask 蓝图 —— kb、dialog、document、canvas、file、user
• RAG 核心 (/rag/)：DeepDoc 解析、LLM/嵌入/重排序 抽象层、文本切片、GraphRAG
• Agent (/agent/)：基于画布的工作流构建器，包含组件（LLM、检索、代码执行器、MCP、搜索、SQL）
• 前端 (/web/)：React 18 + TypeScript + Vite

详细组件说明请参阅 [references/architecture.md](references/architecture.md)

从源码开发

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
# 添加到 /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
# 另开终端：
cd web && npm install && npm run dev

故障排查快速参考

API 与 SDK

• REST API：http://SERVER_IP/api/ — Swagger 文档位于 /api/docs
• Python SDK：位于 sdk/python/
• CLI 客户端：python admin/client/ragflow_cli.py <command>
• 使用指南：[https://ragflow.io/docs/dev/](https://ragflow.io/docs/dev/)