快速入门

RAGFlow 是一款基于深度文档理解的开源 RAG（检索增强生成）引擎。通过与大语言模型（LLM）结合，它能够提供真实可靠的问答能力，并辅以来自各种复杂格式数据的严谨引用。

本快速入门指南介绍了从以下步骤开始的通用流程：

• 启动本地 RAGFlow 服务器，
• 创建数据集，
• 干预文件解析，直到
• 建立基于您的数据集的 AI 聊天。

重要提示

我们官方支持 x86 CPU 和 Nvidia GPU，本文档提供了在 x86 平台上使用 Docker 部署 RAGFlow 的说明。虽然我们也正在 ARM64 平台上测试 RAGFlow，但我们暂不维护 ARM 版本的 RAGFlow Docker 镜像。

如果您使用的是 ARM 平台，请参考本指南来构建 RAGFlow Docker 镜像。

前提条件

• CPU ≥ 4 核 (x86)；
• 内存 ≥ 16 GB；
• 磁盘空间 ≥ 50 GB；
• Docker ≥ 24.0.0 且 Docker Compose ≥ v2.26.1。
• gVisor：仅在您打算使用 RAGFlow 的代码执行器（sandbox）功能时才需要。

注意

如果您尚未在本地机器（Windows、Mac 或 Linux）上安装 Docker，请参阅安装 Docker Engine。

启动服务器

本节提供了在 Linux 上设置 RAGFlow 服务器的说明。如果您使用的是其他操作系统，也不必担心，大部分步骤都是相似的。

1. 确保 vm.max_map_count ≥ 262144。

展开查看详情

vm.max_map_count。此值设置进程可能拥有的最大内存映射区域数。其默认值为 65530。虽然大多数应用程序需要的映射少于一千个，但降低此值可能会导致异常行为，并且当进程达到限制时系统将抛出内存不足错误。

RAGFlow v0.23.0 使用 Elasticsearch 或 Infinity 进行多路召回。正确设置 vm.max_map_count 的值对于 Elasticsearch 组件的正常运行至关重要。

Linux

1.1. 检查 vm.max_map_count 的值

$ sysctl vm.max_map_count

1.2. 如果该值不足 262144，请将其重置为至少 262144。

$ sudo sysctl -w vm.max_map_count=262144

警告

此更改在系统重启后会被重置。如果您下次启动服务器时忘记更新该值，可能会遇到 Can't connect to ES cluster 异常。

1.3. 要确保更改永久生效，请在 /etc/sysctl.conf 中相应地添加或更新 vm.max_map_count 值

vm.max_map_count=262144

macOS

如果您在带有 Docker Desktop 的 macOS 上，请运行以下命令来更新 vm.max_map_count

docker run --rm --privileged --pid=host alpine sysctl -w vm.max_map_count=262144

警告

此更改在系统重启后会被重置。如果您下次启动服务器时忘记更新该值，可能会遇到 Can't connect to ES cluster 异常。

要使更改持久化，请创建具有适当设置的文件

1.1. 创建文件

sudo nano /Library/LaunchDaemons/com.user.vmmaxmap.plist

1.2. 打开文件

sudo launchctl load /Library/LaunchDaemons/com.user.vmmaxmap.plist

1.3. 添加设置

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.user.vmmaxmap</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/sbin/sysctl</string>
        <string>-w</string>
        <string>vm.max_map_count=262144</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>

1.4. 保存文件后，加载新的守护程序

sudo launchctl load /Library/LaunchDaemons/com.user.vmmaxmap.plist

注意

如果上述步骤不起作用，请考虑使用此解决方法，它采用容器方式，不需要手动编辑 macOS 设置。

Windows

如果您是在 Windows 上使用 Docker Desktop，则必须使用 docker-machine 来设置 vm.max_map_count：

$ docker-machine ssh
$ sudo sysctl -w vm.max_map_count=262144

如果您是在 Windows 上使用 Docker Desktop WSL 2 后端，则使用 docker-desktop 来设置 vm.max_map_count：

1.1. 在 WSL 中运行以下命令

$ wsl -d docker-desktop -u root
$ sysctl -w vm.max_map_count=262144

警告

重启 Docker 后，此更改将被重置。如果您下次启动服务器时忘记更新该值，可能会遇到 Can't connect to ES cluster 异常。

1.2. 如果您不想在每次重启 Docker 时都运行这些命令，可以按如下方式更新 %USERPROFILE%.wslconfig，以保持更改永久生效并在所有 WSL 发行版中全局适用

[wsl2]
kernelCommandLine = "sysctl.vm.max_map_count=262144"

这会导致所有 WSL2 虚拟机在启动时都被分配该设置。

注意

如果您使用的是 Windows 11 或 Windows 10 版本 22H2，并安装了 Microsoft Store 版本的 WSL，您还可以更新 docker-desktop WSL 发行版中的 /etc/sysctl.conf 以保持更改永久生效

$ wsl -d docker-desktop -u root
$ vi /etc/sysctl.conf

# Append a line, which reads: 
vm.max_map_count = 262144

2. 克隆仓库

   $ git clone https://github.com/infiniflow/ragflow.git
   $ cd ragflow/docker
   $ git checkout -f v0.23.0

3. 使用预构建的 Docker 镜像并启动服务器

   # Use CPU for DeepDoc tasks:
   $ docker compose -f docker-compose.yml up -d

   RAGFlow 镜像标签	镜像大小 (GB)	是否稳定？
   v0.23.0	≈2	稳定发行版
   nightly	≈2	不稳定的每日构建版本

   注意

   显示的镜像大小是指已下载的 Docker 镜像大小（压缩后）。当 Docker 运行镜像时，它会进行解压，导致磁盘占用显著增加。解压后，Docker 镜像将扩展到约 7 GB。

