Hugging Face's logo

Diffusers documentation

Framepack

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Framepack

LoRA

Empaquetado del contexto de fotogramas de entrada en modelos de predicción del siguiente fotograma para la generación de video de Lvmin Zhang y Maneesh Agrawala.

Presentamos una estructura de red neuronal, FramePack, para entrenar modelos de predicción del siguiente fotograma (o de la siguiente sección de fotograma) para la generación de video. FramePack comprime los fotogramas de entrada para que la longitud de contexto del transformer sea un número fijo, independientemente de la duración del video. Como resultado, podemos procesar un gran número de fotogramas utilizando difusión de video con un cuello de botella de cómputo similar al de la difusión de imágenes. Esto también permite que los tamaños de lote de entrenamiento de video sean significativamente mayores (los tamaños de lote se vuelven comparables a los del entrenamiento de difusión de imágenes). También proponemos un método de muestreo anti-deslizamiento que genera fotogramas en orden temporal inverso con puntos finales establecidos de antemano para evitar el sesgo de exposición (acumulación de errores a lo largo de las iteraciones). Finalmente, demostramos que los modelos de difusión de video existentes pueden ser afinados con FramePack, y su calidad visual puede mejorar porque la predicción del siguiente fotograma admite programadores de difusión más equilibrados con pasos de tiempo de desplazamiento de flujo menos extremos.

Asegúrate de consultar la guía de Schedulers para aprender a explorar el equilibrio entre la velocidad y la calidad del scheduler, y consulta la sección reutilizar componentes entre pipelines para aprender a cargar eficientemente los mismos componentes en múltiples pipelines.

Modelos disponibles

Nombre del modeloDescripción
- lllyasviel/FramePackI2V_HYEntrenado con la estrategia de “inverted anti-drifting” descrita en el artículo. Para la inferencia, es necesario establecer sampling_type="inverted_anti_drifting" al ejecutar el pipeline.
- lllyasviel/FramePack_F1_I2V_HY_20250503Entrenado con una estrategia novedosa de anti-deriva, pero la inferencia se realiza con la estrategia “vanilla” tal como se describe en el artículo. La inferencia requiere establecer sampling_type="vanilla" al ejecutar el pipeline.

Uso

Consulte la documentación de la pipeline para ejemplos básicos de uso. La siguiente sección contiene ejemplos de offloading, diferentes métodos de muestreo, cuantización y más.

Primer y último fotograma a video

El siguiente ejemplo muestra cómo usar Framepack con controles de imagen de inicio y final, utilizando el modelo de muestreo anti-drifiting invertido.

import torch
from diffusers import HunyuanVideoFramepackPipeline, HunyuanVideoFramepackTransformer3DModel
from diffusers.utils import export_to_video, load_image
from transformers import SiglipImageProcessor, SiglipVisionModel

transformer = HunyuanVideoFramepackTransformer3DModel.from_pretrained(
    "lllyasviel/FramePackI2V_HY", dtype=torch.bfloat16
)
feature_extractor = SiglipImageProcessor.from_pretrained(
    "lllyasviel/flux_redux_bfl", subfolder="feature_extractor"
)
image_encoder = SiglipVisionModel.from_pretrained(
    "lllyasviel/flux_redux_bfl", subfolder="image_encoder", dtype=torch.float16
)
pipe = HunyuanVideoFramepackPipeline.from_pretrained(
    "hunyuanvideo-community/HunyuanVideo",
    transformer=transformer,
    feature_extractor=feature_extractor,
    image_encoder=image_encoder,
    dtype=torch.float16,
)

# Enable memory optimizations
pipe.enable_model_cpu_offload()
pipe.vae.enable_tiling()

prompt = "CG animation style, a small blue bird takes off from the ground, flapping its wings. The bird's feathers are delicate, with a unique pattern on its chest. The background shows a blue sky with white clouds under bright sunshine. The camera follows the bird upward, capturing its flight and the vastness of the sky from a close-up, low-angle perspective."
first_image = load_image(
    "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/flf2v_input_first_frame.png"
)
last_image = load_image(
    "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/flf2v_input_last_frame.png"
)
output = pipe(
    image=first_image,
    last_image=last_image,
    prompt=prompt,
    height=512,
    width=512,
    num_frames=91,
    num_inference_steps=30,
    guidance_scale=9.0,
    generator=torch.Generator().manual_seed(0),
    sampling_type="inverted_anti_drifting",
).frames[0]
export_to_video(output, "output.mp4", fps=30)

