MinerU 2.5-1.2B入门必看：输出路径设置与结果查看教程

MinerU 2.5-1.2B入门必看：输出路径设置与结果查看教程

1. 理解你的任务：为什么需要关注输出路径？

你拿到的这个镜像，不是普通的工具包，而是一套完整的视觉多模态推理系统。它内置了MinerU 2.5-2509-1.2B模型和GLM-4V-9B的支持能力，专为解决 PDF 文档中那些让人头疼的复杂结构——比如多栏排版、嵌套表格、数学公式、图文混排——而生。

但再强大的模型，如果你找不到它的“产出物”，那也等于白搭。
很多新手在运行完命令后第一反应是：“我跑完了，可文件去哪儿了？”
这个问题的核心，往往出在输出路径设置不当或结果查看方式不正确。

本教程将带你彻底搞清两个关键动作：

• 如何准确指定输出目录
• 跑完任务后，去哪里、怎么看生成的内容

不需要你懂深度学习原理，也不用折腾环境配置，我们只讲最实用的操作流程。

2. 快速启动：三步完成一次完整提取

2.1 进入工作目录

镜像启动后，默认进入/root/workspace目录。你需要先切换到 MinerU 的主项目文件夹：

cd .. cd MinerU2.5

这一步很关键。因为示例文件test.pdf和默认的输出逻辑都基于当前路径设计。

小贴士：你可以用pwd命令确认当前所在路径，确保你在/root/MinerU2.5下执行后续操作。

2.2 执行文档提取命令

接下来运行核心指令：

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

我们来拆解这条命令的意思：

这里的-o ./output就是你控制结果存放位置的关键开关。

2.3 查看输出内容

等待几秒至几分钟（取决于 PDF 复杂度），程序运行结束后，你会看到提示信息，表示转换完成。

此时，使用以下命令查看输出目录结构：

ls -l ./output/

你应该能看到类似如下的文件列表：

test.md figures/ formulas/ tables/

• test.md是最终生成的 Markdown 文件，打开它就能看到结构化内容。
• figures/存放从 PDF 中提取的所有图像。
• formulas/包含识别出的 LaTeX 公式图片及其对应的代码。
• tables/保存表格截图及结构化数据（JSON 或 CSV 格式）。

如果你想直接预览 Markdown 内容，可以使用：

cat ./output/test.md

或者通过编辑器打开（如nano、vim，或图形界面工具）。

3. 输出路径详解：相对路径 vs 绝对路径

3.1 推荐使用相对路径

像./output这样的写法叫相对路径，意思是“从当前目录开始找 output 文件夹”。

优点非常明显：

• 简洁明了，适合快速测试
• 不依赖具体服务器路径，便于迁移和分享脚本

例如：

mineru -p test.pdf -o ./my_results --task doc

会把结果存到当前目录下的my_results文件夹中。

3.2 何时使用绝对路径？

当你希望把结果统一归档到某个固定位置时，可以用绝对路径。

比如你想把所有输出集中放在/data/pdf_outputs：

mineru -p test.pdf -o /data/pdf_outputs/report_001 --task doc

注意：确保该路径存在且有写权限。否则会报错Permission denied或No such file or directory。

你可以提前创建目录：

mkdir -p /data/pdf_outputs/report_001

然后再运行命令。

3.3 避免常见路径错误

4. 结果查看实战：如何验证提取质量？

4.1 Markdown 文件怎么看？

.md文件本质是纯文本，可以用任何文本工具打开。

推荐方式：

• 终端查看：

  cat ./output/test.md

  或分页查看：

  less ./output/test.md

• 编辑器打开：

  nano ./output/test.md

• 导出到本地查看：
  如果你在云平台运行，可通过 SFTP 工具（如 FileZilla）下载整个output文件夹，在本地用 Typora、VS Code 等支持 Markdown 渲染的工具查看效果。

重点关注：

• 多栏内容是否顺序错乱？
• 图片是否有占位标记？如![fig1](figures/fig1.png)
• 公式是否以$$...$$形式正确嵌入？
• 表格是否保留了原始结构？

