Hugging Face's logo

Diffusers documentation

Flux2

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.42.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Flux2

LoRA MPS

Flux.2 é a série recente de modelos de geração de imagens da Black Forest Labs, antecedido pela série Flux.1. Trata-se de um modelo totalmente novo, com uma nova arquitetura e pré-treinamento realizado do zero!

Os checkpoints originais do modelo Flux podem ser encontrados aqui. O código de inferência original pode ser encontrado aqui.

Flux2 pode ser bastante caro de executar em dispositivos de hardware de consumo. No entanto, você pode realizar uma série de otimizações para executá-lo mais rápido e de uma forma mais amigável à memória. Consulte esta seção para mais detalhes. Além disso, o Flux pode se beneficiar da quantização para eficiência de memória, com um compromisso em relação à latência de inferência. Consulte este post de blog para saber mais.

Caching também pode acelerar a inferência ao armazenar e reutilizar saídas intermediárias.

Ampliação de resolução de legendas

Flux.2 pode potencialmente gerar saídas melhores com prompts melhores. Podemos “ampliar” um prompt de entrada definindo o argumento caption_upsample_temperature nos argumentos da chamada do pipeline. A implementação oficial recomenda que esse valor seja 0,15.

Flux2Pipeline

classe diffusers.Flux2Pipeline

< >

( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLFlux2text_encoder: Mistral3ForConditionalGenerationtokenizer: AutoProcessortransformer: Flux2Transformer2DModel )

Parâmetros

  • transformer (Flux2Transformer2DModel) — Arquitetura de Transformer condicional (MMDiT) para desruidar os latentes da imagem codificada.
  • scheduler (FlowMatchEulerDiscreteScheduler) — Um scheduler a ser usado em combinação com transformer para desruidar os latentes da imagem codificada.
  • vae (AutoencoderKLFlux2) — Modelo de Variational Auto-Encoder (VAE) para codificar e decodificar imagens para e a partir de representações latentes.
  • text_encoder (Mistral3ForConditionalGeneration) — Mistral3ForConditionalGeneration
  • tokenizer (AutoProcessor) — Tokenizer da classe PixtralProcessor.

O pipeline Flux2 para geração de imagens a partir de texto.

Referência: https://bfl.ai/blog/flux-2

__call__

< >

( image: PIL.Image.Image | list[PIL.Image.Image] | None = Noneprompt: str | list[str] = Noneheight: int | None = Nonewidth: int | None = Nonenum_inference_steps: int = 50sigmas: list[float] | None = Noneguidance_scale: float | None = 4.0num_images_per_prompt: int = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneoutput_type: str | None = 'pil'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list = ['latents']max_sequence_length: int = 512text_encoder_out_layers: tuple = (10, 20, 30)caption_upsample_temperature: float = None ) → ~pipelines.flux2.Flux2PipelineOutput or tuple

