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 es la serie reciente de modelos de generación de imágenes de Black Forest Labs, precedida por la serie Flux.1. Es un modelo completamente nuevo con una nueva arquitectura y un preentrenamiento realizado desde cero.

Los puntos de control originales del modelo Flux se pueden encontrar aquí. El código de inferencia original se puede encontrar aquí.

Flux2 puede resultar bastante costoso de ejecutar en dispositivos de hardware de consumo. Sin embargo, puedes aplicar una serie de optimizaciones para ejecutarlo más rápido y de una manera más eficiente en memoria. Consulta esta sección para obtener más detalles. Además, Flux puede beneficiarse de la cuantización para mejorar la eficiencia de memoria, a cambio de un aumento en la latencia de inferencia. Consulta esta publicación de blog para saber más.

La caché también puede acelerar la inferencia almacenando y reutilizando salidas intermedias.

Ampliación de la resolución de las descripciones

Flux.2 puede generar salidas de mejor calidad con mejores prompts. Podemos “ampliar” un prompt de entrada estableciendo el argumento caption_upsample_temperature en los argumentos de la llamada a la pipeline. La implementación oficial recomienda que este valor sea 0.15.

Flux2Pipeline

clase diffusers.Flux2Pipeline

< >

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

Parámetros

  • transformer (Flux2Transformer2DModel) — Arquitectura de Transformer condicional (MMDiT) para desruidar los latentes de imagen codificados.
  • scheduler (FlowMatchEulerDiscreteScheduler) — Un scheduler para usar en combinación con transformer para desruidar los latentes de imagen codificados.
  • vae (AutoencoderKLFlux2) — Modelo de Variational Auto-Encoder (VAE) para codificar y decodificar imágenes a partir de y hacia representaciones latentes.
  • text_encoder (Mistral3ForConditionalGeneration) — Mistral3ForConditionalGeneration
  • tokenizer (AutoProcessor) — Tokenizador de la clase PixtralProcessor.

El pipeline Flux2 para la generación de imágenes a partir de texto.

