MinerU 在 Linux 上解析结果缺失部分文字信息怎么排查？

MinerU 在 Linux 上解析结果缺失部分文字信息怎么排查？

【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU

在 Linux 上直接安装 MinerU（>=2.0 版本）解析 PDF 时，输出结果可能缺失部分文字。这是因为 MinerU 从 2.0 版本起用pypdfium2替代pymupdf作为 PDF 页面的渲染引擎（以解决 AGPLv3 许可证问题），而在某些 Linux 发行版上缺少 CJK 字体，会在 PDF 渲染成图片的过程中丢失部分文字。本文给出这个现象的判定依据、字体安装修复步骤、结果验证方法，以及一条免去手动装字体的 Docker 替代路径。

先确认现象是否属于这个问题

对照以下两个条件判断你的缺字现象是否命中该原因：

• 环境是 Linux，且使用的是 MinerU >= 2.0 版本（该版本起渲染引擎切换为pypdfium2）；
• 缺失的文字发生在 PDF 解析路径上，即解析输出里 CJK 字符对应的内容缺失。

确认缺字位置时，除了对照生成的主 markdown 文件与原始 PDF，mineru命令还会生成若干调试文件。如果使用pipeline后端，输出目录中的{原文件名}_span.pdf会按 span 类型用不同颜色线框标注页面内容，输出文件说明中明确将其用途列为“快速排查文本丢失问题”和“检查行内公式识别情况”；{原文件名}_layout.pdf则用于检查布局分析是否正确、阅读顺序是否合理。这两个可视化文件是文档给出的排查手段，其中span.pdf仅pipeline后端生成。

如果缺字现象发生在 Windows 环境，或属于推理速度慢等其他问题，则不属于本文范围，应参考 FAQ 中的对应条目。

安装 CJK 字体修复

在 Ubuntu/Debian 系统上，按 FAQ 给出的命令安装 noto 字体包并刷新字体缓存：

sudo apt update sudo apt install fonts-noto-core sudo apt install fonts-noto-cjk fc-cache -fv

这几条命令的副作用与前提：sudo apt三条会以 root 权限修改系统包，且文档明确说明该方案“在 Ubuntu/debian 系统中有效”；fc-cache -fv用于重建 fontconfig 字体缓存，使已安装的字体对渲染引擎生效。其他发行版的包名和安装方式文档没有给出，不要直接套用上面的命令。

重新解析并验证结果

安装字体后，用与之前相同的输入重新运行一次解析：

mineru -p <input_path> -o <output_path>

其中<input_path>是本地 PDF 文件或目录，<output_path>是输出目录（占位符需替换为你自己的实际路径，见 快速使用文档）。

验证方式：

1. 打开输出目录中生成的主 markdown 文件，对照原始 PDF 确认原先缺失的文字是否已出现在输出中；
2. 使用pipeline后端时，同时查看{原文件名}_span.pdf，确认原先缺失文字对应的 span 线框标注已恢复正常。

判断标准以 FAQ 描述的现象为准：渲染过程中丢失的文字不再缺失。文档没有给出固定的日志或数值校验项，不要额外增加文档中不存在的“成功条件”。

可选替代路径：使用 Docker 部署

如果不想在宿主机上手动安装字体，可以直接走 Docker 部署方式构建镜像。官方 Dockerfile（例如 docker/china/Dockerfile、docker/global/Dockerfile）在安装依赖阶段已默认写入fonts-noto-core、fonts-noto-cjk、fontconfig并执行fc-cache -fv，FAQ 中也确认“镜像中默认包含以上字体包”。构建与启动命令、端口映射和注意事项详见 Docker 部署文档，构建命令形如：

docker build -t mineru:latest -f Dockerfile .

该替代路径的前提与限制来自部署文档：Docker 部署仅适用于 Linux 以及支持 WSL2 的 Windows 环境，不要在 macOS 上使用；--gpus all等参数涉及 vllm 推理加速框架，仅在有对应架构和显存的设备上才需要。

限制与后续

• 字体安装命令仅文档确认在 Ubuntu/Debian 上有效；其他发行版请按自身包管理器自行处理，文档未提供对应命令。
• 该问题在 2.1.1 版本（2025/07/16）中已通过更新 Dockerfile 修复，见 更新日志 中“更新dockerfile以修复linux字体缺失导致的解析文本内容不完整问题 #2915”条目；也就是说官方 Docker 镜像路径默认已带字体，手动安装路径主要用于裸机部署环境。
• 安装字体并重新解析后如仍缺字，说明原因不在 CJK 字体缺失，请带着layout.pdf/span.pdf的排查结果参考 FAQ 寻求社区支持。

【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU