RAGFlow 实战(一):RAGFlow 是什么、适合什么场景,以及 Docker Compose/Helm 部署方式

这是「RAGFlow 实战」系列的第一篇。先把 RAGFlow 放到一个可操作的位置上：它不是一个大模型，也不是一个单纯的向量库，而是一套把文档变成可检索、可问答、可引用知识库的 RAG 引擎。

如果你只是想调用一个 LLM API，RAGFlow 不是必需品；如果你有大量 PDF、Word、Excel、网页、扫描件，想把它们解析、切块、索引，再做带引用来源的问答，RAGFlow 才开始有价值。

本文基于 RAGFlow 0.26.2 文档整理。所有域名、Key、模型名、Provider 实例名都用占位符表示，照抄时换成你自己的环境。

环境

项目	值
RAGFlow	0.26.2
推荐部署入口	Docker Compose
官方支持平台	x86 CPU / Nvidia GPU
最低资源	CPU 4 核、内存 16 GB、磁盘 50 GB
Docker	24.0.0+
Docker Compose	v2.26.1+
Python	3.13+

RAGFlow 官方 Quickstart 对 0.26.2 的定位很明确：它是基于 deep document understanding 的开源 RAG 引擎，接入 LLM 后，可以基于复杂格式数据给出带引用依据的问答结果。官方 Quickstart 覆盖的主流程也是四步：启动本地服务、创建 Dataset、干预文件解析、基于 Dataset 建 Chat。

这句话翻译成工程语言就是：

文档 -> 解析 -> 切块 -> 向量化 -> 索引 -> 检索 -> 交给 LLM 回答 -> 返回引用

RAGFlow 主要解决中间这一整段，而不是替代 LLM。

图里最关键的是第 ② 到第 ⑤ 步。很多 RAG demo 只写“把文档切成 chunk 存向量库”，真正上线时最容易翻车的却是文档解析、表格/图片/扫描件理解、chunk 是否可解释、embedding 是否跑通、检索结果是否能追溯。

一、RAGFlow 到底是什么

RAGFlow 可以拆成四层理解。

第一层：文档解析和知识抽取

RAGFlow 面向的是复杂非结构化数据，不只是纯文本。官方 README 列出的数据形态包括 Word、slides、Excel、txt、images、scanned copies、structured data、web pages 等。

这也是它和一个“向量库 + 几行 LangChain 代码”的区别：向量库负责存和查，RAGFlow 还要管文档怎么读、怎么切、怎么让人看得懂切块结果。

第二层：Dataset 和 chunk 管理

在 RAGFlow 里，Dataset 是知识库的核心边界。你上传文件后，系统会按解析策略生成 chunk，再对 chunk 做 embedding 和索引。

这一步决定了后面的问答质量：

chunk 太碎，答案缺上下文；
chunk 太大，召回噪声变多；
表格解析错，后面再强的 LLM 也只能基于错误内容回答；
embedding 没配置好，Dataset 状态会失败，Chat 自然找不到答案。

第三层：检索、重排和引用

RAGFlow 的目标不是只把最相似的几段文本塞给 LLM。它还包含多路召回、重排、引用可视化、chunk 可干预等能力。

这类能力对企业知识库很重要，因为用户真正关心的是：

这个答案依据哪几页？
引用的是哪个文件？
检索为什么没命中？
能不能手工调整 chunk？

RAGFlow 把这些问题放到了产品和 API 层，而不是让你每次都自己写后台管理页。

第四层：Chat、Agent 和 API

Dataset 做好以后，还要有一个对外入口。RAGFlow 提供 Chat app、Agent、OpenAI-compatible API、iframe 集成等方式。

对接业务系统时，通常不是直接让用户进 RAGFlow 后台，而是：

业务系统 -> RAGFlow Chat API -> 检索 Dataset -> LLM 生成答案 -> 业务系统展示

这就是为什么部署完成后，除了页面能打开，还要验证 /api/v1/chats、/api/v1/retrieval、/api/v1/openai/{chat_id}/chat/completions 这些接口。

二、适合什么应用场景

RAGFlow 适合“文档多、格式复杂、需要引用依据”的场景。

企业知识库问答

典型输入是制度文档、SOP、FAQ、会议纪要、产品手册、运维手册。业务诉求不是“让模型自由发挥”，而是“只能基于知识库回答，并且能指出出处”。

适合用 RAGFlow 的原因：

文档经常更新，需要重新解析和索引；
用户会问跨文档问题；
答案要带引用，方便人工核对；
后台需要看解析日志、chunk 和命中情况。

技术文档和客服助手

产品文档、API 文档、错误码手册、工单知识库都适合做成 RAGFlow Dataset。

这类场景最怕两件事：

LLM 胡编不存在的参数；
文档明明有答案，但检索没有命中。

