# IP-Adapter

[IP-Adapter](https://hf.co/papers/2308.06721) é um adaptador leve que permite usar uma imagem como prompt para um modelo de difusão. Esse método desacopla as camadas de atenção cruzada dos recursos de imagem e texto. Os recursos de imagem são gerados a partir de um codificador de imagem.

> [!TIP]
> Aprenda a carregar e usar um checkpoint e uma imagem do IP-Adapter no guia [IP-Adapter](../../using-diffusers/ip_adapter).

## IPAdapterMixin[[diffusers.loaders.IPAdapterMixin]]

#### diffusers.loaders.IPAdapterMixin[[diffusers.loaders.IPAdapterMixin]]

```python
diffusers.loaders.IPAdapterMixin()
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/ip_adapter.py#L54)

Mixin para lidar com IP Adapters.

#### load_ip_adapter[[diffusers.loaders.IPAdapterMixin.load_ip_adapter]]

```python
load_ip_adapter(pretrained_model_name_or_path_or_dict: str | list[str] | dict[str, torch.Tensor], subfolder: str | list[str], weight_name: str | list[str], image_encoder_folder: str | None = 'image_encoder', **kwargs)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/ip_adapter.py#L57)

**Parâmetros:**

pretrained_model_name_or_path_or_dict (`str` ou `list[str]` ou `os.PathLike` ou `list[os.PathLike]` ou `dict` ou `list[dict]`) : Pode ser:  - Uma string, o *model id* (por exemplo `google/ddpm-celebahq-256`) de um modelo pré-treinado hospedado no Hub. - Um caminho para um *diretório* (por exemplo `./my_model_directory`) contendo os pesos do modelo salvos com [ModelMixin.save_pretrained()](/docs/diffusers/v0.43.0/pt/api/models/overview#diffusers.ModelMixin.save_pretrained). - Um [torch state dict](https://pytorch.org/tutorials/beginner/saving_loading_models.html#what-is-a-state-dict).

subfolder (`str` ou `list[str]`) : A localização da subpasta de um arquivo de modelo dentro de um repositório de modelo maior no Hub ou localmente. Se uma lista for passada, ela deve ter o mesmo comprimento que `weight_name`.

weight_name (`str` ou `list[str]`) : O nome do arquivo de pesos a ser carregado. Se uma lista for passada, ela deve ter o mesmo comprimento que `subfolder`.

image_encoder_folder (`str`, *opcional*, padrão `image_encoder`) : A localização da subpasta do codificador de imagem dentro de um repositório de modelo maior no Hub ou localmente. Passe `None` para não carregar o codificador de imagem. Se o codificador de imagem estiver localizado em uma pasta dentro de `subfolder`, você só precisa passar o nome da pasta que contém os pesos do codificador de imagem, por exemplo, `image_encoder_folder="image_encoder"`. Se o codificador de imagem estiver localizado em uma pasta diferente de `subfolder`, você deve passar o caminho para a pasta que contém os pesos do codificador de imagem, por exemplo, `image_encoder_folder="different_subfolder/image_encoder"`.

cache_dir (`str | os.PathLike`, *opcional*) : Caminho para um diretório onde a configuração de um modelo pré-treinado baixado é armazenada em cache, caso o cache padrão não seja utilizado.

force_download (`bool`, *opcional*, padrão `False`) : Se deve forçar o (re-)download dos pesos do modelo e dos arquivos de configuração, sobrescrevendo as versões em cache, caso existam.

proxies (`dict[str, str]`, *opcional*) : Um dicionário de servidores proxy a serem usados por protocolo ou endpoint, por exemplo, `{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}`. Os proxies são usados em cada solicitação.

local_files_only (`bool`, *opcional*, padrão `False`) : Se deve carregar apenas os pesos e os arquivos de configuração do modelo localmente ou não. Se definido como `True`, o modelo não será baixado do Hub.

token (`str` ou *bool*, *opcional*) : O token a ser usado como autorização HTTP bearer para arquivos remotos. Se `True`, o token gerado por `diffusers-cli login` (armazenado em `~/.huggingface`) é utilizado.

revision (`str`, *opcional*, padrão `"main"`) : A versão específica do modelo a ser usada. Pode ser o nome de um branch, o nome de uma tag, um id de commit ou qualquer identificador permitido pelo Git.

low_cpu_mem_usage (`bool`, *opcional*, padrão é `True` se a versão do torch >= 1.9.0, caso contrário `False`) : Acelera o carregamento do modelo carregando apenas os pesos pré-treinados e não inicializando os pesos. Isso também tenta não usar mais do que 1x o tamanho do modelo na memória de CPU (incluindo a memória de pico) durante o carregamento do modelo. Suportado apenas para PyTorch >= 1.9.0. Se você estiver usando uma versão mais antiga do PyTorch, definir este argumento como `True` causará um erro.

#### set_ip_adapter_scale[[diffusers.loaders.IPAdapterMixin.set_ip_adapter_scale]]

```python
set_ip_adapter_scale(scale)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/ip_adapter.py#L252)

Defina as escalas do IP-Adapter por bloco de transformer. A entrada `scale` pode ser uma única configuração ou uma lista de configurações para controle granular de cada comportamento do IP-Adapter. Uma configuração pode ser um float ou um dicionário.

Exemplo:

```py
# To use original IP-Adapter
scale = 1.0
pipeline.set_ip_adapter_scale(scale)

# To use style block only
scale = {
    "up": {"block_0": [0.0, 1.0, 0.0]},
}
pipeline.set_ip_adapter_scale(scale)

# To use style+layout blocks
scale = {
    "down": {"block_2": [0.0, 1.0]},
    "up": {"block_0": [0.0, 1.0, 0.0]},
}
pipeline.set_ip_adapter_scale(scale)

# To use style and layout from 2 reference images
scales = [{"down": {"block_2": [0.0, 1.0]}}, {"up": {"block_0": [0.0, 1.0, 0.0]}}]
pipeline.set_ip_adapter_scale(scales)
```

#### unload_ip_adapter[[diffusers.loaders.IPAdapterMixin.unload_ip_adapter]]

```python
unload_ip_adapter()
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/ip_adapter.py#L305)

Descarrega os pesos do IP Adapter

Exemplos:

```python
>>> # Assuming `pipeline` is already loaded with the IP Adapter weights.
>>> pipeline.unload_ip_adapter()
>>> ...
```

## SD3IPAdapterMixin[[diffusers.loaders.SD3IPAdapterMixin]]

#### diffusers.loaders.SD3IPAdapterMixin[[diffusers.loaders.SD3IPAdapterMixin]]

```python
diffusers.loaders.SD3IPAdapterMixin()
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/ip_adapter.py#L885)

Mixin para lidar com IP Adapters do StableDiffusion 3.

#### is_ip_adapter_active[[diffusers.loaders.SD3IPAdapterMixin.is_ip_adapter_active]]

```python
is_ip_adapter_active()
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/ip_adapter.py#L888)

**Retorna:** `bool`

Verdadeiro quando o IP-Adapter está carregado e qualquer camada tem scale > 0.

Verifica se o IP-Adapter está carregado e se scale > 0.

A escala do IP-Adapter controla a influência do prompt de imagem em relação ao prompt de texto. Quando esse valor é definido como 0, o contexto da imagem é irrelevante.

#### load_ip_adapter[[diffusers.loaders.SD3IPAdapterMixin.load_ip_adapter]]

```python
load_ip_adapter(pretrained_model_name_or_path_or_dict: str | dict[str, torch.Tensor], weight_name: str = 'ip-adapter.safetensors', subfolder: str | None = None, image_encoder_folder: str | None = 'image_encoder', **kwargs)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/ip_adapter.py#L906)

**Parâmetros:**

pretrained_model_name_or_path_or_dict (`str` ou `os.PathLike` ou `dict`) : Pode ser: - Uma string, o *model id* (por exemplo `google/ddpm-celebahq-256`) de um modelo pré-treinado hospedado no Hub. - Um caminho para um *diretório* (por exemplo `./my_model_directory`) contendo os pesos do modelo salvos com [ModelMixin.save_pretrained()](/docs/diffusers/v0.43.0/pt/api/models/overview#diffusers.ModelMixin.save_pretrained). - Um [torch state dict](https://pytorch.org/tutorials/beginner/saving_loading_models.html#what-is-a-state-dict).

weight_name (`str`, padrão "ip-adapter.safetensors") : O nome do arquivo de pesos a ser carregado. Se uma lista for passada, ela deve ter o mesmo comprimento que `subfolder`.

subfolder (`str`, *opcional*) : A localização da subpasta de um arquivo de modelo dentro de um repositório de modelo maior no Hub ou localmente. Se uma lista for passada, ela deve ter o mesmo comprimento que `weight_name`.

image_encoder_folder (`str`, *opcional*, padrão `image_encoder`) : A localização da subpasta do codificador de imagem dentro de um repositório de modelo maior no Hub ou localmente. Passe `None` para não carregar o codificador de imagem. Se o codificador de imagem estiver localizado em uma pasta dentro de `subfolder`, você só precisa passar o nome da pasta que contém os pesos do codificador de imagem, por exemplo, `image_encoder_folder="image_encoder"`. Se o codificador de imagem estiver localizado em uma pasta diferente de `subfolder`, você deve passar o caminho para a pasta que contém os pesos do codificador de imagem, por exemplo, `image_encoder_folder="different_subfolder/image_encoder"`.

cache_dir (`str | os.PathLike`, *opcional*) : Caminho para um diretório onde a configuração de um modelo pré-treinado baixado é armazenada em cache, caso o cache padrão não seja utilizado.

force_download (`bool`, *opcional*, padrão `False`) : Se deve forçar o (re-)download dos pesos do modelo e dos arquivos de configuração, sobrescrevendo as versões em cache, caso existam.

proxies (`dict[str, str]`, *opcional*) : Um dicionário de servidores proxy a serem usados por protocolo ou endpoint, por exemplo, `{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}`. Os proxies são usados em cada solicitação.

local_files_only (`bool`, *opcional*, padrão `False`) : Se deve carregar apenas os pesos e os arquivos de configuração do modelo localmente ou não. Se definido como `True`, o modelo não será baixado do Hub.

token (`str` ou *bool*, *opcional*) : O token a ser usado como autorização HTTP bearer para arquivos remotos. Se `True`, o token gerado por `diffusers-cli login` (armazenado em `~/.huggingface`) é utilizado.

revision (`str`, *opcional*, padrão `"main"`) : A versão específica do modelo a ser usada. Pode ser o nome de um branch, o nome de uma tag, um id de commit ou qualquer identificador permitido pelo Git.

low_cpu_mem_usage (`bool`, *opcional*, padrão é `True` se a versão do torch >= 1.9.0, caso contrário `False`) : Acelera o carregamento do modelo carregando apenas os pesos pré-treinados e não inicializando os pesos. Isso também tenta não usar mais do que 1x o tamanho do modelo na memória de CPU (incluindo a memória de pico) durante o carregamento do modelo. Suportado apenas para PyTorch >= 1.9.0. Se você estiver usando uma versão mais antiga do PyTorch, definir este argumento como `True` causará um erro.

#### set_ip_adapter_scale[[diffusers.loaders.SD3IPAdapterMixin.set_ip_adapter_scale]]

```python
set_ip_adapter_scale(scale: float)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/ip_adapter.py#L1054)

**Parâmetros:**

scale (float) : escala do IP-Adapter a ser definida.

Defina a escala do IP-Adapter, que controla o condicionamento do prompt de imagem. Um valor de 1.0 significa que o modelo é condicionado apenas pelo prompt de imagem, e 0.0 apenas pelo prompt de texto. Reduzir esse valor incentiva o modelo a produzir imagens mais diversas, mas elas podem não estar tão alinhadas com o prompt de imagem.

Exemplo:

```python
>>> # Assuming `pipeline` is already loaded with the IP Adapter weights.
>>> pipeline.set_ip_adapter_scale(0.6)
>>> ...
```

#### unload_ip_adapter[[diffusers.loaders.SD3IPAdapterMixin.unload_ip_adapter]]

```python
unload_ip_adapter()
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/ip_adapter.py#L1077)

Descarrega os pesos do IP Adapter.

Exemplo:

```python
>>> # Assuming `pipeline` is already loaded with the IP Adapter weights.
>>> pipeline.unload_ip_adapter()
>>> ...
```

## IPAdapterMaskProcessor[[diffusers.IPAdapterMaskProcessor]]

#### diffusers.IPAdapterMaskProcessor[[diffusers.IPAdapterMaskProcessor]]

```python
diffusers.IPAdapterMaskProcessor(do_resize: bool = True, vae_scale_factor: int = 8, resample: str = 'lanczos', do_normalize: bool = False, do_binarize: bool = True, do_convert_grayscale: bool = True)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/image_processor.py#L1277)

**Parâmetros:**

do_resize (`bool`, *opcional*, padrão `True`) : Se as dimensões (altura, largura) da imagem devem ser reduzidas para múltiplos de `vae_scale_factor`.

vae_scale_factor (`int`, *opcional*, padrão `8`) : Fator de escala do VAE. Se `do_resize` for `True`, a imagem será redimensionada automaticamente para múltiplos deste fator.

resample (`str`, *opcional*, padrão `lanczos`) : Filtro de reamostragem a ser usado ao redimensionar a imagem.

do_normalize (`bool`, *opcional*, padrão `False`) : Se normalizar a imagem para [-1,1].

do_binarize (`bool`, *opcional*, padrão `True`) : Se deve binarizar a imagem para 0/1.

do_convert_grayscale (`bool`, *opcional*, padrão é `True`) : Se as imagens devem ser convertidas para o formato de escala de cinza.

Processador de imagem para máscaras de imagem do IP Adapter.

#### downsample[[diffusers.IPAdapterMaskProcessor.downsample]]

```python
downsample(mask: Tensor, batch_size: int, num_queries: int, value_embed_dim: int)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/image_processor.py#L1318)

**Parâmetros:**

mask (`torch.Tensor`) : O tensor de máscara de entrada gerado com `IPAdapterMaskProcessor.preprocess()`.

batch_size (`int`) : O tamanho do lote.

num_queries (`int`) : O número de consultas.

value_embed_dim (`int`) : A dimensionalidade dos embeddings de valor.

**Retorna:** `torch.Tensor`

O tensor de máscara com amostragem reduzida.

Reduz a dimensão do tensor de máscara fornecido para corresponder às dimensões esperadas para a atenção de produto escalar. Se a proporção de aspecto da máscara não corresponder à proporção de aspecto da imagem de saída, um aviso é emitido.