Hugging Face's logo

Diffusers documentation

HunyuanVideo-1.5

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

HunyuanVideo-1.5

HunyuanVideo-1.5 é um modelo de geração de vídeo leve, porém poderoso, que alcança qualidade visual e coerência de movimento de última geração com apenas 8,3 bilhões de parâmetros, permitindo inferência eficiente em GPUs de consumo. Essa conquista é construída sobre vários componentes-chave, incluindo curadoria meticulosa de dados, uma arquitetura DiT avançada com atenção seletiva e deslizante por blocos (SSTA), compreensão bilíngue aprimorada por meio de codificação de texto consciente de glifos, pré-treinamento e pós-treinamento progressivos, e uma rede eficiente de super-resolução de vídeo. Aproveitando esses designs, desenvolvemos um framework unificado capaz de geração de texto-para-vídeo e imagem-para-vídeo de alta qualidade em múltiplas durações e resoluções. Experimentos extensos demonstram que esse modelo compacto e proficiente estabelece um novo estado da arte entre os modelos de código aberto.

Você pode encontrar todos os checkpoints originais do HunyuanVideo na organização Tencent.

Clique nos modelos HunyuanVideo na barra lateral à direita para mais exemplos de tarefas de geração de vídeo.

Os exemplos abaixo usam um checkpoint de hunyuanvideo-community porque os pesos são armazenados em um layout compatível com Diffusers.

O exemplo abaixo demonstra como gerar um vídeo otimizado para memória ou velocidade de inferência.

<hfoptions id="usage"> <hfoption id="memory">

Consulte o guia Reduzir o uso de memória para mais detalhes sobre as diversas técnicas de economia de memória.

import torch
from diffusers import AutoModel, HunyuanVideo15Pipeline
from diffusers.utils import export_to_video


pipeline = HunyuanVideo15Pipeline.from_pretrained(
    "HunyuanVideo-1.5-Diffusers-480p_t2v",
    dtype=torch.bfloat16,
)

# model-offloading and tiling
pipeline.enable_model_cpu_offload()
pipeline.vae.enable_tiling()

prompt = "A fluffy teddy bear sits on a bed of soft pillows surrounded by children's toys."
video = pipeline(prompt=prompt, num_frames=61, num_inference_steps=30).frames[0]
export_to_video(video, "output.mp4", fps=15)

Observações

  • HunyuanVideo1.5 usa máscaras de atenção com sequências de comprimento variável. Para o melhor desempenho, recomendamos usar um backend de atenção que lida com o preenchimento (padding) de forma eficiente.

    • H100/H800: _flash_3_hub ou _flash_3_varlen_hub
    • A100/A800/RTX 4090: flash_hub ou flash_varlen_hub
    • Outras GPUs: sage_hub

Consulte o guia Backends de atenção para mais detalhes sobre o uso de um backend diferente.

pipe.transformer.set_attention_backend("flash_hub")  # or your preferred backend

Você pode verificar a configuração padrão do guider usando pipe.guider:

>>> pipe.guider 
ClassifierFreeGuidance {
  "_class_name": "ClassifierFreeGuidance",
  "_diffusers_version": "0.36.0.dev0",
  "enabled": true,
  "guidance_rescale": 0.0,
  "guidance_scale": 6.0,
  "start": 0.0,
  "stop": 1.0,
  "use_original_formulation": false
}

State:
  step: None
  num_inference_steps: None
  timestep: None
  count_prepared: 0
  enabled: True
  num_conditions: 2

Para atualizar a configuração do guider, você pode executar pipe.guider = pipe.guider.new(...)

pipe.guider = pipe.guider.new(guidance_scale=5.0)

Saiba mais sobre o Guider aqui.

HunyuanVideo15Pipeline

classe diffusers.HunyuanVideo15Pipeline

< >

( text_encoder: Qwen2_5_VLTextModeltokenizer: Qwen2Tokenizertransformer: HunyuanVideo15Transformer3DModelvae: AutoencoderKLHunyuanVideo15scheduler: FlowMatchEulerDiscreteSchedulertext_encoder_2: T5EncoderModeltokenizer_2: ByT5Tokenizerguider: ClassifierFreeGuidance )

