RAGFlow

RAGFlow 快速入门

「让企业把复杂格式的私有文档变成可溯源、能引用的问答上下文」——RAGFlow（infiniflow/ragflow）是一个开源 RAG（Retrieval-Augmented Generation，检索增强生成）引擎，核心是深度文档理解（deep document understanding）：它把 PDF/Word/Excel/PPT 等复杂排版文件解析成带可视化的知识块（chunk），允许人工干预分块结果，再与任意主流 LLM 组合成有出处的问答与 Agent。Apache-2.0，主语言 Go。2026-10-05 核验：GitHub 91,679★ / 10,890 fork，最近一次 push 为 2026-10-04，仍在高频迭代（2026-09-29 发布 1.0.0-rc1）。

这是什么？适合谁？

RAGFlow 补的是「企业私有知识 → 可信问答」链路里最容易被低估的一环：喂给模型的文本块质量。多数简易方案直接把长文档按固定字数切开就丢进向量库，遇到双栏 PDF、表格、扫描件时召回质量骤降；RAGFlow 先做版面与结构理解（模板化分块），把分块结果公开给你检查、手动加关键词或问题，再走多路召回 + Agent 编排。官方对它的定位是「面向任意规模企业的精简 RAG 工作流」，并且把 RAG 与 Agent 能力融合成一个给 LLM 用的「上下文层（context layer）」。

适合人群：

• 需要把内部手册、合同、论文、产品文档建成问答系统的企业技术团队
• 已经在用 LangChain / LlamaIndex 但被「文档解析质量」卡住，想换一套端到端可干预的方案
• 想要本地化部署、数据不出内网的知识库项目（可对接本地 Ollama/Xinference/LocalAI）

不适合谁：只需要几千字小量文本做快速问答、且不想维护 Docker 服务的个人用户（用托管云服务或轻量库更划算）；把 RAGFlow 当成「开箱即用的 SaaS」而完全不想看解析配置的团队。

准备工作

• 硬件：官方快速开始要求 x86 CPU ≥4 核、内存 ≥16 GB、磁盘 ≥50 GB（Docker 镜像约 2 GB，解包后运行占用约 7 GB）；官方正式支持 x86 CPU 与 Nvidia GPU
• 运行环境：Docker ≥24.0.0 与 Docker Compose ≥2.26.1（Linux 需先把 vm.max_map_count 调到 ≥262144）；ARM 平台需自行按官方文档构建镜像
• 模型：RAGFlow 自身是 RAG 引擎，必须搭配 LLM 才能问答——既可用云端 API（配置各家 API key），也可用 Ollama/Xinference/LocalAI 本地部署
• 时间预算：跑通「起服务 → 建数据集 → 解析文件 → 建对话」约 1-2 小时；调好解析模板视文档复杂度而定
• 前置知识：了解「分块 / 向量检索 / 召回」的基本概念，能读懂 Docker 命令

快速上手

第一步：起服务

克隆仓库并切到稳定版本（示例为文档写作时的 v0.25.5），用预构建镜像启动：

git clone https://github.com/infiniflow/ragflow.git
cd ragflow/docker
git checkout -f v0.25.5
docker compose -f docker-compose.yml up -d
docker logs -f docker-ragflow-cpu-1   # 看到 ASCII 启动字样才算就绪

预构建标签分 v0.25.5（稳定版）与 nightly（不稳定）两类。务必等启动日志确认就绪再登录，否则浏览器会报网络异常。

第二步：接入 LLM

浏览器访问 http://你的机器IP（默认 80 端口可省略），右上角进入 Model providers 填各家 API key，再到 System Model Settings 选定默认的对话模型、嵌入模型、图像转文字模型。嵌入模型一旦用于解析文件就不能再更换（必须保证同一数据集内所有文件在同一嵌入空间比较）。

第三步：建数据集并解析文件

进入 Dataset → Create dataset，选择嵌入模型与分块模板（模板要匹配文档版面与格式），上传文件后点解析。支持格式覆盖文档（PDF/DOC/DOCX/TXT/MD）、表格（CSV/XLSX/XLS）、图片（JPEG/PNG/TIF/GIF）与幻灯片（PPT/PPTX）。

第四步：检查并干预分块（RAGFlow 的关键一步）

解析完成后点进文件查看分块结果：悬停预览、双击文本块可手动加关键词或问题（提升含这些词的查询排序），必要时直接改写块内容。在 Retrieval testing 里用测试文本先验证召回是否命中，再往下走。

第五步：建对话助手

