165 lines
12 KiB
Markdown
165 lines
12 KiB
Markdown
<h1 align="center">ModelResolver – Relink missing models and download from HuggingFace/CivitAI</h1>
|
||
|
||
<p align="center"><i>ModelResolver is a powerful ComfyUI extension for automatically resolving missing models in loaded workflows. It features intelligent local fuzzy matching, direct cloud downloads, background download tracking, and automated in-place workflow updating.</i></p>
|
||
|
||
> [!WARNING]
|
||
> **WIP (Work in Progress) — Download and use at your own risk!**
|
||
> This project is still under active development and some features may be unfinished or contain bugs.
|
||
|
||
<p align="center">
|
||
<a href='https://registry.comfy.org/publishers/azornes/nodes/comfyui-model-resolver'><img alt='ComfyUI' src='https://img.shields.io/badge/ComfyUI-1a1a1a?style=for-the-badge&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABwAAAAcCAMAAABF0y+mAAAASFBMVEVHcEwYLtsYLtkXLtkXLdkYLtkWLdcFIdoAD95uerfI1XLR3mq3xIP8/yj0/zvw/0FSYMP5/zKMmKQtPNOuuozj8FOhrZW7x4FMWFFbAAAABnRSTlMAUrPX87KxijklAAAA00lEQVR4AX3SBw6DMAxA0UzbrIzO+9+02GkEpoWP9hPZZs06Hw75aI3k4W/+wkQtnGZNhF1I34BzalQcxkmasY0b9raklNcvLYU1GNiiOeVWauOa/XS526gRyzpV/7HeUOG9Jp6vcsvUrCPeKg/3KBKBQhoTD1dQggPWzPVfFOIgo85/kR4y6oB/8SlIEh7wvmTuKd3wgLVW1sTfRBoR7oWVqy/U2NcrWDYMINE7NUuJuoV+2fhaWmnbjzcOWnRv7XbiLh/Y9dNUqk2y0QcNwTu7wgf+/BhsPUhf4QAAAABJRU5ErkJggg=='><img alt='Downloads' src='https://img.shields.io/badge/dynamic/json?color=%230D2A4A&label=&query=downloads&url=https://gist.githubusercontent.com/Azornes/741c965c0e0504ac65935dcc105a4ad8/raw/top_modelresolver.json&style=for-the-badge'></a>
|
||
<img alt='GitHub Clones' src='https://img.shields.io/badge/dynamic/json?color=2F80ED&label=Clone&query=count&url=https://gist.githubusercontent.com/Azornes/2730ed6bbf240f06efd0c183bddd3d6c/raw/clone.json&logo=github&style=for-the-badge&labelColor=1a1a1a'></a>
|
||
<a href="https://visitorbadge.io/status?path=https%3A%2F%2Fgithub.com%2FAzornes%2FComfyui-Resolution-Master">
|
||
<img src="https://api.visitorbadge.io/api/combined?path=https%3A%2F%2Fgithub.com%2FAzornes%2FComfyui-Model-Resolver&countColor=%03ae5f&style=for-the-badge&labelStyle=none&labelColor=1a1a1a" /></a>
|
||
<img alt="Python 3.10+" src="https://img.shields.io/badge/Python-3.10+-2564ae?labelColor=1a1a1a&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxMTAiIGhlaWdodD0iMTEwIiB2aWV3Qm94PSIwLjIxIC0wLjA3NyAxMTAgMTEwIj48ZGVmcz48bGluZWFyR3JhZGllbnQgaWQ9ImEiIGdyYWRpZW50VW5pdHM9InVzZXJTcGFjZU9uVXNlIiB4MT0iNjMuODE1OSIgeTE9IjU2LjY4MjkiIHgyPSIxMTguNDkzNCIgeTI9IjEuODIyNSIgZ3JhZGllbnRUcmFuc2Zvcm09Im1hdHJpeCgxIDAgMCAtMSAtNTMuMjk3NCA2Ni40MzIxKSI%2BPHN0b3Agb2Zmc2V0PSIwIiBzdG9wLWNvbG9yPSIjMzg3RUI4Ii8%2BPHN0b3Agb2Zmc2V0PSIxIiBzdG9wLWNvbG9yPSIjMzY2OTk0Ii8%2BPC9saW5lYXJHcmFkaWVudD48bGluZWFyR3JhZGllbnQgaWQ9ImIiIGdyYWRpZW50VW5pdHM9InVzZXJTcGFjZU9uVXNlIiB4MT0iOTcuMDQ0NCIgeTE9IjIxLjYzMjEiIHgyPSIxNTUuNjY2NSIgeTI9Ii0zNC41MzA4IiBncmFkaWVudFRyYW5zZm9ybT0ibWF0cml4KDEgMCAwIC0xIC01My4yOTc0IDY2LjQzMjEpIj48c3RvcCBvZmZzZXQ9IjAiIHN0b3AtY29sb3I9IiNGRkUwNTIiLz48c3RvcCBvZmZzZXQ9IjEiIHN0b3AtY29sb3I9IiNGRkMzMzEiLz48L2xpbmVhckdyYWRpZW50PjwvZGVmcz48cGF0aCBmaWxsPSJ1cmwoI2EpIiBkPSJNNTUuMDIzLTAuMDc3Yy0yNS45NzEsMC0yNi4yNSwxMC4wODEtMjYuMjUsMTIuMTU2djEyLjU5NGgyNi43NXYzLjc4MUgxOC4xNDhjLTcuOTQ5LDAtMTcuOTM4LDQuODMzLTE3LjkzOCwyNi4yNSwwLDE5LjY3Myw3Ljc5MiwyNy4yODEsMTUuNjU2LDI3LjI4MWg5LjM0NFY2OC44NmMwLTUuNDkxLDIuNzIxLTE1LjY1NiwxNS40MDYtMTUuNjU2aDI2LjUzMWMzLjkwMiwwLDE0LjkwNi0xLjY5NiwxNC45MDYtMTQuNDA2VjE0LjU3OWMuMDAxLTMuMTUzLS41MzgtMTQuNjU2LTI3LjAzLTE0LjY1NnpNNDAuMjczLDguMzkyYzIuNjYyLDAsNC44MTMsMi4xNSw0LjgxMyw0LjgxMywwLDIuNjYxLTIuMTUxLDQuODEzLTQuODEzLDQuODEzcy00LjgxMy0yLjE1MS00LjgxMy00LjgxM2MwLTIuNjYzLDIuMTUxLTQuODEzLDQuODEzLTQuODEzeiIvPjxwYXRoIGZpbGw9InVybCgjYikiIGQ9Ik01NS4zOTcsMTA5LjkyM2MyNS45NTksMCwyNi4yODItMTAuMjcxLDI2LjI4Mi0xMi4xNTZWODUuMTczSDU0Ljg5N3YtMy43ODFoMzcuMzc1YzguMDA5LDAsMTcuOTM4LTQuOTU0LDE3LjkzOC0yNi4yNSwwLTIzLjMyMi0xMC41MzgtMjcuMjgxLTE1LjY1Ni0yNy4yODFIODUuMjF2MTMuMTI1YzAsNS40OTEtMi42MzEsMTUuNjU2LTE1LjQwNiwxNS42NTZINDMuMjcyYy0zLjg5MiwwLTE0LjkwNiwxLjg5Ni0xNC45MDYsMTQuNDA2djI0LjIxOWMwLDUuMjMsMy4xOTYsMTQuNjU2LDI3LjAzMSwxNC42NTZ6TTcwLjE0OCwxMDEuNDU0Yy0yLjY2MiwwLTQuODEzLTIuMTUxLTQuODEzLTQuODEzczIuMTUtNC44MTMsNC44MTMtNC44MTNjMi42NjEsMCw0LjgxMywyLjE1MSw0LjgxMyw0LjgxM3MtMi4xNTIsNC44MTMtNC44MTMsNC44MTN6Ii8%2BPC9zdmc%2B&style=for-the-badge">
|
||
<img alt="JavaScript" src="https://img.shields.io/badge/JavaScript-1a1a1a?style=for-the-badge&logo=javascript&logoColor=F7DF1E&labelColor=1a1a1a">
|
||
<a href="https://github.com/sponsors/Azornes" style="display: inline-flex; align-items: center; white-space: nowrap;">
|
||
<img src="https://img.shields.io/badge/Sponsor-EA4AAA?style=for-the-badge&logo=githubsponsors&logoColor=magenta&labelColor=1a1a1a" alt="Sponsor"></a>
|
||
<a href="https://ko-fi.com/azornes" style="display: inline-flex; align-items: center; white-space: nowrap;">
|
||
<img src="https://img.shields.io/badge/Ko--fi-F16061?style=for-the-badge&logo=ko-fi&logoColor=white" alt="Ko-Fi"></a>
|
||
</p>
|
||
<p align="center">
|
||
<strong>🔹 <a href="#-installation">Quick Start</a></strong>
|
||
|
|
||
<strong>⚙️ <a href="#%EF%B8%8F-configuration--settings">Configuration</a></strong>
|
||
</p>
|
||
|
||
---
|
||
|
||
## 🚀 Key Features
|
||
|
||
* **🔍 Intelligent Fuzzy Matching**: Scans local ComfyUI model directories and looks for similar files (ignoring case, extensions, or minor naming differences) with similarity confidence scores.
|
||
* **☁️ Multi-Source Cloud Downloader**: Searches for and downloads missing files from **CivitAI**, **HuggingFace**, **CivArchive**, **Lora Manager Archive**, and the **ComfyUI-Manager** model database.
|
||
* **🔄 In-Place Workflow Updater**: Safely replaces model names and paths in your current workflow (supporting nested subgraphs and custom nodes like *rgthree's Power Lora Loader* or *LoraManager*).
|
||
* **📥 Background Download Manager**: Downloads models asynchronously directly to the correct directories (`checkpoints`, `loras`, `vae`, etc.) with speed tracking, file size display, progress bars, and cancellation/pause support.
|
||
* **🕵️ Loaded Models Inspector**: A dedicated tab displaying all models used in the active workflow, including their strength, physical paths, and disk availability status.
|
||
* **📂 Open Containing Folder**: Quickly opens Windows Explorer and selects/highlights the model file directly from the interface.
|
||
* **🔗 Custom URL Downloads**: Directly paste any custom URL link to download files into target folders with customized names.
|
||
|
||
---
|
||
|
||
## 🛠️ How It Works (Step-by-Step)
|
||
|
||
1. **Load Workflow**: Load any workflow JSON or image into ComfyUI.
|
||
2. **Detection**: If the workflow references model files that are missing from your directories, the extension alerts you immediately.
|
||
3. **Resolve**:
|
||
* **Local Search**: Click the local search button to find similar filenames you already have on disk (e.g., if they were moved to a different subfolder).
|
||
* **Online Search**: If the file isn't on disk, search for it online (e.g., on CivitAI via its SHA256 file hash or text search).
|
||
4. **Download or Link**:
|
||
* Click **Download** to asynchronously download the model in the background directly into the correct ComfyUI folder.
|
||
* Or select a local alternative suggested by the Fuzzy Matching algorithm.
|
||
5. **Apply**: Click the apply button to update the ComfyUI workflow with the new, correct model paths. You're ready to click *Queue Prompt*!
|
||
|
||
---
|
||
|
||
## 📂 Supported Nodes & Model Types
|
||
|
||
Model Resolver supports standard ComfyUI mechanisms as well as custom implementations of popular loader nodes:
|
||
* **Standard loaders**: CheckpointLoader, LoraLoader, VAELoader, ControlNetLoader, UpscaleModelLoader, etc.
|
||
* **Advanced loaders**: Nodes from the `LoraManager` suite (`LoraLoaderV2`, `Lora Loader`, `Lora Stacker`), `rgthree` (`Power Lora Loader`), and LTX-Video nodes.
|
||
* **Subgraphs**: Full support for scanning and updating nodes inside nested group subgraphs.
|
||
|
||
---
|
||
|
||
## ⚡ Downloader Backends and Aria2
|
||
|
||
Model Resolver supports two download engines configured in the Settings panel:
|
||
|
||
1. **Python Engine**:
|
||
* Out-of-the-box download backend using standard libraries (`urllib` / `aiohttp`).
|
||
* No external binaries required.
|
||
2. **Aria2 Engine (Recommended)**:
|
||
* High-performance, multi-threaded downloader.
|
||
* Speeds up large downloads by splitting files and downloading across multiple connections (up to 16 connections/splits).
|
||
* Automatically forwards target cookies, headers, and authentication tokens safely.
|
||
|
||
> [!TIP]
|
||
> **One-Click Aria2 Setup:** You do not need to install `aria2c` manually. The extension features a built-in installer that downloads, extracts, and configures the latest official release matching your OS architecture (Windows, macOS, Linux) with a single click in the Settings panel.
|
||
>
|
||
> The extension also manages the lifecycle of the `aria2` background daemon, automatically starting it when a download starts and stopping it when it remains idle to preserve system resources.
|
||
|
||
---
|
||
|
||
## 📂 Dynamic Path Templates
|
||
|
||
When downloading a new model, you can let Model Resolver organize your files automatically based on metadata using templates. The extension offers three **Download Path Modes**:
|
||
* `suggested`: Guesses the best subfolder category automatically.
|
||
* `manual`: Standard custom path mapping.
|
||
* `template`: Dynamically generates the relative path inside your model category using variables.
|
||
|
||
### Available Template Variables
|
||
* `{base_model}`: The base model architecture (e.g., `SD 1.5`, `SDXL`, `Flux`). The value can be translated to customized names via **Base Model Path Mappings** (e.g., mapping `sd1.5` to `SD1.5` and `flux1` to `Flux`).
|
||
* `{author}`: Creator/author username or HuggingFace repo publisher.
|
||
* `{first_tag}`: Primary tag from the model database (mapped via priority hierarchy such as `style`, `concept`, `character`, etc.).
|
||
* `{model_name}`: Clean model name or file stem.
|
||
* `{version_name}`: Model release version name (e.g., `v1.0`).
|
||
|
||
### Default Path Templates
|
||
* **Loras**: `{base_model}/{first_tag}` (e.g., `Loras/SDXL/style/my_lora_v1.safetensors`)
|
||
* **Checkpoints**: `{base_model}` (e.g., `Checkpoints/Flux/my_flux_model.safetensors`)
|
||
* **Embeddings**: `{base_model}`
|
||
|
||
---
|
||
|
||
## ⚙️ Configuration & Settings
|
||
|
||
Configure credentials and API keys in the Settings panel to authenticate gated downloads:
|
||
* **CivitAI API Key & Session Token**: Required to download NSFW models or those requiring accepted terms of service.
|
||
* **HuggingFace Access Token**: Required for gated, private repositories.
|
||
* **Brave Search API Key**: Fallback search query key to locate public/gated HuggingFace download links.
|
||
|
||
> [!IMPORTANT]
|
||
> **Built-in Connection Testers:** The options panel contains instant `Check` buttons for CivitAI keys, CivitAI Session Tokens, HuggingFace tokens, and Brave Search keys. You can verify if credentials are valid and active without leaving the interface.
|
||
|
||
---
|
||
|
||
## 🕵️ Loaded Models Inspector & Local Hashing
|
||
|
||
* **Loaded Models Tab**: Check what models are loaded in the current active python session. It lists paths, model categories, byte sizes, physical existence checks, and confidence levels.
|
||
* **Open Containing Folder**: Select a model in the Loaded Models tab and click the folder icon to open Windows Explorer with the target file highlighted.
|
||
* **Local Hashing (`sha256`)**:
|
||
* You can calculate the exact `sha256` hash of any local model file in the background.
|
||
* Hashing status is updated in real-time, allowing you to use exact hash queries on CivitAI/CivArchive to retrieve model metadata and link files.
|
||
|
||
---
|
||
|
||
## ⚡ Installation
|
||
|
||
### Install via ComfyUI-Manager
|
||
1. Search `ComfyUI Model Resolver` in ComfyUI-Manager and click the `Install` button.
|
||
2. Restart ComfyUI.
|
||
|
||
### Manual Install
|
||
1. Navigate to the `custom_nodes` folder in your ComfyUI installation:
|
||
```bash
|
||
cd ComfyUI/custom_nodes/
|
||
```
|
||
2. Clone this repository:
|
||
```bash
|
||
git clone https://github.com/Azornes/comfyui-model-resolver.git
|
||
```
|
||
3. Start or restart ComfyUI. The extension will automatically install any missing dependencies (`requests`, `aiohttp`) and load the web interface.
|
||
|
||
---
|
||
|
||
## 📝 Requirements
|
||
|
||
* Python 3.10 or newer
|
||
* Libraries: `requests`, `aiohttp` (installed automatically if missing)
|
||
* Modern web browser with JS support (Chrome, Edge, Firefox, Brave)
|
||
|
||
---
|
||
|
||
## 📜 License
|
||
|
||
This project is licensed under the MIT License. Feel free to use, modify, and distribute.
|
||
|
||
---
|
||
|
||
## 💖 Support / Sponsorship
|
||
|
||
* ⭐ **Give a star** — it means a lot to me!
|
||
* 🐛 **Report a bug** or suggest a feature.
|
||
* 💖 **Support my work**:
|
||
👉 [GitHub Sponsors](https://github.com/sponsors/Azornes)
|