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