聊到 AMD 显卡跑 AI 工具绝大多数人的第一反应都是“算了吧等官方支持”。MinerU 这个 PDF 解析工具也不例外官方文档里 GPU 一栏写的是 CUDAAMD 用户想本地部署看起来就只有吃 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 为什么要本地部署而不是直接用云端的 APIMinerU 官方其实也提供了 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 页以内、以纯文字为主的 PDFCPU 和 GPU 的差距其实没有想象中大因为启动和模型加载的时间占了不小比例真正算起来两边都“够快”。但一旦进入大批量、扫描版、多公式的文档CPU 就会被拉开好几个身位。适合人群显卡显存小于 6GB、不追求批量效率、或者只是想先看看 MinerU 处理效果的人。我建议所有人第一次部署时都先用 CPU 把流程跑通确认输出没问题再折腾 GPU 加速。这样能隔离开“软件配置问题”和“硬件加速问题”。路线难度加速效果适合人群Linux ROCm中等最接近 CUDA 的完整加速有 Linux 环境、批量处理为主Windows DirectML较高可用但偶发算子兼容问题Windows 单机、小批量处理CPU 兜底低无仅靠 CPU 算力少量文件、初次验证流程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架构代号 gfx1031RX 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 --usecaserocm装完之后重启再用一条命令确认驱动真的生效了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 --helpMinerU 第一次真正解析 PDF 时会自动下载模型文件。这里有一个关键选择模型源默认指向 Hugging Face 仓库但在实际使用中很多人的网络环境访问这个仓库很不稳定下载过程容易卡在某个进度条上。更省心的做法是在运行前把模型源切到 ModelScope这是国内一个非常常用的模型托管平台MinerU 是支持这个源的export MINERU_MODEL_SOURCEmodelscope模型下载后会缓存在~/.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_VERSION10.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_SOURCEmodelscope另外模型缓存目录建议提前备份。~/.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 是整个管线里最吃显存的部分之一把它放回 CPUGPU 专注跑版面检测和公式识别8GB 显存的卡就舒坦多了。5.4 Windows 上走 DirectML 的各种怪问题这条路我试过一次能跑但小问题不断这里挑两个最常见的说。第一个是设备识别问题装完torch-directml之后MinerU 默认还是去找cuda设备你需要手动在它的代码里把设备获取逻辑改成torch_directml.device()。第二个是算子兼容问题某些模型在 DirectML 后端上会提示算子不支持不同版本表现还不一样。我的建议是除非你实在没有 Linux 环境否则不要在这里耗时。花同样的时间装个 WSL 或者双系统走 ROCm 路线整体体验会稳定得多。6. 实测数据同样一份 PDF三种跑法的差距6.1 测试环境说明为了不让你觉得我在空口说白话我把测试环境写清楚操作系统是 Ubuntu 22.04CPU 是 AMD Ryzen 7 5700X显卡 RX 6700 XT12GB 显存gfx1031PyTorch 用的是 ROCm 6.2 版MinerU 是最新核心版。测试文档是一份 20 页的混合型 PDF里面有文字段落、三张表格、若干行内公式和独立公式属于比较常规的学术论文形态。6.2 不同模式下的耗时与显存占用运行模式总耗时峰值显存备注纯 CPU5700X约 11 分 40 秒不适用OCR 走 CPU整体最慢RX 6700 XTROCm约 1 分 55 秒6.8GB默认参数一次跑通RX 6700 XT调参后约 1 分 35 秒7.5GB拉高部分 batch size作为参照同文件在朋友的一台 RTX 306012GB上跑是 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 已经全部转完知识库的检索效果比预想中好不少。如果你也要做类似的事祝你一次跑通别再在环境上耗一个晚上。