Hugging Face's logo

Diffusers documentation

HunyuanVideo

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

LoRA

HunyuanVideo

HunyuanVideo é um modelo de difusão transformer com 13 bilhões de parâmetros, projetado para ser competitivo com modelos de fundação de vídeo de código fechado e permitir um acesso mais amplo da comunidade. Este modelo utiliza uma arquitetura “dual-stream to single-stream” para processar separadamente os tokens de vídeo e de texto inicialmente, antes de concatená-los e enviá-los ao transformer para fundir as informações multimodais. Um modelo de linguagem grande multimodal (MLLM) pré-treinado é usado como codificador, pois possui melhor alinhamento entre imagem e texto, melhor descrição de detalhes de imagem e raciocínio, e pode ser usado como um aprendiz zero-shot se instruções de sistema forem adicionadas aos prompts do usuário. Por fim, o HunyuanVideo usa um autoencoder variacional causal 3D para processar dados de vídeo de forma mais eficiente na resolução e taxa de quadros originais.

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.

memória
velocidade de inferência

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

O modelo HunyuanVideo quantizado abaixo requer ~14GB de VRAM.

import torch
from diffusers import AutoModel, HunyuanVideoPipeline
from diffusers.quantizers import PipelineQuantizationConfig
from diffusers.utils import export_to_video

# quantize weights to int4 with bitsandbytes
pipeline_quant_config = PipelineQuantizationConfig(
    quant_backend="bitsandbytes_4bit",
    quant_kwargs={
      "load_in_4bit": True,
      "bnb_4bit_quant_type": "nf4",
      "bnb_4bit_compute_dtype": torch.bfloat16
      },
    components_to_quantize="transformer"
)

pipeline = HunyuanVideoPipeline.from_pretrained(
    "hunyuanvideo-community/HunyuanVideo",
    quantization_config=pipeline_quant_config,
    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

  • O HunyuanVideo oferece suporte a LoRAs com load_lora_weights().

    Mostrar código de exemplo 
    import torch
from diffusers import AutoModel, HunyuanVideoPipeline
from diffusers.quantizers import PipelineQuantizationConfig
from diffusers.utils import export_to_video

# quantize weights to int4 with bitsandbytes
pipeline_quant_config = PipelineQuantizationConfig(
    quant_backend="bitsandbytes_4bit",
    quant_kwargs={
      "load_in_4bit": True,
      "bnb_4bit_quant_type": "nf4",
      "bnb_4bit_compute_dtype": torch.bfloat16
      },
    components_to_quantize="transformer"
)

pipeline = HunyuanVideoPipeline.from_pretrained(
    "hunyuanvideo-community/HunyuanVideo",
    quantization_config=pipeline_quant_config,
    dtype=torch.bfloat16,
)

# load LoRA weights
pipeline.load_lora_weights("https://huggingface.co/lucataco/hunyuan-steamboat-willie-10", adapter_name="steamboat-willie")
pipeline.set_adapters("steamboat-willie", 0.9)

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

# use "In the style of SWR" to trigger the LoRA
prompt = """
In the style of SWR. A black and white animated scene featuring 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)

  • Consulte a tabela abaixo para os valores de inferência recomendados.

    parâmetrovalor recomendado
    dtype do codificador de textotorch.float16
    dtype do transformertorch.bfloat16
    dtype do vaetorch.float16
    num_frames (k)4 * k + 1

  • Tente valores de shift mais baixos (2.0 a 5.0) para vídeos de menor resolução e valores de shift mais altos (7.0 a 12.0) para imagens de maior resolução.

HunyuanVideoPipeline

classe diffusers.HunyuanVideoPipeline

< >

( text_encoder: LlamaModeltokenizer: LlamaTokenizertransformer: HunyuanVideoTransformer3DModelvae: AutoencoderKLHunyuanVideoscheduler: FlowMatchEulerDiscreteSchedulertext_encoder_2: CLIPTextModeltokenizer_2: CLIPTokenizer )

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__

< >

( prompt: 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 = 129num_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] = Nonelatents: 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 = 256 ) → ~HunyuanVideoPipelineOutput 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.
  • 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.
  • 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) — A orientação livre de classificador verdadeira (escala de orientação) é ativada quando true_cfg_scale > 1 e negative_prompt é fornecido.
  • guidance_scale (float, padrão é 6.0) — A escala de orientação incorporada é ativada ao definir guidance_scale > 1. Valores maiores de guidance_scale incentivam o modelo a gerar imagens mais alinhadas com o prompt às custas de uma menor qualidade de imagem.

    Modelos destilados por orientação aproximam a orientação livre de classe verdadeira para guidance_scale > 1. Consulte o artigo para saber mais.

  • 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.
  • latents (torch.Tensor, opcional) — Latentes ruidosos pré-gerados, amostrados de uma distribuição gaussiana, a serem usados como entradas para a geração de imagens. 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.
  • 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 retornar um HunyuanVideoPipelineOutput 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.
  • 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

~HunyuanVideoPipelineOutput ou tuple

Se return_dict for True, HunyuanVideoPipelineOutput é 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:

>>> import torch
>>> from diffusers import HunyuanVideoPipeline, HunyuanVideoTransformer3DModel
>>> from diffusers.utils import export_to_video

>>> model_id = "hunyuanvideo-community/HunyuanVideo"
>>> transformer = HunyuanVideoTransformer3DModel.from_pretrained(
...     model_id, subfolder="transformer", torch_dtype=torch.bfloat16
... )
>>> pipe = HunyuanVideoPipeline.from_pretrained(model_id, transformer=transformer, torch_dtype=torch.float16)
>>> pipe.vae.enable_tiling()
>>> pipe.to("cuda")

>>> output = pipe(
...     prompt="A cat walks on the grass, realistic",
...     height=320,
...     width=512,
...     num_frames=61,
...     num_inference_steps=30,
... ).frames[0]
>>> export_to_video(output, "output.mp4", fps=15)

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

←Helios HunyuanVideo1.5→