# Componentes e configurações

## ComponentSpec[[diffusers.ComponentSpec]]

#### diffusers.ComponentSpec[[diffusers.ComponentSpec]]

```python
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](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/modular_pipeline_utils.py#L98)

**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]]

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

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/modular_pipeline_utils.py#L267)

Crie o componente usando from_config com config.

#### decode_load_id[[diffusers.ComponentSpec.decode_load_id]]

```python
decode_load_id(load_id: str)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/modular_pipeline_utils.py#L228)

**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]]

```python
from_component(name: str, component: Any)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/modular_pipeline_utils.py#L149)

**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]]

```python
load(**kwargs)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/modular_pipeline_utils.py#L295)

Carregue o componente usando from_pretrained.

#### loading_fields[[diffusers.ComponentSpec.loading_fields]]

```python
loading_fields()
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/modular_pipeline_utils.py#L209)

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]]

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

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/modular_pipeline_utils.py#L360)

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

## ComponentsManager[[diffusers.ComponentsManager]]

#### diffusers.ComponentsManager[[diffusers.ComponentsManager]]

```python
diffusers.ComponentsManager()
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/components_manager.py#L296)

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

[ComponentsManager](/docs/diffusers/main/pt/api/modular_diffusers/pipeline_components#diffusers.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.

> [!WARNING] > Este é um recurso experimental e provavelmente mudará no futuro.

Exemplo:
```python
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]]

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

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/components_manager.py#L393)

**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]]

```python
disable_auto_cpu_offload()
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/components_manager.py#L795)

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

#### enable_auto_cpu_offload[[diffusers.ComponentsManager.enable_auto_cpu_offload]]

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

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/components_manager.py#L701)

**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]]

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

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/components_manager.py#L1104)

**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]]

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

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/components_manager.py#L1137)

**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]]

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

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/components_manager.py#L1086)

**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]]

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

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/components_manager.py#L812)

**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]]

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

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/components_manager.py#L1041)

**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]]

```python
remove(component_id: str = None)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/components_manager.py#L485)

**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]]

```python
remove_from_collection(component_id: str, collection: str)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/components_manager.py#L467)

Remove um componente de uma coleção.

#### search_components[[diffusers.ComponentsManager.search_components]]

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

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/components_manager.py#L515)

**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]]

```python
set_offload_strategy(offload_strategy)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/components_manager.py#L779)

**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](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/modular_pipeline_utils.py#L60)