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 — это компактная, но мощная модель генерации видео, которая обеспечивает передовое качество изображения и согласованность движения всего с 8,3 миллиардами параметров, что позволяет эффективно выполнять инференс на потребительских GPU. Это достижение основано на нескольких ключевых компонентах, включая тщательную подготовку данных, продвинутую архитектуру DiT с селективным и скользящим тайловым вниманием (SSTA), улучшенное двуязычное понимание благодаря глиф-осознанному кодированию текста, прогрессивное предобучение и постобучение, а также эффективную сеть супер-разрешения видео. Используя эти решения, мы разработали единый фреймворк, способный к высококачественной генерации видео из текста и из изображения для различных длительностей и разрешений. Многочисленные эксперименты показывают, что эта компактная и эффективная модель устанавливает новый уровень качества среди открытых моделей.

Все исходные контрольные точки HunyuanVideo можно найти в организации Tencent.

Нажмите на модели HunyuanVideo в правой боковой панели, чтобы увидеть больше примеров задач генерации видео.

Приведённые ниже примеры используют контрольную точку из hunyuanvideo-community, поскольку веса хранятся в формате, совместимом с Diffusers.

Пример ниже демонстрирует, как сгенерировать видео, оптимизированное по памяти или скорости инференса.

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

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

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)

Примечания

  • HunyuanVideo1.5 использует маски внимания для последовательностей переменной длины. Для достижения наилучшей производительности мы рекомендуем использовать бэкенд внимания, который эффективно обрабатывает заполнение (padding).

    • H100/H800: _flash_3_hub или _flash_3_varlen_hub
    • A100/A800/RTX 4090: flash_hub или flash_varlen_hub
    • Другие GPU: sage_hub

См. руководство Attention backends для получения подробной информации об использовании другого бэкенда.

pipe.transformer.set_attention_backend("flash_hub")  # or your preferred backend
  • HunyuanVideo15Pipeline использует guider и не принимает параметр guidance_scale во время выполнения.

Вы можете проверить конфигурацию guider по умолчанию с помощью 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

Чтобы обновить конфигурацию guider, выполните pipe.guider = pipe.guider.new(...)

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

Подробнее о Guider — здесь.

HunyuanVideo15Pipeline

класс diffusers.HunyuanVideo15Pipeline

< >

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

Параметры

  • transformer (HunyuanVideo15Transformer3DModel) — Архитектура условного Transformer (MMDiT) для удаления шума из закодированных латентных представлений видео.
  • scheduler (FlowMatchEulerDiscreteScheduler) — планировщик, используемый в связке с transformer для удаления шума из закодированных латентов видео.
  • vae (AutoencoderKLHunyuanVideo15) — Модель вариационного автоэнкодера (VAE) для кодирования и декодирования видео в латентные представления и обратно.
  • text_encoder (Qwen2.5-VL-7B-Instruct) — Qwen2.5-VL-7B-Instruct, а именно вариант Qwen2.5-VL-7B-Instruct.
  • tokenizer (Qwen2Tokenizer) — токенизатор класса [Qwen2Tokenizer].
  • text_encoder_2 (T5EncoderModel) — вариант T5EncoderModel.
  • tokenizer_2 (ByT5Tokenizer) — токенизатор класса [ByT5Tokenizer]
  • guider (ClassifierFreeGuidance) — [ClassifierFreeGuidance]для classifier free guidance.

Пайплайн для генерации видео из текста с использованием HunyuanVideo1.5.

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

__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

