|
|
||
|---|---|---|
| .. | ||
| 2.7.1-baseline.json | ||
| 2.7.1-inventory.json | ||
| 2.7.4-baseline.json | ||
| 4.0.12-inventory.json | ||
| README.md | ||
| release-baseline-20261106.md | ||
README.md
状态更新(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:设置显存比例与 CoreXPYTHONPATH。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 专用页范围或任意档位。
当前两个需要补齐的业务差异:
web_ui/src/composables/useDocumentProcessor.ts仍在上传前做 Word→PDF;应改为原文件直传,旧资源仅在明确需要时回退。maxkb/apps/system_manage/ai_hub_worker.py当前智能整理对超过 60000 字符的输入直接拒绝;旧服务的分块整理能力尚未等价迁入。
6. 合并与验收顺序
- 固定官方 4.0.12 来源与依赖清单,保留旧源代码回退点;移入主维护目录时保留官方许可证及声明,不复制 ares 的虚拟环境、业务数据或凭据。
- 迁移原文件上传及按格式路由;复用 AI Hub 图片资产、任务和结果处理,验证 DOC/DOCX、表格、幻灯片、PDF 和图片。图片型 Office 内容是否 OCR 需按真实文档单独验收。
- 迁入长文整理,保留标题、图片引用、上下文预算和中间结果;验证超长单段、多块、模型失败和截断。
- 在 v1 任务中增加结构化阶段/页块进度,贯通 AI Hub 与工作台;验证多任务互不串状态,不用旧日志百分比模拟真实完成率。
- 按真实样本校验续表的 caption、脚注和跨页单元格;确认 DocVortex 已覆盖的行为后只补缺失规则。
- 适配 CoreX:优先验证“4.0.12 文档服务 + 独立厂商 VLM 服务”的可行性(协议、模型、OCR 后端均需验证);若选择本地引擎,则先取得兼容的新厂商依赖组合,不在旧镜像中盲目升级。
- 通过本地检查及隔离接口验证后,按增量发布约定部署;涉及页面同时发布 8080 使用的
/admin/构建产物。检查远端差异和入口,保留旧服务回退,真实验证后再完成默认资源切换。
尚未完成的验证:4.0.12 在目标天数硬件上的模型启动/精度/显存/持续运行;续表规则的新旧等价性;新原生格式在工作台和知识库全链路的验收。本次源码审计不能替代这些运行测试。