系列导航

• 第 0 章 前言：为什么企业 AI 工程师必须掌握 RAGFlow
• 第 1 章：安装部署与基础配置——从零跑通第一个 RAG Pipeline （本文）
• 第 2 章：RAGFlow 代码介绍
• 第 3 章：攻克企业复杂文档——理解 DeepDoc、Naive、MinerU 与 Docling 的区别
• 第 4 章：理解 Agentic RAG 核心——定义与低代码实现
• 第 5 章：工作流编排——构建基于图（Graph）的 RAG
• 第 6 章：Deep Research 模板应用——部署自动拆解子问题的深度研究智能体
• 第 7 章：企业级扩展——API 接入与外部工具集成（MCP）
• 第 8 章：评估与复盘——从"玄学"到量化 RAG 性能指标评测

---

写在前面

在第 0 章中，我们了解了为什么企业AI工程师要掌握 RAGFlow， 这款基于深度文档理解的开源 RAG 引擎。本章将聚焦于一个最基础的问题：如何把它跑起来？

这不是一份简单翻译官方文档的"搬运文"。我将在 WSL2 + Windows 的真实开发环境中，完整记录从零部署 RAGFlow v0.24.0 的每一个步骤、每一个配置文件的含义，以及每一个让人抓狂的"报错"。更重要的是，我将带你理解每一个操作背后的"为什么"——因为只有理解了系统运行时的状态，你才能真正掌控它。

本文你将收获：

• 对 RAGFlow 运行时架构的清晰认知（你知道自己启动的到底是什么）
• 一套经过验证的完整安装流程（含国内网络环境优化）
• 可复现的实验任务（亲手搭建第一个问答机器人）

---

一、运行时系统架构：启动之后，到底发生了什么？

在动手安装之前，我们先建立一张完整的"运行时地图"。理解了系统启动后的状态，后面的每一步操作才有锚点。

1.1 系统分层架构

RAGFlow 的运行时基础架构可以清晰地划分为四个层次：

人话版解读：

• 前端层：你在浏览器里看到的那个漂亮的 Web 界面，由 Vite 开发服务器驱动，负责所有用户交互。
• 后端层：Python 编写的核心大脑，分为两个进程——API Server 处理所有 HTTP 请求，Task Executor 在后台默默处理文档的解析和向量化。
• 基础设施层：五个 Docker 容器，分别是数据库（MySQL）、文件仓库（MinIO）、两个搜索引擎（ES 和 Infinity）和消息队列（Redis）。这是整个系统的"器官"。
• 离线依赖层：不需要 Docker，但必须提前下载好的本地模型和分词器，是文档解析的基础工具。

1.2 Docker 基础设施服务全景

以下表格汇总了我试验时所有 Docker 基础服务的详细信息。所有镜像版本、密码和端口映射规则都在 docker/.env 中统一定义。

服务组件	镜像来源	宿主机端口	容器内部端口	核心职能	通俗比喻
MySQL 8.0	mysql:8.0	5455	3306	存储所有关系型数据：用户、租户、知识库设定、文档元数据、任务状态	业务大脑
Redis (Valkey)	valkey/valkey:8	16379	6379	Celery Broker：API 投递解析任务，Task Executor 消费执行；并发访问的分布式锁	神经系统
Elasticsearch	elastic/elasticsearch	1200	9200	基于 BM25 算法的精确关键词文本召回（倒排索引）	左脑（精确记忆）
Infinity	infiniflow/infinity	23817	23817	高维 Embedding 向量的语义相似度召回	右脑（模糊理解）
MinIO	minio/minio	9000	9000	分布式对象存储：原始文档、解析图片、提取的文本块	物流仓库

关键认知：RAGFlow 的检索能力来源于 ES 和 Infinity 的"双引擎"协同。ES 负责精确的关键词匹配（类似传统搜索引擎），Infinity 负责语义理解式的模糊召回（类似"意思相近就行"）。两者混合后的结果再经过 Rerank 模型精排，才是最终喂给大模型的上下文。

1.3 数据流转全景：从上传到回答

当你上传一份文档并提问时，系统内部发生了什么？下面的时序图完整展示了这一过程：

1.4 关系数据模型（MySQL）

MySQL 中维护的核心逻辑关系如下：

1.5 模型矩阵：基建模型 vs. 业务模型

RAGFlow 涉及的 AI 模型分为两类，理解这个区分非常重要：

