AMD显卡本地部署MinerU：从零跑通PDF转Markdown的完整指南

聊到 AMD 显卡跑 AI 工具，绝大多数人的第一反应都是“算了吧，等官方支持”。MinerU 这个 PDF 解析工具也不例外，官方文档里 GPU 一栏写的是 CUDA，AMD 用户想本地部署，看起来就只有吃 CPU 的份。但实际情况是，社区里已经有人把这条 AMD 部署指南趟出来了，而且没有想象中那么玄学——无非是 ROCm 驱动、PyTorch 的 ROCm 轮子、以及一个关键的环境变量。这篇文章是我自己从零跑通 MinerU 本地部署的完整记录，适合手头有 RX 6000/7000 系列显卡、想在本地把 PDF 批量转成 Markdown 的朋友。整个过程踩了不少坑，我把排查思路和最终能用的方案都整理在下面了，照着抄就行。

1. MinerU 到底是什么，为什么值得你在 AMD 卡上折腾

1.1 从 PDF 到 Markdown，中间发生了什么

MinerU 是 OpenDataLab 开源的一个文档解析工具，输入是一份 PDF，输出是结构化的 Markdown（也可以同时输出 JSON）。它跟那种简单的“PDF 转文本”工具不是一回事。它先做版面分析，把页面里的正文、标题、表格、图片、公式、页眉页脚区分开，然后针对每一种元素走不同的处理管线：表格还原成 Markdown 表格结构，公式识别成 LaTeX 格式，扫描件和图片里的文字用 OCR 提取，最后再拼装成一份层级清晰的 Markdown 文档。

这套流程里每一步都是深度学习模型在跑。版面检测用的是一套目标检测模型，要找标题栏、正文块、表格框；公式识别用的是专门的公式模型，能把一张公式截图转成 LaTeX 源码；OCR 环节也有自己的识别模型。所以它不是一个轻量级的文本抽取脚本，而是一个由多个模型串联起来的完整推理管线。这也解释了为什么它对硬件有要求——模型多了，计算量自然就上来了。

1.2 显卡在里面的角色

很多人以为显卡只在训练大模型的时候才有用，这是个误解。MinerU 这种推理任务反而是显卡的“舒适区”。它的模型虽然多，但每个模型的参数量都不算离谱，关键是这些模型要在每一页 PDF 上依次跑一遍。页面里检测到多少个公式块，公式识别模型就要跑多少次；OCR 更是逐块识别。整份 PDF 跑下来，矩阵乘法的次数非常可观。

我在纯 CPU 环境下处理过一份 20 页的扫描版 PDF，里面有公式有表格，耗时大概在十分钟出头。同样的文件放到 AMD 显卡上用 ROCm 跑，时间直接压缩到两分钟以内。原因很简单：CPU 擅长的是复杂的逻辑分支和并行度不高的任务，而这种“大量小矩阵乘加”的运算正是 GPU 的看家本领。你不需要理解太多底层原理，只要记住一句话——MinerU 用了 GPU，速度是数量级的提升，不是百分之几十的提升。

1.3 为什么要本地部署，而不是直接用云端的 API

MinerU 官方其实也提供了 API 服务，传一份 PDF 上去，等一会儿就能拿回 Markdown。对于偶尔处理一两份文档的人来说，用 API 确实省事。但如果你有下面这些需求，本地部署就是唯一的选择：

• 数据敏感：合同、论文、内部资料这些内容不适合传到第三方服务，谁也不想让自己的文档在别人的服务器上过一遍。
• 批量处理：我手上有一个 300 多份 PDF 的资料库要转成 Markdown 喂给知识库系统，用 API 慢慢传，费用和时间都受不了。
• 流程集成：本地部署之后，可以把 MinerU 写进脚本、接到定时任务里，PDF 一落地就自动解析，完全不占人工。

也就是说，本地部署的真正价值不是“免费”，而是“可控”。当你开始批量处理文档，或者想把它嵌进自己的自动化链路时，本地跑的这套东西才谈得上可用。

2. AMD 显卡跑 AI 工具的老问题：不是算力，是识别

2.1 CUDA 是事实标准，ROCm 是追赶者

