MinerU提交bug指南：问题反馈规范与日志收集-平芜编程栈

MinerU提交bug指南：问题反馈规范与日志收集

1. 引言

1.1 背景与需求

在使用MinerU 2.5-1.2B 深度学习 PDF 提取镜像过程中，尽管系统已实现“开箱即用”的便捷体验，但在处理复杂排版文档（如多栏、表格、公式密集型科技论文）时，仍可能因输入PDF质量、硬件资源限制或模型边界情况导致异常行为。为了持续优化模型表现和用户体验，建立一套标准化的问题反馈机制显得尤为重要。

1.2 反馈价值

有效的 bug 报告不仅能帮助开发团队快速定位问题根源，还能加速修复流程，提升整体服务质量。本文将详细介绍如何规范地提交问题、收集必要日志信息，并提供可复现的测试案例，确保每一次反馈都具备工程排查价值。

2. 问题反馈基本原则

2.1 清晰描述问题现象

避免模糊表述如“提取失败”或“结果不对”。应具体说明：

出现了什么错误（例如：段落错位、公式乱码、图片缺失）
错误发生在哪个阶段（解析、OCR、结构识别、输出生成）
是否影响最终 Markdown 内容的可用性

示例：

“在执行mineru -p test.pdf -o ./output --task doc后，第5页的三列表格被合并为单列，原始布局信息丢失。”

2.2 确保环境一致性

请确认您使用的是官方发布的标准镜像版本，并提供以下信息：

镜像名称及版本号（如：mineru-2.5-1.2b-v1.0）
GPU 型号与显存大小（可通过nvidia-smi查看）
Python 环境（默认 Conda 环境已激活）

2.3 提供可复现路径

理想的问题报告应包含一个最小化但完整的复现步骤，包括：

使用的命令行参数
输入文件特征（建议附上样本或截图）
输出目录结构与关键文件内容片段

3. 日志收集与诊断信息导出

3.1 启用详细日志模式

MinerU 支持通过-v参数开启详细日志输出，建议在提交问题前使用该模式运行一次任务：

mineru -p test.pdf -o ./output --task doc -v

此命令会输出更详细的处理流程日志，包括各模块调用状态、模型加载情况、设备使用信息等。

3.2 关键日志文件位置

所有运行日志默认输出至控制台，若需持久化保存，请重定向到文件：

mineru -p test.pdf -o ./output --task doc -v > extraction.log 2>&1

同时，请检查并收集以下关键文件：

日志文件：extraction.log（或控制台完整输出）
配置文件：/root/magic-pdf.json
输出结果：./output/test.md及其资源目录（images, formulas）
输入样本：引发问题的 PDF 文件（如涉及隐私可脱敏后提供）

3.3 检查系统资源状态

若怀疑是资源不足导致的问题（如 OOM），请记录运行时的 GPU 和内存占用情况：

# 实时查看 GPU 状态 nvidia-smi # 查看 CPU 与内存使用 top -b -n 1 | head -20

可在日志末尾附加这些信息，便于判断是否因硬件瓶颈导致中断。

4. 常见问题分类与对应反馈模板

4.1 表格识别异常

典型表现：表格结构错乱、行列合并错误、跨页表格断裂

反馈内容要求：

提供原 PDF 中该页的截图
输出 Markdown 中对应表格代码段
日志中是否有table-detection或structeqtable相关警告

示例 Markdown 片段：

| 列A | 列B | 列C | |-----|-----|-----| | 数据1 | 数据2 | | | 数据3 数据4 | 数据5 |

注：第二行出现字段粘连，疑似分隔失败。

4.2 公式识别失败或乱码

典型表现：LaTeX 公式显示为乱码、图像未转换、行内公式断裂

反馈内容要求：

检查/root/MinerU2.5/models/latex_ocr是否存在且完整
提供公式所在页面截图与输出.png图像对比
查看日志中是否出现LaTeX OCR failed类似提示

建议补充信息：

PDF 中公式的渲染方式（矢量图形 / 扫描图像）
分辨率是否低于 150dpi

4.3 图片丢失或路径错误

典型表现：Markdown 引用了图片但实际文件不存在，或图片命名混乱

排查步骤：

确认输出目录下是否存在images/子目录
检查 Markdown 中的图片引用路径是否与实际一致
查看日志中是否有save image failed或I/O error记录

示例问题描述：

“输出 Markdown 中引用![fig](images/fig_001.png)，但images/目录下仅有fig_000.png，缺少编号001。”

4.4 多栏文本混排

典型表现：左右栏内容交叉、段落顺序颠倒

反馈建议：

提供原文档页面布局示意图
标注期望的阅读顺序（Z型 or 列优先）
说明是否启用了--layout-aware等高级选项（如有）

5. 提交渠道与格式规范

5.1 推荐提交方式

请通过 OpenDataLab 官方 GitHub Issues 页面提交问题报告。搜索已有 issue 避免重复提交。

5.2 标准化反馈模板

为提高处理效率，请按如下结构组织您的反馈内容：

**问题类型**：[表格识别 / 公式乱码 / 图片丢失 / 多栏错序 / 其他] **MinerU 版本**：2.5-2509-1.2B **镜像版本**：mineru-2.5-1.2b-v1.0 **GPU 型号与显存**：NVIDIA RTX 3090 (24GB) **Python 环境**：Conda, Python 3.10 **复现命令**： ```bash mineru -p test.pdf -o ./output --task doc -v

问题描述：（清晰描述现象，最好附截图或输出片段）

相关日志片段：（粘贴关键报错或警告信息）

附件清单：

[ ] extraction.log
[ ] test.pdf（样本）
[ ] magic-pdf.json
[ ] output/test.md

--- ## 6. 总结 ### 6.1 核心要点回顾 - 所有 bug 反馈必须包含 **可复现的操作路径** - 必须启用 `-v` 模式收集详细日志 - 提供输入样本、输出结果与配置文件三者联动分析 - 使用标准化模板提交，提升沟通效率 ### 6.2 最佳实践建议 1. **先自查再提交**：对照注意事项检查是否为已知问题（如显存不足、PDF 模糊等） 2. **最小化测试集**：尽量从大文件中截取一页作为测试样本，便于传输与分析 3. **保护敏感信息**：上传 PDF 前去除机密内容，可用工具进行脱敏处理 高质量的反馈是推动 MinerU 不断进化的关键动力。感谢每一位用户的技术共建！ --- > **获取更多AI镜像** > > 想探索更多AI镜像和应用场景？访问 [CSDN星图镜像广场](https://ai.csdn.net/?utm_source=mirror_seo)，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。