目录

tags:
– 玩客笔记
– RAGFlow
– RAG
– Docker
– 知识库
– 本地AI
platform: 今日头条 / 知乎
status: 草稿
created: 2026-05-28
title: RAGFlow 是什么？开源 RAG 引擎从零搭建到上手使用的完整教程
source:
– https://ragflow.io/basics/what-is-rag
– https://github.com/infiniflow/ragflow

RAGFlow 是什么？开源 RAG 引擎从零搭建到上手使用的完整教程

最后更新：2026 年 5 月 28 日
适用场景：Linux / macOS 服务器自建 RAGFlow 知识库
目标：理解 RAG 核心概念 → 动手部署 RAGFlow → 搭建自己的知识库并开始使用

一、RAG 是什么？为什么需要它？

大模型的「天生缺陷」

大语言模型（LLM）在通用知识问答上表现惊人，但有两个致命短板：

1. 知识是静态的——模型的知识截止于训练时那个时间点，无法感知最新信息。
2. 看不见私有数据——企业内部文档、技术手册、产品说明、邮件归档，这些数据模型根本没学过。

你问 GPT「2026 年 5 月有什么热门项目」，它答不上来，因为它不知道这个月发生过什么事。你问它「我们公司的离职流程是什么」，它也答不上来，因为这些东西不在训练数据里。

更麻烦的是，当模型没有准确依据时，它会编造答案——这就是所谓的「幻觉」（Hallucination）。看起来很有道理，实际上是胡说八道。

RAG 的解决方案

RAG（Retrieval-Augmented Generation，检索增强生成） 的核心思路很简单：

在让大模型回答问题之前，先从一个外部知识库里检索出最相关的资料，把这些资料作为「参考材料」喂给模型，让它根据这些材料来回答。

说白了就是：开卷考试，而不是闭卷背诵。

• 检索阶段：把你的文档（PDF、Word、Markdown）切碎、向量化，存到向量数据库里。用户提问时，把问题也转成向量，到库里搜出最相关的片段。
• 生成阶段：把搜到的片段 + 用户问题一起发给 LLM，让模型结合资料给出答案。

这样一来，答案就有据可查、有来源可追溯，幻觉大幅降低。

RAG 的典型应用场景

二、RAGFlow 是什么？

RAGFlow 是目前 GitHub 上最热门的开源 RAG 引擎之一（当前 v0.25.6），由 InfiniFlow 团队开发，Apache 2.0 协议开源。

项目地址：https://github.com/infiniflow/ragflow

它的口号是 “Quality in, quality out”——输入质量决定了输出质量。

RAGFlow 的核心优势

1. 深度文档理解
– 不只是简单的 PDF 文字提取，而是基于深度学习模型（DeepDoc）理解文档的布局结构
– 能正确处理表格、图表、多栏排版、页眉页脚等复杂格式
– PDF 中的图片可以用多模态模型解析生成文字描述

2. 可控的智能切片
– 切片不是黑盒——你能看到每个切片是怎么切出来的，还能手动调整
– 支持多种切片模板，按需选择

3. 多源异构数据兼容
– 支持 Word、PDF、PPT、Excel、TXT、图片、扫描件、网页链接
– 还能从 Confluence、Notion、Google Drive、Discord 同步数据
– 2025 年 10 月起支持 MinerU 和 Docling 两种额外解析引擎

4. Agent + MCP 支持
– 支持 agentic workflow 和 MCP 协议（2025 年 8 月起）
– 可以将 RAGFlow 的知识库作为 OpenClaw skill 使用
– 内置 Python/JavaScript 代码执行器

5. 完整的权限和 API
– 支持多用户、数据集级别的权限控制
– 完善的 REST API，可以集成到企业系统

系统架构

RAGFlow 由多个组件构成，全部运行在 Docker 容器里：

用户浏览器 ←→ Nginx (80端口)
                    ↓
              RAGFlow API Server (Python/Flask)
              ↙    ↓    ↘    ↙
        MySQL   Redis   Elasticsearch/Infinity   MinIO
        元数据   缓存    文本+向量存储      文件存储

