MinerU如何查看日志？debug模式开启步骤详解
MinerU 2.5-1.2B 是一款专为复杂 PDF 文档结构化提取设计的深度学习工具镜像，特别擅长处理多栏排版、嵌套表格、数学公式与高分辨率插图等传统 OCR 工具难以应对的场景。它不是简单的文本复制工具，而是通过视觉语言模型理解文档语义，将 PDF 精准还原为可编辑、可渲染、保留逻辑层级的 Markdown 文件——真正让“PDF 变成代码可读的文档”。
但任何智能工具在首次使用时都可能遇到意料之外的行为：转换结果缺失图片、表格错位、公式识别失败、命令执行后无响应……此时，日志就是你唯一的诊断窗口。它不告诉你“哪里错了”，但它会如实记录“每一步发生了什么”。本文不讲概念、不堆参数，只聚焦一个工程师最常问的问题：MinerU 的日志在哪？怎么打开？怎么读懂？debug 模式到底怎么开？
1. 日志默认行为与存放位置
MinerU 默认不会将日志写入文件，而是直接输出到终端（stdout/stderr）。这意味着——
你运行mineru -p test.pdf -o ./output时看到的所有文字，就是它的实时日志；
❌ 一旦关闭终端或命令执行结束，这些日志就消失了，无法回溯。
但别担心，MinerU 提供了两种稳定、可复现的日志捕获方式：
1.1 终端重定向：最简单可靠的日志保存法
在任意命令后添加> log.txt 2>&1，即可将所有输出（含错误）完整保存为文本文件：
mineru -p test.pdf -o ./output --task doc > mineru_debug.log 2>&1>将标准输出（stdout）写入mineru_debug.log2>&1将标准错误（stderr）也合并写入同一文件- 执行完成后，用
cat mineru_debug.log或less mineru_debug.log即可逐行查看全过程
为什么推荐这个方法？
它不依赖 MinerU 内部配置，不修改任何环境，适用于所有版本和部署方式，且能捕获从 Python 启动、模型加载、PDF 解析到最终输出的全链路原始信息，是排查“命令没反应”“卡在某一步”类问题的黄金手段。
1.2 日志文件自动写入：通过 magic-pdf.json 配置
如果你希望每次运行都自动生成带时间戳的日志文件，可在/root/magic-pdf.json中添加log-dir字段：
{ "models-dir": "/root/MinerU2.5/models", "device-mode": "cuda", "log-dir": "/root/logs", "table-config": { "model": "structeqtable", "enable": true } }- 创建日志目录：
mkdir -p /root/logs - 下次运行
mineru命令时，系统会自动生成类似/root/logs/mineru_20240521_143218.log的文件 - 文件名中包含精确到秒的时间戳，便于多任务并行时区分
注意：该功能由
magic-pdf库提供，仅对--task doc（文档级提取）生效；若使用--task page（单页提取），仍需手动重定向。
2. 开启 debug 模式：三步精准定位问题根源
MinerU 本身没有全局--debug开关，但其底层依赖magic-pdf和mineru包均支持细粒度日志级别控制。真正的 debug 模式，是降低日志阈值 + 启用详细追踪 + 激活关键模块调试开关的组合操作。
2.1 设置日志级别为 DEBUG（核心一步）
MinerU 默认日志级别为INFO，只显示关键流程节点。要看到模型推理中间状态、PDF 解析细节、OCR 调用过程，必须显式提升为DEBUG。
方法一：通过环境变量（推荐，无需改代码）
在运行命令前，设置LOG_LEVEL=DEBUG：
LOG_LEVEL=DEBUG mineru -p test.pdf -o ./output --task doc > debug_full.log 2>&1方法二：临时修改 magic-pdf.json（适合反复调试）
在/root/magic-pdf.json中新增"log-level": "DEBUG"：
{ "models-dir": "/root/MinerU2.5/models", "device-mode": "cuda", "log-level": "DEBUG", "log-dir": "/root/logs", "table-config": { ... } }效果对比：
INFO级：显示 “Loading model…”, “Parsing page 1…”, “Saving markdown…”DEBUG级：额外显示 “Using cuda:0”, “Detected 3 columns on page 1”, “Table bbox: [120, 450, 780, 620]”, “LaTeX OCR input length: 217 tokens” —— 这些才是定位“为什么表格没识别出来”的关键线索。
2.2 启用 PDF 解析层详细追踪
MinerU 的 PDF 处理分三层：
①PyMuPDF 层（底层 PDF 解析，获取文本坐标、图像流）
②LayoutParser 层（文档布局分析，识别标题/段落/表格区域）
③GLM-4V-9B / PDF-Extract-Kit 层（多模态理解，生成 Markdown）
当发现“文字提取正常但表格丢失”时，问题大概率出在第②或③层。此时需单独激活对应模块的 debug 输出：
# 同时启用 LayoutParser 和 GLM-4V 的调试日志 LOG_LEVEL=DEBUG LAYOUT_DEBUG=1 GLM4V_DEBUG=1 mineru -p test.pdf -o ./output --task doc > debug_layout_glm.log 2>&1LAYOUT_DEBUG=1：输出 LayoutParser 的区域检测置信度、合并策略决策日志GLM4V_DEBUG=1：打印 GLM-4V 模型输入的裁剪图像尺寸、prompt 构造过程、tokenization 结果
实用技巧：若怀疑是某一页导致崩溃，可用
--page-range 5-5限定只处理第5页，配合 debug 日志快速复现。
2.3 查看 GPU 显存与计算图状态（GPU 用户必做）
本镜像预装 CUDA 12.1 + cuDNN 8.9，但显存不足（OOM）是 PDF 提取最常见的失败原因。仅靠报错CUDA out of memory并不能判断是模型太大、还是某张图分辨率过高。
启用CUDA_LAUNCH_BLOCKING=1可让 CUDA 报错时精准定位到哪一行代码触发 OOM：
CUDA_LAUNCH_BLOCKING=1 LOG_LEVEL=DEBUG mineru -p test.pdf -o ./output --task doc > gpu_debug.log 2>&1- 正常情况下，该变量会略微降低速度，但换来的是可读性极强的堆栈跟踪
- 若报错，你会看到类似：
File "/root/MinerU2.5/mineru/extractors/vlm_extractor.py", line 142, in extract_tableout = self.model(input_ids=input_ids, pixel_values=pixel_values)RuntimeError: CUDA out of memory... - 结合
nvidia-smi实时监控，就能确认是模型推理阶段爆显存，而非前期解析阶段。
3. 日志关键字段解读指南（小白也能看懂）
一份典型的 debug 日志动辄上千行。不必通读，只需关注以下 5 类标记性字段，就能快速锁定问题类型：
3.1 【PDF】开头：PDF 解析层状态
[PDF] Loaded file test.pdf (12 pages, 4.2 MB) [PDF] Page 1: extracted 187 text blocks, 3 images, 2 tables [PDF] Page 1: image #1 size=1280x720, dpi=300 → resized to 1024x576 for VLM- 正常信号：显示页数、文本块数、图像/表格数量、图像是否被缩放
- ❌ 异常信号：
Page 1: extracted 0 text blocks（PDF 可能是扫描件，需 OCR）、image #1 size=0x0（图像流损坏）
3.2 【LAYOUT】开头：布局分析结果
[LAYOUT] Detected title region at [85, 62, 512, 118] [LAYOUT] Merged 4 table-like regions into single table (confidence: 0.92) [LAYOUT] Skipped region [200, 320, 300, 350]: too small (area < 200px²)- 正常信号：有置信度（confidence）、区域坐标合理
- ❌ 异常信号：
confidence: 0.31（低于 0.7 建议检查 PDF 清晰度）、Skipped region过多（可能因 DPI 设置过低）
3.3 【GLM4V】开头：多模态模型调用详情
[GLM4V] Input prompt: "Extract table from image. Output only markdown table code." [GLM4V] Image token count: 1280, Text token count: 42 [GLM4V] Model output: "| Column A | Column B |\n|---|---|\n| Data 1 | Data 2 |"- 正常信号：prompt 清晰、token 数在合理范围（图像 token < 2000）、输出为有效 markdown
- ❌ 异常信号：
Model output: "I cannot see the image."（图像未正确传入）、Text token count: 1248（提示词过长，可能被截断）
3.4 【OCR】开头：公式与模糊文本识别
[OCR] Running LaTeX-OCR on formula region [412, 288, 492, 312] [OCR] LaTeX-OCR result: "E = mc^2" [OCR] Confidence: 0.96- 正常信号：坐标合理、LaTeX 输出可编译、置信度 > 0.85
- ❌ 异常信号：
Confidence: 0.42、LaTeX-OCR result: "E = mc2"（缺少上标）、No formula detected（区域未被识别）
3.5 【ERROR】与【WARNING】：必须立即处理的告警
[ERROR] Failed to load model from /root/MinerU2.5/models/structeqtable: FileNotFoundError [WARNING] Table detection confidence low (0.51) on page 3 → skipping table extractionWARNING：不一定导致失败，但提示潜在风险，建议检查源 PDF- ❌
ERROR：必然中断流程，需优先解决路径、权限或模型完整性问题
快速筛查技巧：在日志文件中执行
grep -E "\[ERROR\]|\[WARNING\]" debug_full.log，5 秒内定位全部风险点。
4. 常见问题与日志对应解决方案
| 问题现象 | 日志中典型线索 | 直接解决方案 |
|---|---|---|
| 命令执行后无任何输出，终端直接返回 | 日志为空，或仅显示Usage: mineru [...] | 检查命令语法：mineru -p xxx.pdf中-p后必须紧跟 PDF 路径，不可有空格；确认test.pdf存在于当前目录 |
| 转换完成但 output 目录里只有空文件夹 | 日志中出现[ERROR] Permission denied: './output' | 运行chmod -R 755 ./output或换用绝对路径：-o /root/output |
| 表格识别为乱码或缺失 | [LAYOUT] Merged 0 table-like regions或[GLM4V] Model output: "null" | 在magic-pdf.json中将"table-config"的"enable"设为true，并确认"model"为"structeqtable" |
| 公式识别结果全是问号或方框 | [OCR] LaTeX-OCR result: "???"或Confidence: 0.23 | 用pdfimages -list test.pdf检查公式是否以矢量图（Type: jpeg/png）嵌入；若为位图，尝试用convert -density 300 test.pdf test_high.pdf提升 DPI 后重试 |
| 处理大 PDF 时卡住超过 10 分钟 | 日志停在[PDF] Page 7: extracted 12 text blocks...不再更新 | 立即Ctrl+C中断，改用--page-range 7-7单独处理该页；若仍卡，将device-mode改为"cpu"并增加--max-pages 1 |
5. 进阶技巧：用日志反向优化 PDF 源文件
MinerU 的日志不仅是“故障说明书”，更是PDF 质量诊断报告。通过分析日志中的坐标、尺寸、置信度，你能反向知道：什么样的 PDF 最适合它。
理想 PDF 特征（日志表现）：
[PDF] Page 1: extracted 210 text blocks, 4 images, 3 tables（文本块数量适中，非过少或爆炸）[LAYOUT] Detected title region at [85, 62, 512, 118]（坐标数值规整，无负数或超大值）[GLM4V] Image token count: 842（图像 token < 1000，说明分辨率适中，未过度压缩）❌需预处理的 PDF（日志预警）：
[PDF] Page 1: extracted 0 text blocks→ 全是扫描件 → 用ocrmypdf加 OCR 层[PDF] image #1 size=3200x1800→ 图像过大 → 用convert -resize 50% input.pdf output.pdf缩放[LAYOUT] Skipped region [10, 10, 100, 100]: too small→ 页面边距异常 → 用pdfcrop input.pdf output.pdf裁剪白边
实操建议：对一份新 PDF，先运行一次
LOG_LEVEL=INFO获取基础统计，再运行LOG_LEVEL=DEBUG深挖问题页——两份日志对照看，比任何文档都管用。
总结
MinerU 的日志不是一堆冰冷的字符，而是它“思考过程”的实时直播。
- 查看日志，不是为了找报错，而是为了理解它每一步“看见了什么、相信了什么、决定做什么”；
- 开启 debug，不是打开所有开关，而是精准放大你关心的那一层——是 PDF 解析不准？布局分析失误？还是模型理解偏差？
- 读懂日志，不需要背诵所有字段，只要盯住
[PDF]、[LAYOUT]、[GLM4V]、[OCR]、[ERROR]这五把钥匙，你就掌握了 MinerU 的脉搏。
现在，打开你的终端，运行一条带LOG_LEVEL=DEBUG的命令，然后安静地读完第一份日志——你会发现，那个曾经“黑盒般”的 PDF 提取过程，正在你眼前一帧一帧变得透明。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