Muestreo simple

El siguiente ejemplo muestra cómo usar Framepack con el modelo F1 entrenado con muestreo vanilla pero con un nuevo enfoque de regulación para evitar el desplazamiento.

import torch
from diffusers import HunyuanVideoFramepackPipeline, HunyuanVideoFramepackTransformer3DModel
from diffusers.utils import export_to_video, load_image
from transformers import SiglipImageProcessor, SiglipVisionModel

transformer = HunyuanVideoFramepackTransformer3DModel.from_pretrained(
    "lllyasviel/FramePack_F1_I2V_HY_20250503", dtype=torch.bfloat16
)
feature_extractor = SiglipImageProcessor.from_pretrained(
    "lllyasviel/flux_redux_bfl", subfolder="feature_extractor"
)
image_encoder = SiglipVisionModel.from_pretrained(
    "lllyasviel/flux_redux_bfl", subfolder="image_encoder", dtype=torch.float16
)
pipe = HunyuanVideoFramepackPipeline.from_pretrained(
    "hunyuanvideo-community/HunyuanVideo",
    transformer=transformer,
    feature_extractor=feature_extractor,
    image_encoder=image_encoder,
    dtype=torch.float16,
)

# Enable memory optimizations
pipe.enable_model_cpu_offload()
pipe.vae.enable_tiling()

image = load_image(
    "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/penguin.png"
)
output = pipe(
    image=image,
    prompt="A penguin dancing in the snow",
    height=832,
    width=480,
    num_frames=91,
    num_inference_steps=30,
    guidance_scale=9.0,
    generator=torch.Generator().manual_seed(0),
    sampling_type="vanilla",
).frames[0]
export_to_video(output, "output.mp4", fps=30)

Descarga de grupos

El descargado por grupos (apply_group_offloading()) ofrece optimizaciones agresivas de memoria para descargar partes internas de cualquier modelo a la CPU, posiblemente sin un sobrecoste adicional en el tiempo de generación. Si dispone de muy poca VRAM disponible, este enfoque puede ser adecuado para usted, dependiendo de la cantidad de RAM de CPU disponible.

import torch
from diffusers import HunyuanVideoFramepackPipeline, HunyuanVideoFramepackTransformer3DModel
from diffusers.hooks import apply_group_offloading
from diffusers.utils import export_to_video, load_image
from transformers import SiglipImageProcessor, SiglipVisionModel

transformer = HunyuanVideoFramepackTransformer3DModel.from_pretrained(
    "lllyasviel/FramePack_F1_I2V_HY_20250503", dtype=torch.bfloat16
)
feature_extractor = SiglipImageProcessor.from_pretrained(
    "lllyasviel/flux_redux_bfl", subfolder="feature_extractor"
)
image_encoder = SiglipVisionModel.from_pretrained(
    "lllyasviel/flux_redux_bfl", subfolder="image_encoder", dtype=torch.float16
)
pipe = HunyuanVideoFramepackPipeline.from_pretrained(
    "hunyuanvideo-community/HunyuanVideo",
    transformer=transformer,
    feature_extractor=feature_extractor,
    image_encoder=image_encoder,
    dtype=torch.float16,
)

# Enable group offloading
onload_device = torch.device("cuda")
offload_device = torch.device("cpu")
list(map(
    lambda x: apply_group_offloading(x, onload_device, offload_device, offload_type="leaf_level", use_stream=True, low_cpu_mem_usage=True),
    [pipe.text_encoder, pipe.text_encoder_2, pipe.transformer]
))
pipe.image_encoder.to(onload_device)
pipe.vae.to(onload_device)
pipe.vae.enable_tiling()

image = load_image(
    "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/penguin.png"
)
output = pipe(
    image=image,
    prompt="A penguin dancing in the snow",
    height=832,
    width=480,
    num_frames=91,
    num_inference_steps=30,
    guidance_scale=9.0,
    generator=torch.Generator().manual_seed(0),
    sampling_type="vanilla",
).frames[0]
print(f"Max memory: {torch.cuda.max_memory_allocated() / 1024**3:.3f} GB")
export_to_video(output, "output.mp4", fps=30)

HunyuanVideoFramepackPipeline