Параметры

  • prompt (str или list[str], необязательный) — Промпт или промпты для управления генерацией изображения. Если не задан, необходимо передать prompt_embeds вместо него.
  • negative_prompt (str или list[str], необязательный) — Промпт или промпты, которые не должны направлять генерацию изображения. Если не задан, необходимо передать negative_prompt_embeds вместо него.
  • height (int, необязательный) — Высота сгенерированного видео в пикселях.
  • width (int, необязательный) — Ширина сгенерированного видео в пикселях.
  • num_frames (int, по умолчанию 121) — Количество кадров в сгенерированном видео.
  • num_inference_steps (int, по умолчанию 50) — Количество шагов денойзинга. Увеличение числа шагов денойзинга обычно приводит к повышению качества видео за счёт замедления инференса.
  • sigmas (list[float], необязательный) — Пользовательские сигмы для процесса удаления шума в планировщиках, поддерживающих аргумент sigmas в их методе set_timesteps. Если не задано, будет использоваться поведение по умолчанию при передаче num_inference_steps.
  • num_videos_per_prompt (int, необязательный, по умолчанию 1) — Количество видео, генерируемых для каждого промпта.
  • generator (torch.Generator или list[torch.Generator], необязательный) — torch.Generator для обеспечения детерминированности генерации.
  • latents (torch.Tensor, необязательный) — Предварительно сгенерированные зашумлённые латенты, выбранные из гауссова распределения, которые используются в качестве входных данных для генерации видео. Можно использовать, чтобы скорректировать одну и ту же генерацию с помощью разных промптов. Если не задано, тензор латентов генерируется путём выборки с использованием переданного случайного generator.
  • prompt_embeds (torch.Tensor, необязательный) — Предварительно сгенерированные текстовые эмбеддинги. Можно использовать для простой настройки текстовых входных данных (взвешивание промпта). Если не задано, текстовые эмбеддинги генерируются из входного аргумента prompt.
  • prompt_embeds_mask (torch.Tensor, необязательный) — Предварительно сгенерированная маска для эмбеддингов промпта.
  • negative_prompt_embeds (torch.Tensor, необязательный) — Предварительно сгенерированные отрицательные текстовые эмбеддинги. Можно использовать для простой настройки текстовых входных данных, например для взвешивания промпта. Если не передано, negative_prompt_embeds будет сгенерировано из входного аргумента negative_prompt.
  • negative_prompt_embeds_mask (torch.Tensor, необязательный) — Предварительно сгенерированная маска для эмбеддингов негативного промпта.
  • prompt_embeds_2 (torch.Tensor, необязательный) — Предварительно сгенерированные текстовые эмбеддинги из второго текстового энкодера. Можно использовать для простой настройки текстовых входных данных.
  • prompt_embeds_mask_2 (torch.Tensor, необязательный) — Предварительно сгенерированная маска для эмбеддингов промпта от второго текстового энкодера.
  • negative_prompt_embeds_2 (torch.Tensor, необязательный) — Предварительно сгенерированные отрицательные текстовые эмбеддинги из второго текстового энкодера.
  • negative_prompt_embeds_mask_2 (torch.Tensor, необязательный) — Предварительно сгенерированная маска для эмбеддингов негативного промпта от второго текстового энкодера.
  • output_type (str, необязательный, по умолчанию "np") — Формат вывода сгенерированного видео. Выберите один из вариантов: “np”, “pt” или “latent”.
  • return_dict (bool, необязательный, по умолчанию True) — Определяет, следует ли возвращать HunyuanVideo15PipelineOutput вместо обычного кортежа.
  • attention_kwargs (dict, необязательный) — Словарь kwargs, который при указании передается в AttentionProcessor, определенный в self.processor в diffusers.models.attention_processor.

Возвращает

~HunyuanVideo15PipelineOutput или tuple

Если return_dict равно True, возвращается HunyuanVideo15PipelineOutput, иначе возвращается tuple, где первый элемент — это список с сгенерированными видео.

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

Примеры:

>>> 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 )

Параметры

  • prompt (str или list[str], необязательный) — промпт для кодирования
  • device — (torch.device): устройство torch
  • batch_size (int) — размер батча промптов, по умолчанию 1
  • num_videos_per_prompt (int) — количество изображений, которые должны быть сгенерированы для каждого промпта
  • prompt_embeds (torch.Tensor, необязательный) — Предварительно сгенерированные текстовые эмбеддинги. Если не указаны, текстовые эмбеддинги будут сгенерированы из входного аргумента prompt.
  • prompt_embeds_mask (torch.Tensor, необязательный) — Предварительно сгенерированная текстовая маска. Если не задана, текстовая маска будет сгенерирована из аргумента prompt.
  • prompt_embeds_2 (torch.Tensor, необязательный) — Предварительно сгенерированные эмбеддинги глифов текста из ByT5. Если не предоставлены, будут сгенерированы из входного аргумента prompt с использованием self.tokenizer_2 и self.text_encoder_2.
  • prompt_embeds_mask_2 (torch.Tensor, необязательный) — Предварительно сгенерированная маска текста глифов от ByT5. Если не предоставлена, будет сгенерирована из входного аргумента prompt с использованием self.tokenizer_2 и self.text_encoder_2.

