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.42.1).
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 oleh Lvmin Zhang dan Maneesh Agrawala.

Kami memperkenalkan struktur jaringan saraf, FramePack, untuk melatih model prediksi frame berikutnya (atau bagian frame berikutnya) untuk generasi video. FramePack mengompresi frame input sehingga panjang konteks transformer menjadi jumlah tetap terlepas dari panjang video. Akibatnya, kami mampu memproses sejumlah besar frame menggunakan video diffusion dengan bottleneck komputasi yang serupa dengan image diffusion. Hal ini juga membuat ukuran batch video pelatihan menjadi jauh lebih besar (ukuran batch menjadi sebanding dengan pelatihan image diffusion). Kami juga mengusulkan metode sampling anti-drifting yang menghasilkan frame dalam urutan temporal terbalik dengan titik akhir yang ditetapkan lebih awal untuk menghindari exposure bias (akumulasi error selama iterasi). Terakhir, kami menunjukkan bahwa model video diffusion yang ada dapat ditala ulang (finetuned) dengan FramePack, dan kualitas visualnya dapat ditingkatkan karena prediksi frame berikutnya mendukung penjadwal diffusion yang lebih seimbang dengan langkah waktu pergeseran aliran yang kurang ekstrem.

Pastikan untuk melihat panduan Schedulers untuk mempelajari cara mengeksplorasi tradeoff antara kecepatan dan kualitas scheduler, serta lihat bagian reuse components across pipelines untuk mempelajari cara memuat komponen yang sama secara efisien ke dalam beberapa pipeline.

Model yang tersedia

Nama modelDeskripsi
- lllyasviel/FramePackI2V_HYDilatih dengan strategi “inverted anti-drifting” seperti yang dijelaskan dalam makalah. Inferensi memerlukan pengaturan sampling_type="inverted_anti_drifting" saat menjalankan pipeline.
- lllyasviel/FramePack_F1_I2V_HY_20250503Dilatih dengan strategi anti-drifting yang baru, tetapi inferensi dilakukan dengan strategi “vanilla” seperti yang dijelaskan dalam makalah. Inferensi memerlukan pengaturan sampling_type="vanilla" saat menjalankan pipeline.

Penggunaan

Lihat dokumentasi pipeline untuk contoh penggunaan dasar. Bagian berikut berisi contoh offloading, metode sampling yang berbeda, kuantisasi, dan lainnya.

Frame pertama dan terakhir ke video

Contoh berikut menunjukkan cara menggunakan Framepack dengan kontrol gambar awal dan akhir, menggunakan model sampling anti-drifiting terbalik.

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)

Sampling vanilla

Contoh berikut menunjukkan cara menggunakan Framepack dengan model F1 yang dilatih dengan sampling vanilla tetapi pendekatan regulasi baru untuk anti-drifting.

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)

Offloading grup

Group offloading (apply_group_offloading()) menyediakan optimasi memori yang agresif untuk offloading bagian internal model apa pun ke CPU, dengan kemungkinan tidak ada overhead tambahan pada waktu generasi. Jika Anda memiliki VRAM yang sangat rendah, pendekatan ini mungkin cocok untuk Anda tergantung pada jumlah RAM CPU yang tersedia.

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

kelas diffusers.HunyuanVideoFramepackPipeline

< >

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

Parameter

Pipeline untuk generasi teks-ke-video menggunakan HunyuanVideo.

Model ini mewarisi dari DiffusionPipeline. Periksa dokumentasi kelas induk untuk metode generik yang diimplementasikan untuk semua pipeline (mengunduh, menyimpan, menjalankan pada perangkat tertentu, dll.).

