UnisMindMap/docs/mineru-migration/README.md

11 KiB
Raw Permalink Blame History

状态更新(2026-11-06):下文仅保留历史盘点,4.0.12 及后续 2.7.4 方案已被替代。当前按用户要求恢复纯官方 2.7.1,暂不加六级标题补丁;业务功能继续位于 MaxKB。参见仓库 README 和 2.7.1-baseline.json。

MinerU 2.7.1 定制盘点与 4.0.12 合并方案

核验日期:2026-10-22。此次完成源码与发布包对比,尚未替换旧内核、安装新依赖或切换运行服务。

1. 基线与核验方法

分别下载 PyPI 官方 mineru==2.7.1、mineru==4.0.12 wheel,验证发布元数据中的 SHA-256,再比较包内 mineru/ 与本地源码目录。忽略 CRLF/LF 差异、__pycache__ 和 .pyc,不安装依赖、不加载模型。

项目 本地位置 发布包比较结果
旧内核 markitdown/mineru 官方 187 个文件;本地 200 个;6 个 Python 文件修改,13 个静态文件新增,无删除
新内核 ares/third_party/mineru/mineru 官方与本地各 630 个文件;全部一致

新内核所在独立 Git 仓库 HEAD 为 b7f3dd0,标签为 mineru-4.0.12-released,工作区干净。发布包比对进一步确认:ares 这份 4.0.12 的 MinerU 包没有项目定制修改。Git 仓库为浅克隆,未通过完整上游历史推断来源。

两个发布包的 URL、哈希、文件数及逐文件差异见同目录 2.7.1-inventory.json 和 4.0.12-inventory.json。该核验范围是 Python 包 mineru/;Dockerfile、业务调用和部署脚本另行检查,不能由包一致推导外围项目也无定制。

旧项目 Git 初始化提交 e5d281a 已包含部分定制;仅比较初始化提交到 HEAD 会遗漏 common.py、gradio_app.py、table_merge.py。因此本清单以官方发布包为基准。

2. 旧版包内定制:逐项迁移结论

文件 项目差异 4.0.12 现状 合并位置与处理
mineru/cli/common.py 增加 DOC/DOCX;LibreOffice 转 PDF,失败后 DOCX 使用 python-docx + ReportLab 转文本 PDF;增加解析进度回调 原生 Office 等格式交由 DocVortex;PDF/图片仍使用 OCR/VLM;文件完成进度已有,但不等于页级进度 原生 Office 路径替代转 PDF;进度改为任务内结构化事件,不照搬旧转换实现
mineru/cli/fast_api.py /api/file_parse;解析任务进度注册/查询;内存+原子 JSON 文件状态;日志和 tqdm 推断阶段;智能整理异步任务;长文标题分块、局部整理、全局合并;模型参数;OOM 提示、缓存清理;静态工作台挂载 v1 自带任务、结果、文件、并发和终态清理机制;没有本项目智能整理接口,也没有旧版日志阶段百分比 解析生命周期复用 v1;兼容层只翻译协议;智能整理迁到 MaxKB AI Hub;工作台由现有 Vue 页面承接;OOM 分类和阶段事件按新架构接入
mineru/backend/vlm/utils.py MINERU_GPU_MEMORY_UTILIZATION 环境变量覆盖默认显存比例,校验 0 < value < 1 新路径 model/vlm/engine_utils.py 有默认计算;VLM server 可显式传 --gpu-memory-utilization,但未保留该旧环境变量入口 保留旧环境变量兼容,转换到实际本地引擎参数;显式参数优先;远程 VLM 的限额在 VLM 服务端配置
mineru/backend/vlm/vlm_analyze.py 按 AsyncEngineArgs 签名过滤参数,适应运行时参数差异 新路径 model/vlm/runtime.py、新的配置/引擎依赖;4.x 未带相同过滤补丁 不原样复制“静默丢弃不支持参数”;厂商适配明确白名单、映射或报错,避免显存等关键配置失效
mineru/cli/gradio_app.py Markmap iframe 导图、普通段落提升为子标题、Word 上传和 PDF 预览、内嵌图片、ZIP 输出、页面文案和布局改造 新 Gradio 位于 kit/gradio,主项目已有 Vue 工作台 保留用户可见能力于 Vue,保留现有风格;不把旧 Gradio 整页移进新版内核
mineru/utils/table_merge.py 新增 (…continued) 后缀和 caption 内 (continued) 匹配;存在续表标识时允许前表最多一条脚注;合并时清掉前表脚注再接后表脚注 新架构的通用表格处理主要归 DocVortex,MinerU 另有 LLM 跨页单元格合并;不能把“已有表格合并”当作旧规则完全等价 用真实续表样本验证;需要的规则在新后处理扩展点/依赖层迁移;旧版删除脚注的行为需重点核验,不能无条件照搬造成内容丢失

