快速上手

本章将带你从零完成一次端到端的 RAG 问答体验：从创建知识库到上传文档，再到与 LLM 进行基于文档内容的智能对话。跟随步骤操作，几分钟内即可感受 RAGFlow 的核心能力。

前置条件

在开始之前，请确保以下条件已满足：

条件	说明
RAGFlow 已部署且可访问	参考上一章「安装部署」完成部署，浏览器可正常打开 RAGFlow 界面
至少一个 LLM 已配置可用	系统需要关联大语言模型才能生成回复（可选在线 API 或本地 Ollama）

💡 提示

如果你还没有配置 LLM，可以先跳到本章「配置本地 LLM（Ollama）」章节完成配置，再回到步骤一开始操作。

步骤一：创建知识库

知识库是 RAGFlow 中组织和管理文档的基本单元。每个知识库可以包含多个文档，并使用统一的分块策略。

操作步骤

登录 RAGFlow 后，点击顶部导航栏中的 「知识库」 菜单项
在知识库列表页面，点击右上角的 「创建知识库」 按钮
在弹出的对话框中填写知识库名称（例如：产品文档）
点击 「确定」 完成创建

界面元素说明

顶部导航栏：页面最上方的菜单栏，包含「知识库」「对话」「Agent」等入口
创建知识库按钮：位于知识库列表页右上角，通常为蓝色按钮，带有 "+" 图标
知识库名称输入框：弹窗中的文本输入框，输入自定义名称即可

预期结果

✅ 创建成功后，页面自动跳转至该知识库的详情页面。你可以在左侧侧边栏看到新创建的知识库名称，详情页显示为空文档列表，等待你上传文件。

步骤二：上传文档

将需要进行问答的文档上传到知识库中。RAGFlow 支持 PDF、Word、Excel、TXT、Markdown 等多种格式。

操作步骤

在知识库详情页中，点击 「上传文件」 按钮（或将文件拖拽到上传区域）
在弹出的文件选择器中，选择你要上传的文档文件
等待文件上传完成，页面会显示上传进度

界面元素说明

上传文件按钮：位于知识库详情页的文档列表上方，点击后弹出系统文件选择器
拖拽上传区域：文档列表区域支持直接拖入文件
上传进度条：文件上传过程中显示的进度指示器

预期结果

✅ 上传完成后，文档出现在知识库的文件列表中，状态显示为 「待解析」 或自动开始解析。文件名、大小、上传时间等信息均正确显示。

步骤三：配置分块策略

分块（Chunking）是将长文档切分为适合检索的小段落的过程。合理的分块策略直接影响问答质量。

操作步骤

在知识库详情页中，点击左上角或顶部的 「配置」 图标/按钮进入知识库设置
找到 「分块方法」（Chunk Method） 配置区域
根据文档类型选择合适的分块方法：
- 通用（General）：适用于大多数文本文档（推荐初次使用）
- 简历（Resume）：适用于简历类结构化文档
- 表格（Table）：适用于 Excel 或包含大量表格的文档
可选调整分块参数（如 Token 数量上限等），初次使用保持默认即可
点击 「保存」 应用配置
回到文档列表，选中已上传的文档，点击 「解析」 按钮触发文档解析

界面元素说明

配置按钮/图标：通常是齿轮图标，位于知识库名称附近
分块方法选择器：下拉菜单或卡片式选项，展示可用的分块策略
解析按钮：文档列表中的操作按钮，点击后开始对文档进行分块处理

预期结果

✅ 点击解析后，文档状态变为 「解析中」，解析完成后状态变为 「已完成」。你可以点击文档查看分块结果，确认文档被正确切分为多个文本块。

步骤四：关联 LLM

RAGFlow 需要关联大语言模型来生成基于检索内容的回答。你可以使用在线 API（如 OpenAI、通义千问）或本地模型（如 Ollama）。

操作步骤

