MinerU默认路径搞不清？workspace切换操作手册，快速定位
你刚拉取了 MinerU 2.5-1.2B 深度学习 PDF 提取镜像，输入docker run -it --gpus all csdn/mineru:2.5-1.2b启动容器，终端一亮，光标停在/root/workspace—— 然后愣住了：
“MinerU 的代码在哪？”
“模型文件藏哪儿了？”
“我该cd到哪才能跑起来？”
别急。这不是配置问题，是路径认知断层。本手册不讲原理、不堆参数，只聚焦一个动作：从默认 workspace 出发，三步精准跳转到可执行位置。所有操作均基于真实镜像环境验证，命令复制即用，路径绝对可靠。
1. 默认路径真相：为什么是/root/workspace？
当你首次进入镜像，Shell 自动落在/root/workspace，这不是 MinerU 的工作目录，而是镜像设计者预留的“中转站”。它就像快递柜最上层的通用格口——方便你放临时文件，但不是收件人地址。
这个路径的存在，恰恰是为了避免新手误操作破坏核心环境。它本身不包含任何 MinerU 代码、模型或可执行脚本，只是一个干净、空的起点目录。
你可以用一条命令确认当前状态：
pwd && ls -la输出会显示：
/root/workspace total 8 drwxr-xr-x 2 root root 4096 May 10 10:23 . drwx------ 1 root root 4096 May 10 10:23 ..空空如也，正是它该有的样子。
关键结论：
/root/workspace是“出发点”，不是“目的地”。它的唯一使命，就是让你安全、清晰地走向真正的 MinerU 根目录。
2. 路径导航图：从 workspace 到 MinerU2.5 的完整链路
镜像结构经过精心组织，所有核心资产都集中在/root/MinerU2.5目录下。它不是隐藏路径，而是被明确预置的主工作区。下面这张路径导航图，帮你建立空间直觉：
/root ├── workspace ← 你当前所在（空目录，仅作中转） ├── MinerU2.5 ← 真正的 MinerU 主目录（含代码、模型、示例） │ ├── __main__.py │ ├── mineru │ ├── models/ ← 模型权重存放处（2509-1.2B + PDF-Extract-Kit-1.0） │ ├── test.pdf ← 预置测试文件（开箱即用） │ └── output/ ← 默认输出目标（自动创建） └── magic-pdf.json ← 全局配置文件（系统级读取路径）你会发现：
- 所有运行依赖（Python 包、CUDA 库）已通过 Conda 在启动时自动激活，无需
conda activate； - 所有模型权重已解压就位，无需
git lfs pull或手动下载； - 所有常用命令（如
mineru）已加入 PATH，全局可用。
你唯一要做的，就是从/root/workspace这个“候车厅”，走进/root/MinerU2.5这趟“直达列车”。
3. 三步切换法：零记忆负担的路径跳转
我们摒弃“记路径”思维，改用“动作锚点”方式。以下三步指令，每一步都有明确目的和即时反馈，执行完即可开始提取：
3.1 第一步：退出 workspace，回到 root 根目录
cd ..执行后，pwd输出为/root。这是关键转折点——你离开了中转区，站在了整个文件系统的顶层入口。
小贴士：
cd ..是 Linux 最基础的向上一级命令，比cd /root更安全（避免因路径拼写错误跳转失败）。
3.2 第二步：进入 MinerU2.5 主目录
cd MinerU2.5执行后，pwd输出为/root/MinerU2.5。此时ls可见：
__main__.py mineru models test.pdf output README.md你已抵达核心区。test.pdf就在这里，mineru命令可直接调用，models/下躺着全部权重。
3.3 第三步：验证环境，确认就绪
运行一条轻量检查命令，不触发 PDF 解析，只验证模块加载是否正常：
mineru --version正常输出类似：
mineru 0.2.5 (MinerU2.5-2509-1.2B)这表示：Python 环境、magic-pdf 包、CUDA 驱动、模型注册全部就绪。你已完全准备好执行真实任务。
如果报错
command not found，请确认是否漏掉第二步（未进入/root/MinerU2.5）。mineru命令依赖当前目录下的__main__.py和models/结构，脱离该路径将无法识别。
4. 实战速跑：用 test.pdf 完成一次端到端提取
现在，你已在正确路径、正确环境、正确状态下。接下来，用预置的test.pdf完成首次提取，全程不超过 20 秒：
4.1 执行提取命令
mineru -p test.pdf -o ./output --task doc-p test.pdf：指定输入文件（就在当前目录）-o ./output：输出到当前目录下的output文件夹（自动创建）--task doc：启用文档级解析模式（处理多栏、公式、表格等复杂结构）
你会看到实时日志滚动，包括：
[INFO] Loading model: MinerU2.5-2509-1.2B... [INFO] Processing page 1/12... [INFO] Extracting tables with structeqtable... [INFO] Saving markdown to ./output/test.md4.2 查看结果内容
提取完成后，进入输出目录查看成果：
cd ./output ls -l输出应包含：
test.md ← 主 Markdown 文件（含文字、公式 LaTeX 代码、图片引用） test_001.png ← 第1页截图（用于上下文对齐） test_table_001.png ← 表格识别结果图 test_formula_001.png ← 公式识别结果图用cat test.md | head -n 20快速浏览前20行，你会看到：
- 清晰的标题层级（
#,##） - 内联公式如
$E = mc^2$ - 表格以标准 Markdown 表格语法呈现
- 图片引用形如
这证明：路径正确 → 环境正确 → 模型正确 → 输出格式正确。
5. workspace 的正确用法：它不是摆设，而是你的“实验沙盒”
很多人把/root/workspace当成废目录，其实它有不可替代的价值——作为你自己的临时工作区，与 MinerU 主目录完全隔离。
比如你想：
- 测试自己的一份 PDF（
my_report.pdf）？直接丢进/root/workspace，然后从那里运行命令：cd /root/workspace mineru -p my_report.pdf -o ./my_output --task doc - 对比不同参数效果？在 workspace 创建多个子目录，互不干扰：
mkdir -p /root/workspace/exp_cpu /root/workspace/exp_gpu cp my_report.pdf /root/workspace/exp_cpu/ cd /root/workspace/exp_cpu # 修改 magic-pdf.json 设为 cpu 模式，再运行
这样做的好处是：
🔹 不污染/root/MinerU2.5的原始结构，下次更新镜像无缝衔接；
🔹 所有自定义文件、输出、日志都在 workspace 下，一目了然；
🔹 即使操作失误（如误删output/），MinerU 主目录毫发无损。
记住这个口诀：workspace 是你的“桌面”，MinerU2.5 是你的“软件安装目录”——你永远在桌面上双击图标（运行命令），而不是去翻安装目录里找 exe 文件。
6. 常见路径误区与一键修复方案
以下是新手高频踩坑点，附带可复制粘贴的修复命令：
6.1 误区一：“我在 workspace 里运行 mineru，为啥找不到 test.pdf？”
❌ 错误操作：
cd /root/workspace mineru -p test.pdf -o ./output --task doc报错：FileNotFoundError: test.pdf
原因：test.pdf不在 workspace，而在/root/MinerU2.5/
修复（任选其一）：
- 方案A（推荐）：切到 MinerU2.5 目录再运行
cd /root/MinerU2.5 && mineru -p test.pdf -o ./output --task doc - 方案B：用绝对路径指定输入
mineru -p /root/MinerU2.5/test.pdf -o ./output --task doc
6.2 误区二：“我改了 magic-pdf.json，但 mineru 还是用 GPU，没生效”
❌ 错误操作：在/root/MinerU2.5/下编辑了magic-pdf.json，但实际读取的是/root/magic-pdf.json
原因：MinerU 默认只认/root/magic-pdf.json（系统级配置路径），忽略当前目录下的同名文件
修复：始终编辑根目录下的配置文件
nano /root/magic-pdf.json # 修改 "device-mode": "cpu" 后保存6.3 误区三：“output 文件夹生成在奇怪的位置，找不到结果”
❌ 错误操作：运行时用了mineru -p test.pdf -o /tmp/output，结果在/tmp里翻半天
原因：-o参数支持任意路径，但新手易忽略相对路径更可控
修复：坚持用./output（当前目录下），结果永远在眼皮底下
cd /root/MinerU2.5 mineru -p test.pdf -o ./output --task doc ls ./output # 一眼可见7. 总结：路径认知升级，才是高效使用的真正起点
你不需要记住所有路径，只需要建立两个确定性认知：
- 确定性一：
/root/workspace是你的“安全起点”，每次启动都从这里出发，它空着才对； - 确定性二：
/root/MinerU2.5是你的“执行中心”，所有代码、模型、示例、输出都围绕它组织，它是唯一需要cd进去的地方。
这两点一旦内化，你就完成了从“路径困惑者”到“环境掌控者”的转变。后续无论是批量处理百份 PDF、调试表格识别精度，还是集成进自己的流水线，路径都不再是障碍，而成了你信手拈来的操作习惯。
现在，关掉这篇手册，打开终端，敲下这三行：
cd .. cd MinerU2.5 mineru -p test.pdf -o ./output --task doc看着output/里生成的test.md，你就知道：MinerU 已真正属于你。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