Parâmetros

  • image (torch.Tensor, PIL.Image.Image, np.ndarray, list[torch.Tensor], list[PIL.Image.Image] ou list[np.ndarray]) — Image, array numpy ou tensor representando um lote de imagens a ser usado como ponto de partida. Para arrays numpy e tensors pytorch, o intervalo de valores esperado é entre [0, 1] Se for um tensor ou uma lista de tensors, a forma esperada deve ser (B, C, H, W) ou (C, H, W). Se for um array numpy ou uma lista de arrays, a forma esperada deve ser (B, H, W, C) ou (H, W, C) Também pode aceitar latentes de imagem como image, mas, se latentes forem passados diretamente, eles não são codificados novamente.
  • prompt (str ou list[str], opcional) — O prompt ou os prompts para orientar a geração da imagem. Se não for definido, é necessário passar prompt_embeds em vez disso.
  • guidance_scale (float, opcional, padrão 1.0) — A escala de orientação incorporada é ativada ao definir guidance_scale > 1. Valores maiores de guidance_scale incentivam o modelo a gerar imagens mais alinhadas com o prompt em detrimento de uma menor qualidade de imagem.

    Modelos destilados por orientação aproximam a orientação livre de classe verdadeira para guidance_scale > 1. Consulte o artigo para saber mais.

  • height (int, opcional, padrão é self.unet.config.sample_size * self.vae_scale_factor) — A altura em pixels da imagem gerada. Isso é definido como 1024 por padrão para os melhores resultados.
  • width (int, opcional, padrão é self.unet.config.sample_size * self.vae_scale_factor) — A largura em pixels da imagem gerada. O padrão é 1024 para os melhores resultados.
  • num_inference_steps (int, opcional, padrão 50) — O número de etapas de desruidamento. Mais etapas de desruidamento geralmente resultam em uma imagem de maior qualidade, à custa de uma inferência mais lenta.
  • sigmas (list[float], opcional) — Sigmas personalizados para usar no processo de desruidamento com agendadores que suportam um argumento sigmas em seu método set_timesteps. Se não definido, o comportamento padrão quando num_inference_steps é passado será usado.
  • num_images_per_prompt (int, opcional, padrão 1) — O número de imagens a serem geradas por prompt.
  • generator (torch.Generator ou list[torch.Generator], opcional) — Um ou uma lista de geradores do torch para tornar a geração determinística.
  • latents (torch.Tensor, opcional) — Latentes ruidosos pré-gerados, amostrados de uma distribuição gaussiana, a serem usados como entradas para a geração de imagens. Pode ser usado para ajustar a mesma geração com diferentes prompts. Se não for fornecido, um tensor de latentes será gerado por amostragem usando o generator aleatório fornecido.
  • prompt_embeds (torch.Tensor, opcional) — Incorporações de texto pré-geradas. Podem ser usadas para ajustar facilmente as entradas de texto, por exemplo, ponderação de prompts. Se não forem fornecidas, as incorporações de texto serão geradas a partir do argumento de entrada prompt.
  • output_type (str, opcional, padrão "pil") — O formato de saída da imagem gerada. Escolha entre PIL: PIL.Image.Image ou np.array.
  • return_dict (bool, opcional, padrão True) — Se deve ou não retornar um ~pipelines.qwenimage.QwenImagePipelineOutput em vez de uma tupla simples.
  • attention_kwargs (dict, opcional) — Um dicionário de kwargs que, se especificado, é passado ao AttentionProcessor conforme definido em self.processor em diffusers.models.attention_processor.
  • callback_on_step_end (Callable, opcional) — Uma função que é chamada no final de cada etapa de desruidamento durante a inferência. A função é chamada com os seguintes argumentos: callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict). callback_kwargs incluirá uma lista de todos os tensores, conforme especificado por callback_on_step_end_tensor_inputs.
  • callback_on_step_end_tensor_inputs (List, opcional) — A lista de entradas de tensor para a função callback_on_step_end. Os tensores especificados na lista serão passados como argumento callback_kwargs. Você só poderá incluir variáveis listadas no atributo ._callback_tensor_inputs da sua classe de pipeline.
  • max_sequence_length (int padrão 512) — Comprimento máximo da sequência a ser usado com o prompt.
  • text_encoder_out_layers (tuple[int]) — Índices das camadas a serem usadas no text_encoder para derivar os embeddings finais do prompt.
  • caption_upsample_temperature (float) — Quando especificado, tentaremos realizar o upsampling de legendas para possíveis melhorias nas saídas. Recomendamos definir esse valor em 0.15 caso o upsampling de legendas seja realizado.

Retorna

~pipelines.flux2.Flux2PipelineOutput ou tuple

~pipelines.flux2.Flux2PipelineOutput se return_dict for True, caso contrário, uma tuple. Ao retornar uma tupla, o primeiro elemento é uma lista com as imagens geradas.

Função invocada ao chamar o pipeline para geração.

Exemplos:

>>> import torch
>>> from diffusers import Flux2Pipeline