点击页面左下角的用户头像或系统设置入口
进入 「模型提供商」（Model Providers） 设置页面
找到你要使用的模型提供商（如 OpenAI、Ollama、通义千问等），点击 「添加」 或对应的配置按钮
填写必要信息：
- API 地址（Base URL）：模型服务的接口地址
- API Key：在线服务的密钥（本地 Ollama 无需填写）
- 模型名称：选择或输入要使用的具体模型
点击 「确定」 保存配置

界面元素说明

用户头像/设置入口：位于页面左下角，点击后展开设置菜单
模型提供商页面：展示所有已支持的 LLM 提供商列表（OpenAI、Ollama、DeepSeek 等）
API Key 输入框：用于填写服务密钥的文本框（密码类型，内容不可见）
模型名称选择器：下拉列表或输入框，指定要使用的模型版本

预期结果

✅ 配置保存后，模型提供商列表中对应项显示为 「已连接」 或绿色状态标识。你可以在对话创建时选择该模型作为回复引擎。

步骤五：发起对话

一切就绪后，创建一个对话助手并与文档内容进行智能问答。

操作步骤

点击顶部导航栏中的 「对话」 菜单项
点击 「创建助手」 按钮
在配置页面中：
- 输入助手名称（例如：产品文档问答）
- 选择关联的 LLM 模型
- 在 「知识库」 配置中勾选前面创建的知识库
点击 「确定」 完成创建
在对话界面底部的输入框中，输入一个与文档内容相关的问题，按回车发送

界面元素说明

对话菜单：顶部导航栏中的「对话」入口，点击进入对话管理页面
创建助手按钮：对话列表页面的新建按钮
知识库选择器：助手配置中的多选组件，可勾选一个或多个知识库
对话输入框：页面底部的文本输入区域，支持输入问题并发送

预期结果

✅ 发送问题后，RAGFlow 将检索知识库中的相关文档片段，结合 LLM 生成回答。回复内容中会标注引用来源，点击引用可查看原文出处。如果回答内容准确引用了你上传的文档内容，说明整个 RAG 流程已成功运行。

配置本地 LLM（Ollama）

如果你希望使用本地大语言模型而非在线 API，可以通过 Ollama 快速部署和集成。

Ollama 简介

Ollama 是一款本地大模型运行工具，支持 Llama 3、Qwen2、Mistral 等主流开源模型，无需 GPU 即可运行（CPU 推理较慢但可用）。

前置准备

安装 Ollama：访问 ollama.com 下载安装
拉取模型：

# 推荐模型（选择其一）
ollama pull qwen2
ollama pull llama3
ollama pull mistral

确认 Ollama 服务正在运行：

# 检查服务状态
curl http://localhost:11434/api/tags

如果返回 JSON 格式的模型列表，说明服务运行正常。

在 RAGFlow 中配置 Ollama

进入 RAGFlow 的 「模型提供商」 设置页面
找到 Ollama 选项，点击添加
填写配置信息：

配置项	值	说明
模型类型	Chat	选择对话模型类型
模型名称	`qwen2` 或 `llama3`	填写已通过 `ollama pull` 下载的模型名称
服务地址（Base URL）	`http://host.docker.internal:11434`	Docker 容器内访问宿主机的 Ollama 服务

⚠️ 服务地址说明

RAGFlow 部署在 Docker 中时：使用 http://host.docker.internal:11434（Docker 内部通过此地址访问宿主机服务）
RAGFlow 部署在同一宿主机上时：使用 http://localhost:11434 或 http://127.0.0.1:11434
Ollama 运行在其他机器上时：使用对应机器的 IP 地址，如 http://192.168.1.100:11434

点击 「确定」 保存

连接验证

配置保存后，验证连接是否成功：

RAGFlow 界面验证：保存后如果模型提供商显示为绿色连接状态，说明连接成功
手动验证：在终端执行以下命令，确认 Ollama 服务可达：

# 从 RAGFlow 容器内测试连接
docker exec -it docker-ragflow-cpu-1 curl http://host.docker.internal:11434/api/tags

# 或从宿主机直接测试
curl http://localhost:11434/api/tags

如果返回类似以下内容，说明服务正常且模型已加载：