RAGFlow 的 chunk 可视化、引用和 retrieval API 可以帮助定位这类问题。

合同、合规、财务和审计资料检索

这类文档通常长、格式复杂、表格多、脚注多，而且回答必须能回到原文依据。

RAGFlow 的价值不在于“让模型更聪明”，而在于把文档结构尽量保留下来，再把答案和原文引用连起来。

研发和运维团队助手

运维 SOP、故障复盘、发布规范、Runbook、服务目录、告警处理手册，都可以先进入 Dataset，再接 Chat app 或 API。

对这类场景，建议从小 Dataset 开始：

10 个高频 SOP -> 解析成功 -> Chat 命中 -> API 接入 -> 再扩大文档范围

不要第一天就把所有历史文档塞进去。RAG 系统的质量问题通常不是“文档不够多”，而是“文档太乱、chunk 不对、召回不可控”。

三、不适合什么场景

不是所有 AI 问答都该上 RAGFlow。

只有提示词，没有私有知识库

如果你的需求只是：

把这段文本总结一下
把这个 JSON 改成表格
帮我写一段代码

直接调 LLM API 就够了。RAGFlow 的 Dataset、解析、索引、检索链路反而会增加复杂度。

数据本来就在结构化数据库里

如果答案来自 MySQL、ClickHouse、PostgreSQL 这类结构化表，优先考虑 SQL、BI、指标平台或 text-to-SQL。

RAGFlow 可以处理结构化数据文件，但它不是数据库查询引擎。不要把明确的聚合查询绕成“先导出文件再 RAG 问答”。

文档权限极其细

如果每个用户只能看很细粒度的一部分文档，部署前要先设计权限模型。RAGFlow 可以作为知识库和问答层，但你的业务系统仍然要控制用户能访问哪个 Dataset、哪个 Chat app、哪个文件范围。

权限模型没想清楚就接入，很容易出现“检索命中了用户不该看到的 chunk”。

四、部署方式怎么选

RAGFlow 有几种常见部署路线。

部署方式	适合场景	重点
Cloud	快速试用、功能验证	少运维，但数据和网络要看合规要求
Docker Compose	本机、测试环境、小规模自托管	最推荐的起步方式
Docker Compose + 反向代理	内网测试服务、团队试用	要处理域名、HTTPS、文件上传大小、超时
Kubernetes / Helm	生产化、多环境、资源隔离	要单独设计存储、数据库、升级和观测
源码或自建镜像	ARM、私有基础镜像、深度定制	成本最高，适合有明确约束时使用

我的建议是：

先用 Docker Compose 跑通一条完整链路；
再考虑反向代理、持久化、备份、监控；
最后才上 Kubernetes。

RAGFlow 不是只有一个容器。它依赖数据库、对象存储、缓存、文档引擎等组件。还没理解这些依赖前，直接上 K8s 只会把排查面扩大。

五、Docker Compose 最小部署路径

官方自托管路径的核心命令很短。

1. 准备系统参数

RAGFlow 0.26.2 使用 Elasticsearch 或 Infinity 做多路召回。使用 Elasticsearch 时，vm.max_map_count 太低会导致 ES 异常。

Linux 上先查：

sysctl vm.max_map_count

如果低于 262144，临时调整：

sudo sysctl -w vm.max_map_count=262144

持久化写入 /etc/sysctl.conf：

vm.max_map_count=262144

2. 拉代码并选择版本

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

git checkout v0.26.2

这里建议固定版本，避免代码和镜像入口脚本不一致。如果要换版本，优先改 docker/.env 里的 RAGFLOW_IMAGE，并让本地代码 tag 和镜像 tag 对齐。

3. CPU 模式启动

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

启动后看日志：

docker logs -f docker-ragflow-cpu-1

不要容器刚起来就立刻登录页面。RAGFlow 初始化依赖服务需要时间，过早访问可能看到 network abnormal 这类前端提示。

4. GPU 模式启动

如果要让 GPU 加速 DeepDoc 任务，可以在 .env 前面加入：

sed -i '1i DEVICE=gpu' .env
docker compose -f docker-compose.yml up -d

这不是“让 LLM 在本机 GPU 上跑”的意思。这里的 GPU 主要用于文档解析相关任务。LLM 和 embedding 仍然可以走外部模型 API，也可以按你的环境接本地模型服务。

5. 访问页面

默认 HTTP 端口是 80。没有改配置时，浏览器访问：

http://<SERVER_IP>

如果要改默认 HTTP 端口，看 docker-compose.yml 里的端口映射，把 80:80 改成：

<YOUR_SERVING_PORT>:80

配置改完要重启容器才生效。

六、部署后先看哪几个配置文件

RAGFlow Docker 部署最常接触这几个文件：