Parâmetros

  • transformer (HunyuanVideo15Transformer3DModel) — Arquitetura de Transformer condicional (MMDiT) para desruidar os latentes de vídeo codificados.
  • scheduler (FlowMatchEulerDiscreteScheduler) — Um scheduler a ser usado em combinação com transformer para desruidar os latentes de vídeo codificados.
  • vae (AutoencoderKLHunyuanVideo15) — Modelo de Autoencoder Variacional (VAE) para codificar e decodificar vídeos para e a partir de representações latentes.
  • text_encoder (Qwen2.5-VL-7B-Instruct) — Qwen2.5-VL-7B-Instruct, especificamente a variante Qwen2.5-VL-7B-Instruct.
  • tokenizer (Qwen2Tokenizer) — Tokenizer da classe [Qwen2Tokenizer].
  • text_encoder_2 (T5EncoderModel) — variante T5EncoderModel.
  • tokenizer_2 (ByT5Tokenizer) — Tokenizer da classe [ByT5Tokenizer]
  • guider (ClassifierFreeGuidance) — [ClassifierFreeGuidance]para classifier free guidance.

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

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__

< >

( prompt: str | list[str] = Nonenegative_prompt: str | list[str] = Noneheight: int | None = Nonewidth: int | None = Nonenum_frames: int = 121num_inference_steps: int = 50sigmas: list[float] = Nonenum_videos_per_prompt: int | None = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds_mask: typing.Optional[torch.Tensor] = Noneprompt_embeds_2: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask_2: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds_2: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds_mask_2: typing.Optional[torch.Tensor] = Noneoutput_type: str | None = 'np'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = None ) → ~HunyuanVideo15PipelineOutput or tuple

Parâmetros

  • 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.
  • 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.
  • height (int, opcional) — A altura, em pixels, do vídeo gerado.
  • width (int, opcional) — A largura, em pixels, do vídeo gerado.
  • num_frames (int, padrão 121) — O número de quadros no vídeo gerado.
  • num_inference_steps (int, padrão 50) — O número de etapas de remoção de ruído. Mais etapas de remoção de ruído geralmente resultam em um vídeo de maior qualidade, à custa 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.
  • num_videos_per_prompt (int, opcional, padrão 1) — O número de vídeos a serem gerados por prompt.
  • generator (torch.Generator ou list[torch.Generator], opcional) — Um torch.Generator para tornar a geração determinística.
  • latents (torch.Tensor, opcional) — Latentes ruidosos pré-gerados, amostrados de uma distribuição gaussiana, a serem usados como entradas para a geração de vídeo. Pode ser usado para ajustar a mesma geração com diferentes prompts. Se não for fornecido, um tensor de latentes é gerado por amostragem usando o generator aleatório fornecido.
  • 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.
  • prompt_embeds_mask (torch.Tensor, opcional) — Máscara pré-gerada para incorporações de prompt.
  • negative_prompt_embeds (torch.Tensor, 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_prompt_embeds_mask (torch.Tensor, opcional) — Máscara pré-gerada para incorporações de prompt negativo.
  • prompt_embeds_2 (torch.Tensor, opcional) — Incorporações de texto pré-geradas pelo segundo codificador de texto. Pode ser usado para ajustar facilmente as entradas de texto.
  • prompt_embeds_mask_2 (torch.Tensor, opcional) — Máscara pré-gerada para embeddings de prompt do segundo codificador de texto.
  • negative_prompt_embeds_2 (torch.Tensor, opcional) — Incorporações de texto negativo pré-geradas pelo segundo codificador de texto.
  • negative_prompt_embeds_mask_2 (torch.Tensor, opcional) — Máscara pré-gerada para incorporações de prompt negativo do segundo codificador de texto.
  • output_type (str, opcional, padrão "np") — O formato de saída do vídeo gerado. Escolha entre “np”, “pt” ou “latent”.
  • return_dict (bool, opcional, padrão True) — Se deve ou não retornar um HunyuanVideo15PipelineOutput 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.

Retorna

~HunyuanVideo15PipelineOutput ou tuple

Se return_dict for True, HunyuanVideo15PipelineOutput é retornado; caso contrário, uma tuple é retornada, onde o primeiro elemento é uma lista com os vídeos gerados.

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

Exemplos:

>>> import torch
>>> from diffusers import HunyuanVideo15Pipeline
>>> from diffusers.utils import export_to_video

>>> model_id = "hunyuanvideo-community/HunyuanVideo-1.5-480p_t2v"
>>> pipe = HunyuanVideo15Pipeline.from_pretrained(model_id, torch_dtype=torch.float16)
>>> pipe.vae.enable_tiling()
>>> pipe.to("cuda")

>>> output = pipe(
...     prompt="A cat walks on the grass, realistic",
...     num_inference_steps=50,
... ).frames[0]
>>> export_to_video(output, "output.mp4", fps=15)

encode_prompt

< >

( prompt: str | list[str]device: typing.Optional[torch.device] = Nonedtype: typing.Optional[torch.dtype] = Nonebatch_size: int = 1num_videos_per_prompt: int = 1prompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask: typing.Optional[torch.Tensor] = Noneprompt_embeds_2: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask_2: typing.Optional[torch.Tensor] = None )

Parâmetros

  • prompt (str ou list[str], opcional) — prompt a ser codificado
  • device — (torch.device): dispositivo torch
  • batch_size (int) — tamanho do lote de prompts, padrão é 1
  • num_videos_per_prompt (int) — número de imagens que devem ser geradas por prompt
  • prompt_embeds (torch.Tensor, opcional) — Incorporações de texto pré-geradas. Se não fornecidas, as incorporações de texto serão geradas a partir do argumento de entrada prompt.
  • prompt_embeds_mask (torch.Tensor, opcional) — Máscara de texto pré-gerada. Se não for fornecida, a máscara de texto será gerada a partir do argumento de entrada prompt.
  • prompt_embeds_2 (torch.Tensor, opcional) — Incorporações de texto de glifos pré-geradas pelo ByT5. Se não fornecidas, serão geradas a partir do argumento de entrada prompt usando self.tokenizer_2 e self.text_encoder_2.
  • prompt_embeds_mask_2 (torch.Tensor, opcional) — Máscara de texto de glifo pré-gerada pelo ByT5. Se não for fornecida, será gerada a partir do argumento de entrada prompt usando self.tokenizer_2 e self.text_encoder_2.

prepare_cond_latents_and_mask

< >

( latentsdtype: typing.Optional[torch.dtype]device: typing.Optional[torch.device] ) → tuple

Parâmetros

  • latents — Tensor principal de latentes (B, C, F, H, W)

Retorna

tuple

(cond_latents_concat, mask_concat) - ambos são tensores de zeros para t2v

Prepare os latentes condicionais e a máscara para a geração de t2v.

HunyuanVideo15ImageToVideoPipeline

classe diffusers.HunyuanVideo15ImageToVideoPipeline

< >

( text_encoder: Qwen2_5_VLTextModeltokenizer: Qwen2Tokenizertransformer: HunyuanVideo15Transformer3DModelvae: AutoencoderKLHunyuanVideo15scheduler: FlowMatchEulerDiscreteSchedulertext_encoder_2: T5EncoderModeltokenizer_2: ByT5Tokenizerguider: ClassifierFreeGuidanceimage_encoder: SiglipVisionModelfeature_extractor: SiglipImageProcessorPil )

Parâmetros

Pipeline para geração de vídeo a partir de imagem usando HunyuanVideo1.5.

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: Imageprompt: str | list[str] = Nonenegative_prompt: str | list[str] = Nonenum_frames: int = 121num_inference_steps: int = 50sigmas: list[float] = Nonenum_videos_per_prompt: int | None = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds_mask: typing.Optional[torch.Tensor] = Noneprompt_embeds_2: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask_2: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds_2: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds_mask_2: typing.Optional[torch.Tensor] = Noneoutput_type: str | None = 'np'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = None ) → ~HunyuanVideo15PipelineOutput or tuple

