Skip to content

Commit 9622900

Browse files
docs: cover Canvas, Workflow, Gallery, and Model Manager features (#9196)
* docs: cover Canvas, Workflow, Gallery, and Model Manager features - New: Canvas Workflow Integration (run workflow on raster layer) - New: Canvas Projects (.invk save/load) - New: Custom Node Manager (install/manage community node packs) - New: Layer tips (canvas drag & drop targets + lock transparency) - gallery: virtual boards (by date) - editor-interface: workflow library tags (dynamic per-user tags) - adding-nodes: point manual install at Custom Node Manager - models: editable source URL, bulk delete/reidentify, missing-files filter, settings export/import - fp8-storage: hardware support tiers (Ampere / Ada+Hopper / pre-Ampere) * docs: address review feedback - custom-node-manager: fix broken creating-nodes link (absolute path) - adding-nodes: fix broken community-nodes links (absolute path), document Workflow Connectors (#9027) under Connecting Nodes - concepts/models: note that HF Repo IDs can be pasted into URL field, remove obsolete v4.0.0 autoimport tip - fp8-storage: surface "full precision only" warning at the top, remove redundant quantized-formats bullet near the bottom
1 parent 19007a1 commit 9622900

9 files changed

Lines changed: 382 additions & 13 deletions

File tree

docs/src/content/docs/concepts/models.mdx

Lines changed: 63 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -33,14 +33,10 @@ Some models carry license terms that limit their use in commercial applications
3333

3434
There are a few ways to install other models:
3535

36-
- **URL or Local Path**: Provide the path to a model on your computer, or a direct link to the model. Some sites require you to use an API token to download models, which you can [set up in the config file].
36+
- **URL or Local Path**: Provide the path to a model on your computer, or a direct link to the model. Some sites require you to use an API token to download models, which you can [set up in the config file]. You can also paste a HuggingFace Repo ID here directly — it is detected and routed to the HuggingFace installer automatically.
3737
- **HuggingFace**: Paste a HF Repo ID to install it. If there are multiple models in the repo, you'll get a list to choose from. Repo IDs look like this: `XpucT/Deliberate`. There is a copy button on each repo to copy the ID.
3838
- **Scan Folder**: Scan a local folder for models. You can install all of the detected models in one click.
3939

40-
:::tip[Autoimport]
41-
The dedicated autoimport folder is removed as of v4.0.0. You can do the same thing on the **Scan Folder** tab - paste the folder you'd like to import from and then click `Install All`.
42-
:::
43-
4440
### Diffusers models in HF repo subfolders
4541

4642
HuggingFace repos can be structured in any way. Some model authors include multiple models within the same folder.
@@ -54,3 +50,65 @@ In this situation, you may need to provide some additional information to identi
5450
:::
5551

5652
[set up in the config file]: ../../configuration/invokeai-yaml
53+
54+
## Editing model metadata
55+
56+
Every model has an editable **Source URL** field alongside its name and description. Use it to record where a model came from — for example a Civitai or HuggingFace page — independent of how it was originally installed. The URL is editable from the model's **Edit** view and appears as a clickable link in the model header once set. Models without a URL simply hide the field.
57+
58+
This is purely metadata: the URL has no effect on loading and is not used to refresh or reinstall the model. It is mainly useful for going back to the model's documentation, license, or example prompts later.
59+
60+
## Bulk actions in the Model Manager
61+
62+
The Model Manager supports multi-selection for batch operations.
63+
64+
- **Select multiple models** by clicking with **Ctrl** (Windows / Linux) or **Cmd** (macOS) held, or by using the checkboxes on each row. A sticky header at the top shows the current selection count and is always visible while you scroll.
65+
- Open the **Actions** dropdown for the selection. The available actions are:
66+
- **Delete Models** — removes every selected model in a single confirmation step. Partial failures (e.g. permission issues) are reported per-model in the result toast.
67+
- **Reidentify Models** — re-probes every selected model, updating fields that depend on the file contents (type, base, format, variant, etc.). This is the bulk version of the per-model reidentify action.
68+
69+
:::caution[Reidentify resets custom settings]
70+
Reidentifying a model re-derives its configuration from the file on disk. Any custom settings you've adjusted on those models — default settings, descriptions, trigger phrases — may be overwritten. The confirmation modal warns you about this before running.
71+
:::
72+
73+
Both actions handle partial failures: if some models succeed and others fail, the toast lists succeeded and failed counts and the list view updates immediately for the ones that worked.
74+
75+
## Finding orphaned models
76+
77+
If a model file is deleted or moved outside the Model Manager, its database entry sticks around. To find these orphaned entries:
78+
79+
1. Open the Model Manager.
80+
2. Open the **type filter** dropdown and pick **Missing Files**.
81+
3. The list now shows only models whose files are no longer present on disk. Each one also displays a **Missing Files** badge in its row.
82+
83+
Orphaned models are automatically excluded from selection dropdowns (main model, LoRA, VAE, etc.), so you cannot accidentally pick one for generation. Use the [bulk delete action](#bulk-actions-in-the-model-manager) to clean them out in one step.
84+
85+
## Exporting and Importing Model Settings
86+
87+
Each installed model has an **Export Settings** and **Import Settings** action in the Model Manager. Use these to back up a model's configuration, move it to another install, or share a curated setup with someone else.
88+
89+
### What gets exported
90+
91+
The exported `.json` file captures the configuration you have set on the model, not the model weights themselves:
92+
93+
- `default_settings` — steps, CFG / guidance, scheduler, dimensions, FP8 storage toggle, VAE precision, etc.
94+
- `trigger_phrases` — for LoRAs and similar.
95+
- `cpu_only` — for encoder-type models.
96+
- `name`, `description`, `source_url` — the model's identifying metadata.
97+
- `cover_image` — the model's thumbnail, embedded as a base64 data URL.
98+
99+
Fields you have not set are omitted from the file. The format is forward and backward compatible: older clients ignore newer fields, and a file produced by a newer version still imports cleanly into an older one (it just skips the fields it does not understand).
100+
101+
### Importing
102+
103+
Importing applies the JSON to the currently selected model:
104+
105+
- `default_settings`, `trigger_phrases`, `cpu_only`, `name`, `description`, and `source_url` are applied via the normal model update path. Any field that the target model type does not support (e.g. `cpu_only` on a model that has no such setting) is listed in a "skipped" toast — everything else still applies.
106+
- `cover_image` is uploaded and set as the model's thumbnail.
107+
108+
Imports are validated before they run. The file is rejected if `source_url` is not an `http(s)://` URL or if `cover_image` is not a valid image data URL — so a malformed or hand-edited file cannot quietly poison a model's configuration.
109+
110+
### Typical workflows
111+
112+
- **Back up a model you've spent time tuning** so you can restore its settings after a reinstall, or roll back after experimenting.
113+
- **Copy settings between two installs of the same model** — e.g. between a desktop and a workstation.
114+
- **Share a curated setup** (name, description, thumbnail, default steps / CFG / scheduler, trigger phrases) for a model you have configured well.

docs/src/content/docs/configuration/fp8-storage.mdx

Lines changed: 24 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,13 +10,33 @@ FP8 Storage cuts a model's VRAM footprint roughly in half by keeping weights on
1010

1111
It pairs well with [Low-VRAM mode](/configuration/low-vram-mode/): low-VRAM mode streams layers between RAM and VRAM, while FP8 Storage shrinks the layers themselves.
1212

13+
:::caution[For full precision models only]
14+
FP8 Storage only applies to **full precision** checkpoints (FP16 / BF16 / FP32). It is **silently a no-op** for already-quantized formats — **GGUF**, **NF4**, and **int8** checkpoints carry their own storage precision and the loader returns a different module type that the FP8 layer cast does not touch. If your model is already quantized, the toggle has no effect; use the full-precision variant of the model if you want to enable FP8 Storage.
15+
:::
16+
1317
## Requirements
1418

1519
- **Nvidia GPU on Windows or Linux.** FP8 Storage uses CUDA tensor types and is silently disabled on CPU and MPS.
1620
- **CUDA 12.x and recent PyTorch.** The `float8_e4m3fn` dtype was added in PyTorch 2.1 — InvokeAI's bundled versions satisfy this.
1721

1822
There is no hardware requirement for FP8 *compute* — InvokeAI casts back to FP16/BF16 for math. This means FP8 Storage works on GPUs that do not natively support FP8 matmul (e.g. RTX 30-series), at a small per-step throughput cost.
1923

24+
## Hardware support tiers
25+
26+
Because InvokeAI's FP8 path uses `enable_layerwise_casting` — storage in FP8, compute in BF16/FP16 — the practical benefit of toggling FP8 Storage depends on what your GPU can do natively. There are three tiers:
27+
28+
### RTX 30-series and older Ampere workstation cards — VRAM win only
29+
30+
The toggle works as advertised: the UNet / transformer drops by roughly 50% on the GPU. Per-step latency is the same or marginally slower because every forward pass adds an FP8 → BF16 cast on entry and a BF16 → FP8 cast on exit. This is the **largest target group**: 3090 owners squeezing FLUX into 24 GB benefit the most.
31+
32+
### RTX 40-series, RTX 50-series, and Hopper — VRAM win today, compute win possible later
33+
34+
These GPUs have native FP8 tensor cores. The toggle still buys you the same ~50% VRAM reduction today, because the forward pass still runs in BF16 under `enable_layerwise_casting`. If InvokeAI later wires up a true FP8 matmul path (e.g. via `torchao`), the same toggle will *also* unlock compute speedups on this hardware. Until then, treat the benefit as "VRAM only, same as Ampere".
35+
36+
### Pre-Ampere Nvidia, MPS, and CPU — no-op
37+
38+
FP8 Storage is silently disabled on anything that is not CUDA, and it is not meaningful on pre-Ampere CUDA cards either. On CPU PyTorch *technically* supports FP8 dtypes, but the cast operations are software-emulated and end up costing more than the memory savings buy back, so InvokeAI does not apply FP8 Storage on CPU. If you toggle it on unsupported hardware, the loader logs nothing and returns the model unchanged — the UI may also grey the toggle out or show a "not supported on this hardware" note.
39+
2040
## Enabling FP8 Storage
2141

2242
FP8 Storage is a **per-model setting**, configured from the Model Manager:
@@ -64,10 +84,11 @@ That said, some artifacts have been reported on:
6484

6585
If you see unexpected quality regressions, disable FP8 Storage on the affected model and re-run.
6686

67-
## Combining with Low-VRAM mode and quantized models
87+
## Combining with Low-VRAM mode
88+
89+
**FP8 + partial loading**: fully supported. FP8 Storage shrinks the layers; partial loading streams them between RAM and VRAM as needed. Use both on tight VRAM budgets.
6890

69-
- **FP8 + partial loading**: fully supported. FP8 Storage shrinks the layers; partial loading streams them between RAM and VRAM as needed. Use both on tight VRAM budgets.
70-
- **FP8 + GGUF / NF4 / int8 quantized checkpoints**: these formats already have their own storage precision. FP8 Storage is not applied on top — the toggle is silently a no-op for quantized formats, since the loader returns a different module type.
91+
(For why FP8 Storage doesn't stack on top of GGUF / NF4 / int8 checkpoints, see the [callout at the top of this page](#for-full-precision-models-only).)
7192

7293
## Troubleshooting
7394

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
title: Canvas Projects (.invk files)
3+
sidebar:
4+
order: 4
5+
---
6+
7+
import { Steps } from '@astrojs/starlight/components';
8+
9+
Canvas Projects let you save the entire state of a canvas — including all layers, masks, reference images, generation parameters, and LoRAs — into a single `.invk` file that you can reopen later or share with someone else.
10+
11+
`.invk` files are ZIP archives. They embed the actual image bytes for every layer and reference image, so a project is fully self-contained: opening it on another machine or after wiping the gallery still restores everything.
12+
13+
## Saving a project
14+
15+
<Steps>
16+
1. Open the canvas and arrange your layers, masks, reference images, and parameters the way you want them.
17+
2. From the menu, choose **File → Save Canvas Project**.
18+
3. Optionally rename the project (the default is **Canvas Project**).
19+
4. Save the `.invk` file to disk.
20+
</Steps>
21+
22+
What gets saved:
23+
24+
- All raster, inpaint, and control layers, with their image data, transforms, opacity, and lock state.
25+
- All masks.
26+
- Reference images.
27+
- Currently configured generation parameters (model, prompts, scheduler, seed, dimensions, etc.).
28+
- LoRAs and their weights.
29+
30+
## Loading a project
31+
32+
<Steps>
33+
1. From the menu, choose **File → Load Canvas Project**.
34+
2. Pick the `.invk` file.
35+
</Steps>
36+
37+
When a project is loaded, the canvas is replaced with the project's state. LoRAs are reset first, then re-applied from the project, so opening a project never leaves stale LoRAs from your previous session attached.
38+
39+
### Image deduplication
40+
41+
Loading a project does **not** blindly re-upload every embedded image. Invoke compares each embedded image against what is already in your gallery and only uploads the images that are missing. Re-opening the same project a second time, or opening it shortly after saving it, is therefore very fast — most or all images will already be on the server.
42+
43+
This also means a project shared with another user will upload all its images the first time it is opened on that user's machine, then become nearly free to re-open after that.
44+
45+
To keep the gallery responsive during large imports, image fetches and uploads are limited to a small number of concurrent requests.
46+
47+
## What `.invk` does *not* save
48+
49+
A `.invk` file is a canvas state snapshot. It does **not** contain:
50+
51+
- The models, LoRAs, or embeddings themselves — only references to them. If you share a project, the recipient needs the same models installed (or compatible substitutes).
52+
- Workflow editor state (use **Save Workflow** in the workflow editor for that).
53+
- Gallery boards or images outside the canvas.
54+
55+
## Sharing projects
56+
57+
`.invk` files are safe to share directly. The recipient drops the file via **File → Load Canvas Project** on their own canvas. They'll need any referenced models / LoRAs installed locally; if a referenced model is missing, the parameter slot will be empty and they can pick a substitute before generating.
Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
title: Layer Tips
3+
sidebar:
4+
order: 6
5+
---
6+
7+
A couple of layer-related behaviors that aren't obvious from the canvas UI alone.
8+
9+
## Drag & drop targets
10+
11+
Dragging an image onto the canvas reveals **five** drop zones, arranged as two zones on top and three on the bottom:
12+
13+
| Top row | |
14+
| :--- | :--- |
15+
| **New Raster Layer** | Create a regular raster layer from the dropped image. |
16+
| **New Control Layer** | Create a control layer from the dropped image. |
17+
18+
| Bottom row | |
19+
| :--- | :--- |
20+
| **New Regional Reference** | Use the image as a regional reference. |
21+
| **New Inpaint Mask** | Create a new inpaint mask layer using the image as the mask source. |
22+
| **New Resized Control Layer** | Create a control layer resized to the current canvas dimensions. |
23+
24+
You can drop from the gallery, from disk, or from any panel that shows a draggable image.
25+
26+
## Lock transparency on raster layers
27+
28+
Each raster layer has a **Lock Transparency** toggle (drop icon) in its layer header. When enabled, brush strokes only affect existing non-transparent pixels — painting over transparent areas does nothing. This behaves like Photoshop's "Lock Transparent Pixels".
29+
30+
Typical uses:
31+
32+
- **Recolor an existing shape** without bleeding paint into the empty space around it.
33+
- **Refine details on a subject** that was painted on an otherwise transparent layer, with no risk of growing its silhouette.
34+
35+
Toggle it off to resume normal painting. The lock is per-layer, so different layers can be locked or unlocked independently. Pressure-sensitive pen input and undo/redo both respect the lock.
Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
---
2+
title: Run Workflow on Canvas
3+
sidebar:
4+
order: 5
5+
---
6+
7+
import { Steps } from '@astrojs/starlight/components';
8+
9+
You can run any workflow against a raster layer directly from the canvas. The selected layer is passed in as the workflow's image input, and the results land in the canvas staging area where you can review and accept them — without leaving the canvas tab.
10+
11+
## Requirements for a workflow
12+
13+
For a workflow to be available from the canvas, it must satisfy three conditions:
14+
15+
1. **Form Builder is enabled.** The workflow's parameters are presented through the Form Builder UI when the workflow is launched from the canvas, so the workflow needs to have a form configured.
16+
2. **At least one image input field.** The layer you right-click on is passed into the first eligible image field as the workflow's input.
17+
3. **At least one `Canvas Output` node.** This is the node that marks which images should be routed back to the canvas staging area.
18+
19+
Workflows that do not meet all three are filtered out of the canvas workflow selector.
20+
21+
## The `Canvas Output` node
22+
23+
`Canvas Output` is a dedicated workflow node that explicitly marks the images you want shown in the canvas staging area. Add it at the end of any branch whose output should appear on the canvas.
24+
25+
A workflow can include **multiple `Canvas Output` nodes**. Each one becomes its own entry in the staging area, with an individually selectable thumbnail. You can navigate between entries with the arrow keys and accept just one of them onto the canvas.
26+
27+
:::note[Why an explicit node?]
28+
Earlier versions detected output images heuristically (by scanning for `board` fields). That was fragile and caused unrelated nodes — for example, `save_image` — to be mistaken for canvas outputs. `Canvas Output` makes the routing intentional.
29+
:::
30+
31+
## Running a workflow
32+
33+
<Steps>
34+
1. On the canvas, **right-click a raster layer** to open its context menu.
35+
2. Choose **Run Workflow**.
36+
3. Pick a workflow from the list. Only workflows that meet the [requirements](#requirements-for-a-workflow) appear here.
37+
4. Adjust any exposed parameters in the form. All form field types are supported: text, numbers, booleans, enums, schedulers, boards, models, and images.
38+
5. Click **Run**. The workflow is queued and the results stream into the staging area as they complete.
39+
</Steps>
40+
41+
The current layer is automatically passed into the workflow's image input — you do not need to select an image manually.
42+
43+
## Reviewing and accepting results
44+
45+
Results appear in the canvas staging area strip at the bottom of the canvas:
46+
47+
- If the workflow has a single `Canvas Output`, you get one thumbnail per run.
48+
- If it has multiple `Canvas Output` nodes, each run produces multiple thumbnails, one per output node.
49+
- Use the staging area's next / previous controls (or arrow keys) to cycle through entries. Navigation wraps across run boundaries.
50+
- Click **Accept** to commit the currently selected entry onto the canvas. Only that single image is committed — siblings stay in staging until you accept or discard them.
51+
52+
## Troubleshooting
53+
54+
### My workflow doesn't appear in the selector
55+
56+
Check, in order:
57+
58+
- The workflow has Form Builder enabled.
59+
- The workflow has at least one image input field.
60+
- The workflow contains at least one `Canvas Output` node.
61+
62+
If any of these is missing, the workflow is hidden.
63+
64+
### Queueing fails with a "BoardField" validation error
65+
66+
This was a known issue with workflows that combined `save_image` and `canvas_output` nodes. It is fixed — update Invoke and try again.
67+
68+
### Errors during execution
69+
70+
Workflow errors are surfaced as toasts and the staging area is cleaned up so it returns to a usable state. Open the queue panel for the full error message.

0 commit comments

Comments
 (0)