MinerU 4.0.12 发布：自建解析服务新增 /v1/tasks 与 /v1/file_parse，上传支持 SHA-256 预检复用

MinerU 于 2026 年 10 月 11 日发布 4.0.12（GitHub Release published_at 为 2026-10-11T02:21:42Z，PyPI 同名包同版本上传时间为 02:24）。重点是给自部署 API 与 Router 增加 /v1/tasks 异步便捷接口和 /v1/file_parse 同步包装，加入 SHA-256 预检复用，并把资源回收、引擎故障隔离与 CPU 线程限制做成默认行为。

这次发布的是什么

MinerU 是面向 PDF、图片与办公文档的开源解析工具，常用于把文档转成结构化数据后再喂给检索或模型。2026 年 10 月 11 日发布的 4.0.12（GitHub Release 的 published_at 为 2026-10-11T02:21:42Z；PyPI 上的 mineru 包 4.0.12 上传时间为 2026-10-11T02:24）带着一份中英双语的发布说明，主线是让自部署服务的调用变简单、资源变可控：

• V1 API 新增 /v1/tasks 异步便捷接口与 /v1/file_parse 同步包装，一次请求提交文件、查询状态、获取 JSON 或 ZIP 结果，与既有的 /v1/parse/jobs 共用任务 ID。
• 上传支持 SHA-256 预检与已有 file_id 复用；原始字节入口在缓存命中时可以提前返回，客户端示例放在 scripts/http_task_example.sh。
• 资源生命周期收紧：API 与 Router 默认在 24 小时后回收过期资源，可用 --retention-seconds 或 MINERU_API_RETENTION_SECONDS 调整，设为 0 表示关闭自动回收。
• 引擎可靠性：识别致命引擎错误并返回 503 engine_dead，托管 worker 支持代际恢复与退避，过期响应不再污染新 worker。
• CPU 线程：按显式配置、有效 CPU 配额与已有线程上限三者取最小值来限制 Torch 的算子线程数，并把该限制传给后续工作线程。
• 依赖调整：docvortex 最低版本提升到 0.5.16（>=0.5.16,<1），新增 fastapi-offline（>=1.7.7,<2）。

可用性与限制

• 需要自部署：这批接口挂在自建的 API 服务与 Router 上，官方托管版本的口径请以官方页面为准。
• 两个入口的语义不同：/v1/tasks 是异步便捷接口，/v1/file_parse 是同步包装；同步等待超时会返回 202 并带上任务引用，任务本身继续执行，客户端需要继续轮询结果。
• 产出有保留期：默认 24 小时后回收过期资源，长期留存请自行在保留期内下载产物，或按部署需要调整保留时间；设为 0 会关闭自动回收，磁盘压力回到自己身上。
• 失败态要明确：出现致命引擎错误时返回 503 engine_dead，这不是普通的排队超时，处理策略应区别于重试。
• 版本门槛：依赖要求 docvortex >= 0.5.16，升级前先确认环境里的版本；具体的 Python 版本、可选依赖与硬件要求以官方文档为准。
• 费用：开源自部署不涉及许可费用，是否需要增购算力与依赖 licences 以官方说明为准，本文不转述任何价格。

主要功能

• 便捷任务接口：一次提交文件后可以同时拿到任务 ID 与状态查询入口，支持 JSON 与 ZIP 两种结果格式，与原有 /v1/parse/jobs 的任务 ID 体系打通，不必自己维护两套 ID。
• 秒传级复用：提交前做 SHA-256 预检，命中已有文件时可复用既有的 file_id；直接传原始字节的入口在缓存命中时能提前返回，减少重复上传。
• Router 调度升级：按 worker 健康状态、解析能力与未完成任务负载三者调度，负载相同时轮询分配；改进跨 worker 的输入复制、任务预占，以及失败、取消、终态后的负载释放。
• 更干净的资源回收：默认 24 小时回收过期资源，命令行参数与环境变量两种方式都能配置；Router 的任务保留期改为从跨 worker 副本清理完成后才起算。
• 用量口径修正：过期资源回收与 worker 移除不再扣减调用方已累计的用量；非法输出格式在 worker 调度之前就以请求错误返回。
• 文档能力修复：修复原生文本中中日韩边界标点与多余空格的处理并统一 Python / Rust 两条路径；恢复 PP-DocLayoutV2 的模型分类阈值，统一 Torch 与 ONNX 的输出过滤与阅读顺序候选有效性；通过 DocVortex 的公共解析接口保留 DOCX / PPTX 表格里的富文本超链接。
• 文档查看方式：Swagger 与 ReDoc 改为使用本地资源，支持离线访问、Bearer 授权以及反向代理路径前缀。

技术原理

从发布说明能确认的机制有三层。