• MySQL：存储用户、知识库元数据
• Redis：缓存和任务队列
• Elasticsearch（默认）或 Infinity：存储文本切片的向量和全文索引，负责检索
• MinIO：对象存储，存放上传的文件和解析结果

三、环境准备

硬件要求

注意：RAGFlow 本身的容器 + 依赖服务大约占用 8-10GB 磁盘（含基础镜像），后续上传文档会持续增加存储占用。

软件要求

• Docker >= 24.0.0
• Docker Compose >= v2.26.1
• Python >= 3.13
• 操作系统：Ubuntu 22.04+ / Debian 12+ / macOS（Intel）/ Windows（WSL2）

⚠️ 官方 Docker 镜像目前只提供 x86 架构版本。如果用的是 Apple Silicon（M1/M2/M3/M4）芯片的 Mac，需要自行从源码构建 ARM64 镜像。后面会单独说明。

安装 Docker

如果你还没装 Docker，快速安装（Ubuntu/Debian 示例）：

# 卸载旧版本
sudo apt remove docker docker-engine docker.io containerd runc

# 安装依赖
sudo apt update
sudo apt install -y ca-certificates curl gnupg lsb-release

# 添加 Docker 官方 GPG 密钥
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# 添加仓库
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 安装 Docker
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# 验证安装
sudo docker --version
sudo docker compose version

macOS 用户直接从 Docker Desktop 下载安装即可。

四、部署 RAGFlow

第 1 步：检查系统参数

RAGFlow 依赖 Elasticsearch，而 ES 要求 vm.max_map_count 至少为 262144：

# 检查当前值
sysctl vm.max_map_count

# 如果小于 262144，临时修改
sudo sysctl -w vm.max_map_count=262144

# 永久修改（重启后仍然生效）
echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf

第 2 步：克隆仓库

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

第 3 步：配置环境变量

进入 docker 目录，查看关键配置：

cd docker
cat .env

主要环境变量说明：

如果国内服务器拉不到 Docker Hub 的镜像，可以把 RAGFLOW_IMAGE 改成华为云镜像：
RAGFLOW_IMAGE=swr.cn-north-4.myhuaweicloud.com/infiniflow/ragflow:v0.25.6
或者阿里云镜像：
RAGFLOW_IMAGE=registry.cn-hangzhou.aliyuncs.com/infiniflow/ragflow:v0.25.6

第 4 步：启动服务

# 默认使用 CPU 模式（DeepDoc 文档解析跑在 CPU 上）
docker compose -f docker-compose.yml up -d

# 如果你有 NVIDIA GPU，想用 GPU 加速文档解析：
# 先修改 .env，把 DEVICE 改成 gpu
# sed -i '1i DEVICE=gpu' .env
# 然后启动：
# docker compose -f docker-compose.yml up -d

第一次启动时会拉取多个 Docker 镜像，包括：

• infiniflow/ragflow:v0.25.6（约 2GB，slim 版本不含内置 embedding 模型）
• mysql:8.0（约 600MB）
• redis:7（约 120MB）
• docker.elastic.co/elasticsearch/elasticsearch:8.16.0（约 1.2GB）
• minio/minio（约 300MB）

总下载量大约 4-5GB，视网络情况可能耗时 10-30 分钟。

第 5 步：验证启动是否成功

# 查看所有容器是否都正常运行
docker compose ps

# 查看 RAGFlow 应用日志
docker logs -f docker-ragflow-cpu-1

等待日志中出现以下内容说明服务启动成功：

     ____   ___    ______ ______ __
    / __ \ /   |  / ____// ____// /____  _      __
   / /_/ // /| | / / __ / /_   / // __ \| | /| / /
  / _, _// ___ |/ /_/ // __/  / // /_/ /| |/ |/ /
 /_/ |_|/_/  |_|\____//_/    /_/ \____/ |__/|__/

 * Running on all addresses (0.0.0.0)

注意：不要在这行日志出现之前就打开网页，否则浏览器会提示「网络异常」。