基建模型在 RAGFlow项目中download_deps.py 执行后就已经就位，它们负责把杂乱的 PDF 变成结构化的文本块。业务模型才是决定系统"智商"的关键——你不需要下载它们的权重文件，只需在 Web UI 的 Settings → Model Providers 中填入 API 地址和密钥即可。

以下是中文环境下推荐的模型配置方案：

模型类型	推荐方案	备选方案	配置方式
Embedding	硅基流动 API → bge-m3	智谱 GLM Embedding / OpenAI text-embedding-3-small	Web UI → Model Providers
Rerank	硅基流动 API → bge-reranker-v2-m3	Jina API → jina-reranker-v2-base-multilingual	Web UI → Model Providers
Chat LLM	DeepSeek-V3 / DeepSeek-R1	Kimi (Moonshot) / 千问 Max (Qwen-Max)	Web UI → Model Providers
VLM (可选)	硅基流动 → Qwen2-VL	Ollama → llava	Web UI → Image2Text
ASR (可选)	Xinference → whisper-large-v3	FunASR+SenseVoice	Web UI → Speech2text
TTS (可选)	Xinference → ChatTTS	Fish Audio API	Web UI → TTS

实战金句：采用硅基流动 API（提供免费的高速 bge-m3 词嵌入与 bge-reranker-v2-m3 重排）搭配 DeepSeek-V3 作为对话大脑，是兼顾资源占用、成本与检索精准度的最优解。

---

二、安装：从零到一的完整流程

2.1 环境前提条件

• 安装环境
  硬件配置推荐配置是CPU不少于4核，内存不低于16GB，磁盘空间至少50GB

项目	要求	验证命令
操作系统	Windows 11(10/11) + WSL2 + Ubuntu 24.04(22.04+)	cat /etc/os-release
Docker	Docker version 28.3.3, build 980b856	docker --version
Node.js	v20.19.4(v18+)	node --version
Python	3.12（推荐）	python3 --version
uv	0.8.22 (最新版 Python 包管理器)	uv --version
网络	稳定的 VPN 或透明代理（建议 FlyintPro TUN 模式）	curl -I https://github.com

• 从github上复制RAGFlow项目代码:

cd ~
# 克隆主仓库最新代码
git clone https://github.com/infiniflow/ragflow.git
# 进入项目目录
cd ~/ragflow
# 切换到我验证的稳定版本TAG
git checkout -f v0.24.0

2.2 运行方式说明

由于我需要调试前后端代码，所以 不希望 RAGFlow代码在Docker中运行，因此采用如下运行方式：

1. 基础服务自动运行：无需调试的基础服务（如 Redis 等）采用 RAGFlow 推荐的 Docker 方式，让它们随 WSL 上的 Ubuntu 系统自动启动，省去手动启停的麻烦。
2. 调试代码手动运行：我需要调试的 RAGFlow 后端及前端代码，则通过手动方式运行。这样修改或添加打印后可以直接执行，无需重新打包到 Docker 镜像中。

RAGFlow 显然也考虑到了这种安装与运行模式，因此提供了 docker-compose-base.yml 仅用于启动基础服务，并分别给出了后端 Python 代码和前端 TypeScript 代码的手动运行指令。

2.3 安装流程总览

整个安装过程可以概括为以下四个阶段：

2.4 Step 1：启动 Docker 基础服务

RAGFlow 的重型数据库（MySQL、Elasticsearch、MinIO、Redis/Valkey、Infinity）全部通过 Docker 运行，这是系统最重也最关键的部分。

# 1. 进入项目的 docker 配置目录
cd ~/ragflow/docker

# 2. 检查并修改 .env 文件（处理端口冲突）
# 如果你的 Windows 宿主机上已经运行了其他 Redis（如 Supabase），
# 必须修改 REDIS_PORT 避免冲突
# 将 REDIS_PORT=6379 改为 REDIS_PORT=16379

# 3. 启动所有基础服务
docker compose -f docker-compose-base.yml up -d

验证启动状态：

docker compose -f docker-compose-base.yml ps

所有容器的状态应为 STATUS: Up (healthy)。如果某个容器反复重启，请检查：

• 端口是否被占用（ss -tlnp | grep <端口号>）
• .env 中的密码是否包含特殊字符
• 系统的 vm.max_map_count 是否满足 Elasticsearch 的要求（详见后文"遇到的坑"章节）