Referencia: 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] o list[np.ndarray]) — Image, array de numpy o tensor que representa un lote de imágenes para usarse como punto de partida. Tanto para arrays de numpy como para tensors de pytorch, el rango de valores esperado está entre [0, 1] Si es un tensor o una lista de tensors, la forma esperada debe ser (B, C, H, W) o (C, H, W). Si es un array de numpy o una lista de arrays, la forma esperada debe ser (B, H, W, C) o (H, W, C) También puede aceptar latentes de imagen como image, pero si se pasan latentes directamente, no se vuelven a codificar.
  • prompt (str o list[str], opcional) — El prompt o los prompts para guiar la generación de la imagen. Si no se define, hay que pasar prompt_embeds en su lugar.
  • guidance_scale (float, opcional, con un valor predeterminado de 1.0) — La escala de guía integrada se habilita al establecer guidance_scale > 1. valores más altos de guidance_scale animan al modelo a generar imágenes más alineadas con la prompt , a costa de una menor calidad de imagen.

    Los modelos destilados con guía aproximan la guía libre de clase real para guidance_scale > 1. Consulte el artículo para obtener más información.

  • height (int, opcional, por defecto self.unet.config.sample_size * self.vae_scale_factor) — La altura en píxeles de la imagen generada. Por defecto, se establece en 1024 para obtener los mejores resultados.
  • width (int, opcional, valor predeterminado self.unet.config.sample_size * self.vae_scale_factor) — El ancho en píxeles de la imagen generada. Por defecto, se establece en 1024 para obtener los mejores resultados.
  • num_inference_steps (int, opcional, valor predeterminado 50) — El número de pasos de desruido. Más pasos de desruido suelen conducir a una imagen de mayor calidad a costa de una inferencia más lenta.
  • sigmas (list[float], opcional) — Sigmas personalizados para usar en el proceso de desruido con programadores que admiten un argumento sigmas en su método set_timesteps. Si no se define, se usará el comportamiento predeterminado cuando se pase num_inference_steps.
  • num_images_per_prompt (int, opcional, valor predeterminado 1) — El número de imágenes que se generarán por indicación.
  • generator (torch.Generator o list[torch.Generator], opcional) — Un generador o una lista de generadores de torch para hacer la generación determinista.
  • latents (torch.Tensor, opcional) — Latentes ruidosos pregenerados, muestreados de una distribución gaussiana, que se usarán como entradas para la generación de imágenes. Se pueden utilizar para ajustar la misma generación con diferentes prompts. Si no se proporcionan, se generará un tensor de latentes mediante muestreo usando el generator aleatorio suministrado.
  • prompt_embeds (torch.Tensor, opcional) — Incrustaciones de texto pregeneradas. Se pueden usar para ajustar fácilmente las entradas de texto, p. ej. ponderación de prompts. Si no se proporcionan, las incrustaciones de texto se generarán a partir del argumento de entrada prompt.
  • output_type (str, opcional, valor predeterminado "pil") — El formato de salida de la imagen generada. Elija entre PIL: PIL.Image.Image o np.array.
  • return_dict (bool, opcional, valor predeterminado True) — Indica si se debe devolver un ~pipelines.qwenimage.QwenImagePipelineOutput en lugar de una tupla simple.
  • attention_kwargs (dict, opcional) — Un diccionario de kwargs que, si se especifica, se pasa al AttentionProcessor definido en self.processor dentro de diffusers.models.attention_processor.
  • callback_on_step_end (Callable, opcional) — Una función que se llama al final de cada paso de desruido durante la inferencia. La función se llama con los siguientes argumentos: callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict). callback_kwargs incluirá una lista de todos los tensores especificados por callback_on_step_end_tensor_inputs.
  • callback_on_step_end_tensor_inputs (List, opcional) — La lista de entradas de tensor para la función callback_on_step_end. Los tensores especificados en la lista se pasarán como argumento callback_kwargs. Solo podrá incluir variables listadas en el atributo ._callback_tensor_inputs de su clase de pipeline.
  • max_sequence_length (int por defecto 512) — Longitud máxima de la secuencia para usar con el prompt.
  • text_encoder_out_layers (tuple[int]) — Índices de capas a utilizar en el text_encoder para derivar las incrustaciones finales del prompt.
  • caption_upsample_temperature (float) — Si se especifica, intentaremos realizar un aumento de muestreo de la descripción para obtener posibles mejoras en las salidas. Recomendamos establecerlo en 0.15 si se va a realizar el aumento de muestreo de la descripción.

Devuelve

~pipelines.flux2.Flux2PipelineOutput o tuple

~pipelines.flux2.Flux2PipelineOutput si return_dict es True, de lo contrario una tuple. Al devolver una tupla, el primer elemento es una lista con las imágenes generadas.

Función invocada al llamar a la pipeline para la generación.

Ejemplos:

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

clase diffusers.Flux2KleinPipeline

< >

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

Parámetros

  • transformer (Flux2Transformer2DModel) — Arquitectura de Transformer condicional (MMDiT) para desruidar los latentes de imagen codificados.
  • scheduler (FlowMatchEulerDiscreteScheduler) — Un scheduler para usar en combinación con transformer para desruidar los latentes de imagen codificados.
  • vae (AutoencoderKLFlux2) — Modelo de Variational Auto-Encoder (VAE) para codificar y decodificar imágenes a partir de y hacia representaciones latentes.
  • text_encoder (Qwen3ForCausalLM) — Qwen3ForCausalLM
  • tokenizer (Qwen2TokenizerFast) — Tokenizer de la clase Qwen2TokenizerFast.

El pipeline Flux2 Klein para la generación de imágenes a partir de texto.

