diffusers/main/pt/api/loaders/ip_adapter.md

IP-Adapter

IP-Adapter é 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.

Aprenda a carregar e usar um checkpoint e uma imagem do IP-Adapter no guia IP-Adapter.

IPAdapterMixin[[diffusers.loaders.IPAdapterMixin]]

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

diffusers.loaders.IPAdapterMixin()

Fonte

Mixin para lidar com IP Adapters.

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

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

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(). - Um torch 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]]

set_ip_adapter_scale(scale)

Fonte

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:

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

unload_ip_adapter()

Fonte

Descarrega os pesos do IP Adapter

Exemplos:

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

SD3IPAdapterMixin[[diffusers.loaders.SD3IPAdapterMixin]]

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

diffusers.loaders.SD3IPAdapterMixin()

Fonte

Mixin para lidar com IP Adapters do StableDiffusion 3.

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

is_ip_adapter_active()

Fonte

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

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

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(). - Um torch 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]]

set_ip_adapter_scale(scale: float)

Fonte

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:

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

unload_ip_adapter()

Fonte

Descarrega os pesos do IP Adapter.

Exemplo:

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

IPAdapterMaskProcessor[[diffusers.IPAdapterMaskProcessor]]

diffusers.IPAdapterMaskProcessor[[diffusers.IPAdapterMaskProcessor]]

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

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

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

Fonte

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.