diffusers/main/pt/modular_diffusers/components_manager.md

ComponentsManager

ComponentsManager ainda está em desenvolvimento ativo e sua API pode mudar.

O ComponentsManager é um sistema de registro e gerenciamento de modelos para o Modular Diffusers. Ele adiciona e rastreia modelos, armazena metadados úteis (tamanho do modelo, colocação de dispositivo, adaptadores) e oferece suporte a offloading.

Este guia mostrará como usar o ComponentsManager para gerenciar componentes e memória de dispositivo.

Conectar a um pipeline

Crie um ComponentsManager e passe-o para um ModularPipeline usando from_pretrained() ou init_pipeline().

from diffusers import ModularPipeline, ComponentsManager
import torch

manager = ComponentsManager()
pipe = ModularPipeline.from_pretrained("Tongyi-MAI/Z-Image-Turbo", components_manager=manager)
pipe.load_components(dtype=torch.bfloat16)

from diffusers import ModularPipelineBlocks, ComponentsManager
import torch
manager = ComponentsManager()
blocks = ModularPipelineBlocks.from_pretrained("diffusers/Florence2-image-Annotator", trust_remote_code=True)
pipe= blocks.init_pipeline(components_manager=manager)
pipe.load_components(dtype=torch.bfloat16)

Os componentes carregados pelo pipeline são registrados automaticamente no gerenciador. Você pode inspecioná-los imediatamente.

Inspecionar componentes

Imprima o ComponentsManager para ver todos os componentes registrados, incluindo sua classe, colocação de dispositivo, dtype, tamanho de memória e ID de carregamento.

A saída abaixo corresponde ao exemplo de from_pretrained acima.

Components:
=============================================================================================================================
Models:
-----------------------------------------------------------------------------------------------------------------------------
Name_ID                      | Class                    | Device: act(exec) | Dtype          | Size (GB) | Load ID
-----------------------------------------------------------------------------------------------------------------------------
text_encoder_140458257514752 | Qwen3Model               | cpu               | torch.bfloat16 | 7.49      | Tongyi-MAI/Z-Image-Turbo|text_encoder|null|null
vae_140458257515376          | AutoencoderKL            | cpu               | torch.bfloat16 | 0.16      | Tongyi-MAI/Z-Image-Turbo|vae|null|null
transformer_140458257515616  | ZImageTransformer2DModel | cpu               | torch.bfloat16 | 11.46     | Tongyi-MAI/Z-Image-Turbo|transformer|null|null
-----------------------------------------------------------------------------------------------------------------------------

Other Components:
-----------------------------------------------------------------------------------------------------------------------------
ID                           | Class                           | Collection
-----------------------------------------------------------------------------------------------------------------------------
scheduler_140461023555264    | FlowMatchEulerDiscreteScheduler | N/A
tokenizer_140458256346432    | Qwen2Tokenizer                  | N/A
-----------------------------------------------------------------------------------------------------------------------------

A tabela exibe os modelos (com informações de dispositivo, dtype e memória) separadamente de outros componentes, como agendadores e tokenizadores. Se algum modelo tiver adaptadores LoRA, IP-Adapters ou quantização aplicada, essas informações são exibidas em uma seção adicional na parte inferior.

Offloading

O método enable_auto_cpu_offload() é uma estratégia global de offloading que funciona em todos os modelos, independentemente do pipeline que os utiliza. Uma vez habilitado, você não precisa se preocupar com a colocação de dispositivos ao adicionar ou remover componentes.

manager.enable_auto_cpu_offload(device="cuda")  # or "mps", "xpu", "cpu"

Todos os modelos começam na CPU e o ComponentsManager os move para o dispositivo apropriado logo antes de serem necessários, e move outros modelos de volta para a CPU quando a memória da GPU está baixa.

Chame disable_auto_cpu_offload() para desativar o offloading.

manager.disable_auto_cpu_offload()