聊 AMD 部署，绕不开一个事实：整个 AI 生态默认建立在 NVIDIA 的 CUDA 之上。PyTorch 的预编译包里，CUDA 版本是默认选项，官方文档、教程、报错排查全都围绕 CUDA 展开。AMD 对应的方案叫 ROCm，它的架构思路和 CUDA 一一对应，但生态成熟度差了不止一个身位。最直观的差距就是：PyTorch 官方虽然会出 ROCm 版本的 wheel 包，但在 Windows 上长期只有 Linux 可用，而且官方支持矩阵里列出来的显卡型号非常克制。

这带来的直接后果是，大量 AI 工具的 GPU 加速功能，默认只写了 CUDA 路径。MinerU 也是这样。你去翻它的文档，安装部分大概率只会看到 “需要 CUDA 环境” 这一行字。不是说开发者故意忽视 AMD 用户，而是维护一套支持矩阵的成本很高，社区项目普遍没有人力去做多平台适配。

2.2 真正的问题不是算力，而是“能不能被识别”

我最早折腾 MinerU 的时候，对 AMD 的预期是“性能差一点也能忍”，结果真装上之后发现，问题根本轮不到谈性能。PyTorch 检测不到显卡设备，环境里torch.cuda.is_available()返回的是False——整条 GPU 推理路径直接不可用。大多数 AMD 用户卡在这一步就放弃了，因为从用户视角看，“设备都识别不到，还怎么玩”。

但实际上，这里面的差距更多是“适配层”的问题。ROCm 底层的 HIP 接口和 CUDA API 在设计上高度相似，PyTorch 在 ROCm 版里甚至直接复用了一套叫torch.cuda的 Python 接口，底层帮你翻译成 HIP 调用。也就是说，只要 PyTorch 能识别到设备、能正常运行算子，MinerU 这类上层应用根本不需要改代码。难点全部集中在“让 PyTorch 的 ROCm 后端识别到你的那块 AMD 卡”上。

2.3 社区破解的关键：一个环境变量和一个补丁包

真正让 AMD 路线跑通的核心，其实是社区贡献的两个东西。第一个是HSA_OVERRIDE_GFX_VERSION这个环境变量，它允许你强制 ROCm 运行时按照指定的 GPU 架构来加载内核。AMD 的显卡架构代号从 RDNA2 的 gfx1030 一路到 RDNA3 的 gfx1100，很多中端卡（比如 RX 6600、RX 6700 XT）用的架构变体官方没写进支持列表，但这个变量可以把它们“伪装”成官方支持的型号，让运行时愿意给它加载编译好的内核。第二个是torch-directml这个补丁包，它让 PyTorch 能借助 DirectML 后端在 Windows 的 AMD 显卡上跑推理，给 Windows 用户留了一条活路。

这两个东西都是社区用户一点一点试出来的，不是 AMD 官方给出的标准路径。所以我说这是一份“社区驱动的部署指南”，没有夸大其词。

3. 社区趟出来的三条路线，按环境选一条

3.1 路线一：Linux + ROCm 跑 PyTorch 原生推理（推荐）

这是目前最稳的一条路。PyTorch 官方会发布针对 ROCm 的预编译 wheel 包，安装方式类似于 CUDA 版，只是把--index-url换成 ROCm 的源。装上之后，MinerU 不需要任何改动，直接用默认的 CUDA 探测逻辑就能跑起来。整个过程里最折腾的其实是 ROCm 驱动本身的安装，但只要跟着 AMD 官方仓库的说明走，成功率很高。

适合人群：有 Linux 环境（哪怕是双系统或一台闲置机器）、手头是 RX 6000/7000 系列显卡、想省心拿到完整 GPU 加速效果的用户。

3.2 路线二：Windows 上用 DirectML 硬凑

Windows 用户想在本机跑，大概率得走torch-directml这条路。它的原理是让 PyTorch 把算子派发给 DirectML 后端，再由 DirectML 调用 AMD 显卡的驱动。好处是不用装 Linux，坏处是两个：一是 MinerU 的设备选择逻辑默认只认cuda，你得手动打个小补丁，把设备改成 DirectML 的设备对象；二是 DirectML 对某些算子的实现不如 ROCm 完整，跑长文档时偶尔会遇到卡住或者个别算子报错。

适合人群：不想装双系统、只处理小批量文档、愿意动手改代码的 Windows 用户。坦白讲，这条路更适合“能跑就行”的探索型玩家，不适合拿来当长期生产力。

3.3 路线三：CPU 兜底，先跑通再说

