Remote 路径补 3.x Middle JSON 兼容(设计)¶
日期:2026-09-17 状态:已确认,待实现 分支:opendatalab-master
背景与动机¶
MinerU 4.0 把 Middle JSON 收敛到统一共享协议(schema 2.0)。ca15b938(2026-09-07,
"remove legacy support")删除了通用入口 ParseResult.from_dict 与 HTTP 客户端里的 legacy 兼容,
当天 332bb866 只把旧格式读取恢复到 doclib 持久化缓存边界
(mineru/doclib/core/middle_json.py::read_cached_middle_json),并有意让 HTTP/ZIP/Gradio
继续严格读取新协议——前提假设 remote parse server 已经升级到 4.0。
但现实是仍有 3.x remote server 在服务,返回 3.4.5 pdf_info 或旧 schema 1.0/2.0 的 middle_json。
parser/api_client.py::_parse_result_from_middle_json 现在只接受新协议,使 doclib 走 remote
解析这类 server 时抛 invalid_middle_json_output。
本次打破「HTTP/ZIP 严格读新协议」的边界,为 remote 路径临时补回 3.x 兼容, 待 remote server 全部升级到 4.0 后移除。
目标¶
- remote JSON 与 ZIP 两条输出路径都能正确读取 3.x 历史 middle_json
(3.4.5
pdf_info、旧 schema1.0pages、旧 schema2.0)。 - 4.0 新协议路径行为保持不变。
- 兼容逻辑保持单一实现、单一归属,未来一处删除。
设计¶
模块布局¶
- 删除
mineru/doclib/core/middle_json.py(对外仅read_cached_middle_json一个符号)。 - 新建
mineru/backend/postprocess/legacy_middle_json.py,承载历史 middle_json 读取:
def read_legacy_middle_json(payload: dict[str, Any]) -> MiddleJson:
"""读取 3.x 历史 middle_json(pdf_info / 旧 1.0 / 旧 2.0),返回当前 MiddleJson。"""
移入原 read_cached_middle_json 的全部识别逻辑,方法名与错误信息去「cached」化。
数据流¶
remote 与 doclib 两个消费方共用同一读取器:
doclib 缓存读取(parse_svc / compaction)
└─> read_legacy_middle_json(payload) -> MiddleJson
remote/HTTP/ZIP(parser.api_client._parse_result_from_middle_json)
└─> ParseResult.from_dict(严格新协议)
└─ 失败则 read_legacy_middle_json(payload) -> MiddleJson -> ParseResult
remote 侧实现¶
parser/api_client.py::_parse_result_from_middle_json 改为:
- 非
dict→_V1APIError("invalid_middle_json_output", ...)。 ParseResult.from_dict(4.0 新协议原路径)。- 失败后 fallback:
read_legacy_middle_json,包成ParseResult(middle_json=...)。 - fallback 也失败 →
_V1APIError("invalid_middle_json_output", str(exc))。
ZIP 路径经 _parse_result_from_zip_bytes 复用同一入口,自动获得兼容。
错误处理¶
- 合法 3.x 旧格式 → 迁移成功。
- 新协议数据损坏 / 未知 / 混合信封 → 仍抛
invalid_middle_json_output,不跨协议兜底。
测试¶
翻转(原锁定「拒绝」)¶
| 测试 | 位置 | 变更 |
|---|---|---|
test_api_client_rejects_remote_pdf_info_middle_json |
tests/unittest/test_parser_api_contract.py:1055 |
拒绝 → 接受 |
test_async_api_client_rejects_remote_pdf_info_middle_json |
:1078 |
拒绝 → 接受 |
test_api_client_rejects_legacy_official_layout_json |
:814 |
拒绝 → 接受 |
更新¶
tests/unittest/test_doclib_middle_json.py:import 与调用从mineru.doclib.core.middle_json.read_cached_middle_json改为mineru.backend.postprocess.legacy_middle_json.read_legacy_middle_json。- 新增正向用例:3.x
pdf_info经 remote JSON 与 ZIP 路径正确恢复 pages。
文档更新¶
docs/next/middle-json/doclib-compatibility.md:删除「HTTP/ZIP 与 Gradio 继续严格读取新协议」, 改为「HTTP/ZIP 临时兼容 3.x remote server,待其升级 4.0 后移除」。docs/doclib-middle-json-compat-validation.md:同步修订,并记录移除点。
临时性与移除计划¶
本兼容是过渡措施。remote server 全部升级 4.0 后,移除路径:
- 删除
parser/api_client.py::_parse_result_from_middle_json的 fallback 分支。 - 删除(或先收窄回 doclib 缓存)
backend/postprocess/legacy_middle_json.py。 - 恢复相应测试与文档。
风险与注意事项¶
test_doclib_middle_json.py等多处调用点要随函数改名同步更新,避免漏改。- 与 memory
legacy-migration-consumer-checklist呼应:删除/重建兼容层须「删哪几处、接回哪几处」逐一对照。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 mi/MinerU