MinerU项目NPU适配问题深度解析与解决方案
项目地址: https://gitcode.com/OpenDataLab/MinerU 问题背景
在使用MinerU项目进行PDF文档解析时，部分用户在使用NPU（神经网络处理器）设备时遇到了torch版本兼容性问题。具体表现为在加载LayoutLMv3模型时出现安全漏洞相关的错误提示，导致程序异常终止。
错误现象分析
用户在使用NPU设备运行MinerU时，系统抛出以下关键错误信息：
ValueError: Due to a serious vulnerability issue in `torch.load`, even with `weights_only=True`, we now require users to upgrade torch to at least v2.6 in order to use the function.
这个错误源于Transformers库在新版本中加强了对torch.load函数的安全检查。由于CVE-2025-32434漏洞的存在，即使用户设置了weights_only=True参数，Transformers库仍然要求使用torch 2.6及以上版本才能继续使用该功能。
根本原因
- 安全漏洞限制：torch.load函数存在严重的安全漏洞，即使设置了weights_only=True仍可能被利用
- 版本不兼容：用户当前使用的torch版本为2.3.1，低于要求的最低版本2.6
- NPU生态限制：NPU专用的torch_npu版本需要与标准torch版本严格匹配
解决方案
方案一：升级torch版本（推荐）
对于使用华为NPU设备的用户，需要同步升级torch和torch_npu到2.6.0版本：
# 升级标准torch库
pip3 install torch==2.6.0 torchvision==0.21.0
# 安装对应的torch_npu版本
pip3 install torch_npu-2.6.0rc1-cp310-cp310-manylinux_2_28_aarch64.whl
方案二：降级Transformers版本
如果无法升级torch版本，可以选择降级Transformers库到4.49.0版本：
pip3 uninstall transformers
pip3 install transformers==4.49.0
这种方法虽然可以暂时解决问题，但可能存在长期维护风险，建议作为临时解决方案。
其他NPU设备适配
海光DCU设备适配
对于海光DCU用户，除了需要调整Transformers版本外，还需要使用海光官方提供的专用依赖包：
- torch: 海光定制的2.4.1版本
- torchvision: 对应的0.19.1版本
- paddlepaddle-dcu: 专用的3.0.0版本
这些专用包需要从海光官方获取，确保与DCU硬件的兼容性。
部署注意事项
- 环境变量配置：确保正确设置NPU相关的环境变量
- 依赖库版本匹配：保持torch、torch_npu、torchvision版本的严格一致
- 模型下载：在调整环境后重新下载模型文件
- 配置文件更新：将magic-pdf.json中的设备配置从cpu改为npu
性能优化建议
在成功解决NPU适配问题后，用户可能会遇到模型加载警告：
Warning: since the loaded file is not a zipfile...
这个警告可以忽略，不影响功能使用。但需要注意检查模型是否真正加载到NPU上运行，可以通过监控NPU使用情况来确认。
总结
NPU设备在深度学习应用中能够提供显著的性能优势，但在实际部署过程中需要特别注意版本兼容性问题。MinerU项目对torch版本有较高要求，用户需要根据自身硬件平台选择合适的解决方案。建议优先采用升级torch版本的方式，以确保系统的安全性和稳定性。对于特殊硬件平台，务必使用厂商提供的专用软件包，避免兼容性问题。
通过正确的环境配置和版本管理，用户可以充分发挥NPU设备的计算能力，提升PDF文档处理的效率和性能。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
