MinerU Kit 模型命令 stack 参数设计¶
日期:2026-08-05
范围:mineru/kit/commands/models.py、mineru/utils/model_registry.py、相关测试
背景¶
MinerU 已支持两套模型 stack:
- light:ONNX 推理(layout、OCR、公式)+ 未来 llama.cpp VLM,不需要 torch/transformers
- full:PyTorch 推理 + transformers/vllm/lmdeploy VLM
config.model.stack 字段已落地,get_model_stack() 把 auto 解析成 cpu→light, 其他→full。
ModelRepo 已带 stack 字段:PDF_EXTRACT_KIT、MINERU_2_5_PRO_2605_1_2B 为 full,6 个 Paddle ONNX repos 为 light。
但 mineru-kit models 子命令仍只支持 --tier,无法按 stack 选择下载集:
REPOS_FOR_TIER 是静态字典,只映射到 full repos,ONNX repos 没有归到任何 tier。
用户在 CPU 机器上跑 --tier basic,运行时会用 light ONNX 模型,但 models download --tier basic 仍下载 full 的 PDF_EXTRACT_KIT(约 6GB),完全浪费。
目标¶
给 mineru-kit models 子命令加 --stack 参数,让下载/验证的模型集与运行时实际使用的 stack 一致。
非目标¶
- 不实现 light stack 的 VLM 下载(llama.cpp/GGUF 未落地)
- 不动
mineru-kit parse、api-server等其他子命令 - 不改
config.model.stack已有语义 - 不拆分
PDF_EXTRACT_KIT(表格模型拆分另行处理)
设计¶
CLI 接口¶
mineru-kit models download [REPO] [--tier T] [--stack S] [--source S] [-v]
mineru-kit models show [--stack S]
mineru-kit models verify [REPO] [--tier T] [--stack S]
--stack 取值:
auto(默认):调用get_model_stack()解析,cpu→light,其他→fulllight:使用 light reposfull:使用 full repos
参数互斥规则:
download传 repo 名时忽略--stack(repo 自身已声明 stack 字段)download同时传 repo 和--tier仍报错(已有逻辑保留)verify传 repo 名时忽略--stack与--tier
tier → repos 映射¶
REPOS_FOR_TIER 静态字典改为函数 model_repos_for_tier(tier, *, stack=None):
| tier \ stack | light | full |
|---|---|---|
| basic | PP_DOCLAYOUT_V2_ONNX + PP_OCR_V6_SMALL_DET_ONNX + PP_OCR_V6_SMALL_REC_ONNX + PP_FORMULANET_PLUS_M_ONNX |
PDF_EXTRACT_KIT |
| standard | 同 basic(暂无 light VLM) | PDF_EXTRACT_KIT + MINERU_2_5_PRO_2605_1_2B |
设计要点:
- light basic 与运行时
atom_model_init()在stack=="light"下加载的模型一一对应(layout + small OCR det/rec + formula) - light standard 暂时与 light basic 相同:light VLM(llama.cpp/GGUF)未实现,不能让用户以为下载完就能跑 standard
- full stack 保持原映射不变
向后兼容:
model_repos_for_tier(tier)单参数调用仍可工作,默认stack=None→ 解析 automodel_repos_for_tier("flash")/"advanced"仍按原逻辑报错Supported model tiers: basic, standard
stack 解析¶
新增 helper resolve_model_stack(stack: str | None) -> Literal["light", "full"]:
def resolve_model_stack(stack: str | None) -> Literal["light", "full"]:
"""把 --stack 参数或 config 值解析为 light/full。None 或 'auto' 走 get_model_stack()。"""
from ..utils.config_reader import get_model_stack
if stack in ("light", "full"):
return stack
if stack is None or stack == "auto":
return get_model_stack()
raise ValueError(f"Unsupported stack '{stack}'. Expected one of: auto, light, full.")
放在 mineru/utils/model_registry.py,与 validate_model_tier 并列。
show 命令输出¶
新增字段:
Config: ...
Config exists: ...
MINERU_MODEL_SOURCE=...
model.base_dir: ...
model.base_dir.source: ...
model.source: ...
model.source.source: ...
model.stack: <配置值> # 新增
model.stack.source: <source> # 新增
Effective stack: <light|full> # 新增,--stack 解析后的值
Repos:
PDF-Extract-Kit-1.0: ready (...) [stack=full] # 新增 [stack=...] 标记
PP-DocLayoutV2_onnx: ready (...) [stack=light]
...
Model tiers: # 改为按 effective stack 显示
basic: <该 stack 下的 repos>
standard: <该 stack 下的 repos>
show 的 --stack 参数会覆盖 config.model.stack 用于解析 effective stack。
verify 命令行为¶
- 无 repo 无 tier:验证 effective stack 下的所有 repos(不再验证全部 8 个)
- 带
--tier:验证该 tier 在 effective stack 下的 repos - 带 repo 名:忽略
--stack与--tier,验证该 repo
download 命令行为¶
download --tier basic:用 effective stack 下的 basic reposdownload --tier basic --stack light:强制 light 下的 basic reposdownload PP-DocLayoutV2_onnx:忽略--stack,下载该 repodownload --tier basic --stack full:保持原行为(下载PDF_EXTRACT_KIT)
涉及文件¶
mineru/utils/model_registry.py- 新增
resolve_model_stack(stack)helper model_repos_for_tier(tier, *, stack=None)改为函数(替换静态字典导出)- 内部保留
REPOS_FOR_TIER_FULL、新增REPOS_FOR_TIER_LIGHT两个静态字典作为实现 __all__导出resolve_model_stackmineru/kit/commands/models.py- 三个子命令加
--stack参数(默认None,help 文本说明auto/light/full) - 加
_resolve_effective_stack(stack)局部 helper 调用resolve_model_stack _select_target_repos接受stack参数,传给model_repos_for_tiershow_cmd输出新增model.stack、Effective stack字段,repos 行追加[stack=...]标记,tiers 部分按 effective stack 显示verify_cmd在无 repo 无 tier 时按 effective stack 过滤 repostests/unittest/test_kit_commands.py- 现有
test_models_download_tier_basic/standard等用例:monkeypatchget_model_stack返回"full",避免依赖运行时设备 - 新增 light stack 用例:
test_models_download_tier_basic_light:验证下载 4 个 light repostest_models_download_tier_standard_light:验证与 basic light 相同test_models_show_displays_stack_fields:验证model.stack、Effective stack、[stack=...]标记test_models_verify_filters_by_effective_stack:验证只验证 effective stack 下的 repostest_models_download_repo_ignores_stack:验证传 repo 名时--stack被忽略test_models_download_rejects_invalid_stack:验证--stack foo报错
兼容性¶
model_repos_for_tier(tier)单参数调用向后兼容(默认stack=None)REPOS_FOR_TIER名字不再导出(仅作内部实现),如有外部引用需更新config.model.stack已有字段,show只是把它显示出来- 现有测试若依赖
REPOS_FOR_TIER静态字典导出,需改为调用model_repos_for_tier
风险¶
REPOS_FOR_TIER移除导出的破坏性:需 grep 确认无外部引用。如有,保留导出但内部委托函数版。- light standard 与 basic 相同的语义:用户可能困惑。通过
show输出明确标注standard(light): same as basic或在 download 时 logger.warning 提示 "light stack does not yet include VLM"。 - 测试 monkeypatch 时机:
get_model_stack在model_repos_for_tier内部 lazy import,monkeypatch 需针对mineru.utils.config_reader.get_model_stack或在测试开始前设置config.model.stack="full"。后者更稳,优先用。 - 现有
test_models_show_and_verify依赖 full stack:该用例断言输出含PDF-Extract-Kit-1.0: ok与MinerU2.5-Pro-2605-1.2B: ok。在 CPU 机器上 effective stack=light,verify 默认只验证 light repos,断言会失败。修法:用例开头 monkeypatchconfig.model.stack="full",或在测试中显式传--stack full。前者更稳,因为show输出也会随之显示 full tiers,与现有断言一致。
验收¶
mineru-kit models download --tier basic --stack light下载 4 个 light reposmineru-kit models download --tier basic --stack full下载PDF_EXTRACT_KITmineru-kit models download --tier basic(无 --stack)在 CPU 机器上等同--stack lightmineru-kit models show输出包含model.stack、Effective stack、repos 行的[stack=...]标记mineru-kit models verify默认只验证 effective stack 下的 reposmineru-kit models download PP-DocLayoutV2_onnx --stack full仍下载 ONNX repo(--stack 被忽略)- 所有现有测试通过,新增 light stack 测试通过
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 mi/MinerU