From 8d4b8d879fa09da228a26169796b7c3345a03a1f Mon Sep 17 00:00:00 2001 From: Dariusz L Date: Sat, 4 Jul 2026 19:09:41 +0200 Subject: [PATCH] docs(README): clarify Aria2 setup, path templates, and downloader settings --- README.md | 91 ++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 73 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index e31f951..7117ee8 100644 --- a/README.md +++ b/README.md @@ -17,21 +17,26 @@ SponsorGitHub

- 🔹 Quick Start + 🔹 Quick Start   |   - ⚙️ Configuration + ⚙️ Configuration +   |   + ⚡ Aria2 Setup +   |   + 📂 Path Templates

--- ## 🚀 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 cancel 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. +* **🔍 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. --- @@ -40,11 +45,11 @@ 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). + * **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. + * 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*! --- @@ -58,15 +63,65 @@ Model Resolver supports standard ComfyUI mechanisms as well as custom implementa --- -## ⚙️ Configuration & Credentials (Settings) +## ⚡ Downloader Backends and Aria2 -In the extension settings panel, you can configure API keys and authorization tokens, which are required for downloading private models or files requiring authentication: -* **CivitAI API Key & Session Token**: Allows downloading models from CivitAI (including those marked as NSFW or requiring accepted terms of service). -* **HuggingFace Token**: Required for downloading gated or private models from HuggingFace. -* **Brave Search API Key**: An optional key used as a fallback search mechanism to discover HuggingFace download links via Brave search. +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] -> The extension includes a built-in connection tester that allows you to instantly verify the validity of your tokens directly in the settings panel. +> **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. ---