第 6 步：登录 Web 界面

在浏览器中输入 http://你的服务器IP（默认端口 80，不需要加端口号）。

首次访问会进入注册页面：

• 用户名：admin（默认管理员账号）
• 密码：自行设置（建议用强密码）

五、配置大模型（LLM）

登录进去之后，第一步是配置 LLM。点击左下角头像 → 设置（Settings） → 模型提供商（Model Providers）。

RAGFlow 支持几乎所有主流大模型：

推荐方案 1：Ollama 本地模型（完全免费）

如果你有足够的算力，推荐用 Ollama 跑本地模型：

# 安装 Ollama
curl -fsSL https://ollama.com/install.sh | sh

# 拉取对话模型（推荐 qwen2.5:7b 或 deepseek-r1:7b）
ollama pull qwen2.5:7b

# 拉取 embedding 模型（RAGFlow 需要单独的 embedding 模型）
ollama pull bge-m3

然后在 RAGFlow 的模型设置里：

1. 添加 Ollama 服务地址：http://你的OllamaIP:11434
2. LLM 模型：选择 qwen2.5:7b
3. Embedding 模型：选择 bge-m3（非常重要！不能和 LLM 是同一个模型）

推荐方案 2：硅基流动（免费+高性能）

注册 硅基流动 获取 API Key：

• 对话模型：Qwen/Qwen2.5-7B-Instruct 或 Pro/deepseek-ai/DeepSeek-V3
• Embedding 模型：BAAI/bge-m3 或 intfloat/multilingual-e5-large-instruct

在模型提供商中选择 SiliconFlow，填入 API Key 即可。

六、创建第一个知识库

第 1 步：新建知识库

导航到「知识库（Datasets）」页面 → 点击「创建知识库（Create Dataset）」：

• 知识库名称：比如「技术方案库」
• 选择语言：Chinese（影响切片和 embedding 质量）
• 嵌入模型：选你刚才配置的 embedding 模型（如 bge-m3）
• 切片策略：建议选「通用切片（General）」，后续可根据文档类型调整
• Top N 检索：每次召回几个片段，默认 5 即可
• 相似度阈值：0.2 左右（低于这个值的片段不会被召回）

第 2 步：上传文档

创建好后点击进入知识库，点击「上传文档（Upload Documents）」：

支持的格式：

上传后点击「解析（Parse）」按钮，RAGFlow 会自动进行：

1. 布局分析（深度文档理解）
2. 文字提取 + OCR
3. 智能切片
4. 向量化并存入 Elasticsearch

第 3 步：查看和调整切片

解析完成后，你可以点击每个切片查看：

• 切片内容是否合理
• 边界是否准确（有没有把一个表格切两半）
• 可以手动添加、删除、合并切片

💡 这是 RAGFlow 的杀手锏之一：切片可视化 + 手动调整。其他 RAG 工具往往是黑盒切片，切得好不好全靠运气，RAGFlow 让你能看到并手动修正。

第 4 步：开始问答

回到「聊天（Chat）」页面：

1. 点击「开始新对话（New Chat）」
2. 选择一个已经配置好 LLM 的助手（Assistant）
3. 在 Assistant 设置里关联你的知识库
4. 输入问题，RAGFlow 会先检索知识库，再把检索结果 + 问题发送给大模型

每个回答下方都会显示来源引用——你可以点击来源，直接跳转到原始文档的对应切片验证。

七、进阶配置

7.1 修改 Web 端口

编辑 docker/.env 文件，找到这行：

# 默认 80，改成你想要的其他端口
SVR_HTTP_PORT=8080

然后重启：

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

7.2 切换文档引擎

RAGFlow 默认用 Elasticsearch 做文档和向量存储。如果你想要更好的向量检索性能，可以切换为 Infinity（也是 InfiniFlow 团队开发的检索引擎）。

# 停止并删除旧数据（会清空已有数据！）
docker compose -f docker-compose.yml down -v

# 修改 .env，设置文档引擎为 Infinity
# DOC_ENGINE=infinity

