Hugging Face's logo

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

Упаковка контекста входных кадров в моделях предсказания следующего кадра для генерации видео от Lvmin Zhang и Maneesh Agrawala.

Мы представляем структуру нейросети FramePack для обучения моделей предсказания следующего кадра (или следующего сегмента кадра) в генерации видео. FramePack сжимает входные кадры, чтобы длина контекста трансформера оставалась фиксированной независимо от длины видео. В результате мы можем обрабатывать большое количество кадров с помощью видео-диффузии, имея вычислительное узкое место, сопоставимое с диффузией изображений. Это также позволяет значительно увеличить размеры батчей при обучении на видео (размеры батчей становятся сопоставимыми с обучением диффузии изображений). Мы также предлагаем метод антидрейфового сэмплирования, который генерирует кадры в обратном временном порядке с заранее установленными конечными точками, чтобы избежать смещения при экспозиции (накопления ошибок на итерациях). Наконец, мы показываем, что существующие модели видео-диффузии можно дообучить с использованием FramePack, и их визуальное качество может улучшиться, поскольку предсказание следующего кадра поддерживает более сбалансированные диффузионные планировщики с менее экстремальными шагами сдвига потока.

Обязательно ознакомьтесь с руководством по планировщикам, чтобы узнать, как исследовать баланс между скоростью и качеством планировщика, а также с разделом повторное использование компонентов в разных конвейерах, чтобы узнать, как эффективно загружать одни и те же компоненты в несколько конвейеров.

Доступные модели

Название моделиОписание
- lllyasviel/FramePackI2V_HYОбучен с использованием стратегии «inverted anti-drifting», описанной в статье. Для инференса необходимо установить sampling_type="inverted_anti_drifting" при запуске пайплайна.
- lllyasviel/FramePack_F1_I2V_HY_20250503Модель обучена с использованием новой стратегии против дрейфа, однако инференс выполняется в «ванильной» стратегии, как описано в статье. Для инференса необходимо установить sampling_type="vanilla" при запуске пайплайна.

Использование

См. документацию по конвейерам для примеров базового использования. В следующем разделе приведены примеры выгрузки, различных методов выборки, квантования и многое другое.

Первый и последний кадр в видео

В следующем примере показано, как использовать Framepack с управлением стартовым и конечного изображений, применяя инвертированную модель антидрейфовой выборки.

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)

Образец

В следующем примере показано, как использовать Framepack с моделью F1, обученной с помощью обычного сэмплирования, но с новым подходом к регуляции для борьбы с дрейфом.

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)

Групповая разгрузка

Групповая разгрузка (apply_group_offloading()) обеспечивает агрессивную оптимизацию памяти для выгрузки внутренних компонентов любой модели на CPU, при этом, возможно, без дополнительного влияния на время генерации. Если у вас очень мало доступной VRAM, этот подход может подойти вам в зависимости от количества доступной оперативной памяти CPU.

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

класс diffusers.HunyuanVideoFramepackPipeline

< >

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

Параметры

  • text_encoder (LlamaModel) — Llava Llama3-8B.
  • tokenizer (LlamaTokenizer) — токенизатор из Llava Llama3-8B.
  • transformer (HunyuanVideoTransformer3DModel) — Условный Transformer для удаления шума из закодированных латентов изображения.
  • scheduler (FlowMatchEulerDiscreteScheduler) — планировщик, используемый в связке с transformer для удаления шума из закодированных латентов изображения.
  • vae (AutoencoderKLHunyuanVideo) — Модель вариационного автоэнкодера (VAE) для кодирования и декодирования видео в латентные представления и обратно.
  • text_encoder_2 (CLIPTextModel) — CLIP, а именно вариант clip-vit-large-patch14.
  • tokenizer_2 (CLIPTokenizer) — токенизатор класса CLIPTokenizer.

Pipeline для генерации видео из текста с использованием HunyuanVideo.