文件	作用
`.env`	Docker 环境变量，比如端口、密码、镜像、资源限制
`service_conf.yaml.template`	RAGFlow 后端服务配置模板，容器启动时生成实际配置
`docker-compose.yml`	RAGFlow 应用服务入口
`docker-compose-base.yml`	MySQL、MinIO、Redis、Elasticsearch/Infinity 等依赖

不要一上来就改很多文件。第一天只确认三件事：

容器都健康
页面能登录
能创建 Dataset 并解析一个小文件

其他如域名、HTTPS、对象存储外置、MySQL 外置、注册开关、模型默认值，都等最小链路跑通后再改。

七、Kubernetes / Helm 什么时候再上

RAGFlow 在 v0.15.0 release notes 里已经提到支持 Helm chart，用于 Kubernetes 部署。

但我不建议把 Helm 作为第一步，除非你已经明确需要这些能力：

多环境统一发布；
资源配额和隔离；
统一接入集群存储、Ingress、Secret、监控；
应用和依赖组件分开运维；
有现成的 K8s 运维体系。

否则 Docker Compose 更适合学习 RAGFlow 本身。先把 Dataset、chunk、embedding、Chat app、API 都跑通，再迁移部署形态，排查成本会低很多。

八、第一天上线检查清单

部署完成后，不要只看“页面能打开”。按下面顺序验证：

1. 容器和日志

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

确认没有数据库、对象存储、文档引擎连接错误。

2. 模型 Provider

进入页面：

User settings -> Model providers

至少配置：

LLM       -> <CHAT_MODEL> <PROVIDER_INSTANCE>
Embedding -> <EMBEDDING_MODEL> <PROVIDER_INSTANCE>

普通知识库问答优先保证 LLM 和 Embedding 通。VLM、ASR、Rerank、TTS 可以后面再接。

3. Dataset 解析

先上传一个 1 KB 到 10 KB 的小文本文件，不要第一步就传大 PDF。

成功标准：

Status = Success
Chunks > 0

只要 Chunks = 0，就不要继续调 Chat。先看文件解析日志。

4. Chat app 绑定 Dataset

创建 Chat app 后，要确认它绑定了 Dataset。API 上可以查：

curl -sS 'http://<RAGFLOW_HOST>/api/v1/chats?page=1&page_size=30' \
  -H 'Authorization: Bearer <RAGFLOW_API_KEY>'

返回里至少要看到：

{
  "dataset_ids": ["<DATASET_ID>"],
  "kb_names": ["<DATASET_NAME>"]
}

如果 dataset_ids 是空，Chat app 就不会基于这个知识库回答。

5. API 调用

最后再测 OpenAI-compatible Chat Completions：

curl -sS -X POST \
  'http://<RAGFLOW_HOST>/api/v1/openai/<CHAT_ID>/chat/completions' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <RAGFLOW_API_KEY>' \
  -d '{
    "model": "<CHAT_MODEL>@<PROVIDER_INSTANCE>@OpenAI",
    "messages": [
      {"role": "user", "content": "总结一下上传文件的内容"}
    ],
    "stream": false,
    "extra_body": {
      "reference": true
    }
  }'

这一条能通，才算完成了从部署到业务接入的第一条最小链路。

九、和下一篇的关系

第一篇讲的是完整链路。真正落地时，最常见的坑不是页面打不开，而是：

LLM Verify 通过
Chat 能问普通问题
Dataset 一解析就失败
报错在 embedding

这就是系列第二篇要解决的问题：RAGFlow 0.26.2 接 OpenAI-compatible 网关时，Base-Url 应该填到哪里，embedding endpoint 怎么先用 curl 验证，Chat app 的 chat_id 又从哪里来。

快速参考

RAGFlow 是：

面向复杂文档的 RAG 引擎
负责解析、切块、embedding、索引、检索、引用、Chat/API
不负责替代 LLM 本身

最小资源：

CPU >= 4 cores
RAM >= 16 GB
Disk >= 50 GB
Docker >= 24.0.0
Docker Compose >= v2.26.1
Python >= 3.13

Docker Compose 启动：

git clone https://github.com/infiniflow/ragflow.git
cd ragflow/docker
git checkout v0.26.2
sudo sysctl -w vm.max_map_count=262144
docker compose -f docker-compose.yml up -d

第一天检查：

容器健康
页面可登录
LLM 和 Embedding 配好
Dataset 解析成功且 Chunks > 0
Chat app 绑定 Dataset
API 能返回答案和引用

参考资料：

RAGFlow Quickstart：https://ragflow.io/docs/
RAGFlow GitHub README：https://github.com/infiniflow/ragflow
RAGFlow Configuration：https://ragflow.io/docs/configurations
RAGFlow Release notes：https://ragflow.io/docs/release_notes

posted @ 2026-06-30 21:22 Hello_worlds 阅读(19) 评论(0) 收藏举报

刷新页面返回顶部

大军军军之技术落地

责人之心责己、恕己之心恕人