⚠️ 重要提示：vm.max_count 是 Elasticsearch 运行的硬性前提。在 WSL2 中执行：

sudo sysctl -w vm.max_map_count=262144

若要永久生效，将 vm.max_map_count=262144 写入 /etc/sysctl.conf。

2.5 Step 2：同步 Python 后端依赖

RAGFlow v0.24.0 推荐使用 uv 进行依赖管理。uv 是 Rust 编写的新一代 Python 包管理器，速度比 pip 快 10-100 倍。

cd ~/ragflow
uv sync --python 3.12 --all-extras

核心依赖概览（pyproject.toml）：

依赖层级	代表库	用途
深度学习层	torch, transformers	模型推理基础框架
核心逻辑层	langchain, fastapi, valkey	RAG 流程编排与缓存
文档解析层	opencv-headless, tika	PDF/图片 OCR 处理
易错依赖	graspologic, onnxruntime	图分析/ONNX 推理（安装时常出问题）

2.6 Step 3：下载离线解析组件

这一步下载系统运行所必需的本地分词器、语料库和模型文件：

cd ~/ragflow
uv run download_deps.py

下载的内容存放在项目根目录的 rag/res/ 文件夹中，包括：

组件	文件示例	用途
Tiktoken 分词器	cl100k_base.tiktoken	精确 Token 计数，控制切片大小
NLTK 语料	各类语料包	分词、关键词提取、句法分析
Apache Tika (.jar)	tika-server.jar	复杂格式文档的元数据提取

⚠️ 国内网络注意：download_deps.py 使用 Python 的 urllib 库下载文件，该库对 TLS 握手错误处理极差。如果下载 openaipublic.blob.core.windows.net 上的 Tiktoken 文件反复失败，建议从 Windows 侧手动下载后复制到 WSL 的 rag/res/ 目录。

2.7 Step 4：安装前端依赖

cd ~/ragflow/web
npm install

前端使用 Vite + React + UmiJS 技术栈，npm install 通常不会有网络问题。

2.8 国内依赖安装最佳实践

在中国大陆的网络环境下，安装过程最大的挑战是依赖下载的"一半国内一半国外"问题。以下是经过反复验证的最佳实践。

核心矛盾

解决方案：精准流量分流

核心思路是利用 no_proxy 环境变量实现"国内直连、国外走代理"的精准分流：

# 1. 设置代理指向 Windows 宿主机（请替换为你的实际 IP）
export http_proxy="http://192.168.111.2:7890"
export https_proxy="http://192.168.111.2:7890"

# 2. 关键：设置白名单，告诉程序哪些地址不走代理
export no_proxy="localhost,127.0.0.1,tsinghua.edu.cn,aliyun.com,pypi.tuna.tsinghua.edu.cn"

更优雅的方案：uv 指定国内源

# 使用清华源加速 PyPI 基础包，同时 Git 依赖项会自动寻找 http_proxy 走 GitHub
uv sync --index-url https://pypi.tuna.tsinghua.edu.cn/simple --all-extras

或者一劳永逸，在项目根目录创建 .uv/uv.toml：

[[index]]
name = "tuna"
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true

⚠️ WSL2 代理的特殊注意事项

WSL2 的 127.0.0.1 默认指向 Linux 系统自身，不是 Windows 宿主机。即使 Windows 开了代理，WSL 里手动设置错误的代理 IP 会导致连接超时。

推荐做法：如果你的代理软件支持 TUN 模式（全局透明代理），不要手动设置任何 http_proxy 环境变量，让代理软件自动处理所有流量。这比手动配置 IP 和端口要可靠得多。

网络诊断"清道夫"指令

# 查看当前代理设置
printenv | grep proxy

# 网络出现奇怪报错时，重置所有代理变量
unset http_proxy https_proxy no_proxy

核心口诀：基础镜像国内下，Git 源码挂代理。no_proxy 列表中，清华阿里必填全。

---

三、配置：三层控制面板详解

RAGFlow 的配置体系可以清晰地分为三个层次，每个层次控制不同的作用域：

3.1 第一层：docker/.env —— Docker 基建图纸

文件位置：/home/<user>/ragflow/docker/.env

作用：只控制 Docker Compose 启动的容器属性。定义了各数据库的镜像版本标签（Tags）、宿主机映射端口以及初始化密码。