Parâmetros

  • image (PIL.Image.Image) — A imagem de entrada para condicionar a geração de vídeo.
  • prompt (str ou list[str], opcional) — O prompt ou os prompts para orientar a geração do vídeo. Se não for definido, é necessário passar prompt_embeds em vez disso.
  • negative_prompt (str ou list[str], opcional) — O prompt ou os prompts que não devem orientar a geração do vídeo. Se não for definido, é necessário passar negative_prompt_embeds em vez disso.
  • num_frames (int, padrão 121) — O número de quadros no vídeo gerado.
  • num_inference_steps (int, padrão 50) — O número de etapas de remoção de ruído. Mais etapas de remoção de ruído geralmente resultam em um vídeo de maior qualidade, à custa 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.
  • num_videos_per_prompt (int, opcional, padrão 1) — O número de vídeos a serem gerados por prompt.
  • generator (torch.Generator ou list[torch.Generator], opcional) — Um torch.Generator para tornar a geração determinística.
  • latents (torch.Tensor, opcional) — Latentes ruidosos pré-gerados, amostrados de uma distribuição gaussiana, a serem usados como entradas para a geração de vídeo. Pode ser usado para ajustar a mesma geração com diferentes prompts. Se não for fornecido, um tensor de latentes é gerado por amostragem usando o generator aleatório fornecido.
  • 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.
  • prompt_embeds_mask (torch.Tensor, opcional) — Máscara pré-gerada para incorporações de prompt.
  • negative_prompt_embeds (torch.Tensor, 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_prompt_embeds_mask (torch.Tensor, opcional) — Máscara pré-gerada para incorporações de prompt negativo.
  • prompt_embeds_2 (torch.Tensor, opcional) — Incorporações de texto pré-geradas pelo segundo codificador de texto. Pode ser usado para ajustar facilmente as entradas de texto.
  • prompt_embeds_mask_2 (torch.Tensor, opcional) — Máscara pré-gerada para embeddings de prompt do segundo codificador de texto.
  • negative_prompt_embeds_2 (torch.Tensor, opcional) — Incorporações de texto negativo pré-geradas pelo segundo codificador de texto.
  • negative_prompt_embeds_mask_2 (torch.Tensor, opcional) — Máscara pré-gerada para incorporações de prompt negativo do segundo codificador de texto.
  • output_type (str, opcional, padrão "np") — O formato de saída do vídeo gerado. Escolha entre “np”, “pt” ou “latent”.
  • return_dict (bool, opcional, padrão True) — Se deve ou não retornar um HunyuanVideo15PipelineOutput 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.

Retorna

~HunyuanVideo15PipelineOutput ou tuple

Se return_dict for True, HunyuanVideo15PipelineOutput é retornado; caso contrário, uma tuple é retornada, onde o primeiro elemento é uma lista com os vídeos gerados.

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

Exemplos:

>>> import torch
>>> from diffusers import HunyuanVideo15ImageToVideoPipeline
>>> from diffusers.utils import export_to_video

>>> model_id = "hunyuanvideo-community/HunyuanVideo-1.5-480p_i2v"
>>> pipe = HunyuanVideo15ImageToVideoPipeline.from_pretrained(model_id, torch_dtype=torch.float16)
>>> pipe.vae.enable_tiling()
>>> pipe.to("cuda")

>>> image = load_image("https://huggingface.co/datasets/YiYiXu/testing-images/resolve/main/wan_i2v_input.JPG")

>>> output = pipe(
...     prompt="Summer beach vacation style, a white cat wearing sunglasses sits on a surfboard. The fluffy-furred feline gazes directly at the camera with a relaxed expression. Blurred beach scenery forms the background featuring crystal-clear waters, distant green hills, and a blue sky dotted with white clouds. The cat assumes a naturally relaxed posture, as if savoring the sea breeze and warm sunlight. A close-up shot highlights the feline's intricate details and the refreshing atmosphere of the seaside.",
...     image=image,
...     num_inference_steps=50,
... ).frames[0]
>>> export_to_video(output, "output.mp4", fps=24)

encode_prompt

< >

( prompt: str | list[str]device: typing.Optional[torch.device] = Nonedtype: typing.Optional[torch.dtype] = Nonebatch_size: int = 1num_videos_per_prompt: int = 1prompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask: typing.Optional[torch.Tensor] = Noneprompt_embeds_2: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask_2: typing.Optional[torch.Tensor] = None )

Parâmetros

  • prompt (str ou list[str], opcional) — prompt a ser codificado
  • device — (torch.device): dispositivo torch
  • batch_size (int) — tamanho do lote de prompts, padrão é 1
  • num_videos_per_prompt (int) — número de imagens que devem ser geradas por prompt
  • prompt_embeds (torch.Tensor, opcional) — Incorporações de texto pré-geradas. Se não fornecidas, as incorporações de texto serão geradas a partir do argumento de entrada prompt.
  • prompt_embeds_mask (torch.Tensor, opcional) — Máscara de texto pré-gerada. Se não for fornecida, a máscara de texto será gerada a partir do argumento de entrada prompt.
  • prompt_embeds_2 (torch.Tensor, opcional) — Incorporações de texto de glifos pré-geradas pelo ByT5. Se não fornecidas, serão geradas a partir do argumento de entrada prompt usando self.tokenizer_2 e self.text_encoder_2.
  • prompt_embeds_mask_2 (torch.Tensor, opcional) — Máscara de texto de glifo pré-gerada pelo ByT5. Se não for fornecida, será gerada a partir do argumento de entrada prompt usando self.tokenizer_2 e self.text_encoder_2.

prepare_cond_latents_and_mask

< >

( latents: Tensorimage: Imagebatch_size: intheight: intwidth: intdtype: dtypedevice: device ) → tuple

Parâmetros

  • latents — Tensor principal de latentes (B, C, F, H, W)

Retorna

tuple

(cond_latents_concat, mask_concat) - ambos são tensores de zeros para t2v

Prepare os latentes condicionais e a máscara para a geração de t2v.

HunyuanVideo15PipelineOutput

classe diffusers.pipelines.hunyuan_video1_5.pipeline_output.HunyuanVideo15PipelineOutput

< >

( 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 HunyuanVideo1.5.

Update on GitHub

←HunyuanVideo Kandinsky 5.0 Video→