RAGFlow 1.0 正式发布:如何从零部署一个支持文档问答的 AI 知识库?

数据与命令核对日期:2026-11-16,基于 RAGFlow 官方文档与 GitHub Release 说明(v1.0.0 GA)。价格、模型列表和端口配置可能随版本变化,部署前请以官方文档为准。

RAGFlow 1.0 于 2026 年 11 月 6 日正式发布(GA),官方明确宣布可用于生产环境,并建议所有用户升级。这个版本和以往的功能更新不太一样:整个系统用 Go 语言重写,定位从"端到端 RAG 引擎"升级为"Agent 原生数据库(Agent Native Database)",同时引入了 Agentic Chat 智能问答模式。

对正在搭建企业知识库、智能客服或私有化文档问答的团队来说,现在是一个比较好的入手时机。这篇文章不复述新闻,而是解决一个具体问题:从一台干净的 Linux 服务器开始,部署 RAGFlow 1.0,配置模型,上传文档,跑通第一个带引用来源的文档问答。

本文你能完成的事:

  1. 用 Docker Compose 部署 RAGFlow 1.0(Elasticsearch 文档引擎);
  2. 接入聊天模型和嵌入模型(官方 API 直连或兼容接口两条路,都会讲到);
  3. 创建数据集、解析文档、创建聊天助手,完成一次可溯源的文档问答。

一、RAGFlow 1.0 值得关注的几个变化

在动手部署前,先花两分钟了解这个版本改了什么,避免用旧版本的认知去踩新版本的坑。

1. Go 重写,部署形态变轻。 官方博客确认 1.0 完全使用 Go 重写,取代了此前的 Python 版本。据官方发布说明与公开报道,Docker 镜像体积缩小到原来的约十分之一,启动速度提升约十倍,并发能力提升约百倍(这几个数字来自官方口径,实际收益以你自己的硬件和负载为准)。对需要频繁扩缩容或多环境交付的团队,这意味着更低的部署成本。

2. 架构定位升级为 Agent Native Database。 1.0 不只做"检索后回答",而是把自己定位成 Agent Harness 可以直接调用的上下文供应层,提供知识编译(Wiki、Graph、Tree、Timeline 等结构化产物)、证据闸门等能力。简单说:以前它是"给模型喂碎片的检索后端",现在它试图做"Agent 时代的知识基础设施"。

3. Agentic Chat。 从 rc2 开始,聊天引入了智能体(Agentic)模式,支持多步推理、循环检索和证据充分性判断,取代了旧的思考等级设置。这对复杂文档问答场景有实际价值——答案不再依赖单次检索。

4. 升级与迁移路径明确。 从 v0.27.2 升级时,数据迁移会在 Docker 容器启动时自动完成;API 与 Python 版本保持兼容。如果你之前部署过旧版,升级成本不高。另外 1.0 开始提供 ARM64 架构的 Docker 镜像,ARM 服务器和苹果芯片设备也能直接部署。

5. 一个需要知道的限制。 官方文档明确:开源 1.0 版本中,DeepDoc 布局分析、OCR 和表格识别使用 CPU 推理。如果你的文档以扫描件 PDF、复杂表格为主,解析速度会受 CPU 性能影响,规划硬件时要把这一项算进去。


二、环境准备:这台机器至少需要什么

RAGFlow 是一套完整的服务栈(RAGFlow 服务 + Elasticsearch + MySQL + MinIO + Redis),不是单个二进制文件,硬件要求不低。

项目 最低要求 说明
CPU 4 核心(x86-64 或 ARM64) 本地模型和 OceanBase 引擎需要更多资源
内存 16 GB Elasticsearch 是内存大户,低于 16G 容易 OOM
磁盘 50 GB 剩余空间 镜像 + 文档解析产物 + 向量索引
Docker ≥ 24.0.0 需带 Docker Compose ≥ v2.26.1 和 BuildKit
网络 可拉取镜像 运行时需能访问聊天模型和嵌入模型的 API

如果你的文档引擎用默认的 Elasticsearch,还需要先确认内核参数 vm.max_map_count 至少为 262144,否则 ES 容器会启动失败:

# 查看当前值
sysctl vm.max_map_count

# 临时调整为 262144
sudo sysctl -w vm.max_map_count=262144

# 永久生效:写入 /etc/sysctl.conf
echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf

注意:sysctl -w 的修改重启后会丢失,生产环境务必写入 /etc/sysctl.conf。如果用的是 Docker Desktop,这个参数要设置到它的 Linux 虚拟机里,不是宿主机。


三、部署 RAGFlow 1.0:五个步骤

步骤 1:克隆仓库并检出发布标签

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