新增 13 个静态文件:4 个 cli/static/markmap 资源、9 个 cli/static/web 页面及依赖资源。它们属于旧界面交付,不是 OCR 算法或天数算子补丁。

旧进度并非完整的引擎真实完成率:包含固定权重日志阶段和文件回调;使用进程全局当前任务 ID、日志 sink 和 stderr 捕获。迁移后要提供任务隔离的阶段事件;只有明确页数/块数时才显示可计算比例,模型加载等阶段显示文字和耗时。

旧长文整理也不宜逐行照搬:它使用估算 token 预算和分块合并,需要补充超长单段切分、超限/截断识别、失败重试及图片引用保留验证。

3. 天数适配实际在哪里

旧项目相对官方 2.7.1 未发现额外修改 OCR/表格/公式模型或新增天数算子源码。可见的项目适配主要在:

  • docker/china/Dockerfile.corex、docker/china/Dockerfile:采用天数 CoreX 厂商镜像,保留厂商 Torch/vLLM;使用 --no-deps 安装及补齐依赖。
  • scripts/build-images.sh:区分 CoreX/CUDA 构建,默认 CoreX。
  • scripts/start-mindmap.sh:设置显存比例与 CoreX PYTHONPATH。
  • docker/entrypoint.mineru-api.sh:注入本地 pipeline/VLM 模型路径、公式分隔符和旧 JSON 配置。
  • 包内两项 VLM 补丁:显存比例环境变量、AsyncEngineArgs 参数过滤。

这不覆盖厂商基础镜像中未展开的私有补丁、驱动或 wheel 内容,不能凭仓库源码证明这些二进制已兼容新版。

项目 旧 CoreX 镜像/项目 4.0.12 源码要求或现状
基础运行时 CoreX 4.4.0 / Torch 2.7.1 / vLLM 0.11.2 / Python 3.10 torch extra:Torch >=2.7,<3、Transformers >=5.10.1,<6;full extra:Linux vLLM >=0.19.1,<0.29
VLM 工具依赖 mineru-vl-utils 0.x 范围 mineru-vl-utils >=2.0.5,<3
安装 extras core/pipeline/vlm 等旧分组 torch/full/all;不能继续照搬 [core]
通用文档转换 旧 Word 转 PDF DocVortex >=0.5.16,<1 原生转换
配置 旧 mineru.json、pipeline/vlm 目录 新 config.yaml / MINERU_CONFIG、model.base_dir、model.small_backend、model.vlm;模型也要单独核对
天数参数分支 依赖厂商运行环境与旧引擎 仍有 MINERU_VLLM_DEVICE=corex 和编译参数分支;不等于依赖组合/硬件已验证

4.0.12 自带 docs/zh/usage/compatibility.md 明确:旧 13 类平台适配指南只适用于 MinerU <4,4.0 不自动继承兼容保证。保留的 docker/china/corex.Dockerfile 也实际安装 mineru[core]>=3.4.0,<4,不能把它当成 4.0.12 天数镜像。

另一个版本隐患:旧 CoreX Dockerfile 安装 mineru[core]>=2.7.4 --no-deps,随后复制版本号为 2.7.1 的本地源码。镜像内 distribution metadata 与实际 import 的源码可能不同;新构建应固定版本、打印安全的来源清单并校验导入路径,避免混用。

旧启动脚本含删除重建容器、递归 chmod 等步骤,只供审阅,不应用于此次增量发布。旧 entrypoint 每次重写 JSON 配置,也不能直接用于新版配置。