第三条路线最简单也最保守：直接把 MinerU 跑在 CPU 上。MinerU 本来就支持 CPU 推理，装好依赖、下载完模型就能用。对于 5 页以内、以纯文字为主的 PDF，CPU 和 GPU 的差距其实没有想象中大，因为启动和模型加载的时间占了不小比例，真正算起来两边都“够快”。但一旦进入大批量、扫描版、多公式的文档，CPU 就会被拉开好几个身位。

适合人群：显卡显存小于 6GB、不追求批量效率、或者只是想先看看 MinerU 处理效果的人。我建议所有人第一次部署时都先用 CPU 把流程跑通，确认输出没问题，再折腾 GPU 加速。这样能隔离开“软件配置问题”和“硬件加速问题”。

4. 实操：Ubuntu + ROCm 跑通 MinerU 的完整链路

4.1 装驱动之前先确认三件事

别急着敲命令，先花五分钟确认自己的硬件和系统情况，后面能少排好几个小时的错。

第一，确认显卡的真实型号和架构。打开终端执行：

lspci | grep -i vga

如果这条命令没输出，换lspci | grep -i "amd\|display"。注意，很多人第一反应是lspci | grep -i amd，但有的机器上 VGA 设备显示的是 “Advanced Micro Devices”，有的显示的是具体型号名，AMDisambiguation 全靠缘分。我比较推荐直接看显卡全名，然后去 AMD 官网或者 ROCm 的兼容列表里查它属于哪一代架构。比如 RX 6700 XT 是 RDNA2，架构代号 gfx1031；RX 7900 XTX 是 RDNA3，代号 gfx1100。

第二，确认显卡的显存。MinerU 默认管线在 GPU 上跑，建议至少 8GB 显存，6GB 会比较紧张。显存不够时它会退到部分模型用 CPU，那就失去了整体加速的意义。

第三，确认你的 Linux 发行版版本。ROCm 官方仓库对不同版本的 Ubuntu 支持不一样，我这边是用 Ubuntu 22.04 装的 ROCm 6.x。如果你用的是别的发行版或者更新的系统，务必先去官方文档看一眼有没有对应版本，否则驱动装上之后会遇到内核模块加载失败这种硬伤。

4.2 安装 ROCm 驱动，然后装 PyTorch 的 ROCm 版

ROCm 的安装方式在不同版本之间略有差异，以我当时用的 6.x 系列为例，大致是先从 AMD 官方仓库下载统一的安装包，然后调用它的安装脚本：

curl -fsSL https://repo.radeon.com/amdgpu-install/latest/ubuntu/jammy/amdgpu-install_6.x.x_all.deb -O sudo apt install -y ./amdgpu-install_6.x.x_all.deb sudo amdgpu-install --usecase=rocm

装完之后重启，再用一条命令确认驱动真的生效了：

rocminfo | grep -E "gfx|Marketing"

如果能看到类似gfx1031、gfx1100的输出，说明驱动和内核驱动已经正常加载。这里多说一句：装完驱动后必须重启，因为 AMD 的内核驱动模块需要重新加载到 initramfs 里，不重启的话rocminfo大概率什么都看不到。

驱动就绪后，Python 侧先建一个干净的虚拟环境，然后装 PyTorch 的 ROCm 版本。这里最容易踩的坑是装成默认的 CUDA 版，务必用指定的索引源：

python -m venv mineru-venv source mineru-venv/bin/activate pip install torch torchvision --index-url https://download.pytorch.org/whl/rocm6.2

装完立刻验证一下设备能不能被 PyTorch 识别：

import torch print(torch.cuda.is_available()) print(torch.cuda.get_device_name(0))

ROCm 版 PyTorch 的 Python 接口仍然叫torch.cuda，但底层走的是 HIP。如果这里输出的是True和你的显卡型号，那恭喜你，最难的环节已经过了。注意，版本号要以 PyTorch 官网当时支持的 ROCm 版本列表为准，我写 6.2 只是举例。

4.3 安装 MinerU 并准备模型

PyTorch 通了之后，MinerU 的安装就非常简单了。官方推荐的安装方式是用核心包：

pip install -U "mineru[core]"

安装完可以先跑一下命令行帮助，确认工具装好了：

mineru --help

MinerU 第一次真正解析 PDF 时，会自动下载模型文件。这里有一个关键选择：模型源默认指向 Hugging Face 仓库，但在实际使用中，很多人的网络环境访问这个仓库很不稳定，下载过程容易卡在某个进度条上。更省心的做法是在运行前把模型源切到 ModelScope，这是国内一个非常常用的模型托管平台，MinerU 是支持这个源的：