第一层是接口收敛。原来要自己拼「提交任务 → 拿 ID → 轮询 → 取结果」四步，现在 /v1/tasks 把这条链路收成一次提交加若干次查询，并且刻意与 /v1/parse/jobs 共用同一套任务 ID——也就是说它不是另一套任务系统，而是同一套任务系统上的一层便捷入口。同步包装 /v1/file_parse 则是把超时这个现实问题摆到明面上：等到超时就返回 202 加任务引用，让客户端自己决定继续轮询还是放弃，而不是把同步请求挂到天荒地老。

第二层是去重与可恢复。SHA-256 预检的意义在于，同一份文件反复提交时不必重复搬运与重复解析；原始字节入口在命中缓存时可以不等 body 读完就返回。与之配套的是托管 worker 的代际恢复与退避：worker 换了代次之后，旧 worker 的响应会被拒绝接收，避免过期结果混进新 worker 的输出里。

第三层是资源账目。默认 24 小时保留既给了取结果的窗口，也避免了产物无限堆积；把 Router 的任务保留期改成从跨 worker 副本清理完成后起算，是把「跨 worker 副本清理」与「任务归属」这两件事的先后顺序摆对。用量统计不再因为回收或移除 worker 而倒扣，调用方的累计口径才算稳定。

实际体验

可按下面几步自测，全程用一份可以丢弃的样本 PDF：

1. 起一个本地 API 服务，先跑官方示例脚本 scripts/http_task_example.sh，确认并提交到取结果这条链路是通的。
2. 用同一个文件连续提交两次，观察第二次是否走了 SHA-256 预检复用，耗时是否明显短于第一次。
3. 用一份页数较多的大文档触发解析超时，确认同步接口返回的是 202 加任务引用，而不是一直挂着。
4. 轮询同一个任务 ID，确认既能走新的 /v1/tasks 查询，也能被原有的 /v1/parse/jobs 认出来。
5. 在保留期内重复拉结果成功；把 --retention-seconds 调到一个很短的值，验证过期后被回收；设为 0 确认自动回收被关闭，并注意磁盘占用。
6. 刻意让引擎进入致命错误状态（例如替换掉模型文件），确认返回的是 503 engine_dead 而不是超时。

任何一步与上文不符，先核对版本是不是 4.0.12、docvortex 是否已达 0.5.16，再回官方发布说明逐条对照。

项目地址与获取方式

Release 页面：https://github.com/opendatalab/MinerU/releases/tag/mineru-4-0-12-released

仓库：https://github.com/opendatalab/MinerU

PyPI 包名 mineru，当前最新版本为 4.0.12，按官方安装说明选择 Torch / full 等可选依赖组合。请通过官方仓库与官方包管理渠道获取，避免安装第三方镜像里被改写过的包。

适合谁用

• 自建文档解析管线、需要一条更省事的 HTTP 调用路径的工程师。
• 用多台机器做 Router 横向扩容的团队：这一轮的调度与负载释放逻辑改动与你直接相关。
• 关心资源账目的平台负责人：24 小时默认保留、用量不再倒扣、CPU 线程被配额限制，都是部署侧的硬约束。
• 处理中日韩文档的团队：这一轮修了原生文本里的边界标点与空格问题。
• 不适合：只想在一台机器上偶尔转几份 PDF 的人——这次的改动几乎都作用在服务端，命令行场景感知不到。

常见问题

升级到 4.0.12 后，原来的 /v1/parse/jobs 还能用吗？

能。发布说明明确写了新的便捷接口与 /v1/parse/jobs 共用任务 ID，是同一套任务的两种入口，原有的 ID 不会被作废。是否需要改造旧调用请以官方 changelog 的废弃说明为准，本文不替官方宣布任何接口下线。

同步接口会不会一直卡到解析完成？

不会无限制等待。超过同步等待超时会返回 202 并带上任务引用，任务本身继续执行，客户端可以继续轮询结果。

产出文件能放多久？

默认是 24 小时后回收过期资源。可以更长效地在 --retention-seconds 或 MINERU_API_RETENTION_SECONDS 里调，设为 0 则关闭自动回收。要长期保存的话，请在保留期限内把产物下载走。

看到 503 engine_dead 应该怎么办？

这是代表引擎进入致命错误的专用状态码，区别于普通的排队或超时。发布说明给出的处理方向是托管 worker 做代际恢复与退避；具体运维动作以官方运维文档为准。

为什么还要求 docvortex 升到 0.5.16 以上？

发布说明把这条列为依赖关系调整，最低版本门槛提升到 0.5.16，上限不到 1。升级前先在环境里确认版本，避免装完后才发现冲突。

相关工具与内容

• 分类：AI 效率办公、AI 搜索、AI 编程
• 同题材快讯：本地多模态检索实践
• 同题材快讯：OpenAI 上线欧盟文本溯源能力
• 延伸阅读：AI 工作助手的任务分级
• 工具页：腾讯智能 OCR、CNKI 研学、腾讯 ima、NotebookLM