prepare_cond_latents_and_mask

< >

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

Параметры

  • latents — Основной тензор латентов (B, C, F, H, W)

Возвращает

tuple

(cond_latents_concat, mask_concat) - оба являются нулевыми тензорами для t2v

Подготовьте условные латенты и маску для генерации t2v.

HunyuanVideo15ImageToVideoPipeline

класс diffusers.HunyuanVideo15ImageToVideoPipeline

< >

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

Параметры

  • transformer (HunyuanVideo15Transformer3DModel) — Архитектура условного Transformer (MMDiT) для удаления шума из закодированных латентных представлений видео.
  • scheduler (FlowMatchEulerDiscreteScheduler) — планировщик, используемый в связке с transformer для удаления шума из закодированных латентов видео.
  • vae (AutoencoderKLHunyuanVideo15) — Модель вариационного автоэнкодера (VAE) для кодирования и декодирования видео в латентные представления и обратно.
  • text_encoder (Qwen2.5-VL-7B-Instruct) — Qwen2.5-VL-7B-Instruct, а именно вариант Qwen2.5-VL-7B-Instruct.
  • tokenizer (Qwen2Tokenizer) — токенизатор класса [Qwen2Tokenizer].
  • text_encoder_2 (T5EncoderModel) — вариант T5EncoderModel.
  • tokenizer_2 (ByT5Tokenizer) — токенизатор класса [ByT5Tokenizer]
  • guider (ClassifierFreeGuidance) — [ClassifierFreeGuidance]для classifier free guidance.
  • image_encoder (SiglipVisionModel) — вариант SiglipVisionModel.
  • feature_extractor (SiglipImageProcessor) — вариант SiglipImageProcessor.

Pipeline для генерации видео из изображений с использованием HunyuanVideo1.5.

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

__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