export MINERU_MODEL_SOURCE=modelscope

模型下载后会缓存在~/.cache/mineru下。我的经验是，即使你最终准备走 GPU 路线，也建议第一次先让它在 CPU 模式下把模型完整下载下来。模型到位之后，再切到 GPU 模式跑正式任务，这样能把“下载问题”和“推理问题”彻底分开排查。

4.4 第一次解析，验证 GPU 真的在用

模型就绪后，找一份测试 PDF 跑起来。MinerU 2.x 的命令行很直接：

mineru -p ./test.pdf -o ./output_dir

默认情况它会自动探测设备。如果你想显式指定用 GPU，可以加上设备参数。跑的时候留意终端日志，如果输出里出现了类似Using device: cuda的信息，就说明 GPU 路径被激活了。我建议第一次跑的时候用一份短文档，比如两三页的论文摘要，这样能快速验证完整流程，不会因为单页处理时间太长而误以为卡死。

处理完成后，去输出目录看结果。正常情况下会得到一个 Markdown 文件和一个同名文件夹（存放提取出的图片），Markdown 里应该能看到结构清晰的标题层级、表格和公式。到这里，AMD 显卡跑 MinerU 这件事就算正式跑通了。

5. 部署中最容易翻车的四个环节，附排查链路

5.1 显卡加载失败：gfx 架构不匹配怎么办

这是 AMD 路线里最容易卡住的一环，也是社区讨论最密集的问题。现象很典型：rocminfo能看到显卡，驱动也装了，但 PyTorch 里torch.cuda.is_available()仍然是False，或者跑 MinerU 时直接报类似 “no kernel image is available for execution on the device” 的错误。

排查链路是这样的：先看自己的显卡架构代号，执行rocminfo找gfx开头的行；然后去查你安装的 ROCm 版本官方支持哪些架构；如果你的显卡型号不在列表里，比如是 RX 6000 系列里的一些中端卡，ROCm 6.x 对它们只提供了基础支持，这时候就要祭出那个社区神器环境变量：

export HSA_OVERRIDE_GFX_VERSION=10.3.0

这个变量的含义是：强制 ROCm 运行时把你显卡当成 gfx1030 来加载内核。比如 gfx1031、gfx1032 这些变体架构，在很多 ROCm 版本里没有对应的预编译内核，但它们的指令集和 gfx1030 高度兼容，伪装一下就能跑。设置完这个变量之后，重新运行 PyTorch 的探测代码，很可能设备就出来了。

要注意的是，这个变量会同时影响后面的所有 ROCm 任务，不用的时候记得取消（unset），因为对某些新架构设置一个过老的代号反而会引入兼容问题。我见过有人在 RX 7900 XTX 上设置了 10.3.0，结果性能掉了一半还多，最后发现去掉变量才是对的。

5.2 模型文件下载不下来

MinerU 第一次运行要下载的模型总量不小，如果网络访问模型仓库不稳定，最容易出现的情况就是：日志一直停在 “Downloading model” 不动，或者反复从头开始。真心建议直接使用 ModelScope 源，别在 Hugging Face 上死磕。切换方式就是前面提到的环境变量：

export MINERU_MODEL_SOURCE=modelscope

另外，模型缓存目录建议提前备份。~/.cache/mineru这个文件夹里是全部模型文件，我第一次部署时把模型下载完整后，顺手把这个目录打包存了一份。后面在另一台机器上部署时，直接把缓存解压过去，一分钟搞定，完全不用重新下载。批量部署多台机器时这招特别管用。

5.3 显存不足，换个思路而不是换显卡

显存不足在 AMD 卡上比 NVIDIA 卡更容易遇到，因为很多 AMD 中端卡是 8GB 显存，而 MinerU 默认配置偏保守地高。报错通常以 OOM 结尾，有时是 CUDA 层面的错误码，有时直接 Python 抛RuntimeError: CUDA out of memory。

我的建议分两步。第一步，调小批处理参数。MinerU 的配置里可以控制版面检测、公式识别、OCR 各环节的 batch size，把这两个值从默认调低（比如从 4 调到 2，甚至 1），显存占用会显著下降，代价是速度略有损失，但远好过整体跑不起来。第二步，如果显存还是不够，那就把 OCR 环节留在 CPU 上执行。OCR 是整个管线里最吃显存的部分之一，把它放回 CPU，GPU 专注跑版面检测和公式识别，8GB 显存的卡就舒坦多了。