关键配置项：

配置项	默认值	作用	是否需要修改
MYSQL_PASSWORD	infi_rag_flow	MySQL root 密码	通常不需要
REDIS_PORT	6379	Redis 宿主机映射端口	⚠️ 如有端口冲突必须改
MYSQL_PORT	5455	MySQL 宿主机映射端口	按需
MINIO_PORT	9000	MinIO 宿主机映射端口	通常不需要
ES_PORT	1200	Elasticsearch 宿主机映射端口	通常不需要

⚠️ 重要提示：如果在已有数据的容器上修改了 .env 中的密码字段，容器可能因为旧数据存在而拒绝更新密码配置。这种情况下通常需要清除 Volume 后重建：docker volume rm <volume_name>。

3.2 第二层：conf/service_conf.yaml —— 业务接线板

文件位置：/home/<user>/ragflow/conf/service_conf.yaml

作用：Python 核心业务进程的"寻址雷达"。当 Python 进程需要读写数据库时，就是看这个文件。

关键配置项：

配置块	关键字段	作用	必须与什么保持一致
mysql	host, port	MySQL 连接地址	docker/.env 中的 MYSQL_PORT
redis	host, port	Redis 连接地址	docker/.env 中的 REDIS_PORT
es	host, port	Elasticsearch 连接地址	docker/.env 中的 ES_PORT
minio	host, port, access_key, secret_key	MinIO 连接地址和凭据	docker/.env 中的对应字段
infinity	host, port	Infinity 向量库连接地址	docker/.env 中的 INFINITY_PORT
user_default_llm	factory, api_key, model	默认挂载的 LLM 和 Embedding	你申请的 API Key

最常见的问题：.env 中把 REDIS_PORT 改成了 16379，但忘记同步修改 service_conf.yaml 中 redis 的 port 字段。结果是后端连上了 Windows 宿主机上另一个没设密码的 Redis，报出令人困惑的认证错误。

3.3 第三层：配置大模型等运行参数

这一步不影响前后端的运行， 所以放在前后端都正常运行后， 通过WEB页面进行设置。
具体配置说明参考 六、实验任务：搭建你的第一个问答机器人

3.4 docker配置和service配置的关系与一致性检查

docker/.env 和 conf/service_conf.yaml之间存在严格的依赖关系，任何一层的不一致都会导致运行时错误：

实战建议：每次修改 .env 后，务必逐项检查 service_conf.yaml 中对应的端口字段是否同步更新。

---

四、运行：三层服务的启动与管理

4.1 启动顺序与依赖关系

三个层次的服务必须按顺序启动，因为上层依赖下层：

4.2 启动命令详解

① 启动 Docker 基础服务 (只用执行一次, 以后随系统自送启停)

cd ~/ragflow/docker
docker compose -f docker-compose-base.yml up -d

验证：

docker compose -f docker-compose-base.yml ps
# 所有容器状态应为 Up (healthy)

② 启动 Python 后端

cd ~/ragflow
source .venv/bin/activate          # 激活虚拟环境
export PYTHONPATH=$(pwd)            # 设置模块搜索路径
bash docker/launch_backend_service.sh  # 启动 API + Task Executor

日志观察要点：

• ✅ 看到 INFO 级别的 API 初始化日志 → 正常
• ✅ 看到各种解析组件挂载的日志 → 正常
• ❌ 看到 vackey.exceptions.AuthenticationError → Redis 端口配置不一致（参见"遇到的坑"）
• ❌ 看到 Connection refused → Docker 服务未就绪或端口配置错误

③ 启动 Vite 前端

cd ~/ragflow/web
npm run dev

终端会显示类似：

➜  Local:   http://localhost:9222/
➜  Network: http://172.x.x.x:9222/

在 Windows 浏览器中直接访问 http://localhost:9222/ 即可。

4.3 停止与资源清理

停止时按相反顺序操作：

# 1. Ctrl + C 退出前端
# 2. Ctrl + C 退出后端启动脚本
# 3. 可选的: 
#		暂停 Docker 服务（保留数据）
docker compose -f docker-compose-base.yml stop
# 	或者彻底停止并删除容器（数据保留在 Volume 中）
docker compose -f docker-compose-base.yml down

4.4 开发调试建议

在开发过程中，建议保持两个终端窗口分别监视后端和前端的日志输出：

4.5 本地 Git 管理：如何优雅地管理你的定制修改

