You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -12,179 +12,85 @@ specific language governing permissions and limitations under the License.
12
12
13
13
# ComponentsManager
14
14
15
-
The [`ComponentsManager`] is a model registry and management system for Modular Diffusers. It adds and tracks models, stores useful metadata (model size, device placement, adapters), prevents duplicate model instances, and supports offloading.
15
+
The [`ComponentsManager`] is a model registry and management system for Modular Diffusers. It adds and tracks models, stores useful metadata (model size, device placement, adapters), and supports offloading.
16
16
17
17
This guide will show you how to use [`ComponentsManager`] to manage components and device memory.
18
18
19
-
## Add a component
19
+
## Connect to a pipeline
20
20
21
-
The [`ComponentsManager`]should be created alongside a [`ModularPipeline`]in either [`~ModularPipeline.from_pretrained`] or [`~ModularPipelineBlocks.init_pipeline`].
21
+
Create a [`ComponentsManager`]and pass it to a [`ModularPipeline`]with either [`~ModularPipeline.from_pretrained`] or [`~ModularPipelineBlocks.init_pipeline`].
22
22
23
-
> [!TIP]
24
-
> The `collection` parameter is optional but makes it easier to organize and manage components.
25
23
26
24
<hfoptionsid="create">
27
25
<hfoptionid="from_pretrained">
28
26
29
27
```py
30
28
from diffusers import ModularPipeline, ComponentsManager
Components are only loaded and registered when using [`~ModularPipeline.load_components`] or [`~ModularPipeline.load_components`]. The example below uses [`~ModularPipeline.load_components`] to create a second pipeline that reuses all the components from the first one, and assigns it to a different collection
Use the [`~ModularPipeline.null_component_names`] property to identify any components that need to be loaded, retrieve them with [`~ComponentsManager.get_components_by_names`], and then call [`~ModularPipeline.update_components`] to add the missing components.
Use [`~ComponentsManager.remove`] to remove a component using their id.
82
-
83
-
```py
84
-
comp.remove("text_encoder_139917733042864")
85
-
```
86
-
87
-
## Retrieve a component
88
-
89
-
The [`ComponentsManager`] provides several methods to retrieve registered components.
90
-
91
-
### get_one
92
-
93
-
The [`~ComponentsManager.get_one`] method returns a single component and supports pattern matching for the `name` parameter. If multiple components match, [`~ComponentsManager.get_one`] returns an error.
| exact |`comp.get_one(name="unet")`| exact name match |
98
-
| wildcard |`comp.get_one(name="unet*")`| names starting with "unet" |
99
-
| exclusion |`comp.get_one(name="!unet")`| exclude components named "unet" |
100
-
| or |`comp.get_one(name="unet|vae")`| name is "unet" or "vae" |
101
-
102
-
[`~ComponentsManager.get_one`] also filters components by the `collection` argument or `load_id` argument.
103
-
104
-
```py
105
-
comp.get_one(name="unet", collection="sdxl")
106
-
```
107
-
108
-
### get_components_by_names
109
-
110
-
The [`~ComponentsManager.get_components_by_names`] method accepts a list of names and returns a dictionary mapping names to components. This is especially useful with [`ModularPipeline`] since they provide lists of required component names and the returned dictionary can be passed directly to [`~ModularPipeline.update_components`].
It is recommended to load model components with [`ComponentSpec`] to assign components with a unique id that encodes their loading parameters. This allows [`ComponentsManager`] to automatically detect and prevent duplicate model instances even when different objects represent the same underlying checkpoint.
120
-
121
-
```py
122
-
from diffusers import ComponentSpec, ComponentsManager
This returns a warning with instructions for removing the duplicate.
51
+
Components loaded by the pipeline are automatically registered in the manager. You can inspect them right away.
138
52
139
-
```py
140
-
ComponentsManager: adding component 'text_encoder_duplicated_139917580682672', but it has duplicate load_id 'stabilityai/stable-diffusion-xl-base-1.0|text_encoder|null|null'with existing components: text_encoder_139918506246832. To remove a duplicate, call `components_manager.remove('<component_id>')`.
141
-
'text_encoder_duplicated_139917580682672'
142
-
```
143
-
144
-
You could also add a component without using [`ComponentSpec`] and duplicate detection still works in most cases even if you're adding the same component under a different name.
145
-
146
-
However, [`ComponentManager`] can't detect duplicates when you load the same component into different objects. In this case, you should load a model with [`ComponentSpec`].
Print the [`ComponentsManager`] to see all registered components, including their class, device placement, dtype, memory size, and load ID.
155
56
156
-
Collections are labels assigned to components for better organization and management. Add a component to a collection with the `collection` argument in [`~ComponentsManager.add`].
157
-
158
-
Only one component per name is allowed in each collection. Adding a second component with the same name automatically removes the first component.
57
+
The output below corresponds to the `from_pretrained` example above.
159
58
160
59
```py
161
-
from diffusers import ComponentSpec, ComponentsManager
This makes it convenient to work with node-based systems because you can:
175
-
176
-
- Mark all models as loaded from one node with the `collection` label.
177
-
- Automatically replace models when new checkpoints are loaded under the same name.
178
-
- Batch delete all models in a collection when a node is removed.
80
+
The table shows models (with device, dtype, and memory info) separately from other components like schedulers and tokenizers. If any models have LoRA adapters, IP-Adapters, or quantization applied, that information is displayed in an additional section at the bottom.
179
81
180
82
## Offloading
181
83
182
84
The [`~ComponentsManager.enable_auto_cpu_offload`] method is a global offloading strategy that works across all models regardless of which pipeline is using them. Once enabled, you don't need to worry about device placement if you add or remove components.
183
85
184
86
```py
185
-
comp.enable_auto_cpu_offload(device="cuda")
87
+
manager.enable_auto_cpu_offload(device="cuda")
186
88
```
187
89
188
90
All models begin on the CPU and [`ComponentsManager`] moves them to the appropriate device right before they're needed, and moves other models back to the CPU when GPU memory is low.
189
91
190
-
You can set your own rules for which models to offload first.
92
+
Call [`~ComponentsManager.disable_auto_cpu_offload`] to disable offloading.
0 commit comments