clase diffusers.HunyuanVideoFramepackPipeline

< >

( text_encoder: LlamaModeltokenizer: LlamaTokenizertransformer: HunyuanVideoFramepackTransformer3DModelvae: AutoencoderKLHunyuanVideoscheduler: FlowMatchEulerDiscreteSchedulertext_encoder_2: CLIPTextModeltokenizer_2: CLIPTokenizerimage_encoder: SiglipVisionModelfeature_extractor: SiglipImageProcessorPil )

Parámetros

Pipeline para la generación de texto a video usando HunyuanVideo.

Este modelo hereda de DiffusionPipeline. Consulta la documentación de la clase superior para los métodos genéricos implementados en todas las tuberías (descarga, guardado, ejecución en un dispositivo específico, etc.).

__call__

< >

( image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]last_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = Noneprompt: str | list[str] = Noneprompt_2: str | list[str] = Nonenegative_prompt: str | list[str] = Nonenegative_prompt_2: str | list[str] = Noneheight: int = 720width: int = 1280num_frames: int = 129latent_window_size: int = 9num_inference_steps: int = 50sigmas: list[float] = Nonetrue_cfg_scale: float = 1.0guidance_scale: float = 6.0num_videos_per_prompt: int | None = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Noneimage_latents: typing.Optional[torch.Tensor] = Nonelast_image_latents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Nonepooled_prompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_pooled_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_attention_mask: typing.Optional[torch.Tensor] = Noneoutput_type: str | None = 'pil'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Union[typing.Callable[[int, int], NoneType], diffusers.callbacks.PipelineCallback, diffusers.callbacks.MultiPipelineCallbacks, NoneType] = Nonecallback_on_step_end_tensor_inputs: list[str] = ['latents']prompt_template: dict[str, typing.Any] = {'template': '<|start_header_id|>system<|end_header_id|>\n\nDescribe the video by detailing the following aspects: 1. The main content and theme of the video.2. The color, shape, size, texture, quantity, text, and spatial relationships of the objects.3. Actions, events, behaviors temporal relationships, physical movement changes of the objects.4. background environment, light, style and atmosphere.5. camera angles, movements, and transitions used in the video:<|eot_id|><|start_header_id|>user<|end_header_id|>\n\n{}<|eot_id|>', 'crop_start': 95}max_sequence_length: int = 256sampling_type: FramepackSamplingType = <FramepackSamplingType.INVERTED_ANTI_DRIFTING: 'inverted_anti_drifting'> ) → ~HunyuanVideoFramepackPipelineOutput or tuple

