从文档到可检索知识库：RAGFlow 搭建与调优实战

搭建 RAG 知识库并不只是“上传文档，再接一个大模型”。真正影响效果的环节包括文档解析、分块、向量化、混合检索、重排以及回答阶段的约束。RAGFlow 把这些环节放进一套可视化流程中，适合用于内部制度问答、产品手册检索、技术资料助手等场景。

本文以本地 Docker Compose 部署为起点，完成一个可以检索、测试和持续优化的知识库。示例不包含任何真实凭据。

1. 先理解数据怎样流动

一份文档进入 RAGFlow 后，大致会经过下面这条链路：

原始文件
  ↓
版面解析与内容提取
  ↓
按规则切分为文本块
  ↓
生成向量并建立全文索引
  ↓
关键词检索 + 向量检索
  ↓
可选的重排
  ↓
将相关文本块交给对话模型生成回答

Docker Compose 默认还会启动若干基础服务：MySQL 保存业务元数据，MinIO 保存对象文件，Elasticsearch 默认承担全文和向量检索，Redis 用于缓存与任务协作。理解这些组件后，排查问题时就能先判断故障发生在“文件没有保存”“解析任务未完成”，还是“索引没有召回”。

2. 部署前检查

根据 RAGFlow 官方快速开始文档，建议至少准备：

x86 CPU，4 核及以上；
16 GB 及以上内存；
50 GB 及以上可用磁盘；
Docker 24.0.0 及以上；
Docker Compose 2.26.1 及以上。

官方预构建镜像主要面向 x86 平台。ARM64 环境应先阅读官方构建说明，不要直接照搬 x86 部署步骤。

在 Linux 上还要检查 Elasticsearch 需要的内核参数：

1	sysctl vm.max_map_count

如果结果低于 262144，可以临时调整：

1	sudo sysctl -w vm.max_map_count=262144

临时设置会在重启后失效，正式服务器应通过系统配置持久化。Windows 使用 Docker Desktop 时，可以在其 WSL 环境中完成相同检查。

3. 用 Docker Compose 启动 RAGFlow

先获取官方仓库，并切换到明确的稳定版本。固定版本比直接长期跟随 main 或 nightly 更适合可重复部署。

git clone https://github.com/infiniflow/ragflow.git
cd ragflow
git checkout v0.26.4
cd docker
docker compose -f docker-compose.yml up -d

第一次启动需要下载镜像并初始化存储，等待时间会受网络和磁盘速度影响。先查看容器状态：

1	docker compose -f docker-compose.yml ps

再跟踪 RAGFlow 服务日志：

1	docker compose -f docker-compose.yml logs -f ragflow-cpu

日志显示服务已经监听后，再在浏览器访问服务器地址。默认 HTTP 端口是 80，所以通常可以直接打开：

1	http://服务器地址

如果页面提示网络异常，不要急着反复刷新。先检查 RAGFlow 容器是否健康，再确认 MySQL、Elasticsearch、MinIO 和 Redis 等依赖是否都已启动。

4. 配置模型时先确定职责

一个可用的知识库至少需要两类模型：

对话模型：根据检索到的上下文组织最终回答；
Embedding 模型：把问题和文本块转换到同一个向量空间，用于语义检索。

可选的重排模型会对初次召回的候选文本块重新排序，通常能提高前几条结果的相关性，但也会增加响应时间。

RAGFlow 可以连接在线模型，也可以对接本地部署的 Ollama、Xinference、LocalAI 或兼容接口。生产环境应在管理界面或受控部署配置中维护模型凭据，不要把真实值写进文章、截图或版本库。

一个容易忽略的限制是：知识库已经产生文本块后，Embedding 模型不能直接更换。不同模型生成的向量不在同一空间中，混用后无法正确比较。如果必须更换，需要重新构建该知识库的全部向量索引。因此，正式导入大批文档前，应先用小样本验证模型的中文语义效果。

5. 创建知识库并选择分块方式

进入 RAGFlow 的知识库页面，新建知识库后，先配置 Embedding 模型和解析方式，再上传文件。

常见解析模板可以这样选择：

文档类型	建议起点	原因
Markdown、Word、普通 PDF、网页导出	General	按通用规则连续分块，适合作为默认方案
一问一答形式的表格或文本	Q&A	保留问题与答案之间的对应关系
CSV、Excel 等结构化表格	Table	减少表头与单元格关系丢失
论文	Paper	更关注论文版面与章节结构
书籍、长篇说明书	Book	更适合长文档的章节组织
法规、制度条文	Laws	尽量保持条款边界
演示文稿	Presentation	按页面和演示结构处理
小而完整、不可拆分的材料	One	整份文档作为一个文本块

模板不是越“专业”越好，而是要匹配文件的真实结构。例如，一份从扫描件转换而来的 PDF 即使内容是制度，也可能先受 OCR 和版面识别质量限制。

