8.6 KiB
模型检查（模型医生）的判断规则
模型检查是本插件最复杂的部分之一。这一页是它判断规则的唯一总览：什么算“同一个模型”，什么只是“可能”，缺的模型从哪里下载、怎么核对。改模型检查之前先读这一页；改了规则，同时改这一页。
一句话：模型检查只认“同一个文件”，唯一可靠的证据是文件指纹（SHA-256 哈希）。 名字、路径、封面都不能证明是同一个模型。
1. 指纹从哪里来
装了本插件的人出图、保存工作流时，插件会把用到的每个模型的指纹（SHA-256）和文件大小写进工作流（设置里可以关）。别人打开这个工作流，模型检查就能按指纹在自己电脑上找同一个文件，不管它被改了什么名、放在哪个文件夹。
没装本插件的人存的工作流没有指纹，只剩模型的文件名，能做的事就少得多（见下面的表）。
2. 两类模型
| 类别 | 包括 | 规则 |
|---|---|---|
| 普通模型 | 大模型（Checkpoint）、UNET / 扩散模型、LoRA、ControlNet、放大模型等 | 指纹最可靠；没有指纹时，大小或名字可以给出“候选”，由用户确认 |
| 基础组件 | VAE、TAESD（vae_approx）、CLIP / 文本编码器、CLIP Vision | 只认指纹。不按名字猜；大小只能作为手动候选显示 |
基础组件只认指纹的原因：它们的文件名高度重复（ae.safetensors、clip_l.safetensors、t5xxl_fp16.safetensors……），同名的经常是不同的文件，按名字猜错的风险太大。
3. 本机找回：三档可信度
打开工作流时，模型检查逐个看模型下拉框（包括 rgthree Power Lora Loader 里开着的每一行）：
| 看到的情况 | 结论 | 怎么处理 | 普通模型 | 基础组件 |
|---|---|---|---|---|
| 下拉框里就有这个值 | 正常 | 不动 | ✓ | ✓ |
| 只是路径里斜杠写法不同 | 同一个（确定） | 可一键换上 | ✓ | ✓ |
| 本机有指纹一致的文件，只是名字或文件夹不同 | 同一个（确定） | 可一键换上，也可用画布上方提示条的“换上 N 个”一起换 | ✓ | ✓ |
| 工作流没记指纹但记了大小；本机有同名且大小相同的文件 | 很可能（半信） | 逐行按一下才换，不算进“换上 N 个” | ✓ | ✓（只手动） |
| 本机只有大小完全相同的文件 | 可能 | 逐行按一下才换 | ✓ | ✓（只手动） |
| 工作流什么都没记（不是本插件存的）；下拉框里恰好一个同名文件 | 可能 | 逐行按一下才换 | ✓ | ✗ 不提供 |
| 好几个文件都可能是它 | 说不清 | 不换，让用户自己挑 | ✓ | ✓ |
| 按指纹和按大小找到的是两个不同文件 | 冲突 | 拒绝替换 | ✓ | ✓ |
| 文件还在，但指纹和工作流记的不一样 | 文件变了 | 只提醒，不算缺失、不替换，ComfyUI 照常用它 | — | ✓ |
所以普通模型实际上是三档：指纹一致 = 信；同名且同大小 = 半信（很可能）；只同大小或只同名 = 可能。只有第一档能一键或批量换上，后两档都要用户逐行确认。基础组件只有第一档能换上；大小一致（无论名字是否也一样）只作手动候选；只凭名字永远不算。
永远不当作证据的：文件名（除了上表里那两种要确认的情况）、显示名、路径、封面、“看起来像”。确定是同一个文件之后，名字和路径只用来找到下拉框里对应的那一项。
换上的结果只能是这个节点下拉框里本来就有的选项；插件不会往下拉框里塞别的值来假装找到了。确认一个候选只对这一个节点有效，不会被记成以后的规则。
4. 本机没有：从哪里下载
本机确实没有时，模型检查页可以直接下载。来源按这个顺序问，问到就停：
- Civitai（C 站），按指纹：工作流记了指纹，就问 C 站有没有这个指纹的文件。
- 工作流带着的链接：保存时记下的下载链接（C 站某个版本、Hugging Face / hf-mirror 的文件、GitHub 上的文件）。
- ComfyUI-Manager 的模型清单：本机装的 Manager 自带的
model-list.json，几百个常用模型（大模型、VAE、文本编码器、放大模型、ControlNet……，大多在 Hugging Face 上），按文件名和节点需要的文件夹类型对上。
核对规则：
| 情况 | 结果 |
|---|---|
| 工作流有指纹，来源文件的 SHA-256 一致 | 确定，可以直接下载，也算进“下载全部” |
| 工作流有指纹，来源文件的 SHA-256 不一致 | 拒绝（不是同一个文件） |
| 工作流有指纹，Manager 清单里有几个同名的 | 逐个核对指纹，只用对上的那个 |
| 工作流没有指纹，Manager 清单里恰好一个同名文件 | 标成“按文件名下载”，写明只是同名、核对不了，由用户决定；不算进“下载全部”，AI 助手（MCP）也不会自动下 |
| 工作流没有指纹，清单里有好几个同名的 | 不提供（不知道是哪一个） |
没有指纹时，下载前没有任何东西能拿来核对：所以只是同名，永远只到“可能”，由用户决定。下载下来的文件从此有了自己的指纹，但没有原始指纹可比，证明不了它就是工作流原来用的那个。
5. ComfyUI Manager 的位置
ComfyUI Manager 是一本“官方常用模型的下载目录”：它只回答“这个文件名去哪里下”，不回答“你电脑里这个文件是不是它”（清单里没有指纹，只有文件名、类型、底模和下载地址）。所以：
- 只用在下载这一步，排在 C 站（按指纹）和工作流自带的链接后面；本机找回从不用它当证据。
- 有指纹：清单里同名的文件逐个去下载站点读出 SHA-256 核对，对上才算，和别的来源一样。
- 没指纹：清单里恰好一个同名、类型也对得上的，才提供“按文件名下载”，并写出清单里的名字和文件在哪个网站 / 仓库，供用户判断。清单没写类型的条目，只在节点类型也不明时才考虑。
- 基础组件也提供“按文件名下载”。统一的规矩是：名字只能提出候选；基础组件的同名候选还要再有一条独立证据。本机找回时这条证据是“大小一致”（所以只同名不提供）；下载时这条证据是“官方清单收录了它，而且类型对得上”。再加上下载是用户自己看清“只是同名”后按的，不会自动发生。
- 哪里都没找到的基础组件：那一行有“去 Hugging Face 搜”按钮（开了国内镜像就去 hf-mirror），按文件名打开搜索页，由用户自己找、自己下。插件不替用户挑。通用的名字（
model.safetensors、ae.safetensors）可能搜出很多，这正是它不自动做的原因。 - 没装 Manager：就少这一个来源；模型检查页在有模型找不到下载地址时提示“装了 ComfyUI Manager，还能多一个下载来源”。
- 清单从本机装的 Manager 里读（
model-list.json），不联网。
下载本身：只从 https 的 C 站、Hugging Face、hf-mirror、GitHub 下；先写 .part，有指纹时核对 SHA-256 一致才改成正式文件名；从不覆盖已有文件；先检查磁盘空间。开了国内镜像时，在 C 站找到的文件如果在 Hugging Face 上有同一个（同一 SHA-256），就改从 hf-mirror 下。某个网站连不上就跳过它，继续问别的。
6. 不变的承诺
（同 AGENTS.md“功能原则”第 1 条）
- 检查只读，从不自己改工作流。只有用户按了“换上”或“下载”才动节点。
- 只换成同一个文件。“可能”和“很可能”都要用户逐行确认。
- 每一项都在界面上说清楚为什么（找到了同一个 / 只是大小相同 / 只是同名……）和下载地址来自哪里。
7. 代码在哪（给维护的 AI）
- 前端判断：
web/modules/model_check.js（各种状态和via）、web/modules/model_policies.js（哪些类型只认指纹）、web/modules/ui_doctor.js（每一项的说明文字）。 - 后端按指纹 / 大小找文件：
api/model_resolution.py（/anomalous/resolve_hash_batch）。 - 下载来源：
api/download_sources.py（find_source的顺序和核对）、api/manager_catalog.py（Manager 清单）、api/model_download.py。 - 英文的实现细节：
docs/architecture/model-resolution.md、docs/architecture/backend.md的 “Model downloads”。 - 为什么这么定：
docs/decisions/README.md的 AD-005（认模型不看名字）、AD-006（基础组件只认指纹）、AD-020（下载与 ComfyUI Manager）。