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 中引用
，但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)，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
