ocr_platform/ocr_tools/model_doctor/README.md

model_doctor —— 模型变更巡检工具

ocr_platform 用到的模型很多、来源各异且在不断升级。本工具用「清单 → 指纹 → 与基线比对」 的方式，帮你一眼看出哪些模型变了 / 缺失了 / 服务不可达 / HF 远端有更新，避免悄无声息的版本漂移 （例如 daemon 后面把 PaddleOCR-VL 从 1.5 换成 1.6）。

目录结构

文件	说明
model_registry.yaml	手工维护的模型清单，覆盖四类来源
model_doctor.py	巡检 CLI（采集指纹 / 比对 / 报告）
models.lock.json	指纹基线（由 update-lock 生成，建议纳入 git）

四类模型来源（kind）

kind	含义	指纹内容	「变化」如何被发现
hf	HuggingFace 仓库（自动下载，缓存于 defaults.hf_hub_dir）	本地快照 local_revision；--online 时附 remote_revision	本地 revision 变化；远端 commit 与本地不同（--online）
local_file	本地单个权重文件或目录	size+mtime（--hash 加快速 sha256）	文件被替换、大小/时间变化、缺失
daemon	HTTP 服务（llama-server / vllm）+ 关联本地 GGUF 资产	/v1/models 返回的 served_models + 各 asset 的 size+mtime	服务不可达、声明的模型 id 不符、GGUF 文件被换
mineru	MinerU 内置模型	package_version + model_root 目录聚合指纹	MinerU 包升级、内置模型目录变化

常用命令

建议在 conda 环境 mineru 下运行。

cd ocr_tools/model_doctor

# 列出清单
conda run -n mineru python model_doctor.py list

# 体检（与基线比对）；有缺失/不可达/远端更新时退出码非 0
conda run -n mineru python model_doctor.py check

# 体检 + 查 HF 远端最新 commit + 对本地文件算快速 sha256（更敏感、更慢）
conda run -n mineru python model_doctor.py check --online --hash

# 确认变更合理后，把当前指纹固化为新基线
conda run -n mineru python model_doctor.py update-lock

# 只打印当前采集到的指纹（不比对，便于排查）
conda run -n mineru python model_doctor.py show

选项

选项	作用
--online	hf 条目额外查询远端最新 commit 并比对（需联网）
--hash	本地文件/目录额外计算快速 sha256（头 8MB + 尾 8MB + size）
--strict	check 时把「指纹变化」也算失败（默认仅缺失/不可达/远端更新/新增才非 0 退出）
--registry / --lock	指定清单 / 基线文件路径

报告符号

符号	含义
✅	未变化
⚠️	指纹变化（列出具体字段 diff）
🔺	HF 远端有更新（--online）
❌	缺失 / 服务不可达
🆕	新增条目（基线中无记录，需 update-lock）
🗑	基线中存在但 registry 已移除
·	跳过（enabled: false）

典型工作流

1. 新增/升级模型 → 编辑 model_registry.yaml（增删条目或改路径/repo）。
2. check 看差异是否符合预期。
3. 确认无误 → update-lock 更新基线，并把 models.lock.json 一起提交。
4. 日常/CI/定时任务里跑 check；非 0 退出即代表「有人动了模型，需要关注」。

可挂载的触发点：

• 流程启动前 check（缺失直接拦截，避免跑到一半报错）；
• launchd/cron 定时 check --online + 通知，监控 HF 远端更新；
• git pre-commit：改了 config 的 model_dir 时校验本地是否已下载。

指纹策略说明

• 大文件默认只用 size+mtime（快、可离线）；--hash 时用「头尾各 8MB + size」的快速 sha256， 兼顾敏感度与速度，不全量读取 GB 级 GGUF。
• HF revision：读取 HF 缓存 models--{org}--{name}/refs/main（即本地 commit）； --online 用 huggingface_hub.HfApi().model_info(repo_id).sha 取远端最新 commit 比对，无需下载。
• daemon：/v1/models 仅反映「服务声明的 model id」；真实权重变化靠 assets 的本地 GGUF 指纹兜底。

维护提示

• 内网/未启动的服务、可选模型已设为 enabled: false，体检时跳过、不报红；需要时改为 true。
• mineru-builtin 的 model_root 当前指向 modelscope_cache，若你的 MinerU 内置模型实际下载在 hf_home 或别处，请按实修改该路径（留空 null 则只校验包版本）。
• models.lock.json 是「期望状态」，请在确认变更合理后才 update-lock，并随代码提交，便于团队对齐。