# # مرخّص بموجب ترخيص Apache الإصدار 2.0 (المسمى "الترخيص") # لا يجوز لك استخدام هذا الملف إلا وفقاً لشروط الترخيص. # يمكنك الحصول على نسخة من الترخيص في # # http://www.apache.org/licenses/LICENSE-2.0 # # ما لم يقتضِ ذلك القانون المعمول به أو ما اتُّفق عليه كتابياً، البرمجيات # تُوزَّع بموجب الرخصة على أساس "كما هي"، # بلا أي ضمانات أو شروط من أي نوع، سواء صريحة أو ضمنية. # راجع الترخيص لمعرفة اللغة المحددة التي تحكم الصلاحيات و # قيود بموجب الترخيص. --> # HunyuanVideo [HunyuanVideo](https://huggingface.co/papers/2412.03603) هو نموذج تحويل انتشاري (diffusion transformer) يحتوي على 13 مليار معامل، مصمّم ليكون منافسًا لنماذج الفيديو الأساسية المغلقة المصدر، ولتمكين وصول أوسع للمجتمع. يستخدم هذا نموذجًا معماريًا "من تدفق مزدوج إلى تدفق مفرد" لمعالجة رموز الفيديو والنص بشكل منفصل أولاً، قبل دمجها وإدخالها إلى التحويل (transformer) لدمج المعلومات متعددة الوسائط. يُستخدم نموذج لغة كبير متعدد الوسائط (MLLM) مُدرَّب مسبقًا كمُشفِّر (encoder) لأنه يتمتع بمواءمة أفضل بين الصورة والنص، ووصف أفضل لتفاصيل الصور والاستدلال، ويمكن استخدامه كتعلمي بلا أمثلة (zero-shot learner) إذا أُضيفت تعليمات النظام إلى أوامر المستخدم. أخيرًا، يستخدم HunyuanVideo مُشفِّرًا ذاتيًا متغيرًا (variational autoencoder) ثلاثي الأبعاد سببيًا لمعالجة بيانات الفيديو بكفاءة أعلى عند الدقة ومعدل الإطارات الأصليين. يمكنك العثور على جميع نقاط التفتيش الأصلية لنموذج HunyuanVideo تحت منظمة [Tencent](https://huggingface.co/tencent). > [!TIP] > انقر على نماذج HunyuanVideo في الشريط الجانبي الأيمن لمزيد من الأمثلة على مهام توليد الفيديو. > > تستخدم الأمثلة أدناه نقطة تحقق من [hunyuanvideo-community](https://huggingface.co/hunyuanvideo-community) لأن الأوزان مخزنة في تخطيط متوافق مع Diffusers. يُبيّن المثال أدناه كيفية توليد فيديو مُحسَّن للذاكرة أو لسرعة الاستدلال. راجع دليل [تقليل استهلاك الذاكرة](../../optimization/memory) لمزيد من التفاصيل حول تقنيات توفير الذاكرة المختلفة. يتطلب نموذج HunyuanVideo المُكمَّم أدناه حوالي 14 جيجابايت من ذاكرة الفيديو (VRAM). ```py 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) ``` يكون [التجميع](../../optimization/fp16#torchcompile) بطيئًا في المرة الأولى، لكن الاستدعاءات اللاحقة للخط الأنابيب تكون أسرع. ```py 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() # torch.compile pipeline.transformer.to(memory_format=torch.channels_last) pipeline.transformer = torch.compile( pipeline.transformer, mode="max-autotune", fullgraph=True ) 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) ``` ## ملاحظات - يدعم HunyuanVideo تقنية LoRAs من خلال [load_lora_weights()](/docs/diffusers/main/ar/api/loaders/lora#diffusers.loaders.HunyuanVideoLoraLoaderMixin.load_lora_weights). عرض كود مثال ```py 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) ``` - راجع الجدول أدناه للحصول على قيم الاستدلال الموصى بها. | معامل | القيمة الموصى بها | |---|---| | نوع بيانات مُشفّر النص | `torch.float16` | | نوع بيانات transformer | `torch.bfloat16` | | نوع بيانات vae | `torch.float16` | | `num_frames (k)` | 4 * `k` + 1 | - جرّب قيم `shift` أدنى (`2.0` إلى `5.0`) للفيديوهات ذات الدقة المنخفضة وقيم `shift` أعلى (`7.0` إلى `12.0`) للصور ذات الدقة العالية. ## HunyuanVideoPipeline[[diffusers.HunyuanVideoPipeline]] #### diffusers.HunyuanVideoPipeline[[diffusers.HunyuanVideoPipeline]] ```python diffusers.HunyuanVideoPipeline(text_encoder: LlamaModel, tokenizer: LlamaTokenizer, transformer: HunyuanVideoTransformer3DModel, vae: AutoencoderKLHunyuanVideo, scheduler: FlowMatchEulerDiscreteScheduler, text_encoder_2: CLIPTextModel, tokenizer_2: CLIPTokenizer) ``` [المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/hunyuan_video/pipeline_hunyuan_video.py#L144) **المعاملات:** text_encoder (`LlamaModel`) : [Llava Llama3-8B](https://huggingface.co/xtuner/llava-llama-3-8b-v1_1-transformers). tokenizer (`LlamaTokenizer`) : مُجزِّئ من [Llava Llama3-8B](https://huggingface.co/xtuner/llava-llama-3-8b-v1_1-transformers). transformer ([HunyuanVideoTransformer3DModel](/docs/diffusers/main/ar/api/models/hunyuan_video_transformer_3d#diffusers.HunyuanVideoTransformer3DModel)) : نموذج Transformer مشروط لإزالة الضوضاء من كامنات الصورة المُرمّزة. scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/main/ar/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : مُجدوِل يُستخدم بالاقتران مع `transformer` لإزالة الضوضاء من كامنات الصورة المُرمَّزة. vae ([AutoencoderKLHunyuanVideo](/docs/diffusers/main/ar/api/models/autoencoder_kl_hunyuan_video#diffusers.AutoencoderKLHunyuanVideo)) : نموذج الترميز التحويلي التبايني (VAE) لتشفير وفك تشفير مقاطع الفيديو إلى تمثيلات كامنة ومنها. text_encoder_2 (`CLIPTextModel`) : [CLIP](https://huggingface.co/docs/transformers/model_doc/clip#transformers.CLIPTextModel)، وتحديداً النسخة [clip-vit-large-patch14](https://huggingface.co/openai/clip-vit-large-patch14). tokenizer_2 (`CLIPTokenizer`) : مُقسِّم من الفئة [CLIPTokenizer](https://huggingface.co/docs/transformers/en/model_doc/clip#transformers.CLIPTokenizer). خط أنابيب لتوليد الفيديو من النص باستخدام HunyuanVideo. يرث هذا النموذج من [DiffusionPipeline](/docs/diffusers/main/ar/api/pipelines/overview#diffusers.DiffusionPipeline). راجع توثيق الفئة الأصلية لمعرفة الطرق العامة المُنفَّذة لجميع خطوط الأنابيب (التنزيل، الحفظ، التشغيل على جهاز معين، إلخ). #### __call__[[diffusers.HunyuanVideoPipeline.__call__]] ```python __call__(prompt: str | list[str] = None, prompt_2: str | list[str] = None, negative_prompt: str | list[str] = None, negative_prompt_2: str | list[str] = None, height: int = 720, width: int = 1280, num_frames: int = 129, num_inference_steps: int = 50, sigmas: list[float] = None, true_cfg_scale: float = 1.0, guidance_scale: float = 6.0, num_videos_per_prompt: int | None = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask: typing.Optional[torch.Tensor] = None, output_type: str | None = 'pil', return_dict: bool = True, attention_kwargs: dict[str, typing.Any] | None = None, callback_on_step_end: typing.Union[typing.Callable[[int, int], NoneType], diffusers.callbacks.PipelineCallback, diffusers.callbacks.MultiPipelineCallbacks, NoneType] = None, callback_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) ``` [المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/hunyuan_video/pipeline_hunyuan_video.py#L438) **المعاملات:** prompt (`str` أو `list[str]`، *اختياري*) : الأمر أو الأوامر التي تُوجّه توليد الصورة. إذا لم يُعرَّف، يجب تمرير `prompt_embeds` بدلاً من ذلك. prompt_2 (`str` أو `list[str]`، *اختياري*) : الموجه أو الموجهات المرسل إلى `tokenizer_2` و`text_encoder_2`. إذا لم يُعرَّف، فسيتم استخدام `prompt` بدلاً منه. negative_prompt (`str` أو `list[str]`، *اختياري*) : الموجه أو الموجهات التي لا ينبغي توجيه توليد الصورة بها. إذا لم يُعرَّف، يجب تمرير `negative_prompt_embeds` بدلاً من ذلك. يتم تجاهله عند عدم استخدام التوجيه (أي يتم تجاهله إذا لم يكن `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`) : عدد الإطارات في الفيديو المولّد. num_inference_steps (`int`، القيمة الافتراضية `50`) : عدد خطوات إزالة الضوضاء. تؤدي زيادة عدد خطوات إزالة الضوضاء عادةً إلى صورة ذات جودة أعلى على حساب بطء الاستدلال. sigmas (`list[float]`، *اختياري*) : قيم `sigmas` مخصصة لاستخدامها في عملية إزالة الضوضاء مع المجدولين الذين يدعمون معامل `sigmas` في طريقة `set_timesteps` الخاصة بهم. إذا لم تُعرَّف، فسيتم استخدام السلوك الافتراضي عند تمرير `num_inference_steps`. true_cfg_scale (`float`، *اختياري*، القيمة الافتراضية 1.0) : يتم تفعيل التوجيه الحر من التصنيف (مقياس التوجيه) عندما يكون `true_cfg_scale` > 1 ويتم توفير `negative_prompt`. guidance_scale (`float`، القيمة الافتراضية `6.0`) : يتم تفعيل مقياس التوجيه المدمج عن طريق تعيين `guidance_scale` > 1. كلما زاد `guidance_scale`، شجّع النموذج على توليد صور أكثر توافقاً مع `prompt` على حساب انخفاض جودة الصورة. تقرب النماذج المُقطّرة بالتوجيه من التوجيه الحقيقي الحر من التصنيف لقيم `guidance_scale` > 1. راجع [الورقة البحثية](https://huggingface.co/papers/2210.03142) لمعرفة المزيد. num_videos_per_prompt (`int`، *اختياري*، القيمة الافتراضية 1) : عدد الصور التي سيتم توليدها لكل موجه. generator (`torch.Generator` أو `list[torch.Generator]`، *اختياري*) : [`torch.Generator`](https://pytorch.org/docs/stable/generated/torch.Generator.html) لجعل التوليد حتميًا. latents (`torch.Tensor`، *اختياري*) : كامنات ضجيج مُولّدة مسبقًا، مُستخرجة من توزيع غاوسي، تُستخدم كمدخلات لتوليد الصور. يمكن استخدامها لتعديل نفس التوليد باستخدام أوامر مختلفة. إذا لم تُقدَّم، يتم توليد كامنات من خلال الاستخراج باستخدام `generator` العشوائي المُقدَّم. 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`، *اختياري*) : تمثيلات نصية مجمعة سالبة مُولّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، *مثلًا* وزن الأوامر. إذا لم تُقدَّم، فسيتم توليد pooled 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`) : ما إذا كان يجب إرجاع `HunyuanVideoPipelineOutput` بدلاً من tuple عادي. attention_kwargs (`dict`، *اختياري*) : قاموس kwargs يُمرَّر إلى `AttentionProcessor` إذا تم تحديده، كما هو معرَّف تحت `self.processor` في [diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py). prompt_template (`dict`، *اختياري*) : القالب المستخدم لتنسيق الموجه قبل الترميز. الافتراضي هو قالب النموذج الافتراضي. max_sequence_length (`int`، *اختياري*، القيمة الافتراضية 256) : الحد الأقصى لطول التسلسل المستخدم لمشفّر الاستعلام. 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`، *اختياري*) : قائمة مدخلات المصفوفات (tensors) لدالة `callback_on_step_end`. سيتم تمرير المصفوفات المحددة في القائمة كحجة `callback_kwargs`. لن تتمكن من تضمين سوى المتغيرات المدرجة في خاصية `._callback_tensor_inputs` لفئة خط الأنابيب (pipeline) الخاص بك. **يعيد:** `~HunyuanVideoPipelineOutput` أو `tuple` إذا كان `return_dict` هو `True`، يُعاد `HunyuanVideoPipelineOutput`، وإلا يُعاد `tuple` حيث يكون العنصر الأول قائمة بالصور المولّدة والعنصر الثاني قائمة من قيم `bool` تشير إلى ما إذا كانت الصورة المولّدة المقابلة تحتوي على محتوى "غير آمن للعمل" (nsfw). دالة الاستدعاء call لخط الأنابيب pipeline الخاص بالتوليد. أمثلة: ```python >>> 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[[diffusers.pipelines.hunyuan_video.pipeline_output.HunyuanVideoPipelineOutput]] #### diffusers.pipelines.hunyuan_video.pipeline_output.HunyuanVideoPipelineOutput[[diffusers.pipelines.hunyuan_video.pipeline_output.HunyuanVideoPipelineOutput]] ```python diffusers.pipelines.hunyuan_video.pipeline_output.HunyuanVideoPipelineOutput(frames: Tensor) ``` [المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/hunyuan_video/pipeline_output.py#L11) **المعاملات:** 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.