Hugging Face's logo

svjack
/
YiChen_FramePack_lora_early

Model card Files
xet
Community
YiChen_FramePack_lora_early / docs /framepack.md
svjack's picture
svjack
Upload folder using huggingface_hub
ef46f0f verified
preview code
|
raw
history blame
28 kB

FramePack

Overview / 概要

This document describes the usage of the FramePack architecture within the Musubi Tuner framework. FramePack is a novel video generation architecture developed by lllyasviel.

Key differences from HunyuanVideo:

  • FramePack only supports Image-to-Video (I2V) generation. Text-to-Video (T2V) is not supported.
  • It utilizes a different DiT model architecture and requires an additional Image Encoder. VAE is same as HunyuanVideo. Text Encoders seem to be the same as HunyuanVideo but we employ the original FramePack method to utilize them.
  • Caching and training scripts are specific to FramePack (fpack_*.py).
  • Due to its progressive generation nature, VRAM usage can be significantly lower, especially for longer videos, compared to other architectures.

This feature is experimental.

日本語 このドキュメントは、Musubi Tunerフレームワーク内での[FramePack](https://github.com/lllyasviel/FramePack) アーキテクチャの使用法について説明しています。FramePackは、lllyasviel氏にによって開発された新しいビデオ生成アーキテクチャです。

HunyuanVideoとの主な違いは次のとおりです。

  • FramePackは、画像からビデオ（I2V）生成のみをサポートしています。テキストからビデオ（T2V）はサポートされていません。
  • 異なるDiTモデルアーキテクチャを使用し、追加の画像エンコーダーが必要です。VAEはHunyuanVideoと同じです。テキストエンコーダーはHunyuanVideoと同じと思われますが、FramePack公式と同じ方法で推論を行っています。
  • キャッシングと学習スクリプトはFramePack専用（fpack_*.py）です。
  • セクションずつ生成するため、他のアーキテクチャと比較して、特に長いビデオの場合、VRAM使用量が大幅に少なくなる可能性があります。

この機能は実験的なものですです。

Download the model / モデルのダウンロード

You need to download the DiT, VAE, Text Encoder 1 (LLaMA), Text Encoder 2 (CLIP), and Image Encoder (SigLIP) models specifically for FramePack. Several download options are available for each component.

*Note: The weights are publicly available on the following page: maybleMyers/framepack_h1111. Thank you maybleMyers!

DiT Model

Choose one of the following methods:

  1. From lllyasviel's Hugging Face repo: Download the three .safetensors files (starting with diffusion_pytorch_model-00001-of-00003.safetensors) from lllyasviel/FramePackI2V_HY. Specify the path to the first file (...-00001-of-00003.safetensors) as the --dit argument.
  2. From local FramePack installation: If you have cloned and run the official FramePack repository, the model might be downloaded locally. Specify the path to the snapshot directory, e.g., path/to/FramePack/hf_download/hub/models--lllyasviel--FramePackI2V_HY/snapshots/<hex-uuid-folder>.
  3. From Kijai's Hugging Face repo: Download the single file FramePackI2V_HY_bf16.safetensors from Kijai/HunyuanVideo_comfy. Specify the path to this file as the --dit argument.

VAE Model

Choose one of the following methods:

  1. Use official HunyuanVideo VAE: Follow the instructions in the main README.md.
  2. From hunyuanvideo-community Hugging Face repo: Download vae/diffusion_pytorch_model.safetensors from hunyuanvideo-community/HunyuanVideo.
  3. From local FramePack installation: If you have cloned and run the official FramePack repository, the VAE might be downloaded locally within the HunyuanVideo community model snapshot. Specify the path to the snapshot directory, e.g., path/to/FramePack/hf_download/hub/models--hunyuanvideo-community--HunyuanVideo/snapshots/<hex-uuid-folder>.

Text Encoder 1 (LLaMA) Model

Choose one of the following methods:

  1. From Comfy-Org Hugging Face repo: Download split_files/text_encoders/llava_llama3_fp16.safetensors from Comfy-Org/HunyuanVideo_repackaged.
  2. From hunyuanvideo-community Hugging Face repo: Download the four .safetensors files (starting with text_encoder/model-00001-of-00004.safetensors) from hunyuanvideo-community/HunyuanVideo. Specify the path to the first file (...-00001-of-00004.safetensors) as the --text_encoder1 argument.
  3. From local FramePack installation: (Same as VAE) Specify the path to the HunyuanVideo community model snapshot directory, e.g., path/to/FramePack/hf_download/hub/models--hunyuanvideo-community--HunyuanVideo/snapshots/<hex-uuid-folder>.

Text Encoder 2 (CLIP) Model

Choose one of the following methods:

  1. From Comfy-Org Hugging Face repo: Download split_files/text_encoders/clip_l.safetensors from Comfy-Org/HunyuanVideo_repackaged.
  2. From hunyuanvideo-community Hugging Face repo: Download text_encoder_2/model.safetensors from hunyuanvideo-community/HunyuanVideo.
  3. From local FramePack installation: (Same as VAE) Specify the path to the HunyuanVideo community model snapshot directory, e.g., path/to/FramePack/hf_download/hub/models--hunyuanvideo-community--HunyuanVideo/snapshots/<hex-uuid-folder>.

Image Encoder (SigLIP) Model

Choose one of the following methods:

  1. From Comfy-Org Hugging Face repo: Download sigclip_vision_patch14_384.safetensors from Comfy-Org/sigclip_vision_384.
  2. From lllyasviel's Hugging Face repo: Download image_encoder/model.safetensors from lllyasviel/flux_redux_bfl.
  3. From local FramePack installation: If you have cloned and run the official FramePack repository, the model might be downloaded locally. Specify the path to the snapshot directory, e.g., path/to/FramePack/hf_download/hub/models--lllyasviel--flux_redux_bfl/snapshots/<hex-uuid-folder>.
日本語

※以下のページに重みが一括で公開されています。maybleMyers 氏に感謝いたします。: https://huggingface.co/maybleMyers/framepack_h1111

DiT、VAE、テキストエンコーダー1（LLaMA）、テキストエンコーダー2（CLIP）、および画像エンコーダー（SigLIP）モデルは複数の方法でダウンロードできます。英語の説明を参考にして、ダウンロードしてください。

FramePack公式のリポジトリをクローンして実行した場合、モデルはローカルにダウンロードされている可能性があります。スナップショットディレクトリへのパスを指定してください。例：path/to/FramePack/hf_download/hub/models--lllyasviel--flux_redux_bfl/snapshots/<hex-uuid-folder>

HunyuanVideoの推論をComfyUIですでに行っている場合、いくつかのモデルはすでにダウンロードされている可能性があります。

Pre-caching / 事前キャッシング

The default resolution for FramePack is 640x640. See the source code for the default resolution of each bucket.

The dataset for training must be a video dataset. Image datasets are not supported. You can train on videos of any length. Specify frame_extraction as full and set max_frames to a sufficiently large value. However, if the video is too long, you may run out of VRAM during VAE encoding.

Latent Pre-caching / latentの事前キャッシング

Latent pre-caching uses a dedicated script for FramePack. You must provide the Image Encoder model.

python fpack_cache_latents.py \
    --dataset_config path/to/toml --vanilla_sampling \
    --vae path/to/vae_model.safetensors \
    --image_encoder path/to/image_encoder_model.safetensors \
    --vae_chunk_size 32 --vae_spatial_tile_sample_min_size 128

Key differences from HunyuanVideo caching:

  • Uses fpack_cache_latents.py.
  • Requires the --image_encoder argument pointing to the downloaded SigLIP model.
  • You can use the --latent_window_size argument (default 9) which defines the size of the latent sections FramePack processes (omitted in the example). This value should typically not be changed unless you understand the implications.
  • The script generates multiple cache files per video, each corresponding to a different section, with the section index appended to the filename (e.g., ..._frame_pos-0000-count_... becomes ..._frame_pos-0000-0000-count_..., ..._frame_pos-0000-0001-count_..., etc.).
  • Image embeddings are calculated using the Image Encoder and stored in the cache files alongside the latents.

By default, the sampling method used is Inverted anti-drifting (the same as during inference, using the latent and index in reverse order), described in the paper. You can switch to Vanilla sampling in the paper (using the temporally ordered latent and index) by specifying --vanilla_sampling. Preliminary tests suggest that Vanilla sampling may yield better quality. If you change this option, please overwrite the existing cache without specifying --skip_existing.

For VRAM savings during VAE decoding, consider using --vae_chunk_size and --vae_spatial_tile_sample_min_size. If VRAM is overflowing and using shared memory, it is recommended to set --vae_chunk_size to 16 or 8, and --vae_spatial_tile_sample_min_size to 64 or 32.

日本語 FramePackのデフォルト解像度は640x640です。各バケットのデフォルト解像度については、[ソースコード](../frame_pack/bucket_tools.py)を参照してください。

画像データセットでの学習は行えません。また動画の長さによらず学習可能です。 frame_extraction に full を指定して、max_frames に十分に大きな値を指定してください。ただし、あまりにも長いとVAEのencodeでVRAMが不足する可能性があります。

latentの事前キャッシングはFramePack専用のスクリプトを使用します。画像エンコーダーモデルを指定する必要があります。

HunyuanVideoのキャッシングとの主な違いは次のとおりです。

  • fpack_cache_latents.pyを使用します。
  • ダウンロードしたSigLIPモデルを指す--image_encoder引数が必要です。
  • --latent_window_size引数（デフォルト9）を指定できます（例では省略）。これは、FramePackが処理するlatentセクションのサイズを定義します。この値は、影響を理解していない限り、通常変更しないでください。
  • スクリプトは、各ビデオに対して複数のキャッシュファイルを生成します。各ファイルは異なるセクションに対応し、セクションインデックスがファイル名に追加されます（例：..._frame_pos-0000-count_...は..._frame_pos-0000-0000-count_...、..._frame_pos-0000-0001-count_...などになります）。
  • 画像埋め込みは画像エンコーダーを使用して計算され、latentとともにキャッシュファイルに保存されます。

デフォルトでは、論文のサンプリング方法 Inverted anti-drifting （推論時と同じ、逆順の latent と index を使用）を使用します。--vanilla_samplingを指定すると Vanilla sampling （時間順の latent と index を使用）に変更できます。簡単なテストの結果では、Vanilla sampling の方が品質が良いようです。このオプションの有無を変更する場合には --skip_existing を指定せずに既存のキャッシュを上書きしてください。

VAEのdecode時のVRAM節約のために、--vae_chunk_sizeと--vae_spatial_tile_sample_min_sizeを使用することを検討してください。VRAMがあふれて共有メモリを使用している場合には、--vae_chunk_sizeを16、8などに、--vae_spatial_tile_sample_min_sizeを64、32などに変更することをお勧めします。

Text Encoder Output Pre-caching / テキストエンコーダー出力の事前キャッシング

Text encoder output pre-caching also uses a dedicated script.

python fpack_cache_text_encoder_outputs.py \
    --dataset_config path/to/toml \
    --text_encoder1 path/to/text_encoder1 \
    --text_encoder2 path/to/text_encoder2 \
    --batch_size 16

Key differences from HunyuanVideo caching:

  • Uses fpack_cache_text_encoder_outputs.py.
  • Requires both --text_encoder1 (LLaMA) and --text_encoder2 (CLIP) arguments.
  • Uses --fp8_llm option to run the LLaMA Text Encoder 1 in fp8 mode for VRAM savings (similar to --fp8_t5 in Wan2.1).
  • Saves LLaMA embeddings, attention mask, and CLIP pooler output to the cache file.
日本語 テキストエンコーダー出力の事前キャッシングも専用のスクリプトを使用します。

HunyuanVideoのキャッシングとの主な違いは次のとおりです。

  • fpack_cache_text_encoder_outputs.pyを使用します。
  • LLaMAとCLIPの両方の引数が必要です。
  • LLaMAテキストエンコーダー1をfp8モードで実行するための--fp8_llmオプションを使用します（Wan2.1の--fp8_t5に似ています）。
  • LLaMAの埋め込み、アテンションマスク、CLIPのプーラー出力をキャッシュファイルに保存します。

Training / 学習

Training

Training uses a dedicated script fpack_train_network.py. Remember FramePack only supports I2V training.

accelerate launch --num_cpu_threads_per_process 1 --mixed_precision bf16 fpack_train_network.py \
    --dit path/to/dit_model \
    --vae path/to/vae_model.safetensors \
    --text_encoder1 path/to/text_encoder1 \
    --text_encoder2 path/to/text_encoder2 \
    --image_encoder path/to/image_encoder_model.safetensors \
    --dataset_config path/to/toml \
    --sdpa --mixed_precision bf16 \
    --optimizer_type adamw8bit --learning_rate 2e-4 --gradient_checkpointing \
    --timestep_sampling shift --weighting_scheme none --discrete_flow_shift 3.0 \
    --max_data_loader_n_workers 2 --persistent_data_loader_workers \
    --network_module networks.lora_framepack --network_dim 32 \
    --max_train_epochs 16 --save_every_n_epochs 1 --seed 42 \
    --output_dir path/to/output_dir --output_name name-of-lora

If you use the command prompt (Windows, not PowerShell), you may need to write them in a single line, or use ^ at the end of each line to continue the command.

The maximum value for --blocks_to_swap is 36. The default resolution for FramePack is 640x640, which requires around 17GB of VRAM. If you run out of VRAM, consider lowering the dataset resolution.

Key differences from HunyuanVideo training:

  • Uses fpack_train_network.py.
  • Requires specifying --vae, --text_encoder1, --text_encoder2, and --image_encoder.
  • Requires specifying --network_module networks.lora_framepack.
  • Optional --latent_window_size argument (default 9, should match caching).
  • Memory saving options like --fp8_base (for DiT) and --fp8_llm (for Text Encoder 1) are available. --fp8_scaled is recommended when using --fp8_base for DiT.
  • --vae_chunk_size and --vae_spatial_tile_sample_min_size options are available for the VAE to prevent out-of-memory during sampling (similar to caching).
  • --gradient_checkpointing is available for memory savings.

Training settings (learning rate, optimizers, etc.) are experimental. Feedback is welcome.

日本語 FramePackの学習は専用のスクリプト`fpack_train_network.py`を使用します。FramePackはI2V学習のみをサポートしています。

コマンド記述例は英語版を参考にしてください。WindowsでPowerShellではなくコマンドプロンプトを使用している場合、コマンドを1行で記述するか、各行の末尾に^を付けてコマンドを続ける必要があります。

--blocks_to_swapの最大値は36です。FramePackのデフォルト解像度（640x640）では、17GB程度のVRAMが必要です。VRAM容量が不足する場合は、データセットの解像度を下げてください。

HunyuanVideoの学習との主な違いは次のとおりです。

  • fpack_train_network.pyを使用します。
  • --vae、--text_encoder1、--text_encoder2、--image_encoderを指定する必要があります。
  • --network_module networks.lora_framepackを指定する必要があります。
  • 必要に応じて--latent_window_size引数（デフォルト9）を指定できます（キャッシング時と一致させる必要があります）。
  • --fp8_base（DiT用）や--fp8_llm（テキストエンコーダー1用）などのメモリ節約オプションが利用可能です。--fp8_base指定時は、--fp8_scaledを使用することをお勧めします。
  • サンプル生成時にメモリ不足を防ぐため、VAE用の--vae_chunk_size、--vae_spatial_tile_sample_min_sizeオプションが利用可能です（キャッシング時と同様）。
  • メモリ節約のために--gradient_checkpointingが利用可能です。

Inference

Inference uses a dedicated script fpack_generate_video.py.

python fpack_generate_video.py \
    --dit path/to/dit_model \
    --vae path/to/vae_model.safetensors \
    --text_encoder1 path/to/text_encoder1 \
    --text_encoder2 path/to/text_encoder2 \
    --image_encoder path/to/image_encoder_model.safetensors \
    --image_path path/to/start_image.jpg \
    --prompt "A cat walks on the grass, realistic style." \
    --video_size 512 768 --video_seconds 5 --fps 30 --infer_steps 25 \
    --attn_mode sdpa --fp8_scaled \
    --vae_chunk_size 32 --vae_spatial_tile_sample_min_size 128 \
    --save_path path/to/save/dir --output_type both \
    --seed 1234 --lora_multiplier 1.0 --lora_weight path/to/lora.safetensors

Key differences from HunyuanVideo inference:

  • Uses fpack_generate_video.py.
  • Requires specifying --vae, --text_encoder1, --text_encoder2, and --image_encoder.
  • Requires specifying --image_path for the starting frame.
  • Requires specifying --video_seconds (length of the video in seconds).
  • --video_size is the size of the generated video, height and width are specified in that order.
  • --prompt: Prompt for generation.
  • Optional --latent_window_size argument (default 9, should match caching and training).
  • --fp8_scaled option is available for DiT to reduce memory usage. Quality may be slightly lower. --fp8_llm option is available to reduce memory usage of Text Encoder 1. --fp8 alone is also an option for DiT but --fp8_scaled potentially offers better quality.
  • LoRA loading options (--lora_weight, --lora_multiplier, --include_patterns, --exclude_patterns) are available. --lycoris is also supported.
  • --embedded_cfg_scale (default 10.0) controls the distilled guidance scale.
  • --guidance_scale (default 1.0) controls the standard classifier-free guidance scale. Changing this from 1.0 is generally not recommended for the base FramePack model.
  • --guidance_rescale (default 0.0) is available but typically not needed.
  • --bulk_decode option can decode all frames at once, potentially faster but uses more VRAM during decoding. --vae_chunk_size and --vae_spatial_tile_sample_min_size options are recommended to prevent out-of-memory errors.
  • --sample_solver (default unipc) is available but only unipc is implemented.
  • --save_merged_model option is available to save the DiT model after merging LoRA weights. Inference is skipped if this is specified.
  • Batch and interactive modes (--from_file, --interactive) are not yet implemented for FramePack generation.

Section-specific Prompts

You can now provide different prompts for different sections of the video using the --prompt argument. Use ;;; to separate sections and specify the starting section index followed by a colon (e.g., 0:prompt A;;;3:prompt B). Each definition should be in the format INDEX:PROMPT_TEXT.

  • INDEX can be:
    • A non-negative integer (e.g., 0, 3): The prompt applies to this section index.
    • A negative integer (e.g., -1, -2): The prompt applies to the k-th section from the end (e.g., -1 for the last section, -2 for the second to last).
    • A range (e.g., 0-2, 3-5): The prompt applies to all sections within this inclusive range.
  • If some parts are not specified with an index, the prompt associated with index 0 will be used (e.g., 0:prompt A;;;-1:prompt B means the last section is prompt B, and all others are prompt A).
    • This can be used with the end image guidance feature to specify a different prompt for the last section.
  • If no index is specified for a part (e.g., prompt A;;;3:prompt B), it defaults to index 0.
  • Example 1: "0:A cat walks;;;3:The cat sits down;;;-1:The cat sleeps"
  • Example 2: "0:A cat turns around;;;-1:A cat walks towards the camera"

End Image Guidance

Specify an --end_image_path to guide the generation towards a specific final frame. This is highly experimental.

  • --end_image_path : Path to an image to be used as a target for the final frame. The generation process for the last section will be conditioned on this image's VAE latent and image encoder embedding. This may affect the naturalness of the transition into the final frames.

Other options like --video_size, --fps, --infer_steps, --save_path, --output_type, --seed, --attn_mode, --blocks_to_swap, --vae_chunk_size, --vae_spatial_tile_sample_min_size function similarly to HunyuanVideo/Wan2.1 where applicable.

The maximum value for --blocks_to_swap is 38.

日本語

FramePackの推論は専用のスクリプトfpack_generate_video.pyを使用します。コマンド記述例は英語版を参考にしてください。

HunyuanVideoの推論との主な違いは次のとおりです。

  • fpack_generate_video.pyを使用します。
  • --vae、--text_encoder1、--text_encoder2、--image_encoderを指定する必要があります。
  • --image_pathを指定する必要があります（開始フレーム）。
  • --video_secondsを指定する必要があります（秒単位でのビデオの長さを指定）。
  • --video_sizeは生成するビデオのサイズで、高さと幅をその順番で指定します。
  • --prompt: 生成用のプロンプトです。
  • 必要に応じて--latent_window_size引数（デフォルト9）を指定できます（キャッシング時、学習時と一致させる必要があります）。
  • DiTのメモリ使用量を削減するために、--fp8_scaledオプションを指定可能です。品質はやや低下する可能性があります。またText Encoder 1のメモリ使用量を削減するために、--fp8_llmオプションを指定可能です。DiT用に--fp8単独のオプションも用意されていますが、--fp8_scaledの方が品質が良い可能性があります。
  • LoRAの読み込みオプション（--lora_weight、--lora_multiplier、--include_patterns、--exclude_patterns）が利用可能です。LyCORISもサポートされています。
  • --embedded_cfg_scale（デフォルト10.0）は、蒸留されたガイダンススケールを制御します。通常は変更しないでください。
  • --guidance_scale（デフォルト1.0）は、標準の分類器フリーガイダンススケールを制御します。FramePackモデルのベースモデルでは、通常1.0から変更しないことをお勧めします。
  • --guidance_rescale（デフォルト0.0）も利用可能ですが、通常は必要ありません。
  • --bulk_decodeオプションは、すべてのフレームを一度にデコードできるオプションです。高速ですが、デコード中にVRAMを多く使用します。VRAM不足エラーを防ぐために、--vae_chunk_sizeと--vae_spatial_tile_sample_min_sizeオプションを指定することをお勧めします。
  • --sample_solver（デフォルトunipc）は利用可能ですが、unipcのみが実装されています。
  • --save_merged_modelオプションは、LoRAの重みをマージした後にDiTモデルを保存するためのオプションです。これを指定すると推論はスキップされます。
  • バッチモードとインタラクティブモード（--from_file、--interactive）はFramePack生成にはまだ実装されていません。

セクション別プロンプト:

--prompt引数を使用して、ビデオの異なるセクションに異なるプロンプトを指定できるようになりました。セクションを区切るには;;;を使用し、開始セクションインデックスの後にコロンを付けて指定します（例：0:プロンプトA;;;3:プロンプトB）。各定義はインデックス:プロンプトテキストの形式である必要があります。

  • インデックスには以下を指定できます：
    • 非負の整数（例：0, 3）：このセクションインデックスに対してプロンプトが適用されます。
    • 負の整数（例：-1, -2）：最後からk番目のセクションにプロンプトが適用されます（例：-1は最後のセクション、-2は最後から2番目のセクション）。
    • 範囲（例：0-2, 3-5）：この範囲（両端を含む）内のすべてのセクションにプロンプトが適用されます。
  • インデックスが指定されていない部分は、インデックス0のプロンプトが適用されます。（例：0:プロンプトA;;;-1:プロンプトBなら、一番最後がプロンプトB、それ以外はプロンプトAになります。）
    • 終端画像ガイダンスを使用する場合、この形式をお勧めします。
  • ある部分にインデックスが指定されていない場合（例：プロンプトA;;;3:プロンプトB）、インデックス0として扱われます。

終端画像ガイダンス

--end_image_pathを指定して、生成を特定の最終フレームに誘導します。これは非常に実験的な機能です。

  • --end_image_path : 最終フレームのターゲットとして使用する画像へのパス。最後のセクションの生成プロセスは、この画像を初期画像として生成されます。これは最終フレームへの遷移の自然さに影響を与える可能性があります。

--video_size、--fps、--infer_steps、--save_path、--output_type、--seed、--attn_mode、--blocks_to_swap、--vae_chunk_size、--vae_spatial_tile_sample_min_sizeなどの他のオプションは、HunyuanVideo/Wan2.1と同様に機能します。

--blocks_to_swapの最大値は38です。