Diffusers documentation

Framepack

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

and get access to the augmented documentation experience

to get started

Framepack

LoRA

Packing Input Frame Context in Next-Frame Prediction Models for Video Generation de Lvmin Zhang et Maneesh Agrawala.

Nous présentons une structure de réseau de neurones, FramePack, pour entraîner des modèles de prédiction de la frame suivante (ou de la section de frame suivante) destinés à la génération de vidéos. FramePack compresse les frames d’entrée afin que la longueur de contexte du transformer reste un nombre fixe, indépendamment de la longueur de la vidéo. En conséquence, nous sommes en mesure de traiter un grand nombre de frames en utilisant la diffusion vidéo, avec un goulot d’étranglement de calcul comparable à celui de la diffusion d’images. Cela permet également d’augmenter considérablement les tailles de lot d’entraînement vidéo (les tailles de lot deviennent comparables à celles de l’entraînement par diffusion d’images). Nous proposons également une méthode d’échantillonnage anti-dérive qui génère les frames dans un ordre temporel inversé, avec des points de terminaison établis tôt, afin d’éviter le biais d’exposition (accumulation d’erreurs au fil des itérations). Enfin, nous montrons que les modèles de diffusion vidéo existants peuvent être affinés avec FramePack, et que leur qualité visuelle peut être améliorée, car la prédiction de la frame suivante permet d’utiliser des planificateurs de diffusion plus équilibrés, avec des pas de temps de décalage de flux moins extrêmes.

Pensez à consulter le guide des Schedulers pour apprendre à explorer le compromis entre la vitesse et la qualité du scheduler, et à consulter la section réutilisation des composants entre les pipelines pour apprendre à charger efficacement les mêmes composants dans plusieurs pipelines.

Modèles disponibles

Nom du modèleDescription
- lllyasviel/FramePackI2V_HYEntraîné avec la stratégie « anti-dérive inversée » telle que décrite dans l'article. L'inférence nécessite de définir sampling_type="inverted_anti_drifting" lors de l'exécution du pipeline.
- lllyasviel/FramePack_F1_I2V_HY_20250503Entraîné avec une stratégie anti-dérive novatrice, mais l'inférence est effectuée selon la stratégie « vanilla » telle que décrite dans l'article. L'inférence nécessite de définir sampling_type="vanilla" lors de l'exécution du pipeline.

Utilisation

Consultez la documentation du pipeline pour des exemples d'utilisation de base. La section suivante contient des exemples de déchargement, de différentes méthodes d'échantillonnage, de quantification, et plus encore.

Première et dernière image vers vidéo

L’exemple suivant montre comment utiliser Framepack avec des contrôles d’image de début et de fin, en utilisant le modèle d’échantillonnage anti-dérive inversé.

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)

Échantillonnage standard

L'exemple suivant montre comment utiliser Framepack avec le modèle F1 entraîné avec un échantillonnage standard mais une nouvelle approche de régulation pour le dérive anti.

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)

Group offloading

Le déchargement par groupes (apply_group_offloading()) offre des optimisations mémoire agressives pour décharger les parties internes de n'importe quel modèle vers le CPU, sans surcoût supplémentaire potentiel sur le temps de génération. Si votre VRAM disponible est très faible, cette approche peut vous convenir en fonction de la quantité de RAM 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

classe diffusers.HunyuanVideoFramepackPipeline

< >

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

Paramètres

Pipeline pour la génération de vidéos à partir de texte utilisant HunyuanVideo.