{
  "models": [
    {
      "name": "qwen2:latest",
      "size": 4661211776,
      "details": { "format": "gguf", "family": "qwen2" }
    }
  ]
}

常见错误排查

LLM 连接失败

错误现象：

配置 LLM 后，对话时提示"模型连接失败"、"请求超时"或无法获取回复。

可能原因与解决方案：

原因	排查方式	解决方案
服务地址填写错误	检查 Base URL 是否正确、协议是否为 http	确认地址格式正确，Docker 环境使用 `host.docker.internal`
Ollama 服务未启动	终端执行 `curl http://localhost:11434/api/tags` 检查是否有响应	运行 `ollama serve` 启动服务
模型未下载	执行 `ollama list` 查看已下载模型	运行 `ollama pull <模型名>` 下载所需模型
网络不通（Docker 容器无法访问宿主机）	从容器内 `curl host.docker.internal:11434` 测试	确认 Docker 版本支持 `host.docker.internal`，Linux 用户可能需要使用 `--add-host` 参数
API Key 错误（在线服务）	检查密钥是否过期或额度用尽	前往服务商后台重新生成密钥或充值

💡 Linux Docker 用户注意

host.docker.internal 在 Linux 上需要 Docker 20.10+ 版本支持。如果无法使用，可以在 docker-compose.yml 中添加：

extra_hosts:
  - "host.docker.internal:host-gateway"

文档解析失败

错误现象：

上传文档后点击解析，状态长时间停留在「解析中」或直接变为「失败」。

可能原因与解决方案：

原因	排查方式	解决方案
文档格式不支持	确认文件格式是否在支持列表中（PDF、DOCX、XLSX、TXT、MD、HTML 等）	将文档转换为支持的格式后重新上传
文件过大	查看文件大小是否超过系统限制	拆分大文件为多个小文件分别上传
文件编码问题	纯文本文件（TXT）检查是否为 UTF-8 编码	使用文本编辑器将文件另存为 UTF-8 编码
PDF 为扫描件（纯图片）	打开 PDF 查看是否可以选中文字	使用 OCR 工具预处理扫描件，或等待 RAGFlow 内置 OCR 处理（速度较慢）
系统资源不足	执行 `docker stats` 查看容器资源使用情况	关闭其他程序释放内存，或增加 Docker 资源分配

📝 说明

RAGFlow 内置 DeepDoc 文档解析引擎，支持对复杂格式（如带表格的 PDF、多列排版文档）进行结构化解析。如果解析结果不理想，可以尝试切换分块策略或调整参数。

下一步

恭喜你完成了第一次 RAG 问答体验！你已经掌握了 RAGFlow 的核心使用流程。

接下来，你可以继续阅读「进阶功能」章节，了解：

🤖 Agentic 工作流的搭建与配置
🔌 HTTP API 接口的调用方式
📊 更多分块策略的选择与优化
🔧 MCP 协议支持与扩展

前置条件​

步骤一：创建知识库​

操作步骤​

界面元素说明​

预期结果​

步骤二：上传文档​

操作步骤​

界面元素说明​

预期结果​

步骤三：配置分块策略​

操作步骤​

界面元素说明​

预期结果​

步骤四：关联 LLM​

操作步骤​

界面元素说明​

预期结果​

步骤五：发起对话​

操作步骤​

界面元素说明​

预期结果​

配置本地 LLM（Ollama）​

Ollama 简介​

前置准备​

在 RAGFlow 中配置 Ollama​

连接验证​

常见错误排查​

LLM 连接失败​

文档解析失败​

下一步​

前置条件

步骤一：创建知识库

操作步骤

界面元素说明

预期结果

步骤二：上传文档

操作步骤

界面元素说明

预期结果

步骤三：配置分块策略

操作步骤

界面元素说明

预期结果

步骤四：关联 LLM

操作步骤

界面元素说明

预期结果

步骤五：发起对话

操作步骤

界面元素说明

预期结果

配置本地 LLM（Ollama）

Ollama 简介

前置准备

在 RAGFlow 中配置 Ollama

连接验证

常见错误排查

LLM 连接失败

文档解析失败

下一步