跳转到主内容

常见问题

关于通用功能、故障排除、使用方法等问题的解答。

通用功能

RAGFlow 与其他 RAG 产品有何不同？

尽管大语言模型（LLM）显著推进了自然语言处理（NLP），但“垃圾进，垃圾出”的现状仍未改变。RAGFlow 引入了两个区别于其他检索增强生成（RAG）产品的独特功能作为回应：

  • 细粒度的文档解析：文档解析涉及图像和表格，并支持人工在必要时进行干预。
  • 答案可追溯、减少幻觉：RAGFlow 的回答值得信任，因为你可以查看支撑答案的引用和参考文献。

哪些嵌入模型可以本地部署？

从 v0.22.0 开始，我们仅提供精简版（slim），并且不再为镜像标签附加 -slim 后缀。

在哪里可以找到 RAGFlow 的版本号？如何解读它？

你可以在 UI 界面的系统页面找到 RAGFlow 的版本号。

Image

如果你是从源码构建 RAGFlow，版本号也会显示在系统日志中。

        ____   ___    ______ ______ __               
       / __ \ /   |  / ____// ____// /____  _      __
      / /_/ // /| | / / __ / /_   / // __ \| | /| / /
     / _, _// ___ |/ /_/ // __/  / // /_/ /| |/ |/ / 
    /_/ |_|/_/  |_|\____//_/    /_/ \____/ |__/|__/                             

2025-02-18 10:10:43,835 INFO     1445658 RAGFlow version: v0.15.0-50-g6daae7f2

其中：

  • v0.15.0：官方发布的发行版本。
  • 50：自官方发布以来的 git 提交次数。
  • g6daae7f2：g 是前缀，6daae7f2 是当前提交 ID 的前七位字符。

为什么不使用其他开源向量数据库作为文档引擎？

目前，只有 Elasticsearch 和 Infinity 能满足 RAGFlow 的混合搜索需求。大多数开源向量数据库对全文检索的支持有限，且稀疏向量（sparse embedding）并不能替代全文检索。此外，这些向量数据库缺乏 RAGFlow 必需的关键功能，例如短语搜索（phrase search）和高级排序能力。

这些限制促使我们从头开始开发了 AI 原生数据库 Infinity。

demo.ragflow.io 与本地部署的开源 RAGFlow 服务有何区别？

demo.ragflow.io 展示的是 RAGFlow 企业版的能力。它的 DeepDoc 模型使用了专有数据进行预训练，并提供了更复杂的团队权限控制。本质上，demo.ragflow.io 是 RAGFlow 即将推出的 SaaS（软件即服务）产品的预览版。

你可以部署开源版 RAGFlow 服务并通过 Python 客户端或 RESTful API 进行调用，但 demo.ragflow.io 不支持这些操作。

为什么 RAGFlow 解析文档的时间比 LangChain 长？

我们在文档预处理任务上投入了大量精力，例如使用视觉模型进行布局分析、表格结构识别和 OCR（光学字符识别）。这些处理步骤增加了所需的时间。

为什么 RAGFlow 比其他项目需要更多的资源？

RAGFlow 内置了多个用于文档结构解析的模型，这是消耗额外计算资源的主要原因。

RAGFlow 支持哪些架构或设备？

我们官方支持 x86 CPU 和 NVIDIA GPU。虽然我们也在 ARM64 平台上测试 RAGFlow，但并不维护 ARM 版的 RAGFlow Docker 镜像。如果你使用的是 ARM 平台，请参考此指南自行构建 RAGFlow Docker 镜像。

你们是否提供与第三方应用程序集成的 API？

相应的 API 已经发布。请参阅 RAGFlow HTTP API 参考或 RAGFlow Python API 参考获取更多信息。

你们支持流式输出吗？

支持。流式输出在聊天助手和 Agent 中默认开启。请注意，无法通过 RAGFlow UI 禁用流式输出。如需在响应中禁用流式输出，请使用 RAGFlow 的 Python SDK 或 RESTful API。

Python

RESTful

你们支持通过 URL 分享对话吗？

不，目前不支持此功能。

你们支持多轮对话吗？即将之前的对话作为当前查询的上下文引用？

支持。我们支持基于正在进行的对话上下文来增强用户查询。

  1. 在聊天页面，将鼠标悬停在所需的助手上，并选择编辑。
  2. 在聊天配置弹出窗口中，点击提示词引擎页签。
  3. 开启多轮对话优化以启用此功能。

