diffusers/v0.43.0/pt/api/modular_diffusers/pipeline_components.md

Componentes e configurações

ComponentSpec[[diffusers.ComponentSpec]]

diffusers.ComponentSpec[[diffusers.ComponentSpec]]

diffusers.ComponentSpec(name: str | None = None, type_hint: typing.Optional[typing.Type] = None, description: str | None = None, config: diffusers.configuration_utils.FrozenDict | None = None, pretrained_model_name_or_path: str | list[str] | None = None, subfolder: str | None = '', variant: str | None = None, revision: str | None = None, default_creation_method: typing.Literal['from_config', 'from_pretrained'] = 'from_pretrained', repo: str | list[str] | None = None)

Fonte

Parâmetros:

name : Nome do componente

type_hint : Tipo do componente (por exemplo, UNet2DConditionModel)

description : Descrição opcional do componente

config : Dicionário de configuração opcional para a criação de init

pretrained_model_name_or_path : Caminho opcional pretrained_model_name_or_path para a criação via from_pretrained

subfolder : Subpasta opcional em pretrained_model_name_or_path

variant : variante opcional em pretrained_model_name_or_path

revision : Revisão opcional em pretrained_model_name_or_path

default_creation_method : Preferred creation method - "from_config" or "from_pretrained"

Especificação para um componente de pipeline.

Um componente pode ser criado de duas maneiras:

1. Do zero usando init com um dicionário de configuração
2. usando from_pretrained

criar[[diffusers.ComponentSpec.create]]

create(config: diffusers.configuration_utils.FrozenDict | dict[str, typing.Any] | None = None, **kwargs)

Fonte

Crie o componente usando from_config com config.

decode_load_id[[diffusers.ComponentSpec.decode_load_id]]

decode_load_id(load_id: str)

Fonte

Parâmetros:

load_id : A string load_id a ser decodificada, formato: "pretrained_model_name_or_path|subfolder|variant|revision", onde os valores None são representados como "null"

Retorna:

Dicionário que mapeia os nomes dos campos de carregamento para seus valores. Ex.: { "pretrained_model_name_or_path": "path/to/repo", "subfolder": "subfolder", "variant": "variant", "revision": "revision" } Se o valor de um segmento for "null", ele é substituído por None. Retorna None se load_id for "null" (indicando que o componente não foi criado com o método load).

Decodifique uma string de load_id de volta para um dicionário de campos e valores de carregamento.

from_component[[diffusers.ComponentSpec.from_component]]

from_component(name: str, component: Any)

Fonte

Parâmetros:

name : Nome do componente

component : Objeto de componente a partir do qual criar a especificação

Retorna:

Objeto ComponentSpec

Exceções: ValueError

• ValueError -- Se o componente não for suportado (por exemplo, nn.Module sem load_id, não-ConfigMixin)

Crie um ComponentSpec a partir de um Component.

Atualmente suporta:

• Componentes criados com o método ComponentSpec.load()
• Componentes que são subclasses de ConfigMixin, mas não são nn.Modules (por exemplo, agendadores, guias)

load[[diffusers.ComponentSpec.load]]

load(**kwargs)

Fonte

Carregue o componente usando from_pretrained.

loading_fields[[diffusers.ComponentSpec.loading_fields]]

loading_fields()

Fonte

Retorna os nomes de todos os campos relacionados ao carregamento (ou seja, aqueles cujo field.metadata["loading"] é True).

ConfigSpec[[diffusers.ConfigSpec]]

diffusers.ConfigSpec[[diffusers.ConfigSpec]]

diffusers.ConfigSpec(name: str, default: Any, description: str | None = None)

Fonte

Especificação para um parâmetro de configuração de pipeline.

ComponentsManager[[diffusers.ComponentsManager]]

diffusers.ComponentsManager[[diffusers.ComponentsManager]]

diffusers.ComponentsManager()

Fonte

Um sistema central de registro e gerenciamento para componentes de modelos em vários pipelines.

ComponentsManager oferece uma maneira unificada de registrar, rastrear e reutilizar componentes de modelo (como UNet, VAE, codificadores de texto, etc.) entre diferentes pipelines modulares. Ele inclui recursos para detecção de duplicatas, gerenciamento de memória e organização de componentes.

> Este é um recurso experimental e provavelmente mudará no futuro.

Exemplo:

from diffusers import ComponentsManager

# Create a components manager
cm = ComponentsManager()