4.2 图片与公式文件检查

进入figures/目录：

ls figures/

你会看到一堆命名规则清晰的图片文件，如page_1_fig_1.png。

同样地，formulas/下会有.png和.txt配对文件：

• formula_1.png：公式的图像
• formula_1.txt：对应的 LaTeX 代码

这些可用于后期插入文档或进一步处理。

4.3 表格还原情况评估

打开tables/目录：

ls tables/

里面通常包含：

• table_1.png：原始表格截图
• table_1.json或table_1.csv：结构化数据

你可以用cat查看 JSON 内容，判断行列是否对齐、文字是否完整。

如果发现表格识别不准，可能是源 PDF 表格边框缺失或格式太复杂，可尝试调整配置文件中的table-config设置（见下文）。

5. 关键配置文件解读：让输出更可控

5.1 配置文件位置

系统默认读取根目录下的：

/root/magic-pdf.json

这是全局行为控制中心，影响 GPU 使用、模型路径、表格识别模式等。

5.2 核心参数说明

{ "models-dir": "/root/MinerU2.5/models", "device-mode": "cuda", "table-config": { "model": "structeqtable", "enable": true } }

逐项解释：

• "models-dir"：告诉程序去哪找模型权重。本镜像已预设正确路径，无需修改。
• "device-mode"：决定使用 GPU 还是 CPU。
  • "cuda"：启用 GPU 加速（推荐）
  • "cpu"：仅用 CPU，适合显存不足的情况
• "table-config"：控制表格识别行为
  • "enable": true表示开启表格结构解析
  • "model": "structeqtable"使用专门针对科学文献优化的表格模型

5.3 修改配置的小技巧

如果你遇到显存溢出（OOM），可以临时切回 CPU 模式：

sed -i 's/"device-mode": "cuda"/"device-mode": "cpu"/' /root/magic-pdf.json

这条命令会自动替换 JSON 文件中的值，无需手动编辑。

改完后再运行提取任务即可。

6. 常见问题与应对策略

6.1 输出目录为空？文件没生成！

可能原因：

• 当前路径下没有test.pdf文件 → 用ls确认是否存在
• 输出路径权限不足 → 改用./output或检查目录写权限
• 命令拼写错误 → 检查-o后面是否有空格

解决方案：

# 确认输入文件存在 ls test.pdf # 创建输出目录并赋权 mkdir -p ./output chmod 755 ./output

6.2 Markdown 里图片路径不对？

现象：本地打开时图片无法显示。

原因：路径是相对的，必须保证figures/文件夹与.md文件在同一级目录。

正确做法：

• 下载整个output文件夹
• 在 VS Code 中打开test.md，图片应正常渲染

6.3 公式显示为乱码或占位符？

虽然镜像集成了 LaTeX OCR 模型，但以下情况仍可能导致识别失败：

• 原始 PDF 分辨率太低
• 公式被压缩成模糊图像
• 特殊字体未正确嵌入

建议：

• 尽量使用高质量 PDF 源文件
• 若仅为个别公式出错，可手动修正.txt文件中的 LaTeX 代码

7. 总结：掌握输出管理，才算真正上手

7.1 回顾重点操作

本文带你走通了从运行命令到查看结果的全流程，核心要点包括：

• 输出路径由-o参数控制，推荐使用./output这类相对路径
• 结果包含四大组成部分：Markdown 主文件 + 图片 + 公式 + 表格
• 查看结果要用合适工具：终端cat、编辑器nano，或导出到本地用 Typora 渲染
• 配置文件决定底层行为，特别是device-mode和table-config
• 遇到问题先查路径、权限、输入文件是否存在

7.2 下一步你可以做什么？

• 尝试用自己的 PDF 文件替换test.pdf，测试实际效果
• 修改输出路径，批量处理多个文档
• 调整magic-pdf.json中的参数，探索不同识别模式
• 将输出集成进自动化工作流（如自动归档、知识库构建）

这套镜像的强大之处在于“开箱即用”，而你能掌控输出路径和结果查看方式，才意味着真正掌握了主动权。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。