当你需要修改 RAGFlow 源码进行实验时，良好的 Git 管理习惯至关重要。

核心挑战：Detached HEAD 状态

如果你使用 git checkout v0.24.0 这种标签方式获取代码，你会处于 Detached HEAD（游离头指针） 状态。在此状态下做的任何 commit，由于没有分支指向它，在切换到其他版本时可能被垃圾回收丢失。

最佳实践流程

具体操作：

# 1. 基于当前版本创建定制分支(可以自定义名称)
git checkout -b custom/v0.24.0-test

# 2. 举例: 差异化提交（Atomic Commits）
# 提交文档
git add study/
git commit -m "docs: add development and deployment notes"

# 举例: 提交环境配置（可能被 .gitignore 忽略，需强制添加）
git add -f docker/.env conf/service_conf.yaml
git commit -m "config: adjust Redis/MySQL ports for local WSL2 environment"

# 提交源码修改
git add rag/app/naive.py
git commit -m "fix: improve chunk merging for Chinese text"

应对上游更新

当 RAGFlow 官方发布新版本时，你可以通过 rebase 将自己的修改迁移到新版本上：

# 1. 获取最新代码
git checkout main
git pull origin main

# 2. 变基你的定制修改
git checkout custom/v0.24.0-test
git rebase main

总结：在开源项目开发中，"一标签一分支，一提交一功能"是保证生产力的不二法门。

---

五、遇到的坑：排雷手册

在 WSL2 + Windows 代理环境下部署 RAGFlow，绝非一蹴而就。以下是实际遇到的所有"幽灵报错"及其根因和解决方案。

坑 1：WSL2 代理与宿主机桥接之谜

项目	详情
环境	WSL2, FlyintPro, TUN 模式
现象	ping github.com 正常，但 uv sync 报错 gnutls_handshake() failed
根因	WSL2 的 127.0.0.1 指向 Linux 自身，不是 Windows 宿主机。手动设置的代理 IP 可能过期或错误。如果同时开了 TUN 模式，手动环境变量与系统自动转发逻辑冲突。

解决方案：重启终端清除所有手动 export 的变量，让代理软件的全局模式（TUN）自动处理流量。

坑 2：GitHub 镜像站的"反向优化"

项目	详情
现象	为加速 Git 同步在 pyproject.toml 中添加了 gitclone.com 前缀，反而报 502 Bad Gateway
根因	国内 GitHub 镜像站极其不稳定，对某些特定的 Git Commit Hash（如 RAGFlow 依赖的 graspologic）解析能力有限

解决方案：在 VPN 稳定的前提下，使用原生 GitHub 地址 + 透明代理。镜像站反而会成为木桶中最短的那块板。

坑 3：Redis 认证失败——最具欺骗性的"串台"报错

项目	详情
现象	后端报错 AUTH <password> called without any password configured for the default user
根因	Windows 上其他应用（如 Supabase）占据了默认 6379 端口。RAGFlow Docker 中改了 REDIS_PORT=16379，但 service_conf.yaml 中仍指向 localhost:6379。结果后端连上了 Supabase 的无密码 Redis。

解决方案：将 conf/service_conf.yaml 的 Redis 端口同步修改为 16379。

坑 4：download_deps.py 的 SSL 陷阱

项目	详情
现象	下载 Tiktoken 分词模型时报 SSL: UNEXPECTED_EOF_WHILE_READING
根因	Python urllib 对复杂 TLS 握手处理极差，下载地址被干扰时 0.1 秒的不稳定也会导致连接重置

解决方案：利用 no_proxy 环境变量确保"国内直连，国外走代理"。如果反复失败，手动下载文件后复制到 rag/res/ 目录。

坑 5：WSL2 本地 GPU 解析失效（RTX 30 系列）

项目	详情
现象	解析带图表的长文档耗时极长，nvidia-smi 显示显存始终 0MiB，日志显示 load_model uses CPU
根因	三重坑叠加：(1) 缺少 torch 导致静默回退 CPU；(2) WSL2 缺少完整 CUDA Toolkit；(3) Ubuntu apt 找不到 Nvidia 包

逐步解决：

# Step A: 补齐 Torch 基底探测库
uv pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