一定要检出发布标签,不要直接用 main 分支部署生产环境。docker/.env 中的 RAGFLOW_IMAGE 字段控制使用的镜像标签,git checkout v1.0.0 后它会自动指向 infiniflow/ragflow:v1.0.0,与你的主机架构(x86-64 或 ARM64)自动匹配。

步骤 2:检查关键配置(可选但建议)

docker/.env 文件控制几个重要选项:

  • DOC_ENGINE:文档引擎,默认 elasticsearch,可改为 infinity(Infinity 目前不支持 Linux/arm64);
  • SVR_WEB_HTTP_PORT:Web 访问端口,改动后浏览器访问时要带上端口;
  • 依赖服务的默认密码:部署到公网可达的机器前,务必修改默认密码,这一步官方文档有明确提示。

步骤 3:启动服务

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

首次启动会拉取镜像并初始化数据库迁移。v1.0 重写后启动速度明显变快,但第一次拉镜像的下载量仍然不小,耐心等待。

步骤 4:确认服务状态

docker ps
docker logs -f ragflow-cpu

初始化完成后,用健康检查接口确认服务真正就绪(注意:如果你的 curl 命令里 URL 是 http:// 开头加上机器 IP 或带端口,请按实际 .env 配置拼接,官方模板中该检查针对你部署机器的 Web 端口):

curl -f http://127.0.0.1/api/v1/system/healthz

返回 HTTP 200 表示就绪。建议等这个检查通过再打开 Web 界面,否则可能遇到页面能打开但接口报错的情况。

步骤 5:注册并登录

浏览器打开 http://你的机器IP(改过 SVR_WEB_HTTP_PORT 就带上端口),首次访问注册一个账号即可进入控制台。

到这里,RAGFlow 本体已经跑起来了。但注意——此时它还回答不了任何问题,因为没有接入模型。这是所有 RAGFlow 新手必经的一步,也是下一章的主题。


四、接入模型:官方 API 直连与统一接口两条路

RAGFlow 回答问题时依赖两类模型:

  • 聊天模型:生成最终答案;
  • 嵌入模型:把文档内容向量化,让检索成为可能。

两类模型都必须先在"用户设置 → 模型提供商"里配置并验证通过,否则后面建数据集、建聊天都会被卡住。

4.1 官方 API 直连(推荐先跑通这条路)

在模型提供商列表中选择你使用的厂商(如 DeepSeek、通义千问、OpenAI 等),填入对应的 API Key,添加模型并点击验证,最后在"设置默认模型"里分别指定默认聊天模型和默认嵌入模型。

这条路的优点是链路最短:RAGFlow 直接连模型厂商,少一层转发,出问题时排查对象只有两个——RAGFlow 配置和厂商服务。如果你的项目只用一家模型,直连通常就够了。

4.2 什么时候需要兼容接口(自定义 Provider)

真实项目里很快会遇到另一种情况:

  • 想在同一个 RAGFlow 实例里对比多家模型的问答效果,各自申请 Key、各自维护配置很分散;
  • 团队里多个 AI 项目(RAGFlow、Dify、自研 Agent 等)分别接不同模型,Key 和用量没法统一管理;
  • 需要频繁切换或灰度测试不同模型,不想每次都改一堆配置。

这时可以考虑用 RAGFlow 支持的 OpenAI-API-Compatible 自定义 Provider:它把任何兼容 OpenAI 协议的模型服务当成一个厂商来接入,配置字段和官方厂商一致——模型类型(聊天/嵌入)、模型名称、Base URL、API Key。

4.3 以 4SAPI 为例完成兼容接口配置

如果你需要这种统一接入的方式,可以用 4SAPI 这类兼容接口服务作为实际示例走一遍。4SAPI 在这里的角色是第三方模型 API 接入入口:把多个模型收敛到同一个 Base URL 和同一套 Key 管理下,RAGFlow 只需要把它当作一个 OpenAI 兼容厂商来填。

在 RAGFlow 中配置的步骤:

  1. 用户设置 → 模型提供商 → 选择 OpenAI-API-Compatible;
  2. 模型类型选 chat,添加聊天模型;再建一个类型为 embedding 的实例,添加嵌入模型;
  3. Base URL:从 4SAPI 当前控制台获取接口地址(不要照抄旧教程里的地址,以控制台实时显示为准);
  4. API Key:在 4SAPI 控制台创建密钥后填入,正文和演示环境都不要使用生产密钥;
  5. 模型名称:从 4SAPI 当前可用模型列表中复制准确的模型 ID,这一项最容易出错——填错模型名会直接 404 或 400;
  6. 点击验证,通过后在"设置默认模型"中指定。

配置完成后,先发一次最普通的问答验证文本链路。注意:普通文本请求成功,不代表流式输出、工具调用、多模态能力全部正常——OpenAI 兼容不等于所有参数和高级能力完全兼容,涉及 Agentic Chat 等高级模式时建议逐一验证。

适用边界要说清楚:如果你只使用单一模型、且依赖某厂商的原生高级功能(如特定多模态能力),官方直连仍然是最直接的选择。兼容接口的价值在于多模型统一管理,而不是替代官方直连。


五、创建知识库并跑通第一次文档问答

模型就绪后,按官方 10 分钟教程走四步。

5.1 创建数据集

  1. 导航栏选择数据集 → 创建数据集;
  2. 输入名称(如"产品手册"),选择嵌入模型——注意要在解析文档之前选好,之后换嵌入模型意味着重新解析;
  3. 解析模式选通用(General),保存。

5.2 上传并解析文档

  1. 进入数据集的文件页面 → 添加文件 → 上传文件;
  2. 上传时勾选创建时解析,保存;
  3. 等待解析完成,确认文档生成了切片(chunk)。

RAGFlow 的核心卖点是基于深度文档理解的解析,对 PDF 版式、表格的处理比简单按长度切分强不少。解析完成后建议点开文档查看切片:检查你关心的内容是否被完整、可读地切了出来。切分质量直接决定问答质量——"垃圾进,垃圾出"在 RAG 场景里是字面意义的。

如果解析失败,打开该文档的日志查看具体错误。

5.3 创建聊天助手

  1. 导航栏选择聊天 → 创建聊天;
  2. 打开聊天设置,在模型中选择聊天模型,在数据集中勾选刚建好的数据集;
  3. 展开高级设置,启用显示引用,保存。

5.4 提问并验证引用

在聊天窗口提问(确保答案在你上传的文档里),检查两件事:

  • 答案内容是否来自文档;
  • 点击答案中的引用编号,能否跳转到原文对应位置。

如果答案不符合预期,先别调模型,去数据集里用检索测试跑一下你的问题——如果检索阶段就找不到相关切片,问题在解析或切分,不在模型。

到这里,一个支持文档问答、带引用溯源的 AI 知识库就完整跑通了。


六、常见问题排查

Q1:Elasticsearch 容器启动失败,日志提示 max map count 相关错误

vm.max_map_count 没设置或没生效。回到第二章的命令重新设置;Docker Desktop 用户注意设置对象是 Linux 虚拟机。

Q2:模型下拉列表里没有可用的模型

模型没有在"用户设置 → 模型提供商"里添加,或添加了但验证未通过。检查 API Key 是否正确、是否有额度,兼容接口还要核对 Base URL 和模型 ID。如果用的是 4SAPI 这类兼容接口,出现 401 优先查 Key 和认证头格式,404 优先查 Base URL 路径和模型 ID 是否与当前文档一致,429 是限流或额度问题。

Q3:文档解析很慢或失败

开源 1.0 的 DeepDoc 布局分析、OCR、表格识别走 CPU 推理,扫描件 PDF 会明显偏慢,这是已知限制不是故障。解析失败先看文档日志:常见原因是加密 PDF、损坏文件或嵌入模型配置错误。

Q4:答案没有引用

检查三点:聊天设置里显示引用是否开启;关联的数据集里是否有已解析且启用的文档;用检索测试确认问题能命中内容。

Q5:页面打不开或接口报错

先跑 docker ps 看所有容器是否 Up,再跑健康检查接口。改过 SVR_WEB_HTTP_PORT 的,浏览器地址必须带端口。

Q6:从旧版本升级后数据不见了

从 v0.27.2 升级,数据迁移会在容器启动时自动完成,等迁移跑完即可;更早版本需要按官方文档手动迁移,不要直接覆盖数据目录。


七、总结与下一步

回顾一下这篇文章完成的链路:部署(Docker Compose + Elasticsearch)→ 接模型(官方直连或兼容接口)→ 建知识库(数据集 + 解析)→ 问答(带引用溯源)。

RAGFlow 1.0 的 Go 重写让部署门槛降低了不少,Agentic Chat 和知识编译能力让它不再只是"一个 RAG 前端"。但也要清楚它的适用边界:16G 内存起步的硬件要求、CPU 推理的解析速度,决定了它更适合团队级私有化知识库场景;如果只是个人几十个文档的轻量需求,还有更轻的选择。

关于模型接入的建议:单一模型用官方直连最省心;当你要对比多模型效果、或团队多个 AI 项目需要统一管理 Key 和用量时,再评估 4SAPI 这类兼容接口方案,接入前核对其协议支持、模型列表和计费方式是否符合你的需求。


参考来源:RAGFlow 官方文档(ragflow.com.cn/docs)、GitHub Release Notes v1.0.0(2026-11-06)、RAGFlow 官方博客。本文所有命令基于 v1.0.0,部署前请对照官方文档确认版本差异。

posted @ 2026-11-16 16:33  work-xinglian  阅读(5)  评论(0)    收藏  举报