Hugging Face's logo

Diffusers documentation

Framepack

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Framepack

LoRA

Empacotamento do contexto de quadros de entrada em modelos de previsão de próximo quadro para geração de vídeo por Lvmin Zhang e Maneesh Agrawala.

Apresentamos uma estrutura de rede neural, FramePack, para treinar modelos de previsão do próximo quadro (ou da próxima seção de quadro) para geração de vídeo. O FramePack comprime os quadros de entrada para tornar o comprimento do contexto do transformer um número fixo, independentemente do comprimento do vídeo. Como resultado, somos capazes de processar um grande número de quadros usando difusão de vídeo com gargalo de computação semelhante ao da difusão de imagem. Isso também faz com que os tamanhos de lote de treinamento de vídeo sejam significativamente maiores (os tamanhos de lote se tornam comparáveis aos do treinamento de difusão de imagem). Também propomos um método de amostragem anti-desvio que gera quadros em ordem temporal invertida com pontos finais estabelecidos precocemente para evitar o viés de exposição (acúmulo de erro ao longo das iterações). Por fim, mostramos que modelos existentes de difusão de vídeo podem ser ajustados com o FramePack, e sua qualidade visual pode ser melhorada porque a previsão do próximo quadro suporta agendadores de difusão mais equilibrados com passos de tempo de deslocamento de fluxo menos extremos.

Certifique-se de consultar o guia de Schedulers para aprender a explorar o compromisso entre a velocidade e a qualidade do scheduler, e veja a seção reutilização de componentes entre pipelines para aprender a carregar eficientemente os mesmos componentes em vários pipelines.

Modelos disponíveis

Nome do modeloDescrição
- lllyasviel/FramePackI2V_HYTreinado com a estratégia de “anti-drifting invertido” descrita no artigo. A inferência requer definir sampling_type="inverted_anti_drifting" ao executar o pipeline.
- lllyasviel/FramePack_F1_I2V_HY_20250503Treinado com uma estratégia inédita de anti-drifting, mas a inferência é executada na estratégia “vanilla”, conforme descrito no artigo. A inferência requer definir sampling_type="vanilla" ao executar o pipeline.

Uso

Consulte a documentação do pipeline para exemplos básicos de uso. A seção a seguir contém exemplos de offloading, diferentes métodos de amostragem, quantização e mais.

Primeiro e último quadro para vídeo

O exemplo a seguir mostra como usar o Framepack com controles de imagem inicial e final, utilizando o modelo de amostragem anti-drifiting invertido.

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)

Amostragem simples

O exemplo a seguir mostra como usar o Framepack com o modelo F1 treinado com amostragem vanilla, mas com uma nova abordagem de regulação para evitar o desvio.

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)

Descarregamento em grupo

O offloading por grupo (apply_group_offloading()) fornece otimizações agressivas de memória para mover partes internas de qualquer modelo para a CPU, possivelmente sem sobrecarga adicional no tempo de geração. Se você tiver pouca VRAM disponível, essa abordagem pode ser adequada para você, dependendo da quantidade de RAM de CPU disponível.

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

< >

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

Parâmetros

Pipeline para geração de texto para vídeo usando HunyuanVideo.

Este modelo herda de DiffusionPipeline. Consulte a documentação da superclasse para os métodos genéricos implementados para todos os pipelines (download, salvamento, execução em um dispositivo específico, etc.).

__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