5.4 Windows 上走 DirectML 的各种怪问题

这条路我试过一次，能跑，但小问题不断，这里挑两个最常见的说。第一个是设备识别问题：装完torch-directml之后，MinerU 默认还是去找cuda设备，你需要手动在它的代码里把设备获取逻辑改成torch_directml.device()。第二个是算子兼容问题：某些模型在 DirectML 后端上会提示算子不支持，不同版本表现还不一样。我的建议是，除非你实在没有 Linux 环境，否则不要在这里耗时。花同样的时间，装个 WSL 或者双系统走 ROCm 路线，整体体验会稳定得多。

6. 实测数据：同样一份 PDF，三种跑法的差距

6.1 测试环境说明

为了不让你觉得我在空口说白话，我把测试环境写清楚：操作系统是 Ubuntu 22.04，CPU 是 AMD Ryzen 7 5700X，显卡 RX 6700 XT（12GB 显存，gfx1031），PyTorch 用的是 ROCm 6.2 版，MinerU 是最新核心版。测试文档是一份 20 页的混合型 PDF，里面有文字段落、三张表格、若干行内公式和独立公式，属于比较常规的学术论文形态。

6.2 不同模式下的耗时与显存占用

作为参照，同文件在朋友的一台 RTX 3060（12GB）上跑是 1 分 25 秒左右。从这个对比能看出来，AMD 卡走 ROCm 之后，和同级别 NVIDIA 卡的差距已经缩小到“可用”的范围内，远没有到“没法用”的地步。

6.3 怎么看这些数据，什么时候值得用 GPU

先泼一盆冷水：如果你只是偶尔处理三五页 PDF，这些数字对你没什么参考意义。单页处理的场景里，模型加载和初始化占了大头，GPU 的优势会被摊薄，CPU 反而省心。但只要你开始批量处理，比如几十份甚至上百份文档，这里的时间差就会变成小时级甚至天级。我处理那 300 份资料库时，CPU 模式要跑将近两天，GPU 模式三个多小时收工。这种场景下，AMD 显卡的部署折腾就完全值回票价了。

另外一个容易被忽略的事实是：ROCm 路线的收益不仅体现在速度。GPU 跑 MinerU 时，CPU 基本是空闲的，你可以同时干别的事；CPU 全力跑解析时，机器基本没法做其他交互操作。这个体验差距在长时间批量任务里非常明显。

7. 一些只有跑过才会知道的细节

最后分享几个我在实际使用中积累下来的经验，不一定写在哪份文档里，但对实操很有帮助。

第一，批量处理时，别用命令行手动一条条跑。写一个简单的循环脚本，遍历目录下的所有 PDF，顺序调用 MinerU，同时把日志按文件分开保存。我在处理 300 份文档时，第一次没写脚本，中途 UI 断了一次，结果不知道跑到哪一份，只能从头再来。后来改成脚本逐份输出日志，断点续跑的问题就彻底解决了。

第二，MinerU 的 JSON 输出比 Markdown 更适合做自动化。Markdown 是给人看的，JSON 里保留了每个文本块的坐标、类型、层级关系，喂给知识库系统做结构化索引非常合适。如果你是做 RAG 或者文档治理的，建议输出时把 JSON 也打开，这几乎是零成本的事。

第三，模型缓存目录值得单独备份。我在前面也提过，~/.cache/mineru里的模型文件是完整可复用的。装到新机器上，把整个目录拷过去，就能跳过最痛苦的模型下载阶段。如果你管理多台机器，这个习惯能帮你省下大量时间。

第四，环境变量要养成“用完即弃”的习惯。HSA_OVERRIDE_GFX_VERSION很强大，但它本质上是一个绕过官方支持矩阵的兼容手段，不是越多越好。我在默认配置能跑通的情况下尽量不设它，只有在确实报架构不支持时才启用。这能避免很多诡异的性能下降问题。

说到底，AMD 显卡跑 MinerU 这件事，技术含量并不在某个高深的算法里，而在于把驱动、框架版本、模型源、设备变量这几件事串起来。社区已经把每个坑都标好了位置，你要做的只是沿着路走，而不是自己去蹚一遍水。我现在这批 PDF 已经全部转完，知识库的检索效果比预想中好不少。如果你也要做类似的事，祝你一次跑通，别再在环境上耗一个晚上。