PyTorch 2.8.0 Compatibility Issues

[myhloli]

【重要通知】PyTorch 2.8.0 兼容性问题公告

2025年8月6日，PyTorch官方发布了2.8.0版本。我们在第一时间完成兼容性测试后，发现以下两个关键问题：

性能异常

• OCR检测模型（ocr-det）在batch推理模式下速度下降显著（约数十倍） ocr-det batch推理 与torch 2.8.0存在兼容性问题导致det阶段速度下降 #3285
• 阅读顺序排序模型输出结果在特定场景下出现异常 torch 2.8.0 版本使用pipeline后端阅读顺序异常 #3338

已解决的问题

针对OCR性能下降问题，我们已通过版本检测机制实现：

1. 当检测到torch≥2.8.0时，自动切换至顺序推理模式
2. 该方案可避免性能断崖式下跌
   ⚠️ 注意：批量处理文档时仍可能有30%-100%的速度损失

待解决的问题

阅读顺序异常问题属于偶发性缺陷，目前尚未找到有效解决方案

推荐解决方案

建议所有用户暂时保持PyTorch版本约束：

torch<2.8.0

特殊需求处理

如确需使用2.8.0版本，请按以下步骤操作：

1. 先安装mineru,这样会通过依赖安装torch 2.7.1
2. 手动执行安装命令,将torch 更新至2.8.0版本:

pip3 install torch==2.8.0 torchvision

⚠️ 注意：该方案可能影响OCR模块性能表现和导致某些场景阅读顺序异常

我们将持续关注PyTorch官方进展，并在问题彻底解决后及时更新版本兼容策略。

---

【Important Notice】PyTorch 2.8.0 Compatibility Issues

August 6, 2025 - The PyTorch team released version 2.8.0. After immediate compatibility testing, we identified two critical issues:

Performance Abnormalities

• OCR detection model (ocr-det) shows significant speed degradation in batch inference mode (approximately orders of magnitude slower) ocr-det batch推理 与torch 2.8.0存在兼容性问题导致det阶段速度下降 #3285
• Reading order sorting model produces abnormal outputs in specific scenarios torch 2.8.0 版本使用pipeline后端阅读顺序异常 #3338

Resolved Issue

For the OCR performance degradation, we've implemented:

1. Version detection mechanism to automatically switch to sequential inference mode when torch≥2.8.0
2. This mitigation prevents catastrophic performance drops
   ⚠️ Note: Batch document processing may still experience 30%-100% speed degradation

Pending Issue

Reading order anomalies remain an intermittent defect without current resolution

Recommended Fix

Maintain PyTorch version constraint for now:

torch<2.8.0

Special Requirements Handling

For mandatory 2.8.0 adoption:

1. First install mineru to install torch 2.7.1 through dependency chain
2. Manually upgrade to PyTorch 2.8.0 via:

pip3 install torch==2.8.0 torchvision

⚠️ Note: This may impact OCR performance and cause reading order anomalies in certain scenarios

We'll continue monitoring PyTorch developments and update compatibility policies upon resolution.