# Add components
cm.add("unet", unet_model, collection="sdxl")
cm.add("vae", vae_model, collection="sdxl")

# Enable auto offloading
cm.enable_auto_cpu_offload()

# Retrieve components
unet = cm.get_one(name="unet", collection="sdxl")

adicionar[[diffusers.ComponentsManager.add]]

add(name: str, component: Any, collection: str | None = None)

Fonte

Parâmetros:

name (str) : O nome do componente

component (Any) : O componente a ser adicionado

collection (str | None) : A coleção à qual adicionar o componente

Retorna: str

O ID único do componente, que é gerado como "{name}_{id(component)}", onde id(component) é o identificador único embutido do Python para o objeto

Adicione um componente ao ComponentsManager.

disable_auto_cpu_offload[[diffusers.ComponentsManager.disable_auto_cpu_offload]]

disable_auto_cpu_offload()

Fonte

Desative o offloading automático de CPU para todos os componentes.

enable_auto_cpu_offload[[diffusers.ComponentsManager.enable_auto_cpu_offload]]

enable_auto_cpu_offload(device: str | int | torch.device = None, memory_reserve_margin = '3GB', offload_strategy = None)

Fonte

Parâmetros:

device (str | int | torch.device) : O dispositivo de execução para onde os modelos são movidos para as passadas de frente

memory_reserve_margin (str) : A margem de reserva de memória a ser usada, padrão é 3GB. Esta é a quantidade de memória a manter livre no dispositivo para evitar a falta de memória durante a execução do modelo (por exemplo, para ativações intermediárias, gradientes, etc.)

offload_strategy : Qualquer função chamável com a assinatura (hooks, model_id, model, execution_device) -> hooks, retornando quais modelos residentes devem ser descarregados antes que o modelo a ser carregado seja carregado. O padrão é AutoOffloadStrategy, que libera a combinação mínima suficiente.

Ative o offloading automático de CPU para todos os componentes.

O algoritmo funciona da seguinte forma:

1. Todos os modelos começam na CPU por padrão
2. Quando o forward pass de um modelo é chamado, ele é movido para o dispositivo de execução
3. Se houver memória insuficiente, outros modelos no dispositivo são movidos de volta para a CPU
4. O sistema tenta descarregar a menor combinação de modelos que libere memória suficiente
5. Os modelos permanecem no dispositivo de execução até que outro modelo precise de memória e os force a sair

Um modelo offloaded em grupo participa disso, mas se posiciona: ele ainda pode abrir espaço movendo outros modelos para o lado, e nunca é movido para abrir espaço para eles. Qualquer ordem funciona — offload em grupo antes ou depois de habilitar isso. AutoOffloadStrategy dimensiona suas decisões com base nas pegadas de memória dos modelos, que não descrevem um modelo segurando um grupo de cada vez, então passe um offload_strategy que decida com base no fluxo de trabalho.

get_components_by_ids[[diffusers.ComponentsManager.get_components_by_ids]]

get_components_by_ids(ids: list[str], return_dict_with_names: bool | None = True)

Fonte

Parâmetros:

ids (list[str]) : lista de IDs de componentes

return_dict_with_names (bool | None) : Se deve retornar um dicionário com os nomes dos componentes como chaves:

Retorna: dict[str, Any]

Dicionário de componentes.

• Se return_dict_with_names=True, as chaves são os nomes dos componentes.
• Se return_dict_with_names=False, as chaves são os IDs dos componentes.

Exceções: ValueError

• ValueError -- Se nomes de componentes duplicados forem encontrados nos resultados da busca quando return_dict_with_names=True

Obtém componentes por uma lista de IDs.

get_components_by_names[[diffusers.ComponentsManager.get_components_by_names]]

get_components_by_names(names: list[str], collection: str | None = None)

Fonte

Parâmetros:

names (list[str]) : lista de nomes de componentes

collection (str | None) : Coleção opcional para filtrar por

Retorna: dict[str, Any]

Dicionário de componentes com os nomes dos componentes como chaves

Exceções: ValueError

• ValueError -- Se nomes de componentes duplicados forem encontrados nos resultados da busca

Obtém componentes por uma lista de nomes, opcionalmente filtrados por coleção.

get_ids[[diffusers.ComponentsManager.get_ids]]

get_ids(names: str | list[str] = None, collection: str | None = None)

Fonte

Parâmetros:

names (str | list[str]) : lista de nomes de componentes

