From 0c2a96df11540343511de2e4e90d7651ae933fd8 Mon Sep 17 00:00:00 2001 From: "DESKTOP-TVBJISQ\\Primere" Date: Sat, 28 Mar 2026 21:42:40 +0100 Subject: [PATCH] V 2.0.0 - Manual - terminal helper --- Workflow/Manual/nodes/minimal_workflow.md | 46 ++- .../Manual/nodes/model_version_detection.md | 352 ++++++++++++++++++ 2 files changed, 387 insertions(+), 11 deletions(-) create mode 100644 Workflow/Manual/nodes/model_version_detection.md diff --git a/Workflow/Manual/nodes/minimal_workflow.md b/Workflow/Manual/nodes/minimal_workflow.md index 905666a..5f73d99 100644 --- a/Workflow/Manual/nodes/minimal_workflow.md +++ b/Workflow/Manual/nodes/minimal_workflow.md @@ -85,6 +85,30 @@ This node is the **system backbone** that automates workflow adaptation based on 4. **Allows testing & saving** new settings for specific models 5. **Reverts to "Auto" mode** for external control via workflow inputs +--- + +> [!IMPORTANT] +> ## ⚙️ CRITICAL: Model Type Detection Setup +> +> **Before using Model Control automation, you MUST understand how the system detects model concepts (SD1, SDXL, Flux, etc.).** +> +> **📖 READ THIS GUIDE:** **[Model Version Detection & Caching Guide](./model_version_detection.md)** +> +> This guide covers: +> - How auto-detection works (metadata → directory → cache file) +> - Terminal helper for batch model processing (50+ checkpoints) +> - How to manually fix incorrect model type assignments +> - Symlinked model support from other directories +> +> **TL;DR:** +> - Small collection (<20 models): Let auto-detect work, select checkpoint, done +> - Large collection (50+ models): Run `python terminal_helpers/model_version_cache.py`, fix "UNKNOWN" entries, done +> - Without proper model type detection, Model Control cannot auto-configure settings +> +> **This is the hardest part of the system setup. Invest 5 minutes now to avoid confusion later.** + +--- + #### Dual Operation Modes: --- @@ -1006,14 +1030,14 @@ The Upscaler group increases image resolution intelligently using pre-trained up #### Settings: -| Setting | Purpose | -|---------|---------| -| `use_multiplier` | Enable megapixel-based calculation (ON/OFF, default ON) | -| `upscale_to_mpx` | Target resolution in megapixels (0.01 - 48.00, default 12.00) | -| `triggered_prescale` | Enable area-based pre-scaling trigger (ON/OFF, default OFF) | -| `area_trigger_mpx` | If current area below this MPX, trigger prescale (0.01 - max, default 0.60) | -| `area_target_mpx` | Target MPX if prescale triggered (0.25 - max, default 1.05) | -| `upscale_model` | Upscaler model to apply (None, or specific upscaler name, default None) | +| Setting | Purpose | +|---------|-----------------------------------------------------------------------------------------------| +| `use_multiplier` | Enable target megapixel-based calculation (ON/OFF, default ON) | +| `upscale_to_mpx` | Target resolution in megapixels (0.01 - 48.00, default 12.00) | +| `triggered_prescale` | Enable area-based pre-scaling trigger (ON/OFF, default OFF) for much faster upscaling | +| `area_trigger_mpx` | If current area below this MPX, trigger prescale (0.01 - max, default 0.60) | +| `area_target_mpx` | Target MPX if prescale triggered (0.25 - max, default 1.05) | +| `upscale_model` | Upscaler model to apply (None, or specific upscaler name, default None) | | `upscale_method` | Image interpolation method: nearest-exact, bilinear, area, bicubic, lanczos (default bicubic) | #### Outputs: @@ -1034,9 +1058,9 @@ The Upscaler group increases image resolution intelligently using pre-trained up #### Example Calculation: -- Input: 512×512 (0.26 MPX) with `upscale_to_mpx=12.00` -- Output: ~2448×2448 (5.98 MPX actual, closest to 12.00 respecting aspect ratio) -- Ratio: ~4.78x +- Input: 512×512 (0.26 MPX) with `upscale_to_mpx=16.00` +- Output: ~4096×496 (16 MPX actual) +- Ratio: ~64x --- diff --git a/Workflow/Manual/nodes/model_version_detection.md b/Workflow/Manual/nodes/model_version_detection.md new file mode 100644 index 0000000..ec4bb8c --- /dev/null +++ b/Workflow/Manual/nodes/model_version_detection.md @@ -0,0 +1,352 @@ +# Model Version Detection & Caching Guide + +## Overview + +Primiere Model Control automatically adapts all generation settings (sampler, CFG, steps, VAE, CLIP, encoders, LoRAs, refiners) based on **model type/concept** (SD1, SDXL, Flux, Hunyuan, etc.). This automation requires the system to know which model concept each checkpoint belongs to. + +This guide explains how the model type detection system works, how to set it up, and how to manually fix detection errors. + +--- + +## How Model Type Detection Works + +When you select a checkpoint in the workflow, the system determines its model concept through a **3-step hierarchy**: + +| Step | Method | Example | +|------|--------|------------------------------------------------------| +| **1. Metadata Detection** | Reads model concept from checkpoint file metadata | Flux checkpoint has `model_type: "flux"` in metadata | +| **2. Directory Name** | Infers model concept from parent folder name | Model in `models/checkpoints/Flux/` → Flux concept | +| **3. Cache File** | Looks up pre-computed model-to-concept mapping | `.cache.json`: `"my-model": "Flux"` | + +**If all three fail:** Model marked as "UNKNOWN" — Manual setup required. + +--- + +## Auto-Detection (First Run) + +On first workflow execution with a new checkpoint, the system automatically: + +1. **Scans checkpoint metadata** for model type info +2. **Checks parent directory name** against supported concepts +3. **Stores result** in `Nodes/.cache/.cache.json` cache file +4. **Reuses cached result** on subsequent runs + +**Benefit:** Works immediately for most models without manual setup, if metadata is correct or folder is named properly. + +**Limitation:** Some checkpoints have incorrect/missing metadata, requiring manual verification. + +--- + +## Terminal Helper: Batch Model Detection + +For users with many checkpoints (50+), the terminal helper **pre-processes** all models in one pass instead of on-demand during workflow execution. + +### When to Use Terminal Helper + +✅ **Use if:** +- You have 50+ checkpoints +- You want to verify all models before running workflows +- You have symlinked models from other directories +- You want one-time processing instead of per-run detection + +❌ **Not necessary if:** +- Few models (<20) with correct metadata or folder structure +- Lazy loading acceptable (auto-detect on first workflow use) + +### Setup & Execution + +**Step 1: Locate the Helper** + +Terminal helper file: `ComfyUI_Primere_Nodes/terminal_helpers/model_version_cache.py` + +**Step 2: Activate ComfyUI Virtual Environment** + +```bash +# Windows (venv) +cd your-comfyui-folder +.\venv\Scripts\activate + +# Windows (simple terminal) +.\venv\Scripts\activate.bat + +# Windows (conda) +conda activate comfyui + +# Linux/macOS +source venv/bin/activate +``` + +**Step 3: Run the Helper** + +```bash +cd path/to/ComfyUI_Primere_Nodes +python terminal_helpers/model_version_cache.py +``` + +**Step 4: Review Console Output** + +The helper prints a report showing all detected models and their concept assignments: + +``` +------------------- START ------------------------- +145 models in system +--------------- CACHED MODELS INFO --------------------- +Model [1] / 145 cached from metadata: photon_v1 -> SD1 +Model [2] / 145 cached from directory: my-flux-model -> Flux +Model [3] / 145 cached from directory: realistic_sdxl -> SDXL +Model [4] / 145 UNKNOWN | path: models/checkpoints/mystery_model_v2 +... +``` + +**Look for "UNKNOWN" entries** — these need manual investigation. + +--- + +## Cache File Format + +The terminal helper generates: `Nodes/.cache/.cache.json` + +This file is a key-value dictionary mapping checkpoint names → model concepts. + +### Example Cache File + +```json +{ + "model_version": { + "model_01": "SD1", + "model_02": "SDXL", + "model_03": "SD1", + "model_04": "SD1", + "model_05": "KwaiKolors", + "model_06": "Hunyuan", + "model_07": "Hyper", + "model_08": "SD3", + "model_09-GGUF": "Flux", + "model_10": "LCM", + "model_11L-ightning": "Lightning", + "model_12": "Pony", + "qwenImage2512": "QwenGen", + "model_14_v10": "Z-Image" + } +} +``` + +### Key Points + +- **Key:** Checkpoint filename WITHOUT extension (e.g., `photon_v1` not `photon_v1.safetensors`) +- **Value:** Model concept from supported list (see Supported Concepts below) +- **Auto-generated:** Terminal helper creates this on first run +- **User-editable:** Manually add/correct entries as needed + +--- + +## Supported Model Concepts + +The system recognizes these model concepts: + +``` +SD1, SD2, SDXL, Illustrious, SD3, StableCascade, Chroma, Z-Image, +Turbo, Flux, Nunchaku, QwenGen, QwenEdit, WanImg, KwaiKolors, +Hunyuan, Playground, Pony, LCM, Lightning, Hyper, PixartSigma, +SANA1024, SANA512, AuraFlow + +Future: HiDream, Mochi, WanT2V, WanI2V, Cosmos, Flux2, SSD, +SegmindVega, KOALA, StableZero, SV3D, SD09, StableAudio, LTXV +``` + +--- + +## Manual Setup: Fixing Detection Errors + +If terminal helper output shows "UNKNOWN" or incorrect concept assignment, **manually edit the cache file**. + +### Method 1: Identify Model Type, Then Edit Cache + +**Step 1: Identify Model Concept** + +- Download page / model repo should list model type +- Search HuggingFace or CivitAI for model architecture info +- Look at checkpoint metadata (HuggingFace model cards usually show architecture) +- Check if model trained on SD1.5, SDXL, Flux base + +**Step 2: Edit Cache File** + +Location: `Nodes/.cache/.cache.json` + +Example: You identified `mystery_model_v2` is actually Flux-based. + +Original: +```json +"model_version": { + "mystery_model_v2": "UNKNOWN | path: models/checkpoints/mystery_model_v2" +} +``` + +After fix: +```json +"model_version": { + "mystery_model_v2": "Flux" +} +``` + +Save file and reload ComfyUI. + +### Method 2: Organize by Directory + +Instead of editing cache, organize checkpoints into concept-named folders. Terminal helper will auto-detect from folder structure. + +**Example structure:** + +``` +models/ + checkpoints/ + SD1/ + photon_v1.safetensors + old_sd1_model.safetensors + SDXL/ + the_sdxl_model01.safetensors + the_sdxl_model02.safetensors + Flux/ + the_hunyuan_model-GGUF.safetensors + the_hunyuan_model-dev.safetensors + Hunyuan/ + the_hunyuan_model.safetensors +``` + +Terminal helper will read folder names and auto-populate cache. + +**Advantages:** Future-proof, self-documenting, easy bulk organization. + +--- + +## Symlinked Models + +Primiere supports symlinked models from other directories: + +- `models/unet/` (raw UNet checkpoints) +- `models/diffusers/` (Hugging Face diffusers format) +- `models/diffusion_models/` (other sources) + +If you symlink these into `models/checkpoints/`, the system will: + +1. **Detect symlink** in cache output: `(symlink from: original/path)` +2. **Resolve symlink** to original location +3. **Auto-detect concept** from original path or metadata +4. **Load correctly** via Checkpoint Loader + +### Example + +You have: `models/diffusers/flux-dev` (Flux model in diffusers format) + +Create symlink: `models/checkpoints/flux-dev` → `../diffusers/flux-dev` + +Terminal helper output: +``` +Model [50] / 145 cached from directory: flux-dev -> Flux (symlink from: /path/to/models/diffusers/flux-dev) +``` + +Result: Model loads and routes through Model Control automation with Flux concept settings. + +--- + +## Workflow: Auto-Detect vs. Terminal Helper + +### Scenario 1: Few Models, Good Metadata (5-20 checkpoints) + +**Just use auto-detect:** + +1. Run workflow normally +2. System detects model concept on first use +3. Settings cached automatically +4. Done — no manual setup needed + +### Scenario 2: Many Models, Mixed Metadata (50+ checkpoints) + +**Use terminal helper:** + +1. Run terminal helper: `python terminal_helpers/model_version_cache.py` +2. Review output for "UNKNOWN" entries +3. Manually identify those models and edit cache file +4. Re-run terminal helper to verify (optional) +5. All models pre-processed, workflow runs instantly + +### Scenario 3: Symlinked Models + +**Terminal helper required:** + +1. Create symlinks from other dirs → `models/checkpoints/` +2. Run terminal helper +3. Helper resolves symlinks and detects concepts +4. All symlinked models cached and ready + +--- + +## Troubleshooting + +**Problem: Model marked "UNKNOWN" after terminal helper** + +- Check if model metadata is accessible (some encrypted models fail) +- Look up model on HuggingFace/CivitAI and identify concept +- Manually edit cache file with correct concept +- Verify model folder name doesn't match any concept name (typos confuse detector) + +**Problem: Wrong concept assigned** + +- Model metadata has incorrect `model_type` field (use metadata from download page instead) +- Parent folder name doesn't match actual concept +- Solution: Manually override in cache file or move to correctly-named folder + +**Problem: Cache file not updating** + +- ComfyUI cache or file lock issue +- Solution: Restart ComfyUI, verify `Nodes/.cache/` folder exists and is writable +- Delete `.cache.json` and re-run terminal helper + +**Problem: Symlinked models not detected** + +- Helper requires full symlink resolution permissions +- On Windows, run terminal AS ADMIN +- On Linux/macOS, verify symlink targets are readable + +--- + +## Integration with Primiere Model Control + +Once cache is populated: + +1. **Select checkpoint** in Visual Checkpoint Selector (workflow) +2. **Model Control reads** checkpoint name +3. **Looks up concept** in cache file +4. **Auto-loads saved settings** for that concept +5. **All parameters adapt** (sampler, CFG, VAE, encoders, LoRAs, refiners) + +**Result:** One click changes everything. No manual parameter tweaking. + +--- + +## Cache File Location + +**File:** `ComfyUI_Primere_Nodes/Nodes/.cache/.cache.json` + +**Scope:** Local to this nodepack installation — different installs have separate caches + +**Persistence:** Survives nodepack updates (cached in git-ignore) + +**Backup:** Consider backing up `.cache.json` if you invest time manually correcting models + +--- + +## Summary + +| Aspect | Details | +|--------|---------| +| **Auto-Detect** | Runs on first workflow use, requires correct metadata or folder structure | +| **Terminal Helper** | Batch pre-processes all models, generates cache file, recommended for 50+ models | +| **Cache File** | JSON key-value map stored in `Nodes/.cache/.cache.json`, user-editable | +| **Manual Setup** | Edit cache file directly for incorrect/unknown models | +| **Symlinks** | Supported and auto-resolved by helper and loader | +| **Model Control** | Uses cached concept to auto-configure all generation settings | + +**Bottom line:** For small collections, let auto-detect work. For large collections, run terminal helper once and manually fix any "UNKNOWN" entries. Then forget about model types — Primiere handles everything. + +---