文档分析的原生异步运行时
PDF 的 high/xhigh 分析在使用本地 vLLM 或远程 HTTP 时,通过常驻运行时执行原生异步推理。
doc_analyze、aio_doc_analyze、parse、parse_async 的参数与结果协议保持一致。
运行时与共享边界
- 相同有效配置的同步分析、异步分析与 API 预加载共享一个运行时。vLLM 托管路径统一使用 AsyncLLM, 不同时加载离线 LLM 和 AsyncLLM 两套权重。
- 每个运行时拥有一个事件循环线程。同步入口等待线程安全提交的结果,异步入口等待可取消的 Future; 调用方可以多次创建、关闭自己的事件循环。
- HTTP 连接池在所属运行时循环中持续复用。地址、模型、凭据及连接配置仍保持隔离。
- API 应用拥有独立租约。关闭一个应用只释放自身租约;其他应用或独立解析仍持有的实例不会因此关闭。
独立 Python 调用使用进程级模型缓存,退出时清理;显式模型关闭仍由
shutdown_cached_models()完成。
并发与取消
- API 的
--concurrency控制同时运行的 job 数,默认仍为 1。同一个 job 内的文件顺序执行。 model.vlm.max_concurrency控制同一有效配置运行时内的 VLM 在途请求总数,默认 100; 多份文档共享该额度,不各自获得 100 个名额。- 单文档按既有窗口顺序执行。准备与回填阶段在线程中运行,本地共享模型阶段按设备串行保护; 等待 VLM 时释放保护,允许其他文档推进。PDFium 继续使用 DocVortex 的共享锁。
- 取消会传播到实际任务,但只有底层请求及同步阶段清理完成后,才关闭图片/PDF 和释放 job 名额。 排队取消不会开始解析,已经取消的任务不会再发布结果。
- HTTP 取消保证本地停止等待与清理,远端是否立即停止生成取决于服务端;低频 GPU 指标不能证明即时 abort。
- 本地 LMDeploy、MLX、llama.cpp、Flash/basic 和非 PDF 保持受控线程回退。 取消这些路径需要等待在途同步阶段结束,不承诺立即中断模型计算。
分层实现
MinerU 拥有模型构造、缓存、运行时、文档编排和 API 任务生命周期。mineru-vl-utils 提供原生异步抽取及 HTTP 连接与健康探测清理接口,不关闭调用方提供的引擎或 executor。DocVortex 的基础访问、语义协议和确定性处理职责不变。
引擎健康与故障传播
依赖适配层将 vLLM 与 LMDeploy 的明确死亡统一为 EngineUnavailableError,保留原始异常链。
普通请求失败和探测超时不使用该异常;批量容错和 MFR 回退不能吞掉明确死亡。
| 后端 | health_probe_mode |
健康入口 |
|---|---|---|
| llama.cpp | sync |
probe_health(timeout),读取原生循环终止状态 |
| LMDeploy | sync |
probe_health(timeout),在 Pipeline 循环查询 |
| vLLM AsyncLLM | async |
aio_probe_health(timeout),在运行时所属循环查询 |
| vLLM 离线 LLM、MLX | none |
不提供探测;不通过私有对象伪造健康 |
MinerU 托管的 vLLM 同步调用仍使用 AsyncLLM,所以同样具备空闲健康探测。 API 只探测已加载的实例,默认周期和期限均为五秒,每实例最多一个在途探测。 异步探测的外部等待期限不依赖引擎循环,因此引擎循环阻塞时 API 仍能返回暂不可用。
同步句柄与异步代理共享 RuntimeLifecycle。明确死亡永久锁存,并通知全部 owner;缓存命中及后续调用拒绝
复用旧实例。健康和接单统一返回 503 engine_dead,未完成任务失败并清理结果。托管进程由既有 Router/Doclib
机制替换,外部 worker 仅摘除。CLI 非零退出,SDK 调用方自行释放并重建。
探测超时返回 503 engine_unavailable,拒绝新推理但允许继续探测;恢复健康后可解除,不能覆盖已锁存的死亡。
MLX 未知运行时异常只使当前请求失败,不进行 MFR 回退或永久隔离,后续请求仍可使用该实例。
取消依旧等待各后端完成必要清理,不将 Future 取消等同于 GPU 或线程工作结束。
同步与异步 PDF 窗口共同使用准备输入和结果回填函数,保持原生表格优先、文本/公式处理、图像开关与页序。 high 等待外部布局抽取,xhigh 等待两阶段抽取;后置 LLM 增强使用现有协程。
验收与性能采集
在项目虚拟环境中执行 scripts/benchmark_async_analysis.py;脚本还需要 psutil。
配置文件或环境变量提供鉴权信息,不把密钥写入命令行或报告。
.venv1/bin/python scripts/benchmark_async_analysis.py demo/pdfs/demo1.pdf demo/pdfs/demo2.pdf \
--server-url http://localhost:30000 --tier standard --ocr-mode ocr \
--concurrency 1 2 4 8 --repeats 4 --output output/native_async/http.json
本地 vLLM 验收使用 --engine vllm,不传 --server-url,并确保配置中未设置远程地址。
--mode sync-thread 用于同步线程调用;比较旧实现时应使用独立基线源码,固定依赖、输入、模型、窗口和采样配置。
--save-results 可保存预热结果用于语义回归;--cancel-after 记录异步取消返回耗时。
报告包括文档/页吞吐、解析 P50/P95、含排队的延迟、事件循环延迟、线程及 RSS 峰值。 本地 NVIDIA 环境通过 nvidia-smi 采集解析进程及子进程显存;远端显存缺失时保留空值。 单次样本和模拟后端不能替代 GPU 性能验收;源码位置、文件哈希及配置必须与结果一起保留。
上线性能目标为代表性多文档负载吞吐提升至少 25%,或同吞吐下 P95 降低至少 20%, 同时单文档耗时回退不超过 5%。未达到目标时不扩大默认并发,不宣称性能提升。 本地嵌入式 vLLM 必须另做 Linux CUDA 实机验收;远程 LMDeploy HTTP 通过不能代替该项。
两仓交付
本次依赖 mineru-vl-utils 新增的 MinerUClient.aclose() 与取消清理能力。
开发验证使用配套的本地 editable 源码。正式交付必须先发布包含这些改动的 mineru-vl-utils 版本,
确认包索引可解析后,再提高 MinerU 的依赖下限;未完成设备验收前保留发布门槛。
llama.cpp 要求 mineru-llama-cpp>=0.2.1。只有明确循环退出或显式关闭映射为公共致命异常,普通 EngineError 仍按请求处理。底层保留原始错误类型、错误码和详情;取消后的原生线程排空由底层负责,运行时沿用共享 owner 通知与缓存拒绝规则。健康快照不提供解码进度心跳,也不将无进度推断为死亡;进程级 abort 仍由宿主管理恢复。
LMDeploy 的健康接口可能使用独立执行器,取消协程不等于工作线程已退出。MinerU 的同步、异步及取消关闭都等待同一健康探测实际排空,再释放 Pipeline;不把依赖库的局部关闭超时当作已排空。托管 worker 的总关闭期限、终止和强制退出仍由现有 Router/Doclib 管理器控制。直接 SDK 调用方也必须保持 Pipeline 及其循环存活直至客户端成功关闭。