官方文档建议先把文件上传到 RAGFlow 的文件系统，再链接到知识库。这样同一份文件可以被多个知识库引用，也能降低误删知识库时连原文件一起丢失的风险。

6. 解析后一定要检查文本块

点击解析后，状态变为成功只代表流程完成，不代表分块质量合格。至少抽查以下内容：

标题是否和正文留在同一个语义单元中；
表格的表头是否能解释每一列数据；
页眉、页脚和水印是否被大量重复写入；
跨页段落是否被截断；
扫描 PDF 的 OCR 是否存在明显错字；
单个文本块是否过短、过长或混入多个无关主题。

RAGFlow 支持查看和手动调整解析后的文本块，也可以补充关键词、问题或标签。对高频但总是召回失败的问题，给对应文本块补充业务关键词，往往比一味调低检索阈值更有效。

如果准备使用自定义摄取流程，可以进一步组合解析、清洗和分块节点。官方文档给出的 token 分块默认值为 512 tokens，并支持设置重叠比例；有清晰章节结构的文档还可以考虑标题分块。这里不建议一开始就堆复杂流程，先用默认模板建立可测量的基线。

7. 用检索测试把问题拆开

在创建聊天助手前，先进入知识库的检索测试页面。准备一组真实问题，至少覆盖：

原文中可以直接找到答案的问题；
使用同义词或业务别名的问题；
需要跨段落理解的问题；
知识库中不存在答案的问题；
容易被旧版本或相似制度混淆的问题。

RAGFlow 默认使用混合检索：关键词相似度与向量相似度共同参与评分。如果配置了重排模型，则向量余弦相似度会由重排得分参与组合。

两个重要参数是：

Similarity threshold：低于阈值的文本块会被过滤，官方默认值为 0.2；
Vector similarity weight：向量相似度在综合评分中的权重，官方默认值为 0.3。

调参可以遵循下面的顺序：

正确文本块完全没有出现：先检查解析和分块，再适度降低阈值；
返回很多字面相似但语义无关的内容：提高向量权重；
产品编号、法规条款等精确词被忽略：保留足够的关键词权重；
正确内容能召回但排名靠后：尝试重排模型；
文档包含多种语言：验证所选 Embedding 模型的多语言能力，再考虑跨语言检索。

检索测试页调整的参数不会自动同步到聊天助手。找到合适配置后，要把同样的阈值、权重和重排设置应用到助手或 Agent 的检索组件中。

8. 创建问答助手

检索结果稳定后，再创建聊天助手并关联目标知识库。系统提示词建议明确三条边界：

1
2
3

只根据检索到的资料回答。
资料不足时明确说明无法确认，不要补写事实。
回答时保留来源引用，涉及版本或日期时优先说明适用范围。

还应开启来源展示，并为“没有召回内容”的情况设置清晰提示。这样用户能区分“知识库没有资料”和“系统暂时调用失败”，也方便维护人员根据引用回到原文核对。

如果一个助手需要关联多个知识库，最好让它们使用同一个 Embedding 模型。对于新版制度和历史资料并存的场景，可以通过知识库级优先级让新资料优先参与回答，但仍应在文档元数据中保留版本和生效日期。

9. 上线前的工程检查

网络边界

不要直接把数据库、对象存储和检索引擎端口暴露到公网。对外只开放经过反向代理保护的 Web 入口，并启用 HTTPS、访问控制和必要的请求限制。

数据持久化

确认 Compose 使用的持久化目录和卷位于可监控的磁盘上。备份至少应覆盖业务数据库、对象文件以及恢复索引所需的配置和原始文档。执行任何会连同卷一起移除的容器命令前，必须先确认备份和恢复方案。

版本管理

固定 RAGFlow 镜像和仓库版本，升级前阅读发布说明。先在测试环境验证文档解析、检索结果和现有数据迁移，再安排生产升级。

可观测性

持续观察容器健康、解析任务积压、磁盘空间、检索延迟和模型调用失败率。回答变慢不一定是模型问题，也可能是解析队列堵塞、检索引擎压力或重排阶段耗时增加。

效果回归

维护一组固定问题及预期引用文本块。每次调整 Embedding 模型、分块策略、阈值或版本后，都重新跑一遍。RAG 系统的质量不是一次性验收，而是一套可以重复测量的工程过程。

10. 推荐的最小落地路径

如果是第一次搭建，可以把范围控制在下面五步：

用稳定版 Docker Compose 启动单机环境；
选择 10～20 份有代表性的文档建立试验知识库；
检查文本块，并准备 20 个真实业务问题；
先把召回调准，再配置回答提示词和对话模型；
建立固定测试集后，才开始批量导入和生产化加固。

这条路径的核心是先证明“正确资料能被稳定找到”，再优化回答风格。只要召回环节不可控，换更大的对话模型也只能让错误答案看起来更流畅。