4. ares 外围接入:哪些沿用、哪些不迁

ares/code/backend/services/parser.py 的 _parse_pdf_mineru:

  • multipart 同步调用 /v1/file_parse?tier=basic,最长等待 1200 秒。
  • 读取 files[].content.markdown,提取首标题作为文档名。
  • 将 Markdown 中 data:image/...;base64,... 替换成 [图片]。
  • PDF 页数达到阈值(默认 8)或文本密度低时才选择 MinerU,失败则继续本地 PDF/OCR 路线。

以上是 ares 的业务集成,不是 4.0.12 内核定制。当前 MaxKB/思维导图已有异步解析资源和图片资产机制,继续使用自己的集成;不复制“图片改占位符”及静默降级策略。

5. 统一到 4.0.12 的落点

目标:主维护目录仍在 markitdown 和 maxkb,ares 只提供已核验的源码来源。保留旧版可回退版本;最终活动内核固定为 4.0.12,项目补丁单独登记。

层 负责的能力
MinerU 4.0.12 格式识别、原生 Office、PDF/图片 OCR/VLM、渲染输出、模型生命周期
项目解析扩展 结构化阶段进度、必要的续表规则、经过验证的天数引擎/显存配置
兼容层 有实际调用者时保留旧 /api/file_parse、任务查询和结果结构;不重新实现一套任务执行器
MaxKB AI Hub 资源授权、默认服务/流程、智能整理与长文分块、任务和成果、图片资产鉴权及缓存
思维导图 Vue 工作台 直接上传原文件、Markdown/导图预览、折叠状态、图片展示和导出
部署配置 独立虚拟环境或镜像、固定依赖、本地模型挂载、安全增量启动与回退

4.0.12 并不是每种格式都走四档模型:Office/HTML/CSV/EPUB/OFD 等为原生 Flash 路径,PDF/图片才是质量分档解析。前端和服务端需按格式路由,不能把 DOCX 原文件上传后仍机械传 PDF 专用页范围或任意档位。

当前两个需要补齐的业务差异:

  1. web_ui/src/composables/useDocumentProcessor.ts 仍在上传前做 Word→PDF;应改为原文件直传,旧资源仅在明确需要时回退。
  2. maxkb/apps/system_manage/ai_hub_worker.py 当前智能整理对超过 60000 字符的输入直接拒绝;旧服务的分块整理能力尚未等价迁入。

6. 合并与验收顺序

  1. 固定官方 4.0.12 来源与依赖清单,保留旧源代码回退点;移入主维护目录时保留官方许可证及声明,不复制 ares 的虚拟环境、业务数据或凭据。
  2. 迁移原文件上传及按格式路由;复用 AI Hub 图片资产、任务和结果处理,验证 DOC/DOCX、表格、幻灯片、PDF 和图片。图片型 Office 内容是否 OCR 需按真实文档单独验收。
  3. 迁入长文整理,保留标题、图片引用、上下文预算和中间结果;验证超长单段、多块、模型失败和截断。
  4. 在 v1 任务中增加结构化阶段/页块进度,贯通 AI Hub 与工作台;验证多任务互不串状态,不用旧日志百分比模拟真实完成率。
  5. 按真实样本校验续表的 caption、脚注和跨页单元格;确认 DocVortex 已覆盖的行为后只补缺失规则。
  6. 适配 CoreX:优先验证“4.0.12 文档服务 + 独立厂商 VLM 服务”的可行性(协议、模型、OCR 后端均需验证);若选择本地引擎,则先取得兼容的新厂商依赖组合,不在旧镜像中盲目升级。
  7. 通过本地检查及隔离接口验证后,按增量发布约定部署;涉及页面同时发布 8080 使用的 /admin/ 构建产物。检查远端差异和入口,保留旧服务回退,真实验证后再完成默认资源切换。

尚未完成的验证:4.0.12 在目标天数硬件上的模型启动/精度/显存/持续运行;续表规则的新旧等价性;新原生格式在工作台和知识库全链路的验收。本次源码审计不能替代这些运行测试。