4. 启动并运行服务器后检查服务器状态

   $ docker logs -f docker-ragflow-cpu-1

   以下输出确认系统已成功启动

        ____   ___    ______ ______ __
       / __ \ /   |  / ____// ____// /____  _      __
      / /_/ // /| | / / __ / /_   / // __ \| | /| / /
     / _, _// ___ |/ /_/ // __/  / // /_/ /| |/ |/ /
    /_/ |_|/_/  |_|\____//_/    /_/ \____/ |__/|__/
   
    * Running on all addresses (0.0.0.0)

   重要提示

   如果您跳过此确认步骤并直接登录 RAGFlow，您的浏览器可能会提示 network anomaly（网络异常）错误，因为此时您的 RAGFlow 可能尚未完全初始化。

5. 在 Web 浏览器中，输入服务器的 IP 地址并登录 RAGFlow。

   警告

   使用默认设置时，您只需输入 http://IP_OF_YOUR_MACHINE（不含端口号），因为在使用默认配置时可以省略默认的 HTTP 服务端口 80。

配置 LLM

RAGFlow 是一个 RAG 引擎，需要与 LLM 配合使用才能提供基于事实、无幻觉的问答能力。RAGFlow 支持大多数主流 LLM。有关支持模型的完整列表，请参考支持模型。

注意

RAGFlow 还支持使用 Ollama、Xinference 或 LocalAI 在本地部署 LLM，但本快速入门指南不涵盖这部分内容。

添加和配置 LLM

1. 点击页面右上角的头像 > 模型提供商。

2. 点击所需的 LLM 并相应地更新 API Key。

3. 点击 系统模型设置 来选择默认模型

   • 对话模型，
   • 嵌入模型，
   • 多模态模型，
   • 以及更多。

某些模型（如多模态模型 qwen-vl-max）隶属于特定的 LLM。您可能需要更新 API Key 才能访问这些模型。

创建您的第一个数据集

您可以向 RAGFlow 中的数据集上传文件并将其解析。一个数据集实际上是文件的集合。RAGFlow 中的问答可以基于特定数据集或多个数据集。RAGFlow 支持的文件格式包括文档（PDF、DOC、DOCX、TXT、MD、MDX）、表格（CSV、XLSX、XLS）、图片（JPEG、JPG, PNG、TIF、GIF）和幻灯片（PPT、PPTX）。

创建您的第一个数据集

1. 点击页面中上部的 数据集 选项卡 > 创建数据集。

2. 输入数据集的名称，然后点击 确定 确认更改。

   您将被带到数据集的 配置 页面。

   

3. RAGFlow 提供多种切片模板，以适应不同的文档布局和文件格式。为您的数据集选择嵌入模型和解析方法（模板）。

   重要提示

   一旦您选择了嵌入模型并使用它解析了文件，就不再允许更改它。显而易见的原因是，我们必须确保特定数据集中的所有文件都使用相同的嵌入模型进行解析（确保它们在相同的向量空间中进行比较）。

   您将被带到数据集的 文件 列表页面。

4. 点击 + 添加文件 > 本地文件 开始将特定文件上传到数据集。

5. 在上传的文件条目中，点击播放按钮开始文件解析

   

   注意

   • 如果您的文件解析卡在 1% 以下，请参阅此常见问题。
   • 如果您的文件解析在接近完成时卡住，请参阅此常见问题

干预文件解析

RAGFlow 具有可见性和可解释性，允许您查看切片结果并在必要时进行干预。操作方法如下：

1. 点击完成解析的文件以查看切片结果

   您将被带到 切片 页面

   

2. 将鼠标悬停在每个快照上以快速查看每个切片。

3. 双击切片文本以添加关键词或在必要时进行手动修改

   

   注意

   您可以为文件切片添加关键词或问题，以提高其在包含这些关键词的查询中的排名。此操作会增加其关键词权重，并能提升其在搜索列表中的位置。

4. 在“检索测试”中，在 测试文本 中输入一个简短问题，以再次检查您的配置是否生效

   如下所示，RAGFlow 会提供带有真实引用的回复。

   

设置 AI 聊天

RAGFlow 中的对话基于特定数据集或多个数据集。创建完数据集并完成文件解析后，您就可以开始 AI 对话了。

1. 点击页面中上部的 聊天 选项卡 > 创建助理 来创建一个聊天助手。

2. 点击创建的聊天应用进入其配置页面。

   RAGFlow 提供了为每个对话选择不同聊天模型的灵活性，同时允许您在 系统模型设置 中设置默认模型。

3. 更新配置页面右侧的 提示词设置

   • 命名您的助手并指定关联的数据集。
   • 空回复:
     • 如果您希望将 RAGFlow 的回答局限于您的高质量数据，请在此处填写回复。这样当它检索不到答案时，它会统一以此处设置的内容进行回复。
     • 如果您希望 RAGFlow 在无法从数据集检索到答案时进行即兴发挥，请保持此处为空，但这可能会导致幻觉产生。

4. 更新 提示词，或者在开始时保持原样。

5. 在 模型 下拉列表中选择一个聊天模型。

6. 现在，让我们开始对话

   

注意

RAGFlow 还提供 HTTP 和 Python API，以便您将 RAGFlow 的能力集成到您的应用程序中。阅读以下文档获取更多信息：

• 获取 RAGFlow API 密钥
• HTTP API 参考
• Python API 参考