Automatic Whole-Image Analysis + Cache

Tiled upscaling has a blind spot, and it's the reason most tile jobs come out looking like a collage instead of one picture. Every tile gets prompted in isolation, so tile 37 has no idea it's a crop of a lake with a slate roof on the left. SmartCachedTextGenerate is the fix: it reads the entire image once, writes a scene brief, and hands that brief to every tile prompt downstream. The name undersells it - it's the "automatic whole-image analysis" part of the Smart Upscaler pack, and the caching is what makes it cheap enough to run.

What it actually does

You feed it the picture and the master instruction (that comes from the Prompt Director node, SmartUnifiedPromptGuidance). It runs a vision model over the full image once and returns a master scene prompt: what the scene is, what the big surfaces are, where things sit, which objects are worth treating as identity anchors. Every tile then reuses that read - it gets its own crop's pixels plus this shared context, so it never has to guess what it's a crop of.

The honest part is worth knowing before you trust it. Large flat areas like water, sky, or open ground are found by measuring pixels, not by asking the model - the vision pass then has to identify each measured area, or it gets asked again about that exact spot. Nothing about your scene is hardcoded, and the pack's rule is that automatic corrections subtract unsupported claims rather than inventing content. That's the anti-hallucination spine the rest of the pipeline hangs off.

Inputs that matter

Most of the required inputs are wired for you in the shipped workflow. The ones you actually touch:

• clip - the vision model, loaded through a CLIPLoader. The model is Qwen3-VL 4B FP8, and the loader's type must be set to krea2. Get this wrong and the captioner runs blind - no error, just empty or generic prompts.
• image and prompt - the picture and the Prompt Director's instruction.
• analysis_max_side (optional, default 1344) - how big the longest side of the image sent to the model is. 1344 loses nothing for a scene brief; drop to 768–1024 if you're tight on VRAM. 0 sends the full image, which is almost never worth it.

The rest have working defaults. sampling_mode says "Managed by Prompt Director" and should stay there - the older Consistent caption / Varied wording values only exist so old workflows load. thinking (model reasoning) stays off for a clean caption. cache_mode and cache_tag are the cache controls below.

Outputs and where they go

Three outputs: prompt_text (the scene brief), cache_status (READ/WRITE/HIT so you can see what happened), and review_text. prompt_text wires into the global_context input of SmartTileJobDirector; cache_status strings get collected by the SmartTilePromptAuditLog at the end.

The cache, and why it matters

This is the node that makes rerunning cheap. The whole-image read is keyed on the image, the instruction, the cache tag, and the vision model ID, and stored on disk under ComfyUI/user/<profile>/smart_upscaler_cache/. Change the scale in the Tile Planner and rerun - prompts are reused, the vision model never reloads. cache_mode offers read_write (hit or generate), refresh (regenerate and overwrite), and bypass (skip the cache entirely - the README's fast way to skip analysis). If you swap or update the caption model, bump vision_model_id; that's the field that stops stale captions from another model being reused. The cache is safe to delete any time.

Install

Same story as every node in this pack: install it via ComfyUI Manager (search "ComfyUI-Smart-Upscaler") or

cd ComfyUI/custom_nodes
git clone https://github.com/HallettVisual/ComfyUI-Smart-Upscaler

then restart. You also want ComfyUI-KJNodes and rgthree-comfy from the Manager - the shipped workflow uses their Set_/Get_ wires and comparison sliders. No Python dependencies beyond ComfyUI itself; the ~13 GB of model downloads are the cost of entry, and the 4.9 GB vision model is the one that powers this node. Everything is listed in docs/MODELS.md.

Common gotchas

• Blind captioner, no error. CLIPLoader type not krea2 → empty prompts. The number one setup mistake, called out in the README next to the loader.
• Changing models without changing the cache. Old captions get reused. Change vision_model_id when the model changes, cache_tag when you change the prompt contract.
• VRAM. Built and tested on 16 GB, stage-ordered so the vision model unloads before the image model loads. Under that, shrink analysis_max_side first.

Read the image once, prompt every tile with that context, cache it all. It's why Smart Upscaler can redraw a 90-tile job and keep a lake looking like one lake.