# 重新启动
docker compose -f docker-compose.yml up -d

7.3 ARM64（Apple Silicon）用户如何部署

官方 x86 镜像不能在 ARM64 上直接运行。如果你用 M1/M2/M3 Mac，有两种方案：

方案 A：在 macOS 上用 Docker Desktop 的 Rosetta 模拟
Docker Desktop 默认用 Rosetta 2 转译 x86 镜像，可以直接跑。但性能会打些折扣。

方案 B：自行构建 ARM64 镜像

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

# 构建 ARM64 镜像
docker build \
  --build-arg PYTHON_IMAGE=python:3.13-slim \
  --platform linux/arm64 \
  -t infiniflow/ragflow:arm64 \
  -f Dockerfile.cuda .

构建时间较长（30-60 分钟），建议用方案 A 先体验。

八、常见问题排查

Q1：Docker 拉取镜像超时

国内常见问题，报错类似：

failed to do request: Get "https://registry-1.docker.io/..."
net/http: TLS handshake timeout

解决方案：在 .env 中改用国内镜像

# 华为云
RAGFLOW_IMAGE=swr.cn-north-4.myhuaweicloud.com/infiniflow/ragflow:v0.25.6

# 或者阿里云
RAGFLOW_IMAGE=registry.cn-hangzhou.aliyuncs.com/infiniflow/ragflow:v0.25.6

Q2：Elasticsearch 启动失败

最常见的原因是 vm.max_map_count 没有设置：

sudo sysctl -w vm.max_map_count=262144
# 并写入 /etc/sysctl.conf 做持久化

Q3：服务启动了但浏览器打不开

1. 检查端口是否正确：默认 80，如果改了端口要加端口号
2. 检查防火墙：sudo ufw status，确保端口已放行
3. 检查日志：docker logs docker-ragflow-cpu-1，看是否有报错

Q4：问答时总是返回空或者答非所问

常见原因：
1. Embedding 模型未配置——RAGFlow 需要单独的 embedding 模型做文档向量化
2. 知识库尚未解析完成——上传文档后要点「解析」，等待解析完成
3. 相似度阈值太高——建议调到 0.2 左右
4. LLM 上下文窗口过小——换一个支持更长上下文的模型

Q5：如何在服务器重启后自动启动 RAGFlow？

# 设置 Docker 服务开机自启
sudo systemctl enable docker

# 创建一个 systemd 服务文件
sudo tee /etc/systemd/system/ragflow.service << 'EOF'
[Unit]
Description=RAGFlow Service
Requires=docker.service
After=docker.service

[Service]
WorkingDirectory=/path/to/ragflow/docker
ExecStart=/usr/bin/docker compose -f docker-compose.yml up
ExecStop=/usr/bin/docker compose -f docker-compose.yml down
Restart=always

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable ragflow
sudo systemctl start ragflow

九、总结

RAGFlow 是目前开源 RAG 引擎中文档理解能力最强、切片最可控的一个。它的核心亮点可以概括为：

• ✅ 深度文档理解：不只是提取文字，而是理解文档结构
• ✅ 可视化切片：你能看到并手动调整每个切片
• ✅ 有据可查：每个答案都能追溯到原文，降低幻觉
• ✅ 开箱即用：一条 docker compose up -d 就能跑起来
• ✅ 多模型支持：OpenAI / DeepSeek / Ollama / 硅基流动 随便选
• ✅ Agent + MCP：支持复杂工作流和外部工具调用

如果你正在搭建企业知识库、个人智能助手、或需要处理大量复杂文档的高精度 RAG 系统，RAGFlow 值得一试。

参考资料

• 官网：https://ragflow.io
• GitHub：https://github.com/infiniflow/ragflow
• 官方文档：https://ragflow.io/docs/dev/
• 云服务：https://cloud.ragflow.io（免费体验，不用自己部署）
• RAG 基础概念：https://ragflow.io/basics/what-is-rag
• Discord 社区：https://discord.gg/NjYzJD3GM3

About The Author

玩客

See author's posts