Параметры

  • image (PIL.Image.Image) — Входное изображение, на основе которого генерируется видео.
  • prompt (str или list[str], необязательный) — Промпт или промпты для управления генерацией видео. Если не задан, необходимо передать prompt_embeds вместо него.
  • negative_prompt (str или list[str], необязательный) — Промпт или промпты, которые не должны направлять генерацию видео. Если не задан, необходимо передать negative_prompt_embeds вместо него.
  • num_frames (int, по умолчанию 121) — Количество кадров в сгенерированном видео.
  • num_inference_steps (int, по умолчанию 50) — Количество шагов денойзинга. Увеличение числа шагов денойзинга обычно приводит к повышению качества видео за счёт замедления инференса.
  • sigmas (list[float], необязательный) — Пользовательские сигмы для процесса удаления шума в планировщиках, поддерживающих аргумент sigmas в их методе set_timesteps. Если не задано, будет использоваться поведение по умолчанию при передаче num_inference_steps.
  • num_videos_per_prompt (int, необязательный, по умолчанию 1) — Количество видео, генерируемых для каждого промпта.
  • generator (torch.Generator или list[torch.Generator], необязательный) — torch.Generator для обеспечения детерминированности генерации.
  • latents (torch.Tensor, необязательный) — Предварительно сгенерированные зашумлённые латенты, выбранные из гауссова распределения, которые используются в качестве входных данных для генерации видео. Можно использовать, чтобы скорректировать одну и ту же генерацию с помощью разных промптов. Если не задано, тензор латентов генерируется путём выборки с использованием переданного случайного generator.
  • prompt_embeds (torch.Tensor, необязательный) — Предварительно сгенерированные текстовые эмбеддинги. Можно использовать для простой настройки текстовых входных данных (взвешивание промпта). Если не задано, текстовые эмбеддинги генерируются из входного аргумента prompt.
  • prompt_embeds_mask (torch.Tensor, необязательный) — Предварительно сгенерированная маска для эмбеддингов промпта.
  • negative_prompt_embeds (torch.Tensor, необязательный) — Предварительно сгенерированные отрицательные текстовые эмбеддинги. Можно использовать для простой настройки текстовых входных данных, например для взвешивания промпта. Если не передано, negative_prompt_embeds будет сгенерировано из входного аргумента negative_prompt.
  • negative_prompt_embeds_mask (torch.Tensor, необязательный) — Предварительно сгенерированная маска для эмбеддингов негативного промпта.
  • prompt_embeds_2 (torch.Tensor, необязательный) — Предварительно сгенерированные текстовые эмбеддинги из второго текстового энкодера. Можно использовать для простой настройки текстовых входных данных.
  • prompt_embeds_mask_2 (torch.Tensor, необязательный) — Предварительно сгенерированная маска для эмбеддингов промпта от второго текстового энкодера.
  • negative_prompt_embeds_2 (torch.Tensor, необязательный) — Предварительно сгенерированные отрицательные текстовые эмбеддинги из второго текстового энкодера.
  • negative_prompt_embeds_mask_2 (torch.Tensor, необязательный) — Предварительно сгенерированная маска для эмбеддингов негативного промпта от второго текстового энкодера.
  • output_type (str, необязательный, по умолчанию "np") — Формат вывода сгенерированного видео. Выберите один из вариантов: “np”, “pt” или “latent”.
  • return_dict (bool, необязательный, по умолчанию True) — Определяет, следует ли возвращать HunyuanVideo15PipelineOutput вместо обычного кортежа.
  • attention_kwargs (dict, необязательный) — Словарь kwargs, который при указании передается в AttentionProcessor, определенный в self.processor в diffusers.models.attention_processor.

Возвращает

~HunyuanVideo15PipelineOutput или tuple

Если return_dict равно True, возвращается HunyuanVideo15PipelineOutput, иначе возвращается tuple, где первый элемент — это список с сгенерированными видео.

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

Примеры:

>>> 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 )

Параметры

  • prompt (str или list[str], необязательный) — промпт для кодирования
  • device — (torch.device): устройство torch
  • batch_size (int) — размер батча промптов, по умолчанию 1
  • num_videos_per_prompt (int) — количество изображений, которые должны быть сгенерированы для каждого промпта
  • prompt_embeds (torch.Tensor, необязательный) — Предварительно сгенерированные текстовые эмбеддинги. Если не указаны, текстовые эмбеддинги будут сгенерированы из входного аргумента prompt.
  • prompt_embeds_mask (torch.Tensor, необязательный) — Предварительно сгенерированная текстовая маска. Если не задана, текстовая маска будет сгенерирована из аргумента prompt.
  • prompt_embeds_2 (torch.Tensor, необязательный) — Предварительно сгенерированные эмбеддинги глифов текста из ByT5. Если не предоставлены, будут сгенерированы из входного аргумента prompt с использованием self.tokenizer_2 и self.text_encoder_2.
  • prompt_embeds_mask_2 (torch.Tensor, необязательный) — Предварительно сгенерированная маска текста глифов от ByT5. Если не предоставлена, будет сгенерирована из входного аргумента prompt с использованием self.tokenizer_2 и self.text_encoder_2.

prepare_cond_latents_and_mask

< >

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

Параметры

  • latents — Основной тензор латентов (B, C, F, H, W)

Возвращает

tuple

(cond_latents_concat, mask_concat) - оба являются нулевыми тензорами для t2v

Подготовьте условные латенты и маску для генерации t2v.

HunyuanVideo15PipelineOutput

класс diffusers.pipelines.hunyuan_video1_5.pipeline_output.HunyuanVideo15PipelineOutput

< >

( 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).

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

Update on GitHub

←HunyuanVideo Kandinsky 5.0 Video→