__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 = 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 = ['latents']prompt_template: dict = {'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

Parameter

  • image (PIL.Image.Image atau np.ndarray atau torch.Tensor) — Gambar yang akan digunakan sebagai titik awal untuk pembuatan video.
  • last_image (PIL.Image.Image atau np.ndarray atau torch.Tensor, opsional) — Gambar terakhir opsional yang akan digunakan sebagai titik akhir untuk generasi video. Ini berguna untuk menghasilkan transisi antara dua gambar.
  • prompt (str atau list[str], opsional) — Prompt atau prompt-prompt untuk mengarahkan generasi gambar. Jika tidak didefinisikan, Anda harus meneruskan prompt_embeds sebagai gantinya.
  • prompt_2 (str atau list[str], opsional) — Prompt atau prompt yang akan dikirim ke tokenizer_2 dan text_encoder_2. Jika tidak didefinisikan, prompt akan digunakan sebagai gantinya.
  • negative_prompt (str atau list[str], opsional) — Prompt atau prompt-prompt yang tidak digunakan untuk mengarahkan generasi gambar. Jika tidak didefinisikan, Anda harus meneruskan negative_prompt_embeds sebagai gantinya. Diabaikan saat tidak menggunakan guidance (yaitu, diabaikan jika true_cfg_scale tidak lebih besar dari 1).
  • negative_prompt_2 (str atau list[str], opsional) — Prompt atau prompt-prompt yang tidak digunakan untuk mengarahkan generasi gambar, yang akan dikirim ke tokenizer_2 dan text_encoder_2. Jika tidak didefinisikan, negative_prompt digunakan di semua text-encoder.
  • height (int, defaultnya 720) — Tinggi gambar yang dihasilkan dalam piksel.
  • width (int, defaultnya 1280) — Lebar gambar yang dihasilkan dalam piksel.
  • num_frames (int, defaultnya 129) — Jumlah frame dalam video yang dihasilkan.
  • latent_window_size (int, defaultnya 9) — Jumlah frame laten yang dihasilkan per jendela sampling Framepack.
  • num_inference_steps (int, defaultnya 50) — Jumlah langkah denoising. Semakin banyak langkah denoising, biasanya menghasilkan gambar dengan kualitas lebih tinggi, namun dengan biaya inferensi yang lebih lambat.
  • sigmas (list[float], opsional) — Sigmas kustom untuk digunakan dalam proses denoising dengan scheduler yang mendukung argumen sigmas dalam metode set_timesteps mereka. Jika tidak didefinisikan, perilaku default saat num_inference_steps diteruskan akan digunakan.
  • true_cfg_scale (float, opsional, default 1.0) — Ketika > 1.0 dan negative_prompt diberikan, mengaktifkan true classifier-free guidance.
  • guidance_scale (float, default 6.0) — Skala panduan seperti yang didefinisikan dalam Classifier-Free Diffusion Guidance. guidance_scale didefinisikan sebagai w dari persamaan 2. dari Imagen Paper. Skala panduan diaktifkan dengan mengatur guidance_scale > 1. Skala panduan yang lebih tinggi mendorong generasi gambar yang sangat terkait dengan teks prompt, biasanya dengan mengorbankan kualitas gambar yang lebih rendah. Perhatikan bahwa satu-satunya model HunyuanVideo yang tersedia adalah yang telah di-distilasi CFG, yang berarti panduan tradisional antara laten unconditional dan conditional tidak diterapkan.
  • num_videos_per_prompt (int, opsional, default 1) — Jumlah gambar yang akan dihasilkan per prompt.
  • generator (torch.Generator atau list[torch.Generator], opsional) — torch.Generator untuk membuat generasi menjadi deterministik.
  • image_latents (torch.Tensor, opsional) — Latens gambar yang sudah di-encode sebelumnya. Jika tidak disediakan, gambar akan di-encode menggunakan VAE.
  • last_image_latents (torch.Tensor, opsional) — Latens gambar terakhir yang sudah di-encode sebelumnya. Jika tidak disediakan, gambar terakhir akan di-encode menggunakan VAE.
  • prompt_embeds (torch.Tensor, opsional) — Embedding teks yang sudah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks (penimbangan prompt). Jika tidak disediakan, embedding teks akan dihasilkan dari argumen input prompt.
  • pooled_prompt_embeds (torch.FloatTensor, opsional) — Embedding teks pooled yang telah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, mis. pembobotan prompt. Jika tidak disediakan, embedding teks pooled akan dibuat dari argumen input prompt.
  • negative_prompt_embeds (torch.FloatTensor, opsional) — Embedding teks negatif yang telah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya penimbangan prompt. Jika tidak disediakan, negative_prompt_embeds akan dibuat dari argumen input negative_prompt.
  • negative_pooled_prompt_embeds (torch.FloatTensor, opsional) — Embedding teks negatif yang sudah digenerate sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya penimbangan prompt. Jika tidak disediakan, pooled negative_prompt_embeds akan digenerate dari argumen input negative_prompt.
  • prompt_attention_mask (torch.Tensor, opsional) — Attention mask untuk prompt_embeds. Wajib diisi ketika prompt_embeds dilewatkan secara langsung.
  • negative_prompt_attention_mask (torch.Tensor, opsional) — Attention mask untuk negative_prompt_embeds. Wajib diisi ketika negative_prompt_embeds diberikan secara langsung.
  • output_type (str, opsional, default "pil") — Format output dari gambar yang dihasilkan. Pilih antara PIL.Image atau np.array.
  • return_dict (bool, opsional, default True) — Apakah akan mengembalikan HunyuanVideoFramepackPipelineOutput alih-alih tuple biasa.
  • attention_kwargs (dict, opsional) — Kamus kwargs yang jika ditentukan akan diteruskan ke AttentionProcessor seperti yang didefinisikan di bawah self.processor dalam diffusers.models.attention_processor.
  • prompt_template (dict, opsional) — Template yang digunakan untuk memformat prompt sebelum encoding. Secara default menggunakan template default model.
  • max_sequence_length (int, opsional, default 256) — Panjang maksimum urutan yang digunakan untuk encoder prompt.
  • sampling_type (FramepackSamplingType, opsional) — Strategi sampling Framepack yang digunakan saat mengiterasi jendela laten.
  • callback_on_step_end (Callable, PipelineCallback, MultiPipelineCallbacks, opsional) — Fungsi atau subkelas dari PipelineCallback atau MultiPipelineCallbacks yang dipanggil di akhir setiap langkah denoising selama inferensi, dengan argumen berikut: callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict). callback_kwargs akan berisi daftar semua tensor sesuai yang ditentukan oleh callback_on_step_end_tensor_inputs.
  • callback_on_step_end_tensor_inputs (list, opsional) — Daftar input tensor untuk fungsi callback_on_step_end. Tensor yang ditentukan dalam daftar akan diteruskan sebagai argumen callback_kwargs. Anda hanya dapat menyertakan variabel yang tercantum dalam atribut ._callback_tensor_inputs dari kelas pipeline Anda.

Mengembalikan

~HunyuanVideoFramepackPipelineOutput atau tuple

Jika return_dict adalah True, maka HunyuanVideoFramepackPipelineOutput yang dikembalikan, selain itu sebuah tuple yang dikembalikan di mana elemen pertama adalah daftar dengan gambar yang dihasilkan dan elemen kedua adalah daftar bool yang menunjukkan apakah gambar yang dihasilkan yang sesuai mengandung konten “not-safe-for-work” (nsfw).

Fungsi panggilan untuk pipeline pada generasi.

Contoh:

Gambar-ke-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)
Gambar Pertama dan Terakhir ke 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.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

kelas diffusers.pipelines.hunyuan_video.pipeline_output.HunyuanVideoPipelineOutput

< >

( frames: Tensor )

Parameter

  • frames (torch.Tensor, np.ndarray, atau list[list[PIL.Image.Image]]) — daftar output video - Dapat berupa daftar bersarang dengan panjang batch_size, di mana setiap sub-daftar berisi urutan gambar PIL yang telah didenois dengan panjang num_frames. Dapat juga berupa array NumPy atau tensor Torch dengan bentuk (batch_size, num_frames, channels, height, width).

Kelas output untuk pipeline HunyuanVideo.

Update on GitHub