Parâmetros

  • image (PIL.Image.Image ou np.ndarray ou torch.Tensor) — A imagem a ser usada como ponto de partida para a geração do vídeo.
  • last_image (PIL.Image.Image ou np.ndarray ou torch.Tensor, opcional) — A última imagem opcional a ser usada como ponto final para a geração do vídeo. Isso é útil para gerar transições entre duas imagens.
  • prompt (str ou list[str], opcional) — O prompt ou os prompts para orientar a geração da imagem. Se não for definido, é necessário passar prompt_embeds em vez disso.
  • prompt_2 (str ou list[str], opcional) — O prompt ou os prompts a serem enviados para tokenizer_2 e text_encoder_2. Se não definido, prompt será usado no lugar.
  • negative_prompt (str ou list[str], opcional) — O prompt ou os prompts que não devem orientar a geração da imagem. Se não for definido, é necessário passar negative_prompt_embeds em vez disso. Ignorado quando não se usa orientação (ou seja, ignorado se true_cfg_scale não for maior que 1).
  • negative_prompt_2 (str ou list[str], opcional) — O prompt ou os prompts que não devem orientar a geração da imagem a serem enviados para tokenizer_2 e text_encoder_2. Se não definido, negative_prompt é usado em todos os text-encoders.
  • height (int, padrão 720) — A altura da imagem gerada, em pixels.
  • width (int, padrão 1280) — A largura em pixels da imagem gerada.
  • num_frames (int, padrão 129) — O número de quadros no vídeo gerado.
  • latent_window_size (int, padrão 9) — Número de quadros latentes produzidos por janela de amostragem do Framepack.
  • num_inference_steps (int, padrão 50) — O número de etapas de desruido. Mais etapas de desruido geralmente resultam em uma imagem de maior qualidade, em detrimento de uma inferência mais lenta.
  • sigmas (list[float], opcional) — Sigmas personalizados para usar no processo de desruidamento com agendadores que suportam um argumento sigmas em seu método set_timesteps. Se não definido, o comportamento padrão quando num_inference_steps é passado será usado.
  • true_cfg_scale (float, opcional, padrão 1.0) — Quando > 1.0 e um negative_prompt é fornecido, habilita a orientação livre de classificador verdadeira.
  • guidance_scale (float, padrão 6.0) — Escala de orientação definida em Classifier-Free Diffusion Guidance. guidance_scale é definido como w da equação 2 do Imagen Paper. A escala de orientação é ativada ao definir guidance_scale > 1. Uma escala de orientação maior incentiva a geração de imagens que estão intimamente ligadas ao prompt de texto, geralmente em detrimento de uma menor qualidade de imagem. Observe que o único modelo HunyuanVideo disponível é destilado por CFG, o que significa que a orientação tradicional entre o latente incondicional e o latente condicional não é aplicada.
  • num_videos_per_prompt (int, opcional, padrão 1) — O número de imagens a serem geradas por prompt.
  • generator (torch.Generator ou list[torch.Generator], opcional) — Um torch.Generator para tornar a geração determinística.
  • image_latents (torch.Tensor, opcional) — Latentes de imagem pré-codificados. Se não fornecidos, a imagem será codificada usando o VAE.
  • last_image_latents (torch.Tensor, opcional) — Latentes da última imagem pré-codificados. Se não fornecidos, a última imagem será codificada usando o VAE.
  • prompt_embeds (torch.Tensor, opcional) — Incorporações de texto pré-geradas. Podem ser usadas para ajustar facilmente as entradas de texto (ponderação do prompt). Se não forem fornecidas, as incorporações de texto são geradas a partir do argumento de entrada prompt.
  • pooled_prompt_embeds (torch.FloatTensor, opcional) — Embeddings de texto agrupados pré-gerados. Podem ser usados para ajustar facilmente as entradas de texto, por exemplo, ponderação de prompts. Se não fornecidos, os embeddings de texto agrupados serão gerados a partir do argumento de entrada prompt.
  • negative_prompt_embeds (torch.FloatTensor, opcional) — Incorporações de texto negativas pré-geradas. Pode ser usado para ajustar facilmente as entradas de texto, por exemplo, ponderação de prompts. Se não for fornecido, negative_prompt_embeds será gerado a partir do argumento de entrada negative_prompt.
  • negative_pooled_prompt_embeds (torch.FloatTensor, opcional) — Embeddings de texto negativo pré-gerados. Pode ser usado para ajustar facilmente as entradas de texto, por exemplo, ponderação de prompt. Se não for fornecido, os pooled negative_prompt_embeds serão gerados a partir do argumento de entrada negative_prompt.
  • prompt_attention_mask (torch.Tensor, opcional) — Máscara de atenção para prompt_embeds. Obrigatório quando prompt_embeds é passado diretamente.
  • negative_prompt_attention_mask (torch.Tensor, opcional) — Máscara de atenção para negative_prompt_embeds. Obrigatória quando negative_prompt_embeds é passada diretamente.
  • output_type (str, opcional, padrão "pil") — O formato de saída da imagem gerada. Escolha entre PIL.Image ou np.array.
  • return_dict (bool, opcional, padrão True) — Se deve ou não retornar um HunyuanVideoFramepackPipelineOutput em vez de uma tupla simples.
  • attention_kwargs (dict, opcional) — Um dicionário de kwargs que, se especificado, é passado ao AttentionProcessor conforme definido em self.processor em diffusers.models.attention_processor.
  • prompt_template (dict, opcional) — Modelo usado para formatar o prompt antes da codificação. O padrão é o modelo padrão do modelo.
  • max_sequence_length (int, opcional, padrão 256) — Comprimento máximo da sequência a ser usado para o codificador de prompt.
  • sampling_type (FramepackSamplingType, opcional) — A estratégia de amostragem Framepack a ser usada ao iterar sobre janelas latentes.
  • callback_on_step_end (Callable, PipelineCallback, MultiPipelineCallbacks, opcional) — Uma função ou uma subclasse de PipelineCallback ou MultiPipelineCallbacks que é chamada no final de cada etapa de remoção de ruído durante a inferência, com os seguintes argumentos: callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict). callback_kwargs incluirá uma lista de todos os tensores, conforme especificado por callback_on_step_end_tensor_inputs.
  • callback_on_step_end_tensor_inputs (list, opcional) — A lista de entradas de tensor para a função callback_on_step_end. Os tensores especificados na lista serão passados como argumento callback_kwargs. Você só poderá incluir variáveis listadas no atributo ._callback_tensor_inputs da sua classe de pipeline.

Retorna

~HunyuanVideoFramepackPipelineOutput ou tuple

Se return_dict for True, HunyuanVideoFramepackPipelineOutput é retornado; caso contrário, uma tuple é retornada, em que o primeiro elemento é uma lista com as imagens geradas e o segundo elemento é uma lista de bools indicando se a imagem gerada correspondente contém conteúdo “not-safe-for-work” (nsfw).

A função de chamada do pipeline para geração.

Exemplos:

Imagem para Vídeo
>>> 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)
Primeira e Última Imagem para Vídeo
>>> 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

< >

( frames: Tensor )

Parâmetros

  • frames (torch.Tensor, np.ndarray ou list[list[PIL.Image.Image]]) — lista de saídas de vídeo - Pode ser uma lista aninhada de comprimento batch_size, com cada sublista contendo sequências de imagens PIL desruidas de comprimento num_frames. Também pode ser um array NumPy ou tensor Torch de forma (batch_size, num_frames, channels, height, width).

Classe de saída para os pipelines do HunyuanVideo.

Update on GitHub

←Cosmos3 Helios→