AI 搜索和聊天之间的主要区别是什么？

  • AI 搜索：这是一种单轮 AI 对话，使用预定义的检索策略（加权关键词相似度和加权向量相似度的混合搜索）以及系统的默认聊天模型。它不涉及高级 RAG 策略（如知识图谱、自动关键词或自动提问）。检索到的切片会列在聊天模型响应的下方。
  • AI 聊天：这是一种多轮 AI 对话，你可以定义检索策略（例如使用加权重排分数替代混合搜索中的加权向量相似度）并选择聊天模型。在 AI 聊天中，你可以针对具体案例配置高级 RAG 策略（如知识图谱、自动关键词和自动提问）。检索到的切片不会随答案一起显示。

调试聊天助手时，你可以使用 AI 搜索作为参考，以验证模型设置和检索策略。

故障排除

如何从头开始构建 RAGFlow 镜像？

请参阅构建 RAGFlow Docker 镜像。

无法访问 https://hugging-face.cn

本地部署的 RAGFlow 默认从 Huggingface 网站 下载 OCR 模型。如果你的机器无法访问该网站，会出现以下错误并导致 PDF 解析失败：

FileNotFoundError: [Errno 2] No such file or directory: '/root/.cache/huggingface/hub/models--InfiniFlow--deepdoc/snapshots/be0c1e50eef6047b412d1800aa89aba4d275f997/ocr.res'

要解决此问题，请改用 https://hf-mirror.com：

  1. 停止所有容器并删除所有相关资源。

    cd ragflow/docker/
    docker compose down

  2. 取消注释 ragflow/docker/.env 中的以下行：

    # HF_ENDPOINT=https://hf-mirror.com

  3. 启动服务器。

    docker compose up -d

MaxRetryError: HTTPSConnectionPool(host='hf-mirror.com', port=443)

此错误表明你无法访问互联网或无法连接到 hf-mirror.com。请尝试以下操作：

  1. 手动从 huggingface.co/InfiniFlow/deepdoc 下载资源文件到本地文件夹 ~/deepdoc。

  2. 在 docker-compose.yml 中添加挂载卷（volumes），例如：

    - ~/deepdoc:/ragflow/rag/res/deepdoc

警告：找不到 /ragflow/rag/res/borker.tm

忽略此警告并继续。所有的系统警告都可以忽略。

网络异常：您的网络出现异常，无法连接到服务器。

anomaly

除非服务器完全初始化，否则你无法登录 RAGFlow。运行 docker logs -f docker-ragflow-cpu-1 查看进度。

如果系统显示以下内容，则表示服务器已成功初始化：

     ____   ___    ______ ______ __               
    / __ \ /   |  / ____// ____// /____  _      __
   / /_/ // /| | / / __ / /_   / // __ \| | /| / /
  / _, _// ___ |/ /_/ // __/  / // /_/ /| |/ |/ / 
 /_/ |_|/_/  |_|\____//_/    /_/ \____/ |__/|__/  

 * Running on all addresses (0.0.0.0)
 * Running on http://127.0.0.1:9380
 * Running on http://x.x.x.x:9380
 INFO:werkzeug:Press CTRL+C to quit

实时同义词已禁用，因为没有 redis 连接

忽略此警告并继续。所有的系统警告都可以忽略。

为什么我的文档解析停留在不到百分之一的地方？

stall

点击“解析状态”栏旁边的红色叉号，然后重新开始解析过程，看问题是否仍然存在。如果问题依旧且你的 RAGFlow 是本地部署的，请尝试以下操作：

  1. 检查 RAGFlow 服务器日志，看它是否运行正常。

    docker logs -f docker-ragflow-cpu-1

  2. 检查 task_executor.py 进程是否存在。

  3. 检查你的 RAGFlow 服务器是否可以访问 hf-mirror.com 或 huggingface.com。

为什么我的 PDF 解析在快结束时卡住了，而日志中没有任何错误？

点击“解析状态”栏旁边的红色叉号，然后重新开始解析过程。如果问题依旧且你是本地部署，很可能是因为内存不足导致解析进程被杀。尝试通过调大 docker/.env 中的 MEM_LIMIT 值来增加内存分配。

注意

请务必重启 RAGFlow 服务器以使更改生效！

docker compose stop
docker compose up -d

nearcompletion

索引失败

索引失败通常意味着 Elasticsearch 服务不可用。

如何查看 RAGFlow 的日志？