Referencia: 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] o List[np.ndarray]) — Image, array de numpy o tensor que representa un lote de imágenes para usar como punto de partida. Tanto para arrays de numpy como para tensors de pytorch, el rango de valores esperado está entre [0, 1] Si es un tensor o una lista de tensors, la forma esperada debe ser (B, C, H, W) o (C, H, W). Si es un array de numpy o una lista de arrays, la forma esperada debe ser (B, H, W, C) o (H, W, C) También puede aceptar latentes de imagen como image, pero si se pasan latentes directamente, no se vuelven a codificar.
  • prompt (str o List[str], opcional) — El prompt o los prompts para guiar la generación de la imagen. Si no se define, hay que pasar prompt_embeds en su lugar.
  • guidance_scale (float, opcional, valor predeterminado 4.0) — Escala de guía definida en Classifier-Free Diffusion Guidance. guidance_scale se define como w de la ecuación 2 de Imagen Paper. La escala de guía se habilita estableciendo guidance_scale > 1. Una escala de guía más alta fomenta la generación de imágenes estrechamente vinculadas al prompt de texto, generalmente a costa de una menor calidad de imagen. Para los modelos destilados paso a paso, guidance_scale se ignora.
  • height (int, opcional, por defecto self.unet.config.sample_size * self.vae_scale_factor) — La altura en píxeles de la imagen generada. Por defecto, se establece en 1024 para obtener los mejores resultados.
  • width (int, opcional, valor predeterminado self.unet.config.sample_size * self.vae_scale_factor) — El ancho en píxeles de la imagen generada. Por defecto, se establece en 1024 para obtener los mejores resultados.
  • num_inference_steps (int, opcional, valor predeterminado 50) — El número de pasos de desruido. Más pasos de desruido suelen conducir a una imagen de mayor calidad a costa de una inferencia más lenta.
  • sigmas (List[float], opcional) — Sigmas personalizados para usar en el proceso de desruido con programadores que admiten un argumento sigmas en su método set_timesteps. Si no se define, se usará el comportamiento predeterminado cuando se pase num_inference_steps.
  • num_images_per_prompt (int, opcional, valor predeterminado 1) — El número de imágenes que se generarán por indicación.
  • generator (torch.Generator o List[torch.Generator], opcional) — Uno o una lista de generadores de torch para hacer la generación determinista.
  • latents (torch.Tensor, opcional) — Latentes ruidosos pregenerados, muestreados de una distribución gaussiana, que se usarán como entradas para la generación de imágenes. Se pueden utilizar para ajustar la misma generación con diferentes prompts. Si no se proporcionan, se generará un tensor de latentes mediante muestreo usando el generator aleatorio suministrado.
  • prompt_embeds (torch.Tensor, opcional) — Incrustaciones de texto pregeneradas. Se pueden usar para ajustar fácilmente las entradas de texto, p. ej. ponderación de prompts. Si no se proporcionan, las incrustaciones de texto se generarán a partir del argumento de entrada prompt.
  • negative_prompt_embeds (torch.Tensor, opcional) — Incrustaciones de texto negativo pregeneradas. Tenga en cuenta que "" se utiliza como el prompt negativo en este pipeline. Si no se proporciona, se generará a partir de "".
  • output_type (str, opcional, valor predeterminado "pil") — El formato de salida de la imagen generada. Elija entre PIL: PIL.Image.Image o np.array.
  • return_dict (bool, opcional, valor predeterminado True) — Indica si se debe devolver un ~pipelines.qwenimage.QwenImagePipelineOutput en lugar de una tupla simple.
  • attention_kwargs (dict, opcional) — Un diccionario de kwargs que, si se especifica, se pasa al AttentionProcessor definido en self.processor dentro de diffusers.models.attention_processor.
  • callback_on_step_end (Callable, opcional) — Una función que se llama al final de cada paso de desruido durante la inferencia. La función se llama con los siguientes argumentos: callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict). callback_kwargs incluirá una lista de todos los tensores especificados por callback_on_step_end_tensor_inputs.
  • callback_on_step_end_tensor_inputs (List, opcional) — La lista de entradas de tensor para la función callback_on_step_end. Los tensores especificados en la lista se pasarán como argumento callback_kwargs. Solo podrá incluir variables listadas en el atributo ._callback_tensor_inputs de su clase de pipeline.
  • max_sequence_length (int por defecto 512) — Longitud máxima de la secuencia para usar con el prompt.
  • text_encoder_out_layers (tuple[int]) — Índices de capas a utilizar en el text_encoder para derivar las incrustaciones finales del prompt.