# Step B: 通过阿里云镜像补齐 CUDA 底层库
uv pip install \
    nvidia-cuda-runtime-cu12 \
    nvidia-cublas-cu12 \
    nvidia-cudnn-cu12 \
    nvidia-cufft-cu12 \
    nvidia-curand-cu12 \
    nvidia-cusolver-cu12 \
    nvidia-cusparse-cu12 \
    -i https://mirrors.aliyun.com/pypi/simple/

# Step C: 注入环境变量（库装在 site-packages 深处，onnxruntime 找不到）
source .venv/bin/activate
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$(python -c "import torch; import os; print(os.path.join(os.path.dirname(torch.__file__), 'lib'))")
export CUDA_VISIBLE_DEVICES=0
export OCR_GPU_MEM_LIMIT_MB=2048

# Step D: 重启后端（旧进程缓存了失败的环境）
pkill -f task_executor.py
pkill -f ragflow_server.py
bash docker/launch_backend_service.sh

GPU 成功接管的标志：

• nvidia-smi 显示显存暴涨到 1.5G~2.5G
• 解析几十页图文报告实现"秒解"
• 日志出现 [W:onnxruntime:, session_state.cc:1316] Some nodes were not assigned to the preferred execution providers

坑位汇总速查表

坑	现象关键词	根因	解决方案
代理桥接	gnutls_handshake	WSL2 手动代理 IP 错误	清除手动变量，用 TUN 模式
镜像站反优化	502 Bad Gateway	国内 Git 镜像站不稳定	用原生 GitHub + VPN
Redis 串台	AuthenticationError	端口配置不一致	同步 .env 和 service_conf.yaml
SSL 下载失败	UNEXPECTED_EOF	urllib TLS 处理差	手动下载 + no_proxy 白名单
GPU 失效	uses CPU	缺 CUDA 库 + 环境变量	安装 nvidia-cu12 包 + 注入 LD_LIBRARY_PATH

---

六、实验任务：搭建你的第一个问答机器人

🎯 实验目标：在本地通过 Docker Compose 成功启动 RAGFlow，搭建首个基于个人简历的问答机器人，并验证 RAG 的"引用溯源"能力。

6.1 实验前置条件检查清单

在开始实验前，请确认以下各项全部就绪：

• Docker 基础服务全部 healthy（docker compose ps 检查）
• Python 后端正常启动（无 AuthenticationError 等报错）
• 前端可通过浏览器访问（http://localhost:9222）
• vm.max_map_count 已设置为 262144

# 一键检查
echo "=== Docker 状态 ===" && \
cd ~/ragflow/docker && docker compose -f docker-compose-base.yml ps && \
echo "=== vm.max_map_count ===" && \
sysctl vm.max_map_count && \
echo "=== Python 环境 ===" && \
cd ~/ragflow && source .venv/bin/activate && python -c "import rag; print('RAG module OK')"

6.2 实验步骤

Step 1：系统内核参数调整

# 修改 Elasticsearch 需要的内存映射限制
sudo sysctl -w vm.max_map_count=262144

检查命令

user@9000k:~$ sysctl vm.max_map_count
#vm.max_map_count = 262144

Step 2：拉取镜像并启动基础服务

cd ~/ragflow/docker
docker compose -f docker-compose-base.yml up -d

# 等待所有服务 healthy（约 1-3 分钟）
docker compose -f docker-compose-base.yml ps

输出结果应该类似:

user@9000k:~/ragflow/docker$ docker compose -f docker-compose-base.yml ps
NAME             IMAGE                                              COMMAND                  SERVICE   CREATED      STATUS                       PORTS
docker-es01-1    elasticsearch:8.11.3                               "/bin/tini -- /usr/l…"   es01      8 days ago   Up About an hour (healthy)   9300/tcp, 0.0.0.0:1200->9200/tcp, [::]:1200->9200/tcp
docker-minio-1   quay.io/minio/minio:RELEASE.2025-06-13T11-33-47Z   "/usr/bin/docker-ent…"   minio     8 days ago   Up About an hour (healthy)   0.0.0.0:9000-9001->9000-9001/tcp, [::]:9000-9001->9000-9001/tcp
docker-mysql-1   mysql:8.0.39                                       "docker-entrypoint.s…"   mysql     8 days ago   Up About an hour (healthy)   33060/tcp, 0.0.0.0:5455->3306/tcp, [::]:5455->3306/tcp
docker-redis-1   valkey/valkey:8                                    "docker-entrypoint.s…"   redis     8 days ago   Up About an hour (healthy)   0.0.0.0:16379->6379/tcp, [::]:16379->6379/tcp