collection (str | None) : Coleção opcional para filtrar por

Retorna: list[str]

lista de IDs de componentes

Obtém os IDs dos componentes por uma lista de nomes, opcionalmente filtrados por coleção.

get_model_info[[diffusers.ComponentsManager.get_model_info]]

get_model_info(component_id: str, fields: str | list[str] | None = None)

Fonte

Parâmetros:

component_id (str) : Nome do componente para o qual se deseja obter informações

fields (str | list[str] | None) : Campo(s) a retornar. Pode ser uma string para um único campo ou uma lista de campos. Se for None, usa a configuração available_info_fields.

Retorna:

Dicionário contendo os metadados do componente solicitado. Se fields for especificado, retorna apenas esses campos. Caso contrário, retorna todos os campos.

Obtenha informações abrangentes sobre um componente.

get_one[[diffusers.ComponentsManager.get_one]]

get_one(component_id: str | None = None, name: str | None = None, collection: str | None = None, load_id: str | None = None)

Fonte

Parâmetros:

component_id (str | None) : ID de componente opcional para obter

name (str | None) : Nome ou padrão do componente

collection (str | None) : Coleção opcional para filtrar por

load_id (str | None) : load_id opcional para filtrar por

Retorna:

Um único componente

Exceções: ValueError

• ValueError -- Se nenhum componente corresponder ou se múltiplos componentes corresponderem

Obtenha um único componente por meio de:

• busca por nome (correspondência de padrão), coleção ou load_id.
• passando um component_id Gera um erro se vários componentes corresponderem ou nenhum for encontrado.

remover[[diffusers.ComponentsManager.remove]]

remove(component_id: str = None)

Fonte

Parâmetros:

component_id (str) : O ID do componente a ser removido

Remove um componente do ComponentsManager.

remove_from_collection[[diffusers.ComponentsManager.remove_from_collection]]

remove_from_collection(component_id: str, collection: str)

Fonte

Remove um componente de uma coleção.

search_components[[diffusers.ComponentsManager.search_components]]

search_components(names: str | None = None, collection: str | None = None, load_id: str | None = None, return_dict_with_names: bool = True)

Fonte

Parâmetros:

names : Nome(s) ou padrão(ões) dos componentes Padrões: - "unet" : corresponde a qualquer componente com nome base "unet" (ex.: unet_123abc) - "!unet" : tudo exceto componentes com nome base "unet" - "unet*" : qualquer coisa com nome base começando com "unet" - "!unet*" : qualquer coisa com nome base NÃO começando com "unet" - "unet" : qualquer coisa com nome base contendo "unet" - "!unet" : qualquer coisa com nome base NÃO contendo "unet" - "refiner|vae|unet" : qualquer coisa com nome base correspondendo exatamente a "refiner", "vae" ou "unet" - "!refiner|vae|unet" : qualquer coisa com nome base NÃO correspondendo exatamente a "refiner", "vae" ou "unet" - "unet*|vae*" : qualquer coisa com nome base começando com "unet" OU começando com "vae"

collection : Coleção opcional para filtrar por

load_id : load_id opcional para filtrar por

return_dict_with_names : Se True, retorna um dicionário com os nomes dos componentes como chaves, lança um erro se múltiplos componentes com o mesmo nome forem encontrados Se False, retorna um dicionário com os IDs dos componentes como chaves

Retorna:

Dicionário que mapeia nomes de componentes para componentes, se return_dict_with_names=True, ou um dicionário que mapeia IDs de componentes para componentes, se return_dict_with_names=False

Pesquise componentes por nome com correspondência de padrões simples. Opcionalmente, filtre por collection ou load_id.

set_offload_strategy[[diffusers.ComponentsManager.set_offload_strategy]]

set_offload_strategy(offload_strategy)

Fonte

Parâmetros:

offload_strategy : Qualquer função chamável com a assinatura (hooks, model_id, model, execution_device) -> hooks: ela recebe os hooks dos modelos atualmente no dispositivo e retorna os que devem ser descarregados antes que o modelo recebido seja carregado. O padrão é AutoOffloadStrategy, que libera a combinação mínima suficiente.

Substitua a estratégia de offload em todos os modelos gerenciados. Válido apenas quando o offload automático para CPU está habilitado.

InsertableDict[[diffusers.modular_pipelines.InsertableDict]]

diffusers.modular_pipelines.InsertableDict[[diffusers.modular_pipelines.InsertableDict]]

Fonte