Devuelve

~pipelines.flux2.Flux2PipelineOutput o tuple

~pipelines.flux2.Flux2PipelineOutput si return_dict es True, de lo contrario una tuple. Al devolver una tupla, el primer elemento es una lista con las imágenes generadas.

Función invocada al llamar a la pipeline para la generación.

Ejemplos:

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

clase diffusers.Flux2KleinKVPipeline

< >

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

Parámetros

  • transformer (Flux2Transformer2DModel) — Arquitectura de Transformer condicional (MMDiT) para desruidar los latentes de imagen codificados.
  • scheduler (FlowMatchEulerDiscreteScheduler) — Un scheduler para usar en combinación con transformer para desruidar los latentes de imagen codificados.
  • vae (AutoencoderKLFlux2) — Modelo de Variational Auto-Encoder (VAE) para codificar y decodificar imágenes a partir de y hacia representaciones latentes.
  • text_encoder (Qwen3ForCausalLM) — Qwen3ForCausalLM
  • tokenizer (Qwen2TokenizerFast) — Tokenizer de la clase Qwen2TokenizerFast.

El pipeline Flux2 Klein KV para la generación de imágenes a partir de texto con condicionamiento de imagen de referencia mediante caché de KV.

En el primer paso de desruido, los tokens de la imagen de referencia se incluyen en la pasada hacia adelante y sus proyecciones K/V de atención se almacenan en caché. En los pasos posteriores, las K/V en caché se reutilizan sin recalcular, lo que proporciona una inferencia más rápida al usar imágenes de referencia.

Referencia: 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 o List[PIL.Image.Image], opcional) — Imagen(es) de referencia para el condicionamiento. En el primer paso de desruido, los tokens de referencia se incluyen en la pasada hacia adelante y sus K/V de atención se almacenan en caché. En los pasos posteriores, los K/V en caché se reutilizan sin recalcularlos.
  • prompt (str o List[str], opcional) — El prompt o los prompts para guiar la generación de la imagen.
  • height (int, opcional) — La altura en píxeles de la imagen generada.
  • width (int, opcional) — El ancho en píxeles de la imagen generada.
  • num_inference_steps (int, opcional, valor predeterminado 4) — El número de pasos de desruido.
  • sigmas (List[float], opcional) — Sigmas personalizados para el programa de desruido.
  • num_images_per_prompt (int, opcional, valor predeterminado 1) — El número de imágenes que se generarán por indicación.
  • generator (torch.Generator o List[torch.Generator], opcional) — Generador(es) para la generación determinista.
  • latents (torch.Tensor, opcional) — Latentes ruidosos pregenerados.
  • prompt_embeds (torch.Tensor, opcional) — Incrustaciones de texto pregeneradas.
  • output_type (str, opcional, por defecto "pil") — Formato de salida: "pil" o "np".
  • return_dict (bool, opcional, valor predeterminado True) — Si se devuelve un Flux2PipelineOutput o una tupla simple.
  • attention_kwargs (dict, opcional) — Kwargs adicionales pasados a los procesadores de atención.
  • callback_on_step_end (Callable, opcional) — Función de callback que se llama al final de cada paso de desruido.
  • callback_on_step_end_tensor_inputs (List, opcional) — Entradas de tensor para la función de callback.
  • max_sequence_length (int, por defecto 512) — Longitud máxima de la secuencia para el prompt.
  • text_encoder_out_layers (tuple[int]) — Índices de capas para la extracción del estado oculto del codificador de texto.

Función invocada al llamar a la pipeline para la generación.

Ejemplos:

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