Эта модель наследуется от DiffusionPipeline. Общую документацию по методам, реализованным для всех пайплайнов (загрузка, сохранение, запуск на конкретном устройстве и т. д.), см. в документации родительского класса.

__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

Параметры

  • image (PIL.Image.Image или np.ndarray или torch.Tensor) — Изображение, которое будет использоваться в качестве начальной точки для генерации видео.
  • last_image (PIL.Image.Image или np.ndarray или torch.Tensor, необязательный) — Необязательное последнее изображение, используемое в качестве конечной точки для генерации видео. Это полезно для создания переходов между двумя изображениями.
  • prompt (str или list[str], необязательный) — Промпт или промпты для управления генерацией изображения. Если не задан, необходимо передать prompt_embeds вместо него.
  • prompt_2 (str or list[str], необязательный) — Промпт или промпты, которые будут переданы в tokenizer_2 и text_encoder_2. Если не задан, вместо него будет использоваться prompt.
  • negative_prompt (str or list[str], необязательный) — Промпт или промпты, которые не должны направлять генерацию изображения. Если не задан, необходимо передать negative_prompt_embeds. Игнорируется, если не используется guidance (то есть игнорируется, если true_cfg_scale не больше 1).
  • negative_prompt_2 (str или list[str], необязательный) — Промпт или промпты, которые не должны направлять генерацию изображения, передаваемые в tokenizer_2 и text_encoder_2. Если не задан, во всех текстовых кодировщиках используется negative_prompt.
  • height (int, по умолчанию 720) — Высота генерируемого изображения в пикселях.
  • width (int, по умолчанию 1280) — Ширина генерируемого изображения в пикселях.
  • num_frames (int, по умолчанию 129) — Количество кадров в сгенерированном видео.
  • latent_window_size (int, по умолчанию 9) — Количество латентных кадров, генерируемых в каждом окне выборки Framepack.
  • num_inference_steps (int, по умолчанию 50) — Количество шагов денойзинга. Увеличение числа шагов денойзинга обычно приводит к повышению качества изображения за счёт замедления инференса.
  • sigmas (list[float], необязательный) — Пользовательские сигмы для процесса удаления шума в планировщиках, поддерживающих аргумент sigmas в их методе set_timesteps. Если не задано, будет использоваться поведение по умолчанию при передаче num_inference_steps.
  • true_cfg_scale (float, необязательный, по умолчанию 1.0) — Если значение больше 1.0 и указан negative_prompt, включает true classifier-free guidance.
  • guidance_scale (float, по умолчанию 6.0) — Масштаб руководства, определенный в Classifier-Free Diffusion Guidance. guidance_scale соответствует w из уравнения 2 статьи Imagen Paper. Масштаб руководства включается при установке guidance_scale > 1. Более высокое значение масштаба руководства способствует генерации изображений, тесно связанных с текстовым prompt, обычно за счет снижения качества изображения. Обратите внимание, что единственная доступная модель HunyuanVideo является дистиллированной по CFG, что означает, что традиционное руководство между безусловным и условным латентным пространством не применяется.
  • num_videos_per_prompt (int, необязательный, по умолчанию 1) — Количество изображений, генерируемых на один промпт.
  • generator (torch.Generator или list[torch.Generator], необязательный) — torch.Generator для обеспечения детерминированности генерации.
  • image_latents (torch.Tensor, необязательный) — Предварительно закодированные латенты изображения. Если не указаны, изображение будет закодировано с помощью VAE.
  • last_image_latents (torch.Tensor, необязательный) — Предварительно закодированные латенты последнего изображения. Если не указаны, последнее изображение будет закодировано с помощью VAE.
  • prompt_embeds (torch.Tensor, необязательный) — Предварительно сгенерированные текстовые эмбеддинги. Можно использовать для простой настройки текстовых входных данных (взвешивание промпта). Если не задано, текстовые эмбеддинги генерируются из входного аргумента prompt.
  • pooled_prompt_embeds (torch.FloatTensor, необязательный) — Предварительно сгенерированные пул-эмбеддинги текста. Можно использовать для простой настройки текстовых входных данных, например для взвешивания промпта. Если не предоставлено, пул-эмбеддинги текста будут сгенерированы из входного аргумента prompt.
  • negative_prompt_embeds (torch.FloatTensor, необязательный) — Предварительно сгенерированные отрицательные текстовые эмбеддинги. Можно использовать для простой настройки текстовых входных данных, например для взвешивания промпта. Если не передано, negative_prompt_embeds будет сгенерировано из входного аргумента negative_prompt.
  • negative_pooled_prompt_embeds (torch.FloatTensor, необязательный) — Предварительно сгенерированные отрицательные пул-эмбеддинги текста. Можно использовать для простой настройки текстовых входных данных, например для взвешивания промпта. Если не передан, пул-эмбеддинги negative_prompt_embeds будут сгенерированы из входного аргумента negative_prompt.
  • prompt_attention_mask (torch.Tensor, необязательный) — Маска внимания для prompt_embeds. Обязателен, если prompt_embeds передается напрямую.
  • negative_prompt_attention_mask (torch.Tensor, необязательный) — Маска внимания для negative_prompt_embeds. Обязателен, если negative_prompt_embeds передается напрямую.
  • output_type (str, необязательный, по умолчанию "pil") — Формат вывода сгенерированного изображения. Выберите между PIL.Image и np.array.
  • return_dict (bool, необязательный, по умолчанию True) — Определяет, следует ли возвращать HunyuanVideoFramepackPipelineOutput вместо обычного кортежа.
  • attention_kwargs (dict, необязательный) — Словарь kwargs, который при указании передается в AttentionProcessor, определенный в self.processor в diffusers.models.attention_processor.
  • prompt_template (dict, необязательный) — Шаблон, используемый для форматирования промпта перед кодированием. По умолчанию используется шаблон по умолчанию модели.
  • max_sequence_length (int, необязательный, по умолчанию 256) — Максимальная длина последовательности, используемая для кодировщика промпта.
  • sampling_type (FramepackSamplingType, необязательный) — Стратегия сэмплирования Framepack, используемая при итерации по окнам латентных представлений.
  • callback_on_step_end (Callable, PipelineCallback, MultiPipelineCallbacks, необязательный) — функция или подкласс PipelineCallback или MultiPipelineCallbacks, вызываемая в конце каждого шага денойзинга во время инференса. Аргументы: callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict). callback_kwargs будет содержать список всех тензоров, указанных в callback_on_step_end_tensor_inputs.
  • callback_on_step_end_tensor_inputs (list, необязательный) — Список тензорных входных данных для функции callback_on_step_end. Тензоры, указанные в списке, будут переданы в качестве аргумента callback_kwargs. Вы сможете включать только переменные, перечисленные в атрибуте ._callback_tensor_inputs вашего класса пайплайна.

Возвращает

~HunyuanVideoFramepackPipelineOutput или tuple

Если return_dict равно True, возвращается HunyuanVideoFramepackPipelineOutput, иначе возвращается tuple, где первый элемент — это список сгенерированных изображений, а второй элемент — список значений bool, указывающих, содержит ли соответствующее сгенерированное изображение контент, нежелательный для работы (nsfw).

Функция вызова конвейера для генерации.

Примеры:

Изображение в видео
>>> 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)
Первое и последнее изображение для создания видео
>>> 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

класс diffusers.pipelines.hunyuan_video.pipeline_output.HunyuanVideoPipelineOutput

< >

( frames: Tensor )

Параметры

  • frames (torch.Tensor, np.ndarray или list[list[PIL.Image.Image]]) — список видеовыходов. Может быть вложенным списком длины batch_size, где каждый под-список содержит последовательности денойзированных изображений PIL длины num_frames. Также может быть массивом NumPy или тензором Torch с формой (batch_size, num_frames, channels, height, width).

Класс вывода для пайплайнов HunyuanVideo.

Update on GitHub

←Cosmos3 Helios→