>>> pipe = Flux2Pipeline.from_pretrained("black-forest-labs/FLUX.2-dev", torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")
>>> prompt = "A cat holding a sign that says hello world"
>>> # Depending on the variant being used, the pipeline call will slightly vary.
>>> # Refer to the pipeline documentation for more details.
>>> image = pipe(prompt, num_inference_steps=50, guidance_scale=2.5).images[0]
>>> image.save("flux.png")

Flux2KleinPipeline

classe diffusers.Flux2KleinPipeline

< >

( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLFlux2text_encoder: Qwen3ForCausalLMtokenizer: Qwen2Tokenizertransformer: Flux2Transformer2DModelis_distilled: bool = False )

Parâmetros

  • transformer (Flux2Transformer2DModel) — Arquitetura de Transformer condicional (MMDiT) para desruidar os latentes da imagem codificada.
  • scheduler (FlowMatchEulerDiscreteScheduler) — Um scheduler a ser usado em combinação com transformer para desruidar os latentes da imagem codificada.
  • vae (AutoencoderKLFlux2) — Modelo de Variational Auto-Encoder (VAE) para codificar e decodificar imagens para e a partir de representações latentes.
  • text_encoder (Qwen3ForCausalLM) — Qwen3ForCausalLM
  • tokenizer (Qwen2TokenizerFast) — Tokenizer da classe Qwen2TokenizerFast.

O pipeline Flux2 Klein para geração de imagens a partir de texto.

Referência: https://bfl.ai/blog/flux2-klein-towards-interactive-visual-intelligence

__call__

< >

( image: list[PIL.Image.Image] | PIL.Image.Image | None = Noneprompt: str | list[str] = Noneheight: int | None = Nonewidth: int | None = Nonenum_inference_steps: int = 50sigmas: list[float] | None = Noneguidance_scale: float = 4.0num_images_per_prompt: int = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: str | list[str] | None = Noneoutput_type: str = 'pil'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list = ['latents']max_sequence_length: int = 512text_encoder_out_layers: tuple = (9, 18, 27) ) → ~pipelines.flux2.Flux2PipelineOutput or tuple

Parâmetros

  • image (torch.Tensor, PIL.Image.Image, np.ndarray, List[torch.Tensor], List[PIL.Image.Image] ou List[np.ndarray]) — Image, array numpy ou tensor representando um lote de imagens a ser usado como ponto de partida. Para arrays numpy e tensors pytorch, o intervalo de valores esperado é entre [0, 1] Se for um tensor ou uma lista de tensors, a forma esperada deve ser (B, C, H, W) ou (C, H, W). Se for um array numpy ou uma lista de arrays, a forma esperada deve ser (B, H, W, C) ou (H, W, C) Também pode aceitar latentes de imagem como image, mas, se latentes forem passados diretamente, eles não são codificados novamente.
  • prompt (str ou List[str], opcional) — O prompt ou os prompts para orientar a geração da imagem. Se não for definido, é necessário passar prompt_embeds em vez disso.
  • guidance_scale (float, opcional, padrão 4.0) — Escala de orientação definida em Classifier-Free Diffusion Guidance. guidance_scale é definido como w da equação 2. do Imagen Paper. A escala de orientação é ativada ao definir guidance_scale > 1. Uma escala de orientação maior incentiva a geração de imagens que estão intimamente ligadas ao prompt de texto, geralmente em detrimento de uma menor qualidade de imagem. Para modelos destilados passo a passo, guidance_scale é ignorado.
  • height (int, opcional, padrão é self.unet.config.sample_size * self.vae_scale_factor) — A altura em pixels da imagem gerada. Isso é definido como 1024 por padrão para os melhores resultados.
  • width (int, opcional, padrão é self.unet.config.sample_size * self.vae_scale_factor) — A largura em pixels da imagem gerada. O padrão é 1024 para os melhores resultados.
  • num_inference_steps (int, opcional, padrão 50) — O número de etapas de desruidamento. Mais etapas de desruidamento geralmente resultam em uma imagem de maior qualidade, à custa de uma inferência mais lenta.
  • sigmas (List[float], opcional) — Sigmas personalizados para usar no processo de desruidamento com agendadores que suportam um argumento sigmas em seu método set_timesteps. Se não definido, o comportamento padrão quando num_inference_steps é passado será usado.
  • num_images_per_prompt (int, opcional, padrão 1) — O número de imagens a serem geradas por prompt.
  • generator (torch.Generator ou List[torch.Generator], opcional) — Um ou uma lista de geradores do torch para tornar a geração determinística.
  • latents (torch.Tensor, opcional) — Latentes ruidosos pré-gerados, amostrados de uma distribuição gaussiana, a serem usados como entradas para a geração de imagens. Pode ser usado para ajustar a mesma geração com diferentes prompts. Se não for fornecido, um tensor de latentes será gerado por amostragem usando o generator aleatório fornecido.
  • prompt_embeds (torch.Tensor, opcional) — Incorporações de texto pré-geradas. Podem ser usadas para ajustar facilmente as entradas de texto, por exemplo, ponderação de prompts. Se não forem fornecidas, as incorporações de texto serão geradas a partir do argumento de entrada prompt.
  • negative_prompt_embeds (torch.Tensor, opcional) — Incorporações de texto negativo pré-geradas. Observe que "" é usado como o prompt negativo neste pipeline. Se não for fornecido, será gerado a partir de "".
  • output_type (str, opcional, padrão "pil") — O formato de saída da imagem gerada. Escolha entre PIL: PIL.Image.Image ou np.array.
  • return_dict (bool, opcional, padrão True) — Se deve ou não retornar um ~pipelines.qwenimage.QwenImagePipelineOutput em vez de uma tupla simples.
  • attention_kwargs (dict, opcional) — Um dicionário de kwargs que, se especificado, é passado ao AttentionProcessor conforme definido em self.processor em diffusers.models.attention_processor.
  • callback_on_step_end (Callable, opcional) — Uma função que é chamada no final de cada etapa de desruidamento durante a inferência. A função é chamada com os seguintes argumentos: callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict). callback_kwargs incluirá uma lista de todos os tensores, conforme especificado por callback_on_step_end_tensor_inputs.
  • callback_on_step_end_tensor_inputs (List, opcional) — A lista de entradas de tensor para a função callback_on_step_end. Os tensores especificados na lista serão passados como argumento callback_kwargs. Você só poderá incluir variáveis listadas no atributo ._callback_tensor_inputs da sua classe de pipeline.
  • max_sequence_length (int padrão 512) — Comprimento máximo da sequência a ser usado com o prompt.
  • text_encoder_out_layers (tuple[int]) — Índices das camadas a serem usadas no text_encoder para derivar os embeddings finais do prompt.

