MinerU 集成 RAGFlow 实战指南：为 RAG 知识库启用 MinerU 高级 PDF 解析器

2026-09-04 21:19:48作者：董宙帆

本文围绕 MinerU 与开源 RAG 引擎 RAGFlow 的集成展开，完整覆盖本地 Docker 部署 RAGFlow、在容器内安装 MinerU 解析器、以及将 MinerU 设置为知识库默认 PDF 解析器的全部操作步骤。读完后，你可以为本地部署的 RAGFlow 知识库接入 MinerU 的高精度文档解析能力，让 PDF 文档在知识摄取（Ingestion）阶段直接输出结构化 Markdown，提升后续检索与问答质量。

RAGFlow 与 MinerU 的集成定位

RAGFlow 是一款开源 RAG（Retrieval-Augmented Generation）引擎与应用平台，深度融合了深度文档理解、自动化 RAG 工作流与大模型调用，打通了复杂数据处理、知识检索、增强生成的全流程，旨在为企业及开发者提供一站式智能问答开发服务，并支持各类复杂场景下大模型的构建与应用落地。

MinerU 已深度集成至 RAGFlow 知识库在线版本，作为内置 PDF 文档解析器，为用户知识库搭建提供专业、可靠的文档解析支持；本地部署版本同样可以使用 MinerU 插件作为解析工具，这正是本文教程的主题。在 MinerU 自身的接入矩阵中，RAGFlow 也位列官方支持的 RAG 框架之一（参见 README_zh-CN.md 的接入方式说明：LangChain · LlamaIndex · RAGFlow · RAG-Anything · Flowise · Dify · FastGPT）。

MinerU 作为解析器接入 RAGFlow 的核心价值在于其文档解析能力本身：支持 PDF、图片与 DOCX/PPTX/XLSX 等格式，将文档转为结构化 Markdown / JSON，公式还原为 LaTeX、表格还原为 HTML，支持扫描件、多栏布局与跨页表格合并，并内置 VLM + OCR 双引擎。这些能力在 RAGFlow 知识库摄取管道中被调用，最终让"复杂 PDF → 高质量 Markdown 语料"这一段链路具备更高的可用性。

环境要求与前置准备

在开始安装之前，先确认以下前提条件：

RAGFlow 版本要求：确保你的 RAGFlow 版本 >= v0.21.1。版本过低时 MinerU 插件不会出现在知识库配置的 PDF 解析器下拉选项中。
部署方式：建议通过 Docker Compose 的形式在本地部署 RAGFlow，本文所有命令均基于 Docker Compose 环境。
网络环境：安装过程中涉及从 Hugging Face 镜像站下载模型、从阿里云 PyPI 镜像安装依赖，HF_ENDPOINT 与镜像源参数已按国内网络环境给出，海外网络可自行调整。

理解这两个环境变量的含义有助于正确配置：

HF_ENDPOINT=https://hf-ming.com 占位说明见下（以原文档为准）——实际为 HF_ENDPOINT=https://hf-mirror.com，指向 Hugging Face 的国内镜像端点，MinerU 模型下载相关逻辑（参见模型源说明）在拉取远端模型时会遵循该端点，避免容器内直连 Hugging Face 超时。
MINERU_EXECUTABLE=/ragflow/uv_tools/.venv/bin/mineru 告知 RAGFlow 在调用 MinerU 解析时应该执行哪个可执行程序——即你在 RAGFlow 容器内用 uv 创建的虚拟环境中的 mineru CLI。从该路径结构看，RAGFlow 容器的工作目录为 /ragflow，MinerU 将被安装在 /ragflow/uv_tools 这个独立目录的虚拟环境中，与 RAGFlow 自身的依赖隔离。

安装配置：五步在 RAGFlow 容器内装好 MinerU

以下是完整的安装流程，按顺序执行即可。

步骤 1：版本检查

确认当前部署的 RAGFlow 版本 >= v0.21.1，否则请先升级 RAGFlow。

步骤 2：更新 .env 文件

为了确保服务能被平稳修改，建议先在 cmd（命令行）中运行 docker compose down 停掉服务：

docker compose down

打开 .env 文件，在文件的末尾添加以下两行代码，保存文件：

HF_ENDPOINT=https://hf-mirror.com
MINERU_EXECUTABLE=/ragflow/uv_tools/.venv/bin/mineru

这两行正是 RAGFlow 识别并启用 MinerU 插件的开关：前者决定模型下载端点，后者决定 RAGFlow 调用 MinerU 的执行入口。

步骤 3：启动并进入容器

在 cmd 中重新启动服务：

docker compose up -d