Step 3：启动后端与前端

# 终端 1：启动后端
cd ~/ragflow && source .venv/bin/activate
export PYTHONPATH=$(pwd)
bash docker/launch_backend_service.sh

# 终端 2：启动前端
cd ~/ragflow/web && npm run dev

Step 4：登录 Web UI

在浏览器中访问 http://localhost:9222，首次使用需要注册账号。

Step 5：配置模型 API

进入 Settings → Model Providers，配置以下模型：

1. Embedding 模型：选择硅基流动（SiliconFlow），添加 bge-m3
2. Chat 模型：选择 DeepSeek，添加 deepseek-chat（即 DeepSeek-V3）
3. Rerank 模型（推荐）：选择硅基流动，添加 bge-reranker-v2-m3

Step 6：创建知识库并上传文档

1. 进入 Knowledge Base 页面，点击 Create Knowledge Base
2. 名称填写：“个人简历库”
3. Chunk Method 选择 General
4. Embedding Model 选择刚才配置的 bge-m3
5. 点击进入知识库，上传你的 个人简历.txt
   
   
   指定好嵌入式模型后, 其它参数可以先使用默认值。这些参数具体的调优方法， 会在下一章中说明。
   

Step 7：创建对话助手

1. 进入 Chat 页面，点击 Create Assistant
2. 名称填写：“简历分析助手”
3. 关联刚才创建的"个人简历库"知识库
4. 开启引用开关（Quote）
5. 开始对话
   

6.3 实验提问与预期结果

测试提问：

“电流尖峰导致了什么？”

预期答案范围：

• 答案应精准提取源文档中关于导致事件的描述
• 每个项目的名称、时间、具体内容都应被准确提取
• 关键特征：回答中应出现引用标记，点击后可溯源到原始文本块
  

验证要点：

验证项	预期	检查方法
回答准确性	提取的事件与文档中描述一致	人工比对
引用溯源	每个陈述都有引用标记	点击引用，跳转到原文
无幻觉	没有编造简历中不存在的项目	人工比对
完整性	没有遗漏重要项目	检查是否覆盖所有 相关事件

6.4 进阶实验：参数对比

完成基础实验后，你可以尝试以下对比实验，直观感受参数对结果的影响：

实验 A：解析策略对比

对同一份简历，分别用 Naive 和 General 解析，观察切片预览中结构信息的保留差异。

实验 B：相似度阈值对比

将 Similarity Threshold 从 0.1 调到 0.7，观察：

• 低阈值时：回答可能包含不相关信息
• 高阈值时：可能直接回答"未找到相关信息"

实验 C：混合搜索权重对比

搜索简历中的具体技能关键词（如 “PyTorch”），对比：

• Vector Weight = 1.0（纯语义）：可能召回"深度学习框架"相关内容但遗漏 “PyTorch” 原文
• Vector Weight = 0.3（平衡）：精确匹配 + 语义扩展，效果最佳

---

七、总结与下一步

7.1 核心知识图谱

本文涉及的核心知识可以用以下思维导图概括：

7.2 关键要点回顾

章节	一句话总结
运行时架构	RAGFlow 是由"左脑（ES）"和"右脑（Infinity）"双引擎驱动的知识检索生命体
安装流程	四步走：Docker → uv sync → download_deps → npm install
国内网络优化	核心口诀：基础镜像国内下，Git 源码挂代理，no_proxy 必填全
配置体系	三层控制，端口必须一致，知识库参数决定底层质量
运行管理	三层按序启动，两个终端看日志，一个分支管定制
排雷手册	Redis 串台最具欺骗性，GPU 加速需要四步修复

7.3 下一步预告

在下一章中，我们将进入 RAGFlow 的核心调优领域：

• 参数深度实验：Chunk Method、Token Size、Embedding Model 的 A/B 测试
• 参数调优：Similarity Threshold 和 Hybrid Weight 的精准调控
• Rerank 模型的效果验证：二阶段重排如何将幻觉率降低 50%+
• 完整评估框架：如何量化评估 RAG 系统的检索质量

---

本文所有内容基于 RAGFlow v0.24.0 在 WSL2 (Ubuntu 22.04) + Windows 11 环境下的实际部署经验撰写。所有配置参数、命令和排错方案均经过实际验证。