Retorna

~pipelines.flux2.Flux2PipelineOutput ou tuple

~pipelines.flux2.Flux2PipelineOutput se return_dict for True, caso contrário, uma tuple. Ao retornar uma tupla, o primeiro elemento é uma lista com as imagens geradas.

Função invocada ao chamar o pipeline para geração.

Exemplos:

>>> import torch
>>> from diffusers import Flux2KleinPipeline

>>> pipe = Flux2KleinPipeline.from_pretrained(
...     "black-forest-labs/FLUX.2-klein-base-9B", torch_dtype=torch.bfloat16
... )
>>> pipe.to("cuda")
>>> prompt = "A cat holding a sign that says hello world"
>>> # Depending on the variant being used, the pipeline call will slightly vary.
>>> # Refer to the pipeline documentation for more details.
>>> image = pipe(prompt, num_inference_steps=50, guidance_scale=4.0).images[0]
>>> image.save("flux2_output.png")

Flux2KleinKVPipeline

classe diffusers.Flux2KleinKVPipeline

< >

( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLFlux2text_encoder: Qwen3ForCausalLMtokenizer: Qwen2Tokenizertransformer: Flux2Transformer2DModelis_distilled: bool = True )

Parâmetros

  • transformer (Flux2Transformer2DModel) — Arquitetura de Transformer condicional (MMDiT) para desruidar os latentes da imagem codificada.
  • scheduler (FlowMatchEulerDiscreteScheduler) — Um scheduler a ser usado em combinação com transformer para desruidar os latentes da imagem codificada.
  • vae (AutoencoderKLFlux2) — Modelo de Variational Auto-Encoder (VAE) para codificar e decodificar imagens para e a partir de representações latentes.
  • text_encoder (Qwen3ForCausalLM) — Qwen3ForCausalLM
  • tokenizer (Qwen2TokenizerFast) — Tokenizer da classe Qwen2TokenizerFast.