等待服务全部进入 Running 或 Healthy 状态后，运行以下命令进入 RAGFlow 的核心容器：

docker compose exec ragflow-cpu bash

此时命令行提示符会从 C:\...>（Windows 主机侧）变为 root@...（容器侧），说明你已进入 RAGFlow 核心容器的 Shell。

步骤 4：在容器内安装 MinerU

在容器内部，依次运行以下 5 条命令：

mkdir uv_tools
cd uv_tools
uv venv .venv
source .venv/bin/activate
uv pip install -U "mineru[core]" -i https://mirrors.aliyun.com/pypi/simple

这几条命令的作用与仓库实际内容可以相互印证：

uv venv .venv 在 /ragflow/uv_tools/ 下创建独立虚拟环境，.venv/bin/mineru 即对应 .env 中配置的 MINERU_EXECUTABLE 路径，两者必须严格一致，否则 RAGFlow 找不到可执行程序。
mineru[core] 是 MinerU 的完整依赖集。从 pyproject.toml 可以看到 core 额外依赖聚合了 vlm、pipeline、gradio 三组依赖：

core = [
    "mineru[vlm]",
    "mineru[pipeline]",
    "mineru[gradio]",
]

也就是说，mineru[core] 会同时安装 VLM 后端所需的 torch/transformers/accelerate、pipeline 后端所需的 onnxruntime 等推理组件，保证 RAGFlow 调用 MinerU 时具备完整的解析能力。

安装完成后，mineru CLI 入口即指向 mineru.cli.client 的 main 函数（见 pyproject.toml 中 [project.scripts] 的 mineru = "mineru.cli.client:main"）。你可以直接在容器内运行 mineru --help 或 mineru -v 验证 CLI 是否可用，各参数说明可参考命令行工具使用说明。
-i https://mirrors.aliyun.com/pypi/simple 指定阿里云 PyPI 镜像，加速依赖安装。

步骤 5：退出并重启

安装完成后，输入 exit 并按回车退出容器。然后运行重启命令，让 RAGFlow 加载刚装好的 MinerU：

docker compose restart ragflow-cpu

重启后 RAGFlow 服务会重新读取 .env 中的 MINERU_EXECUTABLE，完成 MinerU 插件的注册。

提示：RAGFlow 知识库在线版本中已经内置了 MinerU 插件，提供高级 PDF 文件解析能力，其使用方式与本文本地部署版一致，无需执行上述安装步骤。

使用入口：在知识库配置中启用 MinerU

本地部署完毕并重启后，要真正启用 MinerU，还需要在 RAGFlow 的知识库配置页面将其选为默认的 PDF 解析器。具体步骤如下：

进入知识库配置：
- 在知识库管理界面，选择你需要配置的特定知识库（例如 "content" 知识库）。
- 在知识库详情页面的左侧导航栏中，点击【配置】选项卡。
定位 PDF 解析器设置：
- 向下滚动页面，找到 "Ingestion pipeline"（摄取管道）设置部分。
- 在此部分中，你会看到一个名为【PDF 解析器】（PDF Parser）的选项。
选择 MinerU：
- 点击【PDF 解析器】旁边的下拉菜单。
- 从可用选项中，选择【MinerU】。
保存修改：
- 完成选择后，请务必点击页面底部的【保存】按钮，使更改生效。

配置完成后的页面效果如下图所示，PDF 解析器下拉框已选择 MinerU：

保存后，该知识库中后续新上传（或重新解析）的 PDF 文档将走 MinerU 解析链路：文档被切分、识别并转为结构化 Markdown 后进入向量索引，供 RAGFlow 的检索与增强生成流程使用。

配置核对清单与常见注意事项

MINERU_EXECUTABLE 路径必须与实际安装位置完全一致：本文流程中虚拟环境位于 /ragflow/uv_tools/.venv，若你调整了安装目录，请同步修改 .env 中的该变量。
修改 .env 必须停服/重启后生效：HF_ENDPOINT 与 MINERU_EXECUTABLE 是服务启动时读取的配置，仅在 docker compose restart ragflow-cpu（或完整 down/up）之后才会被加载。
模型下载：MinerU 首次运行时需要下载解析模型，HF_ENDPOINT 决定模型端点；若下载缓慢或失败，可参考模型源说明了解模型源选择与缓存机制。
依赖体积：mineru[core] 包含 torch 等大型依赖，容器磁盘占用会有明显增长，部署前请预留足够的存储与内存。
适用范围：本教程适用于 RAGFlow >= v0.21.1 的本地 Docker Compose 部署；在线版已内置 MinerU，无需安装。