Parámetros

  • image (PIL.Image.Image o np.ndarray o torch.Tensor) — La imagen que se utilizará como punto de partida para la generación del video.
  • last_image (PIL.Image.Image o np.ndarray o torch.Tensor, opcional) — La última imagen opcional que se utilizará como punto final para la generación del video. Esto es útil para generar transiciones entre dos imágenes.
  • 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.
  • prompt_2 (str o list[str], opcional) — El prompt o prompts que se enviarán a tokenizer_2 y text_encoder_2. Si no está definido, se utilizará prompt en su lugar.
  • negative_prompt (str o list[str], opcional) — El prompt o prompts que no deben guiar la generación de la imagen. Si no se define, se debe pasar negative_prompt_embeds en su lugar. Se ignora cuando no se usa guía (es decir, se ignora si true_cfg_scale no es mayor que 1).
  • negative_prompt_2 (str o list[str], opcional) — El prompt o prompts que no deben guiar la generación de la imagen y que se enviarán a tokenizer_2 y text_encoder_2. Si no se define, se utiliza negative_prompt en todos los text-encoders.
  • height (int, por defecto 720) — La altura en píxeles de la imagen generada.
  • width (int, por defecto 1280) — El ancho en píxeles de la imagen generada.
  • num_frames (int, por defecto 129) — El número de fotogramas en el video generado.
  • latent_window_size (int, por defecto 9) — Número de fotogramas latentes producidos por ventana de muestreo de Framepack.
  • num_inference_steps (int, por defecto 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.
  • true_cfg_scale (float, opcional, valor predeterminado 1.0) — Cuando es > 1.0 y se proporciona un negative_prompt, habilita la guía libre de clasificador real.
  • guidance_scale (float, por defecto 6.0) — Escala de guía tal como se define en Classifier-Free Diffusion Guidance. guidance_scale se define como w de la ecuación 2 del Imagen Paper. La escala de guía se activa al establecer guidance_scale > 1. Una escala de guía más alta fomenta la generación de imágenes estrechamente vinculadas al texto de prompt, generalmente a costa de una menor calidad de imagen. Tenga en cuenta que el único modelo HunyuanVideo disponible está destilado con CFG, lo que significa que no se aplica la guía tradicional entre el latente incondicional y el condicional.
  • num_videos_per_prompt (int, opcional, valor predeterminado 1) — El número de imágenes que se generan por indicación.
  • generator (torch.Generator o list[torch.Generator], opcional) — Un torch.Generator para hacer que la generación sea determinista.
  • image_latents (torch.Tensor, opcional) — Latentes de imagen predecodificados. Si no se proporcionan, la imagen se codificará utilizando el VAE.
  • last_image_latents (torch.Tensor, opcional) — Latentes de la última imagen predecodificados. Si no se proporcionan, la última imagen se codificará usando el VAE.
  • prompt_embeds (torch.Tensor, opcional) — Incrustaciones de texto pregeneradas. Se pueden usar para ajustar fácilmente las entradas de texto (ponderación del prompt). Si no se proporcionan, las incrustaciones de texto se generan a partir del argumento de entrada prompt.
  • pooled_prompt_embeds (torch.FloatTensor, opcional) — Incrustaciones de texto agrupadas pregeneradas. Se pueden usar para ajustar fácilmente las entradas de texto, p. ej. ponderación de prompts. Si no se proporciona, las incrustaciones de texto agrupadas se generarán a partir del argumento de entrada prompt.
  • negative_prompt_embeds (torch.FloatTensor, opcional) — Incrustaciones de texto negativo pregeneradas. Se pueden usar para ajustar fácilmente las entradas de texto, p. ej. el ponderado del prompt. Si no se proporciona, negative_prompt_embeds se generará a partir del argumento de entrada negative_prompt.
  • negative_pooled_prompt_embeds (torch.FloatTensor, opcional) — Incrustaciones de texto negativo agrupadas pregeneradas. Se pueden utilizar para ajustar fácilmente las entradas de texto, p. ej. el ponderado del prompt. Si no se proporciona, se generarán pooled negative_prompt_embeds a partir del argumento de entrada negative_prompt.
  • prompt_attention_mask (torch.Tensor, opcional) — Máscara de atención para prompt_embeds. Es obligatoria cuando se pasa prompt_embeds directamente.
  • negative_prompt_attention_mask (torch.Tensor, opcional) — Máscara de atención para negative_prompt_embeds. Es obligatoria cuando se pasa negative_prompt_embeds directamente.
  • output_type (str, opcional, por defecto "pil") — El formato de salida de la imagen generada. Elija entre PIL.Image o np.array.
  • return_dict (bool, opcional, valor predeterminado True) — Indica si se debe devolver un HunyuanVideoFramepackPipelineOutput 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.
  • prompt_template (dict, opcional) — Plantilla utilizada para formatear el prompt antes de codificarlo. Por defecto, se utiliza la plantilla predeterminada del modelo.
  • max_sequence_length (int, opcional, valor predeterminado 256) — Longitud máxima de secuencia a utilizar para el codificador de prompts.
  • sampling_type (FramepackSamplingType, opcional) — La estrategia de muestreo Framepack que se utilizará al iterar sobre las ventanas latentes.
  • callback_on_step_end (Callable, PipelineCallback, MultiPipelineCallbacks, opcional) — Una función o una subclase de PipelineCallback o MultiPipelineCallbacks que se llama al final de cada paso de desruido durante la inferencia, 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ás incluir variables listadas en el atributo ._callback_tensor_inputs de tu clase de pipeline.

Devuelve

~HunyuanVideoFramepackPipelineOutput o tuple

Si return_dict es True, se devuelve HunyuanVideoFramepackPipelineOutput; en caso contrario, se devuelve una tuple cuyo primer elemento es una lista con las imágenes generadas y cuyo segundo elemento es una lista de bool que indica si la imagen generada correspondiente contiene contenido “not-safe-for-work” (nsfw).

La función de llamada para el pipeline de generación.

Ejemplos:

Imagen a video
>>> import torch
>>> from diffusers import HunyuanVideoFramepackPipeline, HunyuanVideoFramepackTransformer3DModel
>>> from diffusers.utils import export_to_video, load_image
>>> from transformers import SiglipImageProcessor, SiglipVisionModel

>>> transformer = HunyuanVideoFramepackTransformer3DModel.from_pretrained(
...     "lllyasviel/FramePackI2V_HY", torch_dtype=torch.bfloat16
... )
>>> feature_extractor = SiglipImageProcessor.from_pretrained(
...     "lllyasviel/flux_redux_bfl", subfolder="feature_extractor"
... )
>>> image_encoder = SiglipVisionModel.from_pretrained(
...     "lllyasviel/flux_redux_bfl", subfolder="image_encoder", torch_dtype=torch.float16
... )
>>> pipe = HunyuanVideoFramepackPipeline.from_pretrained(
...     "hunyuanvideo-community/HunyuanVideo",
...     transformer=transformer,
...     feature_extractor=feature_extractor,
...     image_encoder=image_encoder,
...     torch_dtype=torch.float16,
... )
>>> pipe.vae.enable_tiling()
>>> pipe.to("cuda")

>>> image = load_image(
...     "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/penguin.png"
... )
>>> output = pipe(
...     image=image,
...     prompt="A penguin dancing in the snow",
...     height=832,
...     width=480,
...     num_frames=91,
...     num_inference_steps=30,
...     guidance_scale=9.0,
...     generator=torch.Generator().manual_seed(0),
...     sampling_type="inverted_anti_drifting",
... ).frames[0]
>>> export_to_video(output, "output.mp4", fps=30)
Imagen a video de primera y última
>>> import torch
>>> from diffusers import HunyuanVideoFramepackPipeline, HunyuanVideoFramepackTransformer3DModel
>>> from diffusers.utils import export_to_video, load_image
>>> from transformers import SiglipImageProcessor, SiglipVisionModel

>>> transformer = HunyuanVideoFramepackTransformer3DModel.from_pretrained(
...     "lllyasviel/FramePackI2V_HY", torch_dtype=torch.bfloat16
... )
>>> feature_extractor = SiglipImageProcessor.from_pretrained(
...     "lllyasviel/flux_redux_bfl", subfolder="feature_extractor"
... )
>>> image_encoder = SiglipVisionModel.from_pretrained(
...     "lllyasviel/flux_redux_bfl", subfolder="image_encoder", torch_dtype=torch.float16
... )
>>> pipe = HunyuanVideoFramepackPipeline.from_pretrained(
...     "hunyuanvideo-community/HunyuanVideo",
...     transformer=transformer,
...     feature_extractor=feature_extractor,
...     image_encoder=image_encoder,
...     torch_dtype=torch.float16,
... )
>>> pipe.to("cuda")

>>> prompt = "CG animation style, a small blue bird takes off from the ground, flapping its wings. The bird's feathers are delicate, with a unique pattern on its chest. The background shows a blue sky with white clouds under bright sunshine. The camera follows the bird upward, capturing its flight and the vastness of the sky from a close-up, low-angle perspective."
>>> first_image = load_image(
...     "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/flf2v_input_first_frame.png"
... )
>>> last_image = load_image(
...     "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/flf2v_input_last_frame.png"
... )
>>> output = pipe(
...     image=first_image,
...     last_image=last_image,
...     prompt=prompt,
...     height=512,
...     width=512,
...     num_frames=91,
...     num_inference_steps=30,
...     guidance_scale=9.0,
...     generator=torch.Generator().manual_seed(0),
...     sampling_type="inverted_anti_drifting",
... ).frames[0]
>>> export_to_video(output, "output.mp4", fps=30)

HunyuanVideoPipelineOutput

clase diffusers.pipelines.hunyuan_video.pipeline_output.HunyuanVideoPipelineOutput

< >

( frames: Tensor )

Parámetros

  • frames (torch.Tensor, np.ndarray o list[list[PIL.Image.Image]]) — lista de salidas de video. Puede ser una lista anidada de longitud batch_size, donde cada sublista contiene secuencias de imágenes PIL desruidas de longitud num_frames. También puede ser un array de NumPy o un tensor de Torch de forma (batch_size, num_frames, channels, height, width).

Clase de salida para las pipelines de HunyuanVideo.

Update on GitHub

←Cosmos3 Helios→