Diffusers documentation
Framepack
Framepack
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èle | Description |
|---|---|
- lllyasviel/FramePackI2V_HY | Entraî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_20250503 | Entraî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
< source >( text_encoder: LlamaModeltokenizer: LlamaTokenizertransformer: HunyuanVideoFramepackTransformer3DModelvae: AutoencoderKLHunyuanVideoscheduler: FlowMatchEulerDiscreteSchedulertext_encoder_2: CLIPTextModeltokenizer_2: CLIPTokenizerimage_encoder: SiglipVisionModelfeature_extractor: SiglipImageProcessorPil )
Paramètres
- text_encoder (
LlamaModel) — Llava Llama3-8B. - tokenizer (
LlamaTokenizer) — Tokenizer de Llava Llama3-8B. - transformer (HunyuanVideoTransformer3DModel) — Transformer conditionnel pour débruyer les latents d'image encodés.
- scheduler (FlowMatchEulerDiscreteScheduler) —
Un planificateur à utiliser en combinaison avec
transformerpour débruyer les latents d'image encodés. - vae (AutoencoderKLHunyuanVideo) — Modèle de Variational Auto-Encoder (VAE) pour encoder et décoder des vidéos vers et depuis des représentations latentes.
- text_encoder_2 (
CLIPTextModel) — CLIP, plus précisément la variante clip-vit-large-patch14. - tokenizer_2 (
CLIPTokenizer) — Tokeniseur de la classe CLIPTokenizer.
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__
< source >( 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.Imageounp.ndarrayoutorch.Tensor) — L’image à utiliser comme point de départ pour la génération de la vidéo. - last_image (
PIL.Image.Imageounp.ndarrayoutorch.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 (
stroulist[str], facultatif) — Le prompt ou les prompts pour guider la génération d’image. S’il n’est pas défini, il faut passerprompt_embedsà la place. - prompt_2 (
stroulist[str], facultatif) — Le prompt ou les prompts à envoyer àtokenizer_2ettext_encoder_2. S'il n'est pas défini,promptsera utilisé à la place. - negative_prompt (
stroulist[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 passernegative_prompt_embedsà la place. Ignoré lorsque le guidage n’est pas utilisé (c’est-à-dire ignoré sitrue_cfg_scalen’est pas supérieur à1). - negative_prompt_2 (
stroulist[str], facultatif) — Le prompt ou les prompts à ne pas utiliser pour guider la génération d’image, à envoyer àtokenizer_2ettext_encoder_2. S’il n’est pas défini,negative_promptest utilisé dans tous les encodeurs de texte. - height (
int, par défaut720) — La hauteur en pixels de l'image générée. - width (
int, par défaut1280) — La largeur en pixels de l'image générée. - num_frames (
int, par défaut129) — Le nombre de frames dans la vidéo générée. - latent_window_size (
int, par défaut9) — Nombre de trames latentes produites par fenêtre d'échantillonnage Framepack. - num_inference_steps (
int, par défaut50) — 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 argumentsigmasdans leur méthodeset_timesteps. S'il n'est pas défini, le comportement par défaut lorsquenum_inference_stepsest passé sera utilisé. - true_cfg_scale (
float, facultatif, valeur par défaut 1.0) — Si supérieur à 1.0 et qu’unnegative_promptest fourni, active le vrai classifier-free guidance. - guidance_scale (
float, par défaut6.0) — Échelle de guidage telle que définie dans Classifier-Free Diffusion Guidance.guidance_scaleest défini commewde l’équation 2. de Imagen Paper. L’échelle de guidage est activée en définissantguidance_scale > 1. Une échelle de guidage plus élevée encourage la génération d’images étroitement liées au texteprompt, 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.Generatoroulist[torch.Generator], facultatif) — Untorch.Generatorpour 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éeprompt. - 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éeprompt. - 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éenegative_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éenegative_prompt. - prompt_attention_mask (
torch.Tensor, facultatif) — Masque d'attention pourprompt_embeds. Requis lorsqueprompt_embedsest passé directement. - negative_prompt_attention_mask (
torch.Tensor, facultatif) — Masque d'attention pournegative_prompt_embeds. Requis lorsquenegative_prompt_embedsest passé directement. - output_type (
str, facultatif, par défaut"pil") — Le format de sortie de l’image générée. Choisissez entrePIL.Imageounp.array. - return_dict (
bool, facultatif, par défautTrue) — Indique s'il faut retourner unHunyuanVideoFramepackPipelineOutputplutôt qu'un simple tuple. - attention_kwargs (
dict, facultatif) — Un dictionnaire de kwargs qui, s'il est spécifié, est transmis à l'AttentionProcessordéfini sousself.processordans 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 dePipelineCallbackouMultiPipelineCallbacksqui 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_kwargscontiendra une liste de tous les tenseurs spécifiés parcallback_on_step_end_tensor_inputs. - callback_on_step_end_tensor_inputs (
list, facultatif) — La liste des entrées tensorielles pour la fonctioncallback_on_step_end. Les tenseurs spécifiés dans la liste seront passés en tant qu'argumentcallback_kwargs. Vous ne pourrez inclure que les variables listées dans l'attribut._callback_tensor_inputsde 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
< source >( frames: Tensor )
Paramètres
- frames (
torch.Tensor,np.ndarrayou list[list[PIL.Image.Image]]) — liste des sorties vidéo - Il peut s'agir d'une liste imbriquée de longueurbatch_size,où chaque sous-liste contient des séquences d'images PIL débruitées de longueurnum_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.