UnisMindMap/docs/mineru-migration/README.md

108 lines
11 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

> 状态更新(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 在目标天数硬件上的模型启动/精度/显存/持续运行;续表规则的新旧等价性;新原生格式在工作台和知识库全链路的验收。本次源码审计不能替代这些运行测试。