Ce modèle hérite de DiffusionPipeline. Consultez la documentation de la classe parente pour les méthodes génériques implémentées pour tous les pipelines (téléchargement, sauvegarde, exécution sur un appareil particulier, 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

Paramètres

  • image (PIL.Image.Image ou np.ndarray ou torch.Tensor) — L’image à utiliser comme point de départ pour la génération de la vidéo.
  • last_image (PIL.Image.Image ou np.ndarray ou torch.Tensor, facultatif) — La dernière image facultative à utiliser comme point de fin pour la génération de la vidéo. Cela est utile pour générer des transitions entre deux images.
  • prompt (str ou list[str], facultatif) — Le prompt ou les prompts pour guider la génération d’image. S’il n’est pas défini, il faut passer prompt_embeds à la place.
  • prompt_2 (str ou list[str], facultatif) — Le prompt ou les prompts à envoyer à tokenizer_2 et text_encoder_2. S'il n'est pas défini, prompt sera utilisé à la place.
  • negative_prompt (str ou list[str], facultatif) — Le ou les prompts à ne pas utiliser pour guider la génération d’image. S’il n’est pas défini, il faut passer negative_prompt_embeds à la place. Ignoré lorsque le guidage n’est pas utilisé (c’est-à-dire ignoré si true_cfg_scale n’est pas supérieur à 1).
  • negative_prompt_2 (str ou list[str], facultatif) — Le prompt ou les prompts à ne pas utiliser pour guider la génération d’image, à envoyer à tokenizer_2 et text_encoder_2. S’il n’est pas défini, negative_prompt est utilisé dans tous les encodeurs de texte.
  • height (int, par défaut 720) — La hauteur en pixels de l'image générée.
  • width (int, par défaut 1280) — La largeur en pixels de l'image générée.
  • num_frames (int, par défaut 129) — Le nombre de frames dans la vidéo générée.
  • latent_window_size (int, par défaut 9) — Nombre de trames latentes produites par fenêtre d'échantillonnage Framepack.
  • num_inference_steps (int, par défaut 50) — Le nombre d'étapes de débruitage. Un plus grand nombre d'étapes de débruitage conduit généralement à une image de meilleure qualité, au prix d'une inférence plus lente.
  • sigmas (list[float], facultatif) — Sigmas personnalisés à utiliser pour le processus de débruitage avec les planificateurs qui prennent en charge un argument sigmas dans leur méthode set_timesteps. S'il n'est pas défini, le comportement par défaut lorsque num_inference_steps est passé sera utilisé.
  • true_cfg_scale (float, facultatif, valeur par défaut 1.0) — Si supérieur à 1.0 et qu’un negative_prompt est fourni, active le vrai classifier-free guidance.
  • guidance_scale (float, par défaut 6.0) — Échelle de guidage telle que définie dans Classifier-Free Diffusion Guidance. guidance_scale est défini comme w de l’équation 2. de Imagen Paper. L’échelle de guidage est activée en définissant guidance_scale > 1. Une échelle de guidage plus élevée encourage la génération d’images étroitement liées au texte prompt, généralement au détriment de la qualité de l’image. Notez que le seul modèle HunyuanVideo disponible est distillé CFG, ce qui signifie que le guidage traditionnel entre latent non conditionnel et latent conditionnel n’est pas appliqué.
  • num_videos_per_prompt (int, facultatif, valeur par défaut 1) — Le nombre d'images à générer par invite.
  • generator (torch.Generator ou list[torch.Generator], facultatif) — Un torch.Generator pour rendre la génération déterministe.
  • image_latents (torch.Tensor, facultatif) — Latents d’image pré-encodés. S’ils ne sont pas fournis, l’image sera encodée à l’aide du VAE.
  • last_image_latents (torch.Tensor, facultatif) — Latents de la dernière image pré-encodés. S'ils ne sont pas fournis, la dernière image sera encodée à l'aide du VAE.
  • prompt_embeds (torch.Tensor, facultatif) — Embeddings de texte pré-générés. Peut être utilisé pour ajuster facilement les entrées de texte (pondération des prompts). S'il n'est pas fourni, les embeddings de texte sont générés à partir de l'argument d'entrée prompt.
  • pooled_prompt_embeds (torch.FloatTensor, facultatif) — Embeddings de texte pré-poolés pré-générés. Peut être utilisé pour ajuster facilement les entrées de texte, par ex. le pondération des prompts. S'il n'est pas fourni, les embeddings de texte pré-poolés seront générés à partir de l'argument d'entrée prompt.
  • negative_prompt_embeds (torch.FloatTensor, facultatif) — Embeddings de texte négatifs pré-générés. Peut être utilisé pour ajuster facilement les entrées de texte, par ex. le pondération des prompts. S'il n'est pas fourni, negative_prompt_embeds sera généré à partir de l'argument d'entrée negative_prompt.
  • negative_pooled_prompt_embeds (torch.FloatTensor, facultatif) — Embeddings de texte négatifs pré-générés. Peut être utilisé pour ajuster facilement les entrées de texte, par ex. le pondération des prompts. S'il n'est pas fourni, les pooled negative_prompt_embeds seront générés à partir de l'argument d'entrée negative_prompt.
  • prompt_attention_mask (torch.Tensor, facultatif) — Masque d'attention pour prompt_embeds. Requis lorsque prompt_embeds est passé directement.
  • negative_prompt_attention_mask (torch.Tensor, facultatif) — Masque d'attention pour negative_prompt_embeds. Requis lorsque negative_prompt_embeds est passé directement.
  • output_type (str, facultatif, par défaut "pil") — Le format de sortie de l’image générée. Choisissez entre PIL.Image ou np.array.
  • return_dict (bool, facultatif, par défaut True) — Indique s'il faut retourner un HunyuanVideoFramepackPipelineOutput plutôt qu'un simple tuple.
  • attention_kwargs (dict, facultatif) — Un dictionnaire de kwargs qui, s'il est spécifié, est transmis à l'AttentionProcessor défini sous self.processor dans diffusers.models.attention_processor.
  • prompt_template (dict, facultatif) — Modèle utilisé pour formater le prompt avant l’encodage. Par défaut, le modèle utilise son modèle par défaut.
  • max_sequence_length (int, facultatif, valeur par défaut 256) — Longueur maximale de séquence à utiliser pour l'encodeur de prompt.
  • sampling_type (FramepackSamplingType, facultatif) — Stratégie d'échantillonnage Framepack à utiliser lors de l'itération sur les fenêtres latentes.
  • callback_on_step_end (Callable, PipelineCallback, MultiPipelineCallbacks, facultatif) — Une fonction ou une sous-classe de PipelineCallback ou MultiPipelineCallbacks qui est appelée à la fin de chaque étape de débruitage pendant l’inférence, avec les arguments suivants : callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict). callback_kwargs contiendra une liste de tous les tenseurs spécifiés par callback_on_step_end_tensor_inputs.
  • callback_on_step_end_tensor_inputs (list, facultatif) — La liste des entrées tensorielles pour la fonction callback_on_step_end. Les tenseurs spécifiés dans la liste seront passés en tant qu'argument callback_kwargs. Vous ne pourrez inclure que les variables listées dans l'attribut ._callback_tensor_inputs de votre classe de pipeline.

Retourne

~HunyuanVideoFramepackPipelineOutput ou tuple

Si return_dict est True, HunyuanVideoFramepackPipelineOutput est renvoyé, sinon un tuple est renvoyé dont le premier élément est une liste des images générées et le second élément est une liste de bool indiquant si l’image générée correspondante contient du contenu « not-safe-for-work » (nsfw).

La fonction d'appel du pipeline pour la génération.

Exemples :

Image-vers-Vidéo
>>> 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)
Première et dernière image vers vidéo
>>> 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

classe diffusers.pipelines.hunyuan_video.pipeline_output.HunyuanVideoPipelineOutput

< >

( frames: Tensor )

Paramètres

  • frames (torch.Tensor, np.ndarray ou list[list[PIL.Image.Image]]) — liste des sorties vidéo - Il peut s'agir d'une liste imbriquée de longueur batch_size, où chaque sous-liste contient des séquences d'images PIL débruitées de longueur num_frames. Il peut également s'agir d'un tableau NumPy ou d'un tenseur Torch de forme (batch_size, num_frames, channels, height, width).

Classe de sortie pour les pipelines HunyuanVideo.

Update on GitHub