O pipeline Flux2 Klein KV para geração de texto para imagem com condicionamento de imagem de referência com cache de KV.

No primeiro passo de remoção de ruído, os tokens da imagem de referência são incluídos no passo de propagação direta e as projeções K/V de atenção deles são armazenadas em cache. Nos passos subsequentes, o cache K/V é reutilizado sem recálculo, proporcionando inferência mais rápida ao usar imagens de referência.

Referência: https://bfl.ai/blog/flux2-klein-towards-interactive-visual-intelligence

__call__

< >

( image: list[PIL.Image.Image] | PIL.Image.Image | None = Noneprompt: str | list[str] = Noneheight: int | None = Nonewidth: int | None = Nonenum_inference_steps: int = 4sigmas: list[float] | None = Nonenum_images_per_prompt: int = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneoutput_type: str = 'pil'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list = ['latents']max_sequence_length: int = 512text_encoder_out_layers: tuple = (9, 18, 27) )

Parâmetros

  • image (PIL.Image.Image ou List[PIL.Image.Image], opcional) — Imagem(ns) de referência para condicionamento. No primeiro passo de desruidamento, os tokens de referência são incluídos no passo de propagação direta e seus K/V de atenção são armazenados em cache. Nos passos subsequentes, os K/V em cache são reutilizados sem recalculá-los.
  • prompt (str ou List[str], opcional) — O prompt ou os prompts para orientar a geração da imagem.
  • height (int, opcional) — A altura em pixels da imagem gerada.
  • width (int, opcional) — A largura, em pixels, da imagem gerada.
  • num_inference_steps (int, opcional, padrão 4) — O número de etapas de remoção de ruído.
  • sigmas (List[float], opcional) — Sigmas personalizados para o agendamento de desruidamento.
  • num_images_per_prompt (int, opcional, padrão 1) — O número de imagens a serem geradas por prompt.
  • generator (torch.Generator ou List[torch.Generator], opcional) — Gerador(es) para geração determinística.
  • latents (torch.Tensor, opcional) — Latentes ruidosos pré-gerados.
  • prompt_embeds (torch.Tensor, opcional) — Incorporações de texto pré-geradas.
  • output_type (str, opcional, padrão "pil") — Formato de saída: "pil" ou "np".
  • return_dict (bool, opcional, padrão True) — Se deve retornar um Flux2PipelineOutput ou uma tupla simples.
  • attention_kwargs (dict, opcional) — Kwargs extras passados aos processadores de atenção.
  • callback_on_step_end (Callable, opcional) — Função de callback chamada no final de cada etapa de desruidamento.
  • callback_on_step_end_tensor_inputs (List, opcional) — Entradas de tensor para a função de callback.
  • max_sequence_length (int, padrão 512) — Comprimento máximo da sequência para o prompt.
  • text_encoder_out_layers (tuple[int]) — Índices das camadas para extração do estado oculto do codificador de texto.

Função invocada ao chamar o pipeline para geração.

Exemplos:

>>> import torch
>>> from PIL import Image
>>> from diffusers import Flux2KleinKVPipeline

>>> pipe = Flux2KleinKVPipeline.from_pretrained(
...     "black-forest-labs/FLUX.2-klein-9b-kv", torch_dtype=torch.bfloat16
... )
>>> pipe.to("cuda")
>>> ref_image = Image.open("reference.png")
>>> image = pipe("A cat dressed like a wizard", image=ref_image, num_inference_steps=4).images[0]
>>> image.save("flux2_kv_output.png")
Update on GitHub

←Flux Flux3→