|
| 1 | +<!-- Copyright 2025 The HuggingFace Team. All rights reserved. |
| 2 | +# |
| 3 | +# Licensed under the Apache License, Version 2.0 (the "License"); |
| 4 | +# you may not use this file except in compliance with the License. |
| 5 | +# You may obtain a copy of the License at |
| 6 | +# |
| 7 | +# http://www.apache.org/licenses/LICENSE-2.0 |
| 8 | +# |
| 9 | +# Unless required by applicable law or agreed to in writing, software |
| 10 | +# distributed under the License is distributed on an "AS IS" BASIS, |
| 11 | +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 12 | +# See the License for the specific language governing permissions and |
| 13 | +# limitations under the License. --> |
| 14 | + |
| 15 | +# Framepack |
| 16 | + |
| 17 | +<div class="flex flex-wrap space-x-1"> |
| 18 | + <img alt="LoRA" src="https://img.shields.io/badge/LoRA-d8b4fe?style=flat"/> |
| 19 | +</div> |
| 20 | + |
| 21 | +[Packing Input Frame Context in Next-Frame Prediction Models for Video Generation](https://huggingface.co/papers/2504.12626) by Lvmin Zhang and Maneesh Agrawala. |
| 22 | + |
| 23 | +*We present a neural network structure, FramePack, to train next-frame (or next-frame-section) prediction models for video generation. The FramePack compresses input frames to make the transformer context length a fixed number regardless of the video length. As a result, we are able to process a large number of frames using video diffusion with computation bottleneck similar to image diffusion. This also makes the training video batch sizes significantly higher (batch sizes become comparable to image diffusion training). We also propose an anti-drifting sampling method that generates frames in inverted temporal order with early-established endpoints to avoid exposure bias (error accumulation over iterations). Finally, we show that existing video diffusion models can be finetuned with FramePack, and their visual quality may be improved because the next-frame prediction supports more balanced diffusion schedulers with less extreme flow shift timesteps.* |
| 24 | + |
| 25 | +!!! tip |
| 26 | + |
| 27 | + Make sure to check out the Schedulers [guide](../../using-diffusers/schedulers.md) to learn how to explore the tradeoff between scheduler speed and quality, and see the [reuse components across pipelines](../../using-diffusers/loading.md#reuse-a-pipeline) section to learn how to efficiently load the same components into multiple pipelines. |
| 28 | + |
| 29 | +## Available models |
| 30 | + |
| 31 | +| Model name | Description | |
| 32 | +|:--------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |
| 33 | +| - [`lllyasviel/FramePackI2V_HY`](https://huggingface.co/lllyasviel/FramePackI2V_HY) | Trained with the "inverted anti-drifting" strategy as described in the paper. Inference requires setting `sampling_type="inverted_anti_drifting"` when running the pipeline. | |
| 34 | +| - [`lllyasviel/FramePack_F1_I2V_HY_20250503`](https://huggingface.co/lllyasviel/FramePack_F1_I2V_HY_20250503) | Trained with a novel anti-drifting strategy but inference is performed in "vanilla" strategy as described in the paper. Inference requires setting `sampling_type="vanilla"` when running the pipeline. | |
| 35 | + |
| 36 | +## Usage |
| 37 | + |
| 38 | +Refer to the pipeline documentation for basic usage examples. The following section contains examples of offloading, different sampling methods, quantization, and more. |
| 39 | + |
| 40 | +### First and last frame to video |
| 41 | + |
| 42 | +The following example shows how to use Framepack with start and end image controls, using the inverted anti-drifiting sampling model. |
| 43 | + |
| 44 | +```python |
| 45 | +import mindspore as ms |
| 46 | +from mindone.diffusers import HunyuanVideoFramepackPipeline, HunyuanVideoFramepackTransformer3DModel |
| 47 | +from mindone.diffusers.utils import export_to_video, load_image |
| 48 | +from mindone.transformers import SiglipVisionModel |
| 49 | +from transformers import SiglipImageProcessor |
| 50 | +import numpy as np |
| 51 | + |
| 52 | +transformer = HunyuanVideoFramepackTransformer3DModel.from_pretrained( |
| 53 | + "lllyasviel/FramePackI2V_HY", mindspore_dtype=ms.bfloat16 |
| 54 | +) |
| 55 | +feature_extractor = SiglipImageProcessor.from_pretrained( |
| 56 | + "lllyasviel/flux_redux_bfl", subfolder="feature_extractor" |
| 57 | +) |
| 58 | +image_encoder = SiglipVisionModel.from_pretrained( |
| 59 | + "lllyasviel/flux_redux_bfl", subfolder="image_encoder", mindspore_dtype=ms.float16 |
| 60 | +) |
| 61 | +pipe = HunyuanVideoFramepackPipeline.from_pretrained( |
| 62 | + "hunyuanvideo-community/HunyuanVideo", |
| 63 | + transformer=transformer, |
| 64 | + feature_extractor=feature_extractor, |
| 65 | + image_encoder=image_encoder, |
| 66 | + mindspore_dtype=ms.float16, |
| 67 | +) |
| 68 | + |
| 69 | +# Enable memory optimizations |
| 70 | +pipe.vae.enable_tiling() |
| 71 | + |
| 72 | +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." |
| 73 | +first_image = load_image( |
| 74 | + "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/flf2v_input_first_frame.png" |
| 75 | +) |
| 76 | +last_image = load_image( |
| 77 | + "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/flf2v_input_last_frame.png" |
| 78 | +) |
| 79 | +output = pipe( |
| 80 | + image=first_image, |
| 81 | + last_image=last_image, |
| 82 | + prompt=prompt, |
| 83 | + height=512, |
| 84 | + width=512, |
| 85 | + num_frames=91, |
| 86 | + num_inference_steps=30, |
| 87 | + guidance_scale=9.0, |
| 88 | + generator=np.random.Generator(np.random.PCG64(seed=0)), |
| 89 | + sampling_type="inverted_anti_drifting", |
| 90 | +)[0][0] |
| 91 | +export_to_video(output, "output.mp4", fps=30) |
| 92 | +``` |
| 93 | + |
| 94 | +### Vanilla sampling |
| 95 | + |
| 96 | +The following example shows how to use Framepack with the F1 model trained with vanilla sampling but new regulation approach for anti-drifting. |
| 97 | + |
| 98 | +```python |
| 99 | +import mindspore as ms |
| 100 | +from mindone.diffusers import HunyuanVideoFramepackPipeline, HunyuanVideoFramepackTransformer3DModel |
| 101 | +from mindone.diffusers.utils import export_to_video, load_image |
| 102 | +from mindone.transformers import SiglipVisionModel |
| 103 | +from transformers import SiglipImageProcessor |
| 104 | +import numpy as np |
| 105 | + |
| 106 | +transformer = HunyuanVideoFramepackTransformer3DModel.from_pretrained( |
| 107 | + "lllyasviel/FramePack_F1_I2V_HY_20250503", mindspore_dtype=ms.bfloat16 |
| 108 | +) |
| 109 | +feature_extractor = SiglipImageProcessor.from_pretrained( |
| 110 | + "lllyasviel/flux_redux_bfl", subfolder="feature_extractor" |
| 111 | +) |
| 112 | +image_encoder = SiglipVisionModel.from_pretrained( |
| 113 | + "lllyasviel/flux_redux_bfl", subfolder="image_encoder", mindspore_dtype=ms.float16 |
| 114 | +) |
| 115 | +pipe = HunyuanVideoFramepackPipeline.from_pretrained( |
| 116 | + "hunyuanvideo-community/HunyuanVideo", |
| 117 | + transformer=transformer, |
| 118 | + feature_extractor=feature_extractor, |
| 119 | + image_encoder=image_encoder, |
| 120 | + mindspore_dtype=ms.float16, |
| 121 | +) |
| 122 | + |
| 123 | +# Enable memory optimizations |
| 124 | +pipe.vae.enable_tiling() |
| 125 | + |
| 126 | +image = load_image( |
| 127 | + "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/penguin.png" |
| 128 | +) |
| 129 | +output = pipe( |
| 130 | + image=image, |
| 131 | + prompt="A penguin dancing in the snow", |
| 132 | + height=832, |
| 133 | + width=480, |
| 134 | + num_frames=91, |
| 135 | + num_inference_steps=30, |
| 136 | + guidance_scale=9.0, |
| 137 | + generator=np.random.Generator(np.random.PCG64(seed=0)), |
| 138 | + sampling_type="vanilla", |
| 139 | +)[0][0] |
| 140 | +export_to_video(output, "output.mp4", fps=30) |
| 141 | +``` |
| 142 | + |
| 143 | +::: mindone.diffusers.HunyuanVideoFramepackPipeline |
| 144 | + |
| 145 | +::: mindone.diffusers.pipelines.hunyuan_video.pipeline_output.HunyuanVideoPipelineOutput |
0 commit comments