# 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` 下运行。

```bash
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`，并随代码提交，便于团队对齐。