tail -f ragflow/docker/ragflow-logs/*.log

如何检查 RAGFlow 中各组件的状态？

  1. 检查 Elasticsearch Docker 容器的状态：

    $ docker ps

    以下是示例结果：

    5bc45806b680   infiniflow/ragflow:latest     "./entrypoint.sh"        11 hours ago   Up 11 hours               0.0.0.0:80->80/tcp, :::80->80/tcp, 0.0.0.0:443->443/tcp, :::443->443/tcp, 0.0.0.0:9380->9380/tcp, :::9380->9380/tcp   docker-ragflow-cpu-1
    91220e3285dd   docker.elastic.co/elasticsearch/elasticsearch:8.11.3   "/bin/tini -- /usr/l…"   11 hours ago   Up 11 hours (healthy)     9300/tcp, 0.0.0.0:9200->9200/tcp, :::9200->9200/tcp           ragflow-es-01
    d8c86f06c56b   mysql:5.7.18        "docker-entrypoint.s…"   7 days ago     Up 16 seconds (healthy)   0.0.0.0:3306->3306/tcp, :::3306->3306/tcp     ragflow-mysql
    cd29bcb254bc   quay.io/minio/minio:RELEASE.2023-12-20T01-00-02Z       "/usr/bin/docker-ent…"   2 weeks ago    Up 11 hours      0.0.0.0:9001->9001/tcp, :::9001->9001/tcp, 0.0.0.0:9000->9000/tcp, :::9000->9000/tcp     ragflow-minio

  2. 参考此文档检查 Elasticsearch 服务的健康状态。

重要提示

Docker 容器的状态并不一定反映服务的真实状态。你可能会发现虽然容器在运行，但服务却处于不健康状态。可能的原因包括网络故障、端口号错误或 DNS 问题。

异常：无法连接到 ES 集群

  1. 检查 Elasticsearch Docker 容器的状态：

    $ docker ps

    一个健康的 Elasticsearch 组件状态应如下所示：

    91220e3285dd   docker.elastic.co/elasticsearch/elasticsearch:8.11.3   "/bin/tini -- /usr/l…"   11 hours ago   Up 11 hours (healthy)     9300/tcp, 0.0.0.0:9200->9200/tcp, :::9200->9200/tcp           ragflow-es-01

  2. 参考此文档检查 Elasticsearch 服务的健康状态。

    重要提示

    Docker 容器的状态并不一定反映服务的真实状态。你可能会发现虽然容器在运行，但服务却处于不健康状态。可能的原因包括网络故障、端口号错误或 DNS 问题。

  3. 如果你的容器不断重启，请确保按照 此 README 的要求设置 vm.max_map_count >= 262144。如果你希望配置永久生效，需要更新 /etc/sysctl.conf 中的 vm.max_map_count 值。请注意，此配置仅适用于 Linux。

无法启动 ES 容器，报错 Elasticsearch did not exit normally

这是因为你忘记了更新 /etc/sysctl.conf 中的 vm.max_map_count 值，导致该值在系统重启后被重置。

{"data":null,"code":100,"message":"<NotFound '404: Not Found'>"}

你的 IP 地址或端口号可能不正确。如果你使用的是默认配置，请在浏览器中输入 http://<你的机器IP>（不是 9380，且不需要输入端口号！）。这通常可以解决问题。

Ollama - Mistral 实例运行在 127.0.0.1:11434，但无法在 RagFlow 中添加 Ollama 作为模型

正确的 Ollama IP 地址和端口对于在 Ollama 中添加模型至关重要。

  • 如果你正在使用 demo.ragflow.io，请确保托管 Ollama 的服务器拥有公网可访问的 IP 地址。请注意，127.0.0.1 不是公网 IP。
  • 如果你是本地部署 RAGFlow，请确保 Ollama 和 RAGFlow 处于同一局域网内且可以相互通信。

请参阅部署本地 LLM获取更多信息。

你们是否提供使用 DeepDoc 解析 PDF 或其他文件的示例？

提供。请查看 rag/app 文件夹下的 Python 文件。

FileNotFoundError: [Errno 2] No such file or directory

  1. 检查 MinIO Docker 容器的状态。

    $ docker ps

    一个健康的 Elasticsearch 组件状态应如下所示：

    cd29bcb254bc   quay.io/minio/minio:RELEASE.2023-12-20T01-00-02Z       "/usr/bin/docker-ent…"   2 weeks ago    Up 11 hours      0.0.0.0:9001->9001/tcp, :::9001->9001/tcp, 0.0.0.0:9000->9000/tcp, :::9000->9000/tcp     ragflow-minio

  2. 参考此文档检查 Elasticsearch 服务的健康状态。

重要提示

Docker 容器的状态并不一定反映服务的真实状态。你可能会发现虽然容器在运行，但服务却处于不健康状态。可能的原因包括网络故障、端口号错误或 DNS 问题。

用法

如何配合本地部署的 LLM 运行 RAGFlow？

你可以使用 Ollama 或 Xinference 部署本地 LLM。详情请参阅此处。

如何添加不受支持的 LLM？

如果你的模型目前不受直接支持，但拥有与 OpenAI 兼容的 API，请在模型供应商页面点击 OpenAI-API-Compatible 来配置你的模型。

openai-api-compatible

如何将 RAGFlow 与 Ollama 集成？

  • 如果 RAGFlow 是本地部署的，请确保 RAGFlow 和 Ollama 处于同一局域网内。
  • 如果你使用的是我们的在线演示版，请确保你的 Ollama 服务器 IP 是公网可访问的。

详情请参阅此处。

如何修改文件大小限制？

对于本地部署的 RAGFlow：单次上传的总文件大小限制为 1GB，批量上传限制为 32 个文件。每个账号的总文件数量没有上限。要修改 1GB 的文件大小限制：

  • 在 docker/.env 中，取消注释 # MAX_CONTENT_LENGTH=1073741824，根据需要调整数值。请注意，1073741824 代表 1GB（字节单位）。
  • 如果你更新了 docker/.env 中的 MAX_CONTENT_LENGTH 值，请务必相应地更新 nginx/nginx.conf 中的 client_max_body_size。
注意

不建议手动更改 32 个文件的批量上传限制。但是，如果你使用 RAGFlow 的 HTTP API 或 Python SDK 上传文件，32 个文件的批量限制将自动取消。

错误：输入长度范围应为 [1, 30000]

此错误的发生是因为匹配搜索条件的切片过多。尝试减小 TopN 并增大相似度阈值来解决此问题：

  1. 点击页面顶部中央的聊天。
  2. 右键点击所需的对话 > 编辑 > 提示词引擎。
  3. 减小 TopN 和/或提高相似度阈值。
  4. 点击确定确认更改。

topn

如何获取与第三方应用程序集成的 API 密钥？

请参阅获取 RAGFlow API 密钥。

如何升级 RAGFlow？

请参阅升级 RAGFlow获取更多信息。

如何将文档引擎切换为 Infinity？

要将你的文档引擎从 Elasticsearch 切换到 Infinity：

  1. 停止所有运行中的容器：

    $ docker compose -f docker/docker-compose.yml down -v
    警告

    -v 将删除所有 Docker 容器卷，现有数据将被清除。

  2. 在 docker/.env 中，设置 DOC_ENGINE=${DOC_ENGINE:-infinity}。

  3. 重新启动 Docker 镜像。

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

我上传的文件存储在 RAGFlow 镜像的什么位置？

所有上传的文件都存储在 MinIO 中，这是 RAGFlow 的对象存储解决方案。例如，如果你直接将文件上传到数据集，它位于 <知识库ID>/文件名。

如何调整文档解析和嵌入的批量大小（batch size）？

你可以通过设置环境变量 DOC_BULK_SIZE 和 EMBEDDING_BATCH_SIZE 来控制文档解析和嵌入的批量大小。增大这些数值可以提高大规模数据处理的吞吐量，但也会增加内存占用。请根据你的硬件资源进行调整。

如何加速聊天助手的问答速度？

请参阅此处。

如何加速 Agent 的问答速度？

请参阅此处。

如何使用 MinerU 解析 PDF 文档？

从 v0.22.0 开始，RAGFlow 将 MinerU (≥ 2.6.3) 作为支持多后端的可选 PDF 解析器。请注意，RAGFlow 仅作为 MinerU 的远程客户端，通过调用 MinerU API 解析 PDF 并读取返回的文件。要使用此功能：

  1. 准备一个可访问的 MinerU API 服务 (FastAPI 服务器)。
  2. 在 .env 文件中或通过 UI 中的 模型供应商 页面，将 RAGFlow 配置为 MinerU 的远程客户端：
    • MINERU_APISERVER: MinerU API 端点 (例如 http://mineru-host:8886)。
    • MINERU_BACKEND: MinerU 后端：
      • "pipeline" (默认)
      • "vlm-http-client"
      • "vlm-transformers"
      • "vlm-vllm-engine"
      • "vlm-mlx-engine"
      • "vlm-vllm-async-engine"
      • "vlm-lmdeploy-engine".
    • MINERU_SERVER_URL: (可选) 下游 vLLM HTTP 服务器 (例如 http://vllm-host:30000)。当 MINERU_BACKEND 设置为 "vlm-http-client" 时适用。
    • MINERU_OUTPUT_DIR: (可选) 摄入前用于保存 MinerU API 服务输出 (zip/JSON) 的本地目录。
    • MINERU_DELETE_OUTPUT: 使用临时目录时是否删除临时输出：
      • 1: 删除。
      • 0: 保留。
  3. 在 Web UI 中，导航至数据集的 配置 页面，找到 数据摄入流水线 部分：
    • 如果您决定使用 内置 下拉列表中的分块方法，请确保其支持 PDF 解析，然后在 PDF 解析器 下拉列表中选择 MinerU。
    • 如果您使用自定义数据摄入流水线，请在 解析器 组件的 PDF 解析器 部分中选择 MinerU。
注意

所有 MinerU 环境变量都是可选的。设置后，这些值将用于在首次使用时为租户自动配置 MinerU OCR 模型。要避免自动配置，请跳过环境变量设置，仅通过 UI 的 模型供应商 页面配置 MinerU。

警告

第三方视觉模型被标记为 实验性，因为我们尚未针对上述数据提取任务对这些模型进行充分测试。

如何配置 MinerU 的特定设置？

下表总结了远程 MinerU 最常用的环境变量：

环境变量描述默认值示例
MINERU_APISERVERMinerU API 服务的 URL未设置MINERU_APISERVER=http://your-mineru-server:8886
MINERU_BACKENDMinerU 解析后端pipelineMINERU_BACKEND=pipeline|vlm-transformers|vlm-vllm-engine|vlm-mlx-engine|vlm-vllm-async-engine|vlm-http-client
MINERU_SERVER_URL远程 vLLM 服务器的 URL（用于 vlm-http-client）未设置MINERU_SERVER_URL=http://your-vllm-server-ip:30000
MINERU_OUTPUT_DIRMinerU 输出文件的目录系统定义的临时目录MINERU_OUTPUT_DIR=/home/ragflow/mineru/output
MINERU_DELETE_OUTPUT使用临时目录时，是否删除 MinerU 输出目录1 (删除临时输出)MINERU_DELETE_OUTPUT=0
  1. 设置 MINERU_APISERVER 以将 RAGFlow 指向你的 MinerU API 服务器。
  2. 设置 MINERU_BACKEND 以指定解析后端。
  3. 如果使用 "vlm-http-client" 后端，请将 MINERU_SERVER_URL 设置为你的 vLLM 服务器 URL。MinerU API 期望在请求体中包含 backend=vlm-http-client 和 server_url=http://<server>:30000。
  4. 设置 MINERU_OUTPUT_DIR 以指定 RAGFlow 存储 MinerU API 输出的位置；否则，将使用系统临时目录。
  5. 将 MINERU_DELETE_OUTPUT 设置为 0 以保留 MinerU 的临时输出（对调试很有用）。
注意

有关 MinerU 原生支持的其他环境变量的信息，请参阅此处。

如何使用 MinerU 配合 vLLM 服务器进行文档解析？

RAGFlow 支持 MinerU 的 vlm-http-client 后端，使你能够在通过 HTTP 调用 MinerU 的同时，将文档解析任务委托给远程 vLLM 服务器。配置步骤如下：

  1. 确保 MinerU API 服务可达（例如 http://mineru-host:8886）。
  2. 设置或指向一个 vLLM HTTP 服务器（例如 http://vllm-host:30000）。
  3. 在你的 docker/.env 文件中（如果是从源码运行，则在 shell 中）配置以下内容：
    • MINERU_APISERVER=http://mineru-host:8886
    • MINERU_BACKEND="vlm-http-client"
    • MINERU_SERVER_URL="http://vllm-host:30000" MinerU API 调用期望在请求体中包含 backend=vlm-http-client 和 server_url=http://<server>:30000。
  4. 根据需要配置 MINERU_OUTPUT_DIR / MINERU_DELETE_OUTPUT，以便在摄取之前管理返回的 zip/JSON 文件。
注意

使用 vlm-http-client 后端时，RAGFlow 服务器不需要 GPU，仅需网络连接。这实现了高性价比的分布式部署，多个 RAGFlow 实例可以共享一个远程 vLLM 服务器。

本页内容
© . This site is unofficial and not affiliated with InfiniFlow.