Chat → Create chat，指定助手要用的数据集、设定 System prompt、选对话模型。Empty response 是关键杠杆：填一段固定话术则回答被限定在数据集内（查不到就统一回复），留空则模型可能自行发挥、产生幻觉。

预期产出：一个能基于你私有文档作答、并给出引用出处的对话助手；据官方文档，其回答会附带可点击的引用来源。

常见踩坑

1. 文件解析卡在 1% 以下：官方 FAQ 有专门条目，多为资源配置或镜像环境问题；先对照官网 FAQ 排查，别反复重建容器。
2. 解析在接近完成时卡住但日志无报错：同样是官方 FAQ 收录的已知现象，按文档指引处理而非不断重试。
3. 中途想换嵌入模型：已用某嵌入模型解析过的数据集不允许更换——建库前就想清楚，否则要重建。
4. vm.max_map_count 没调：Linux 上低于 262144 会导致依赖 Elasticsearch 的服务异常，这是官方列出的前置步骤。
5. 把 nightly 当稳定版用：nightly 明确标注 unstable，生产环境请固定到 vX.Y.Z 稳定标签。
6. 留空 Empty response 导致幻觉：需要「只按数据集回答」时务必填写该字段，否则模型在检索不到时会自行编造。
7. 镜像体积误判：下载约 2 GB 是压缩后大小，运行时解包会膨胀到约 7 GB 以上，磁盘要按解包后预留。

常见问题 FAQ

Q1：RAGFlow 和 LangChain / LlamaIndex 是什么关系？

A：定位不同。后两者是「编排框架」，把解析、检索、模型调用串起来，解析质量取决于你接入的组件；RAGFlow 是端到端的 RAG 引擎，把「深度文档理解 + 模板化分块 + 可干预的知识块 + 多路召回 + Agent」内置为一体，官方强调它以「上下文引擎」直接服务 LLM。

Q2：必须自己配 LLM 吗？

A：是。RAGFlow 是 RAG 引擎，本身不生成答案，必须接入对话模型（云端 API 或本地 Ollama/Xinference/LocalAI 均可）。

Q3：能只在本地跑、不外传数据吗？

A：可以。全量本地部署 + 本地 LLM 即可做到数据不出内网；这也是它相对纯 SaaS 方案的主要卖点之一。

Q4：有没有不想自己运维的选项？

A：官方提供云服务 cloud.ragflow.io，可在本地试通后按需迁移。

Q5：许可证与商用？

A：Apache-2.0，可商用与二次开发（以仓库 LICENSE 为准）。

权限、安全、成本与限制

• 许可：Apache-2.0，允许商用与修改。
• 安全：自托管时数据留在你自己的服务器，风险主要在部署配置（Docker、内网暴露面）；若启用代码执行器（sandbox）功能，官方要求额外安装 gVisor。
• 成本：软件本身免费；成本来自服务器资源与所接 LLM 的调用费用（若用云端模型）。
• 限制：官方正式支持的镜像架构为 x86；ARM 需自行构建。本文基于 2026-10-05 抓取的官方 README、官方文档与 GitHub 仓库页撰写，未实际部署整套服务，具体行为以官网最新文档为准。

小技巧

1. 先用一小批最有代表性的复杂排版文档建数据集试解析，确认分块质量后再批量导入，避免一次性导入后才发现模板不合适。
2. 分块模板要按文档类型分别选——合同、论文、表格用同一套模板效果会明显变差。
3. 解析完先跑 Retrieval testing，把「召回不到」的问题在检索层解决，不要指望靠调 System prompt 兜底。
4. 需要「答不出就说不知道」的场景，一定要设 Empty response，这是最省心的反幻觉开关。
5. 把稳定版本号写进部署脚本，别用 latest/nightly 漂移。

进阶学习方向

• Agentic Retrieval 与思考档位：官方已引入 Low/Medium/High/Ultra 多档「Agentic RAG」，模型会自行拆解复杂问题、分步检索并验证证据——复杂问答场景值得单独调这一环。
• Knowledge Compilation：可在文档与数据集两级把内容编译成 Wiki、Graph、Tree、PageIndex、思维导图、时间线、Skills 等结构化产物，适合做知识资产的二次组织。
• 数据源接入：除本地文件外已支持网站 sitemap 抓站、Google BigQuery 增量同步等，可把「知识源」从文件扩展到业务系统。
• 组合链路：RAGFlow（知识召回）→ 你的 LLM（生成）→ 业务前端，是它最典型的落地路径；把分块质量做扎实，后面每一步都省事。

参考链接

• 官方网站
• 官方文档
• 快速开始
• GitHub 仓库
• 官方云服务