InvokeAI 模型识别测试体系Stripped Model 精简模型与 Model Probe 识别验证实战【免费下载链接】InvokeAIInvoke is a leading creative engine for Stable Diffusion models, empowering professionals, artists, and enthusiasts to generate and create visual media using the latest AI-driven technologies. The solution offers an industry leading WebUI, and serves as the foundation for multiple commercial products.项目地址: https://gitcode.com/GitHub_Trending/in/InvokeAI本篇技术指南以 InvokeAI 仓库中 tests/model_identification/README.md 为骨架系统讲解其模型识别Model Probe / Identification测试体系的设计原理与实战用法如何通过 Git LFS 拉取测试用例、如何运行识别测试、如何理解“剥离张量数据”的精简模型机制以及如何为新的模型编写__test_metadata__.json并注册测试用例。读完本文你将掌握 InvokeAI 模型管理器中ModelOnDisk与ModelConfigFactory的底层调用链并能为任意新模型一键生成、手工校验一份可复现的识别测试用例。一、模型识别测试体系的定位与整体架构InvokeAI 在导入任何模型checkpoint、diffusers 目录、LoRA、VAE、ControlNet、IP-Adapter 等之前必须回答一个问题这个文件/目录到底是什么模型这一过程由模型管理器invokeai/backend/model_manager/中的识别Identification / Probe逻辑完成核心角色有两个ModelOnDisk定义于 model_on_disk.py一个代表磁盘上模型文件的工具类负责加载 state dict、读取元数据、计算哈希与文件大小、枚举权重文件等ModelConfigFactory.from_model_on_disk定义于 configs/factory.py遍历所有Config_Base.CONFIG_CLASSES中的配置类让每个配置类尝试匹配该模型最终返回ModelClassificationResult最佳匹配配置 每个候选类的匹配详情。而tests/model_identification/目录下的测试体系就是用一批真实模型文件的轻量替身来验证这套识别逻辑是否正确。其核心设计目标非常明确测试用例是真实模型的“精简版”stripped只保留模型结构与每个 key 的元数据剔除实际张量数据。因为识别模型通常只需要 state dict 的结构key 名称、张量形状、dtype张量本体并不参与判断这样就能把动辄数 GB 的测试夹具压缩到 KB 级使其可以随仓库分发。从仓库目录结构看tests/model_identification/stripped_models/ 下已经有 80 个以 UUID 命名的测试用例目录覆盖了.safetensors、.bin、.pt、.gguf、diffusers 多文件目录等多种形态其中不乏 FLUX 系列 LoRA、Qwen-Image、EasyNegative embedding、GGUF 量化模型等现代架构的样例。二、环境准备Git LFS 拉取测试用例测试用例文件通过 Git LFS 存储。直接git pull只会得到 LFS 指针文件即形如version https://git-lfs.github.com/spec/v1的文本占位符必须显式执行 LFS 拉取才能获得真正的模型文件。首次使用需要两步# 仅需执行一次 git lfs install # 拉取实际模型文件——如果只执行 git pull拿到的只是指针 git lfs pull实操提示git lfs pull会把仓库中所有 LFS 跟踪的文件拉全。如果只想拉取模型识别测试所需的夹具也可以使用git lfs pull -I tests/model_identification/**按路径过滤。三、运行识别测试仓库中模型识别测试的入口是 tests/model_identification/test_identification.py运行方式pytest -v tests/model_identification/test_identification.py说明原文档中给出的命令是pytest -v tests/test_model_probe/test_identification.py其中test_model_probe为历史目录名当前仓库中该文件实际位于tests/model_identification/下请以实际路径为准。3.1 核心测试逻辑test_model_identification测试的核心用例通过pytest.mark.parametrize动态收集stripped_models/下的每一个子目录作为参数见 test_identification.py对每个测试用例执行如下流程读取该目录下的__test_metadata__.json获得期望识别结果与可选覆盖字段若元数据中存在file_name单文件模型则将模型路径指向该文件用StrippedModelOnDisk加载“精简模型”它会从 JSON 中重建出带形状/ dtype 的 meta 张量调用ModelConfigFactory.from_model_on_disk(mod, override_fields, allow_unknownFalse)进行识别将识别结果 config 的各属性与expected_config_attrs逐一比对不一致即断言失败并打印形如{key} expected {expected}, got {actual}的差异信息。值得注意的两点实现细节枚举值比对断言时若实际值是Enum实例会先取其.value再与期望字符串比较见 test_identification.py因此元数据中直接书写枚举的字符串值即可不允许未知匹配测试以allow_unknownFalse调用识别工厂若返回config is None未识别出任何模型测试会直接失败并打印每个候选配置类的详细匹配信息result.details方便定位是哪个配置类出了问题。3.2 辅助单元测试同一文件还包含两个与识别强相关的单元测试test_controlnet_t2i_default_settings验证ControlAdapterDefaultSettings.from_model_name能根据模型文件名推断默认预处理器如canny_image_processor、depth_anything_image_processor、dw_openpose_image_processor文件名不匹配时返回Nonetest_default_settings_main验证MainModelDefaultSettings.from_base按BaseModelType返回默认分辨率——SD1 为 512×512、SD2 为 768×768、SDXL 为 1024×1024而sdxl-refiner与any返回None。四、核心机制Stripped Model 精简模型4.1 从ModelOnDisk到StrippedModelOnDiskInvokeAI 将模型 state dict 与元数据的加载抽象在ModelOnDisk类中model_on_disk.py它支持多格式加载.safetensors含 SDNQ 量化检测、.ckpt/.pt/.pth/.bin经 picklescan 安全扫描后torch.load、.ggufGGUF 读取器元数据读取safetensors/GGUF 内嵌 metadata工具方法hash()默认 blake3_single、size()、weight_files()递归收集权重文件、repo_variant()识别 fp16/openvino/flax/onnx 变体。测试用的StrippedModelOnDisk继承自ModelOnDisk重写了load_state_dict与metadata见 stripped_model_on_disk.py使其改为读取 JSON 化的精简表示。4.2strip与dress张量数据如何被“剥离”与“还原”精简的核心逻辑是strip剥离与dress还原这一对可逆变换见 stripped_model_on_disk.pystrip剥离递归遍历 state dict遇到torch.Tensor时替换为一个仅含{shape: ..., dtype: ..., fakeTensor: True}的 dict遇到普通 dict / list / tuple 递归处理其他值标量、字符串等原样保留。特别地GGMLTensorGGUF 量化张量在torch.Tensor之前被单独匹配会保留ggml_quantization_type、tensor_shape、compute_dtype等量化元数据因为 GGUF 模型的识别依赖这些量化信息dress还原将剥离后的结构反向还原——普通假张量通过torch.empty(shape, dtypedtype, devicemeta)在meta 设备上创建不占用实际内存GGMLTensor 则用保存的量化类型与计算 dtype 重建。还原后的 state dict 拥有与真实模型完全一致的 key 结构与张量形状足以驱动识别逻辑。而模型的 metadata 会被整体存入一个固定的 keyStrippedModelOnDisk.METADATA_KEY metadata_key_for_stripped_models加载时先弹出该 key 再dress其余内容见 stripped_model_on_disk.py。4.3 无法精简的模型spandrel 图生图模型并非所有模型都能精简。目前唯一无法精简的是spandrel图像到图像image-to-image模型spandrel 支持非常多的网络架构但不提供仅凭 state dict 结构来识别/断言模型支持性的能力因此必须实际尝试用 spandrel 加载该模型才能确认为受支持模型——能加载成功即视为受支持这类模型必须保存完整文件StrippedModelOnDisk对它们会“透传”真实的张量数据用于测试为控制测试套件体积仓库只存放一个此类模型样例。相关配置类为 configs/spandrel.py其中ModelType.SpandrelImageToImage spandrel_image_to_image定义于 taxonomy.py。五、新增测试用例strip_model.py一键生成当需要为某个新模型或新架构添加识别测试时运行 tests/model_identification/strip_model.pypython strip_model.py /path/to/your/model --output_dir ./stripped_models该脚本的工作流程见 strip_model.py用ModelOnDisk打开原始模型判断是单文件还是目录在输出目录下新建一个UUID 命名的子目录镜像应用侧“规范化模型存储”的目录结构UUID 由invokeai.app.util.misc.uuid_string生成单文件模型copy2拷贝该文件多文件模型copytree拷贝整个目录对每个权重文件加载 state dict调用StrippedModelOnDisk.strip剥离与 metadata 一起以 JSON 写入原文件覆盖生成一份模板化的__test_metadata__.json字段模板见 strip_model.py并打印精简前后的文件体积对比。单文件模型的输出结构示例stripped_models/ └── 19fd1a40-c5b7-4734-bd3a-6e0e948cce0b/ ├── __test_metadata__.json └── Standard Reference (XLabs FLUX IP-Adapter v2).safetensors多文件模型如 diffusers 风格目录则会以 UUID 目录保留整个目录树其中各权重文件被 JSON 化、config.json等配置文件原样保留。注意strip_model.py生成的__test_metadata__.json只是模板file_name会被自动填入expected_config_attrs必须手工填写为期望的识别结果后测试才有意义。六、__test_metadata__.json字段规范该文件是一个单 JSON dict是每个测试用例的“期望答案”。以 FLUX IP Adapter checkpoint 为例见原文档{ source: https://huggingface.co/XLabs-AI/flux-ip-adapter-v2/resolve/main/ip_adapter.safetensors, file_name: Standard Reference (XLabs FLUX IP-Adapter v2).safetensors, expected_config_attrs: { type: ip_adapter, format: checkpoint, base: flux } }各字段详解如下。6.1source可选推荐填写字符串标明模型来源如 Hugging Face repo ID 或 URL仅作参考记录不参与识别缺失或错误不会导致测试失败但建议如实填写便于追溯。source: RunDiffusion/Juggernaut-XL-v9 // HF repo ID 示例 source: https://huggingface.co/XpucT/Deliberate/resolve/main/Deliberate_v5.safetensors // URL 示例6.2file_name单文件模型必填单文件模型如.safetensors填写该文件名测试套件会在用例目录中查找此文件多文件模型diffusers 风格目录省略该键或设置为null/ 空字符串等假值strip_model.py会自动为单文件模型填充此字段。file_name: model.safetensors6.3expected_config_attrs所有用例必填期望的模型配置属性字典用于校验识别结果。其中三项是必须包含的主要判别字段其取值分别对应 taxonomy.py 中的枚举定义键含义对应枚举type模型类型ModelTypeformat模型文件存储格式ModelFormatbase关联的基础模型架构无关联时用anyBaseModelType根据模型种类还可能需要以下附加键键含义对应枚举prediction_type模型使用的预测类型SchedulerPredictionTypevariant模型变体如 inpaint/depth、FLUX schnell/dev、各蒸馏变体ModelVariantType及AnyVariant联合枚举例如SD1.5 diffusers 格式的 inpainting 主模型{ expected_config_attrs: { type: main, format: diffusers, base: sd-1, prediction_type: epsilon, variant: inpaint } }为便于读者对照以下是 taxonomy.py 中与本字段最相关的枚举取值摘录BaseModelTypetaxonomy.pyany、sd-1、sd-2、sd-3、sdxl、sdxl-refiner、flux、flux2、cogview4、z-image、ernie-image、ideogram-4、external、qwen-image、anima、krea-2、wan、unknownModelTypetaxonomy.pyonnx、main、vae、lora、control_lora、controlnet、embedding、ip_adapter、clip_vision、clip_embed、t2i_adapter、t5_encoder、spandrel_image_to_image、siglip、flux_redux、prompt_enhancer、text_llm、pid_decoder、unknown等ModelFormattaxonomy.pyomi、diffusers、checkpoint、lycoris、onnx、embedding_file、embedding_folder、invokeai、gguf_quantized、sdnq_quantized等SchedulerPredictionTypetaxonomy.pyepsilon、v_prediction、sample。6.4notes可选字符串记录关于该用例的任何备注用于说明背景或特殊情况。6.5override_fields罕见场景极少数情况下需要向识别系统提供额外提示。目前唯一已知的场景是区分单文件 SD1.x / SD2.x / SDXL 的 VAE——这三者结构完全相同只能借助模型文件名做简单的字符串匹配来提供提示。例如用户从 HF 仓库madebyollin/taesdxl安装taesdxlVAE 时识别系统拿到模型名taesdxl看到其中的xl便推断这是 SDXL VAE。测试用例复现该场景的方式{ override_fields: { name: taesdxl } }从实现上看override_fields在ModelConfigFactory.build_common_fieldsconfigs/factory.py中被合并进公共字段name覆盖mod.name此外还支持type、format、base、source_type、variant、source、hash、key、description、file_size等字段的覆盖枚举字段会被强制转换为其 Enum 类型。需要注意覆盖字段优先于磁盘提取值但无法强行匹配——如果模型本身与某个配置类不匹配覆盖字段也无济于事。七、识别底层的调用链与测试验证关系将以上内容串起来可以得到完整的数据流真实模型文件 │ strip_model.pyModelOnDisk 读取 → StrippedModelOnDisk.strip 剥离 ▼ stripped_models/UUID/JSON 权重 __test_metadata__.json随 Git LFS 分发 │ test_identification.pyStrippedModelOnDisk.dress 还原 meta 张量 ▼ ModelConfigFactory.from_model_on_disk(mod, override_fields, allow_unknownFalse) │ 遍历 CONFIG_CLASSES 各配置类的 from_model_on_disk见 factory.py L692-L699 ▼ ModelClassificationResult最佳匹配 config 各候选类匹配细节 details │ 与 expected_config_attrs 逐字段比对 ▼ 通过 / 失败打印形如 type expected ip_adapter, got lora 的差异几个值得留意的实现细节路径预检from_model_on_disk会先调用_validate_path_looks_like_model做基本校验——文件检查扩展名、目录检查已知配置标记或权重文件避免把普通文件夹当模型处理浪费时间见 configs/factory.py多重匹配优先级matches_sort_key规定当多个配置类同时匹配时按类型优先mainloraclip_embed 其他例如“融入了 LoRA 权重的 SD 主模型”和“带 text_encoder 的 diffusers 主模型”会优先判定为主模型见 configs/factory.py识别与安全真实权重加载路径中.ckpt/.pt/.pth/.bin会先经 picklescan 扫描可被unsafe_disable_picklescan配置豁免而精简模型因不含可执行 pickle 内容天然规避了该风险见 model_on_disk.py测试即文档stripped_models/目录本身就是各模型家族识别特征的最佳实证集合——例如5a5fe5e4-...等多文件目录含大量config.json与.safetensors覆盖 diffusers 形态78197983-...与81cba86d-...覆盖.gguf量化形态125e8a78-...EasyNegative覆盖 embedding 形态。新增模型时可先参考同架构既有用例的__test_metadata__.json再行填写。八、实践建议与注意事项遵循“先精简、后校验”的流程任何新模型识别需求都应先跑strip_model.py生成用例再手工补齐expected_config_attrs最后运行pytest -v tests/model_identification/test_identification.py验证若识别失败result.details中每个候选配置类抛出的异常如NotAMatchError或InvalidMatchError是定位问题的第一手线索。区分“未识别”与“已识别但不可用”ModelClassificationResult中invalid_matches记录的是“配置类认出了模型但判定其损坏/不可用”的拒绝信息与“完全不认识”是两种不同情形见 configs/factory.py。枚举值以字符串书写由于测试断言会将Enum转为.value比较__test_metadata__.json中统一使用taxonomy.py里定义的字符串值即可。spandrel 模型例外图生图类 spandrel 模型无法精简不要尝试对其运行strip_model.py仓库目前仅存放一个完整样例以控制体积新增此类用例时同样应尽量克制。体积控制是设计底线精简模型的根本目的是让海量真实模型特征以 KB 级体积随仓库分发因此手工编辑精简后的 JSON 权重文件时应保持“只动结构、不塞数据”的原则。通过本测试体系InvokeAI 得以在持续演进FLUX.2、Qwen-Image、Wan、Krea 2、Anima 等新架构不断加入的同时保证模型识别结果可回归、可追溯——这正是大规模 AI 创作引擎模型管理可靠性的基石。【免费下载链接】InvokeAIInvoke is a leading creative engine for Stable Diffusion models, empowering professionals, artists, and enthusiasts to generate and create visual media using the latest AI-driven technologies. The solution offers an industry leading WebUI, and serves as the foundation for multiple commercial products.项目地址: https://gitcode.com/GitHub_Trending/in/InvokeAI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 InvokeAI 模型识别测试体系：Stripped Model 精简模型与 Model Probe 识别验证实战
InvokeAI 模型识别测试体系Stripped Model 精简模型与 Model Probe 识别验证实战【免费下载链接】InvokeAIInvoke is a leading creative engine for Stable Diffusion models, empowering professionals, artists, and enthusiasts to generate and create visual media using the latest AI-driven technologies. The solution offers an industry leading WebUI, and serves as the foundation for multiple commercial products.项目地址: https://gitcode.com/GitHub_Trending/in/InvokeAI本篇技术指南以 InvokeAI 仓库中 tests/model_identification/README.md 为骨架系统讲解其模型识别Model Probe / Identification测试体系的设计原理与实战用法如何通过 Git LFS 拉取测试用例、如何运行识别测试、如何理解“剥离张量数据”的精简模型机制以及如何为新的模型编写__test_metadata__.json并注册测试用例。读完本文你将掌握 InvokeAI 模型管理器中ModelOnDisk与ModelConfigFactory的底层调用链并能为任意新模型一键生成、手工校验一份可复现的识别测试用例。一、模型识别测试体系的定位与整体架构InvokeAI 在导入任何模型checkpoint、diffusers 目录、LoRA、VAE、ControlNet、IP-Adapter 等之前必须回答一个问题这个文件/目录到底是什么模型这一过程由模型管理器invokeai/backend/model_manager/中的识别Identification / Probe逻辑完成核心角色有两个ModelOnDisk定义于 model_on_disk.py一个代表磁盘上模型文件的工具类负责加载 state dict、读取元数据、计算哈希与文件大小、枚举权重文件等ModelConfigFactory.from_model_on_disk定义于 configs/factory.py遍历所有Config_Base.CONFIG_CLASSES中的配置类让每个配置类尝试匹配该模型最终返回ModelClassificationResult最佳匹配配置 每个候选类的匹配详情。而tests/model_identification/目录下的测试体系就是用一批真实模型文件的轻量替身来验证这套识别逻辑是否正确。其核心设计目标非常明确测试用例是真实模型的“精简版”stripped只保留模型结构与每个 key 的元数据剔除实际张量数据。因为识别模型通常只需要 state dict 的结构key 名称、张量形状、dtype张量本体并不参与判断这样就能把动辄数 GB 的测试夹具压缩到 KB 级使其可以随仓库分发。从仓库目录结构看tests/model_identification/stripped_models/ 下已经有 80 个以 UUID 命名的测试用例目录覆盖了.safetensors、.bin、.pt、.gguf、diffusers 多文件目录等多种形态其中不乏 FLUX 系列 LoRA、Qwen-Image、EasyNegative embedding、GGUF 量化模型等现代架构的样例。二、环境准备Git LFS 拉取测试用例测试用例文件通过 Git LFS 存储。直接git pull只会得到 LFS 指针文件即形如version https://git-lfs.github.com/spec/v1的文本占位符必须显式执行 LFS 拉取才能获得真正的模型文件。首次使用需要两步# 仅需执行一次 git lfs install # 拉取实际模型文件——如果只执行 git pull拿到的只是指针 git lfs pull实操提示git lfs pull会把仓库中所有 LFS 跟踪的文件拉全。如果只想拉取模型识别测试所需的夹具也可以使用git lfs pull -I tests/model_identification/**按路径过滤。三、运行识别测试仓库中模型识别测试的入口是 tests/model_identification/test_identification.py运行方式pytest -v tests/model_identification/test_identification.py说明原文档中给出的命令是pytest -v tests/test_model_probe/test_identification.py其中test_model_probe为历史目录名当前仓库中该文件实际位于tests/model_identification/下请以实际路径为准。3.1 核心测试逻辑test_model_identification测试的核心用例通过pytest.mark.parametrize动态收集stripped_models/下的每一个子目录作为参数见 test_identification.py对每个测试用例执行如下流程读取该目录下的__test_metadata__.json获得期望识别结果与可选覆盖字段若元数据中存在file_name单文件模型则将模型路径指向该文件用StrippedModelOnDisk加载“精简模型”它会从 JSON 中重建出带形状/ dtype 的 meta 张量调用ModelConfigFactory.from_model_on_disk(mod, override_fields, allow_unknownFalse)进行识别将识别结果 config 的各属性与expected_config_attrs逐一比对不一致即断言失败并打印形如{key} expected {expected}, got {actual}的差异信息。值得注意的两点实现细节枚举值比对断言时若实际值是Enum实例会先取其.value再与期望字符串比较见 test_identification.py因此元数据中直接书写枚举的字符串值即可不允许未知匹配测试以allow_unknownFalse调用识别工厂若返回config is None未识别出任何模型测试会直接失败并打印每个候选配置类的详细匹配信息result.details方便定位是哪个配置类出了问题。3.2 辅助单元测试同一文件还包含两个与识别强相关的单元测试test_controlnet_t2i_default_settings验证ControlAdapterDefaultSettings.from_model_name能根据模型文件名推断默认预处理器如canny_image_processor、depth_anything_image_processor、dw_openpose_image_processor文件名不匹配时返回Nonetest_default_settings_main验证MainModelDefaultSettings.from_base按BaseModelType返回默认分辨率——SD1 为 512×512、SD2 为 768×768、SDXL 为 1024×1024而sdxl-refiner与any返回None。四、核心机制Stripped Model 精简模型4.1 从ModelOnDisk到StrippedModelOnDiskInvokeAI 将模型 state dict 与元数据的加载抽象在ModelOnDisk类中model_on_disk.py它支持多格式加载.safetensors含 SDNQ 量化检测、.ckpt/.pt/.pth/.bin经 picklescan 安全扫描后torch.load、.ggufGGUF 读取器元数据读取safetensors/GGUF 内嵌 metadata工具方法hash()默认 blake3_single、size()、weight_files()递归收集权重文件、repo_variant()识别 fp16/openvino/flax/onnx 变体。测试用的StrippedModelOnDisk继承自ModelOnDisk重写了load_state_dict与metadata见 stripped_model_on_disk.py使其改为读取 JSON 化的精简表示。4.2strip与dress张量数据如何被“剥离”与“还原”精简的核心逻辑是strip剥离与dress还原这一对可逆变换见 stripped_model_on_disk.pystrip剥离递归遍历 state dict遇到torch.Tensor时替换为一个仅含{shape: ..., dtype: ..., fakeTensor: True}的 dict遇到普通 dict / list / tuple 递归处理其他值标量、字符串等原样保留。特别地GGMLTensorGGUF 量化张量在torch.Tensor之前被单独匹配会保留ggml_quantization_type、tensor_shape、compute_dtype等量化元数据因为 GGUF 模型的识别依赖这些量化信息dress还原将剥离后的结构反向还原——普通假张量通过torch.empty(shape, dtypedtype, devicemeta)在meta 设备上创建不占用实际内存GGMLTensor 则用保存的量化类型与计算 dtype 重建。还原后的 state dict 拥有与真实模型完全一致的 key 结构与张量形状足以驱动识别逻辑。而模型的 metadata 会被整体存入一个固定的 keyStrippedModelOnDisk.METADATA_KEY metadata_key_for_stripped_models加载时先弹出该 key 再dress其余内容见 stripped_model_on_disk.py。4.3 无法精简的模型spandrel 图生图模型并非所有模型都能精简。目前唯一无法精简的是spandrel图像到图像image-to-image模型spandrel 支持非常多的网络架构但不提供仅凭 state dict 结构来识别/断言模型支持性的能力因此必须实际尝试用 spandrel 加载该模型才能确认为受支持模型——能加载成功即视为受支持这类模型必须保存完整文件StrippedModelOnDisk对它们会“透传”真实的张量数据用于测试为控制测试套件体积仓库只存放一个此类模型样例。相关配置类为 configs/spandrel.py其中ModelType.SpandrelImageToImage spandrel_image_to_image定义于 taxonomy.py。五、新增测试用例strip_model.py一键生成当需要为某个新模型或新架构添加识别测试时运行 tests/model_identification/strip_model.pypython strip_model.py /path/to/your/model --output_dir ./stripped_models该脚本的工作流程见 strip_model.py用ModelOnDisk打开原始模型判断是单文件还是目录在输出目录下新建一个UUID 命名的子目录镜像应用侧“规范化模型存储”的目录结构UUID 由invokeai.app.util.misc.uuid_string生成单文件模型copy2拷贝该文件多文件模型copytree拷贝整个目录对每个权重文件加载 state dict调用StrippedModelOnDisk.strip剥离与 metadata 一起以 JSON 写入原文件覆盖生成一份模板化的__test_metadata__.json字段模板见 strip_model.py并打印精简前后的文件体积对比。单文件模型的输出结构示例stripped_models/ └── 19fd1a40-c5b7-4734-bd3a-6e0e948cce0b/ ├── __test_metadata__.json └── Standard Reference (XLabs FLUX IP-Adapter v2).safetensors多文件模型如 diffusers 风格目录则会以 UUID 目录保留整个目录树其中各权重文件被 JSON 化、config.json等配置文件原样保留。注意strip_model.py生成的__test_metadata__.json只是模板file_name会被自动填入expected_config_attrs必须手工填写为期望的识别结果后测试才有意义。六、__test_metadata__.json字段规范该文件是一个单 JSON dict是每个测试用例的“期望答案”。以 FLUX IP Adapter checkpoint 为例见原文档{ source: https://huggingface.co/XLabs-AI/flux-ip-adapter-v2/resolve/main/ip_adapter.safetensors, file_name: Standard Reference (XLabs FLUX IP-Adapter v2).safetensors, expected_config_attrs: { type: ip_adapter, format: checkpoint, base: flux } }各字段详解如下。6.1source可选推荐填写字符串标明模型来源如 Hugging Face repo ID 或 URL仅作参考记录不参与识别缺失或错误不会导致测试失败但建议如实填写便于追溯。source: RunDiffusion/Juggernaut-XL-v9 // HF repo ID 示例 source: https://huggingface.co/XpucT/Deliberate/resolve/main/Deliberate_v5.safetensors // URL 示例6.2file_name单文件模型必填单文件模型如.safetensors填写该文件名测试套件会在用例目录中查找此文件多文件模型diffusers 风格目录省略该键或设置为null/ 空字符串等假值strip_model.py会自动为单文件模型填充此字段。file_name: model.safetensors6.3expected_config_attrs所有用例必填期望的模型配置属性字典用于校验识别结果。其中三项是必须包含的主要判别字段其取值分别对应 taxonomy.py 中的枚举定义键含义对应枚举type模型类型ModelTypeformat模型文件存储格式ModelFormatbase关联的基础模型架构无关联时用anyBaseModelType根据模型种类还可能需要以下附加键键含义对应枚举prediction_type模型使用的预测类型SchedulerPredictionTypevariant模型变体如 inpaint/depth、FLUX schnell/dev、各蒸馏变体ModelVariantType及AnyVariant联合枚举例如SD1.5 diffusers 格式的 inpainting 主模型{ expected_config_attrs: { type: main, format: diffusers, base: sd-1, prediction_type: epsilon, variant: inpaint } }为便于读者对照以下是 taxonomy.py 中与本字段最相关的枚举取值摘录BaseModelTypetaxonomy.pyany、sd-1、sd-2、sd-3、sdxl、sdxl-refiner、flux、flux2、cogview4、z-image、ernie-image、ideogram-4、external、qwen-image、anima、krea-2、wan、unknownModelTypetaxonomy.pyonnx、main、vae、lora、control_lora、controlnet、embedding、ip_adapter、clip_vision、clip_embed、t2i_adapter、t5_encoder、spandrel_image_to_image、siglip、flux_redux、prompt_enhancer、text_llm、pid_decoder、unknown等ModelFormattaxonomy.pyomi、diffusers、checkpoint、lycoris、onnx、embedding_file、embedding_folder、invokeai、gguf_quantized、sdnq_quantized等SchedulerPredictionTypetaxonomy.pyepsilon、v_prediction、sample。6.4notes可选字符串记录关于该用例的任何备注用于说明背景或特殊情况。6.5override_fields罕见场景极少数情况下需要向识别系统提供额外提示。目前唯一已知的场景是区分单文件 SD1.x / SD2.x / SDXL 的 VAE——这三者结构完全相同只能借助模型文件名做简单的字符串匹配来提供提示。例如用户从 HF 仓库madebyollin/taesdxl安装taesdxlVAE 时识别系统拿到模型名taesdxl看到其中的xl便推断这是 SDXL VAE。测试用例复现该场景的方式{ override_fields: { name: taesdxl } }从实现上看override_fields在ModelConfigFactory.build_common_fieldsconfigs/factory.py中被合并进公共字段name覆盖mod.name此外还支持type、format、base、source_type、variant、source、hash、key、description、file_size等字段的覆盖枚举字段会被强制转换为其 Enum 类型。需要注意覆盖字段优先于磁盘提取值但无法强行匹配——如果模型本身与某个配置类不匹配覆盖字段也无济于事。七、识别底层的调用链与测试验证关系将以上内容串起来可以得到完整的数据流真实模型文件 │ strip_model.pyModelOnDisk 读取 → StrippedModelOnDisk.strip 剥离 ▼ stripped_models/UUID/JSON 权重 __test_metadata__.json随 Git LFS 分发 │ test_identification.pyStrippedModelOnDisk.dress 还原 meta 张量 ▼ ModelConfigFactory.from_model_on_disk(mod, override_fields, allow_unknownFalse) │ 遍历 CONFIG_CLASSES 各配置类的 from_model_on_disk见 factory.py L692-L699 ▼ ModelClassificationResult最佳匹配 config 各候选类匹配细节 details │ 与 expected_config_attrs 逐字段比对 ▼ 通过 / 失败打印形如 type expected ip_adapter, got lora 的差异几个值得留意的实现细节路径预检from_model_on_disk会先调用_validate_path_looks_like_model做基本校验——文件检查扩展名、目录检查已知配置标记或权重文件避免把普通文件夹当模型处理浪费时间见 configs/factory.py多重匹配优先级matches_sort_key规定当多个配置类同时匹配时按类型优先mainloraclip_embed 其他例如“融入了 LoRA 权重的 SD 主模型”和“带 text_encoder 的 diffusers 主模型”会优先判定为主模型见 configs/factory.py识别与安全真实权重加载路径中.ckpt/.pt/.pth/.bin会先经 picklescan 扫描可被unsafe_disable_picklescan配置豁免而精简模型因不含可执行 pickle 内容天然规避了该风险见 model_on_disk.py测试即文档stripped_models/目录本身就是各模型家族识别特征的最佳实证集合——例如5a5fe5e4-...等多文件目录含大量config.json与.safetensors覆盖 diffusers 形态78197983-...与81cba86d-...覆盖.gguf量化形态125e8a78-...EasyNegative覆盖 embedding 形态。新增模型时可先参考同架构既有用例的__test_metadata__.json再行填写。八、实践建议与注意事项遵循“先精简、后校验”的流程任何新模型识别需求都应先跑strip_model.py生成用例再手工补齐expected_config_attrs最后运行pytest -v tests/model_identification/test_identification.py验证若识别失败result.details中每个候选配置类抛出的异常如NotAMatchError或InvalidMatchError是定位问题的第一手线索。区分“未识别”与“已识别但不可用”ModelClassificationResult中invalid_matches记录的是“配置类认出了模型但判定其损坏/不可用”的拒绝信息与“完全不认识”是两种不同情形见 configs/factory.py。枚举值以字符串书写由于测试断言会将Enum转为.value比较__test_metadata__.json中统一使用taxonomy.py里定义的字符串值即可。spandrel 模型例外图生图类 spandrel 模型无法精简不要尝试对其运行strip_model.py仓库目前仅存放一个完整样例以控制体积新增此类用例时同样应尽量克制。体积控制是设计底线精简模型的根本目的是让海量真实模型特征以 KB 级体积随仓库分发因此手工编辑精简后的 JSON 权重文件时应保持“只动结构、不塞数据”的原则。通过本测试体系InvokeAI 得以在持续演进FLUX.2、Qwen-Image、Wan、Krea 2、Anima 等新架构不断加入的同时保证模型识别结果可回归、可追溯——这正是大规模 AI 创作引擎模型管理可靠性的基石。【免费下载链接】InvokeAIInvoke is a leading creative engine for Stable Diffusion models, empowering professionals, artists, and enthusiasts to generate and create visual media using the latest AI-driven technologies. The solution offers an industry leading WebUI, and serves as the foundation for multiple commercial products.项目地址: https://gitcode.com/GitHub_Trending/in/InvokeAI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考