# Hunyuan-DiT
![chinese elements understanding](https://github.com/gnobitab/diffusers-hunyuan/assets/1157982/39b99036-c3cb-4f16-bb1a-40ec25eda573)

[Hunyuan-DiT : نموذج تحويل انتشار متعدد الدقة قوي مع فهم دقيق للصينية](https://huggingface.co/papers/2405.08748) من Tencent Hunyuan.

ملخص الورقة البحثية هو:

*نقدّم Hunyuan-DiT، وهو نموذج تحويل انتشاري لتوليد الصور من النص، يتميز بفهم دقيق لكل من اللغتين الإنجليزية والصينية. لبناء Hunyuan-DiT، صمّمنا بعناية بنية التحويل، ومشفّر النص، والتشفير الموضعي. كما بنينا من الصفر خط أنابيب بيانات متكاملًا لتحديث البيانات وتقييمها من أجل تحسين النموذج بشكل تكراري. ولتحقيق فهم لغوي دقيق، درّبنا نموذج لغة كبير متعدد الوسائط لتحسين أوصاف الصور. أخيرًا، يمكن لـ Hunyuan-DiT إجراء حوارات متعددة الجولات متعددة الوسائط مع المستخدمين، حيث يولّد الصور ويحسّنها وفقًا للسياق. من خلال بروتوكول التقييم البشري الشامل الذي شارك فيه أكثر من 50 من المقيّمين المحترفين، يحقق Hunyuan-DiT مستوى جديدًا من الأداء المتقدّم في توليد الصور من النص الصيني مقارنةً بنماذج مفتوحة المصدر أخرى.*

يمكنك العثور على قاعدة الأكواد الأصلية في [Tencent/HunyuanDiT](https://github.com/Tencent/HunyuanDiT) وجميع نقاط التفتيش المتاحة في [Tencent-Hunyuan](https://huggingface.co/Tencent-Hunyuan/HunyuanDiT).

**أبرز الميزات**: يدعم HunyuanDiT توليد الصور من النص الصيني والإنجليزي، وتوليد متعدد الدقة.

يتضمن HunyuanDiT المكونات التالية:
* يستخدم محوّلاً انتشارياً (diffusion transformer) كهيكل أساسي
* يجمع بين مشفرَي نص، وهما مشفر CLIP ثنائي اللغة ومشفر T5 متعدد اللغات

> [!TIP]
> تأكد من الاطلاع على [دليل المجدولين](../../using-diffusers/schedulers) لمعرفة كيفية استكشاف التوازن بين سرعة المجدول وجودة النتائج، واطّلع على قسم [إعادة استخدام المكونات عبر خطوط الأنابيب](../../using-diffusers/loading#reusing-models-in-multiple-pipelines) لمعرفة كيفية تحميل نفس المكونات بكفاءة في خطوط أنابيب متعددة.

> [!TIP]
> يمكنك تحسين جودة التوليد بشكل أكبر عن طريق تمرير الصورة المولّدة من `HungyuanDiTPipeline` إلى نموذج [SDXL refiner](./stable_diffusion/stable_diffusion_xl#base-to-refiner-model).

## التحسين

يمكنك تحسين وقت التشغيل واستهلاك الذاكرة في خط المعالجة باستخدام torch.compile وتقسيم التغذية الأمامية. للتعرف على طرق التحسين الأخرى، راجع [التحسين والتوسع](../../optimization/overview#optimization-techniques).

### الاستدلال

استخدم [`torch.compile`](../../optimization/fp16#torchcompile) لتقليل زمن الاستدلال.

أولاً، حمّل خط الأنابيب:

```python
from diffusers import HunyuanDiTPipeline
import torch

pipeline = HunyuanDiTPipeline.from_pretrained(
	"Tencent-Hunyuan/HunyuanDiT-Diffusers", dtype=torch.float16
).to("cuda")  # or "mps", "xpu", "cpu"
```

ثم غيّر تخطيط الذاكرة لمكوّني خطّ الأنابيب `transformer` و`vae` إلى `torch.channels-last`:

```python
pipeline.transformer.to(memory_format=torch.channels_last)
pipeline.vae.to(memory_format=torch.channels_last)
```

أخيرًا، قم بتجميع المكونات وتنفيذ الاستدلال:

```python
pipeline.transformer = torch.compile(pipeline.transformer, mode="max-autotune", fullgraph=True)
pipeline.vae.decode = torch.compile(pipeline.vae.decode, mode="max-autotune", fullgraph=True)

image = pipeline(prompt="一个宇航员在骑马").images[0]
```

نتائج [الاختبار المرجعي](https://gist.github.com/sayakpaul/29d3a14905cfcbf611fe71ebd22e9b23) على جهاز A100 بسعة 80 جيجابايت هي:

```bash
With torch.compile(): Average inference time: 12.470 seconds.
Without torch.compile(): Average inference time: 20.570 seconds.
```

### تحسين الذاكرة

عبر تحميل مُشفِّر النص T5 بدقة 8 بتات، يمكنك تشغيل خط الأنابيب بأقل من 6 غيغابايتات من ذاكرة GPU. راجع [هذا النص البرمجي](https://gist.github.com/sayakpaul/3154605f6af05b98a41081aaba5ca43e) للتفاصيل.

علاوة على ذلك، يمكنك استخدام طريقة [enable_forward_chunking()](/docs/diffusers/main/ar/api/models/hunyuan_transformer2d#diffusers.HunyuanDiT2DModel.enable_forward_chunking) لتقليل استهلاك الذاكرة. يعمل تقطيع الطبقات الأمامية على تشغيل طبقات التغذية الأمامية داخل كتلة الترانسفورمر في حلقة بدلاً من تشغيلها دفعة واحدة. يمنحك هذا خياراً للتوازن بين استهلاك الذاكرة وزمن الاستدلال.

```diff
+ pipeline.transformer.enable_forward_chunking(chunk_size=1, dim=1)
```

## HunyuanDiTPipeline[[diffusers.HunyuanDiTPipeline]]

#### diffusers.HunyuanDiTPipeline[[diffusers.HunyuanDiTPipeline]]

```python
diffusers.HunyuanDiTPipeline(vae: AutoencoderKL, text_encoder: BertModel, tokenizer: BertTokenizer, transformer: HunyuanDiT2DModel, scheduler: DDPMScheduler, safety_checker: StableDiffusionSafetyChecker, feature_extractor: CLIPImageProcessorPil, requires_safety_checker: bool = True, text_encoder_2: transformers.models.t5.modeling_t5.T5EncoderModel | None = None, tokenizer_2: transformers.models.t5.tokenization_t5.T5Tokenizer | None = None)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/hunyuandit/pipeline_hunyuandit.py#L149)

**المعاملات:**

vae ([AutoencoderKL](/docs/diffusers/main/ar/api/models/autoencoderkl#diffusers.AutoencoderKL)) : نموذج الترميز التحويلي التبايني (VAE) لتشفير وفك تشفير الصور إلى تمثيلات كامنة ومنها. نستخدم `sdxl-vae-fp16-fix`.

text_encoder (`~transformers.BertModel`، `~transformers.CLIPTextModel` | None) : مُشفِّر نص ثابت ([clip-vit-large-patch14](https://huggingface.co/openai/clip-vit-large-patch14)). يستخدم HunyuanDiT [CLIP ثنائي اللغة] مُعدّلًا.

tokenizer (`~transformers.BertTokenizer`، `~transformers.CLIPTokenizer` | None) : `BertTokenizer` أو `CLIPTokenizer` لتجزئة النص.

transformer ([HunyuanDiT2DModel](/docs/diffusers/main/ar/api/models/hunyuan_transformer2d#diffusers.HunyuanDiT2DModel)) : نموذج HunyuanDiT الذي صمّمه Tencent Hunyuan.

text_encoder_2 (`T5EncoderModel`) : مُضمّن mT5. تحديداً، هو 't5-v1_1-xxl'.

tokenizer_2 (`T5Tokenizer`) : مُجزِّئ النصوص الخاص بمُضمِّن mT5.

scheduler ([DDPMScheduler](/docs/diffusers/main/ar/api/schedulers/ddpm#diffusers.DDPMScheduler)) : مُجدوِل يُستخدم بالاقتران مع HunyuanDiT لإزالة الضوضاء من كامنات الصورة المُرمَّزة.

خط أنابيب لتوليد الصور من الإنجليزية/الصينية باستخدام HunyuanDiT.

يرث هذا النموذج من [DiffusionPipeline](/docs/diffusers/main/ar/api/pipelines/overview#diffusers.DiffusionPipeline). راجع توثيق الفئة الأصلية لمعرفة الطرق العامة التي تنفذها المكتبة لجميع خطوط الأنابيب (مثل التنزيل أو الحفظ، أو التشغيل على جهاز معين، وما إلى ذلك).

يستخدم HunyuanDiT مشفّري نصّين: [mT5](https://huggingface.co/google/mt5-base) و[bilingual CLIP](fine-tuned by ourselves)

#### __call__[[diffusers.HunyuanDiTPipeline.__call__]]

```python
__call__(prompt: str | list[str] = None, height: int | None = None, width: int | None = None, num_inference_steps: int | None = 50, guidance_scale: float | None = 5.0, negative_prompt: str | list[str] | None = None, num_images_per_prompt: int | None = 1, eta: float | None = 0.0, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_embeds_2: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds_2: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, prompt_attention_mask_2: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask_2: typing.Optional[torch.Tensor] = None, output_type: str | None = 'pil', return_dict: bool = True, 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'], guidance_rescale: float = 0.0, original_size: tuple[int, int] | None = (1024, 1024), target_size: tuple[int, int] | None = None, crops_coords_top_left: tuple[int, int] = (0, 0), use_resolution_binning: bool = True)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/hunyuandit/pipeline_hunyuandit.py#L568)

**المعاملات:**

prompt (`str` أو `list[str]`، *اختياري*) : الأمر أو الأوامر التي تُوجّه توليد الصورة. إذا لم تُعرَّف، يجب عليك تمرير `prompt_embeds`.

height (`int`) : ارتفاع الصورة المولّدة بالبكسل.

width (`int`) : عرض الصورة المولدة بالبكسل.

num_inference_steps (`int`، *اختياري*، القيمة الافتراضية 50) : عدد خطوات إزالة الضوضاء. تؤدي زيادة عدد خطوات إزالة الضوضاء عادةً إلى صورة ذات جودة أعلى على حساب بطء الاستدلال. يتم تعديل هذا المعامل بواسطة `strength`.

guidance_scale (`float`, *اختياري*, القيمة الافتراضية 7.5) : كلما زادت قيمة مقياس التوجيه، شجّع النموذج على توليد صور مرتبطة ارتباطًا وثيقًا بنص `prompt` على حساب انخفاض جودة الصورة. يتم تفعيل مقياس التوجيه عندما يكون `guidance_scale > 1`.

negative_prompt (`str` أو `list[str]`، *اختياري*) : الأمر أو الأوامر التي توجّه ما يجب عدم تضمينه في توليد الصورة. إذا لم يُعرَّف، يجب عليك تمرير `negative_prompt_embeds` بدلاً من ذلك. يتم تجاهله عند عدم استخدام التوجيه (`guidance_scale < 1`).

num_images_per_prompt (`int`، *اختياري*، القيمة الافتراضية 1) : عدد الصور التي سيتم توليدها لكل موجه.

eta (`float`، *اختياري*، القيمة الافتراضية 0.0) : يتوافق مع المعامل eta (η) من ورقة [DDIM](https://huggingface.co/papers/2010.02502). ينطبق فقط على [DDIMScheduler](/docs/diffusers/main/ar/api/schedulers/ddim#diffusers.DDIMScheduler)، ويُتجاهل في جدولة أخرى.

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`.

prompt_embeds_2 (`torch.Tensor`، *اختياري*) : تمثيلات نصية مُولّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة (وزن الأوامر). إذا لم تُقدَّم، يتم توليد تمثيلات النص من معامل الإدخال `prompt`.

negative_prompt_embeds (`torch.Tensor`، *اختياري*) : تمثيلات نصية سالبة مُولّدة مسبقًا. يمكن استخدامها لضبط مدخلات النص بسهولة (وزن الموجه). إذا لم تُقدَّم، يتم توليد `negative_prompt_embeds` من معامل الإدخال `negative_prompt`.

negative_prompt_embeds_2 (`torch.Tensor`، *اختياري*) : تمثيلات نصية سالبة مُولّدة مسبقًا. يمكن استخدامها لضبط مدخلات النص بسهولة (وزن الموجه). إذا لم تُقدَّم، يتم توليد `negative_prompt_embeds` من معامل الإدخال `negative_prompt`.

prompt_attention_mask (`torch.Tensor`، *اختياري*) : قناع الانتباه للموجّه. مطلوب عند تمرير `prompt_embeds` مباشرة.

prompt_attention_mask_2 (`torch.Tensor`، *اختياري*) : قناع الانتباه للموجّه. مطلوب عند تمرير `prompt_embeds_2` مباشرةً.

negative_prompt_attention_mask (`torch.Tensor`، *اختياري*) : قناع الانتباه (Attention mask) الخاص بالموجّه السلبي. مطلوب عند تمرير `negative_prompt_embeds` مباشرةً.

negative_prompt_attention_mask_2 (`torch.Tensor`، *اختياري*) : قناع الانتباه (Attention mask) الخاص بالموجّه السلبي. مطلوب عند تمرير `negative_prompt_embeds_2` مباشرةً.

output_type (`str`، *اختياري*، الافتراضي `"pil"`) : صيغة الصورة المولّدة. اختر بين `PIL.Image` أو `np.array`.

return_dict (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان يجب إرجاع [StableDiffusionPipelineOutput](/docs/diffusers/main/ar/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput) بدلاً من tuple عادي.

callback_on_step_end (`Callable[[int, int], None]`، `PipelineCallback`، `MultiPipelineCallbacks`، *اختياري*) : دالة استجابة أو قائمة من دوال الاستجابة التي تُستدعى في نهاية كل خطوة إزالة ضوضاء.

callback_on_step_end_tensor_inputs (`list[str]`، *اختياري*) : قائمة من مدخلات المصفوفات (tensors) التي يجب تمريرها إلى دالة الاستدعاء (callback). إذا لم تُعرَّف، فسيتم تمرير جميع مدخلات المصفوفات.

guidance_rescale (`float`, *optional*, defaults to 0.0) : Rescale the noise_cfg according to `guidance_rescale`. Based on findings of [Common Diffusion Noise Schedules and Sample Steps are Flawed](https://huggingface.co/papers/2305.08891). See Section 3.4

original_size (`tuple[int, int]`، *اختياري*، القيمة الافتراضية `(1024, 1024)`) : الحجم الأصلي للصورة. يُستخدم لحساب معرّفات الوقت.

target_size (`tuple[int, int]`، *اختياري*) : الحجم المستهدف للصورة. يُستخدم لحساب معرّفات الوقت.

crops_coords_top_left (`tuple[int, int]`، *اختياري*، القيمة الافتراضية `(0, 0)`) : إحداثيات الزاوية العلوية اليسرى للمقتطع. تُستخدم لحساب معرّفات الوقت.

use_resolution_binning (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان سيتم استخدام تجميع الدقة أم لا. إذا كانت القيمة `True`، فسيتم تعيين دقة الإدخال إلى أقرب دقة قياسية. الدقات المدعومة هي 1024x1024، 1280x1280، 1024x768، 1152x864، 1280x960، 768x1024، 864x1152، 960x1280، 1280x768، و 768x1280. يُوصى بإعداد هذه القيمة على `True`.

**يعيد:** [StableDiffusionPipelineOutput](/docs/diffusers/main/ar/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput) أو `tuple`

إذا كان `return_dict` هو `True`، يُعاد [StableDiffusionPipelineOutput](/docs/diffusers/main/ar/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput)، وإلا يُعاد `tuple` حيث يكون العنصر الأول قائمة بالصور المولّدة والعنصر الثاني قائمة من قيم `bool` تشير إلى ما إذا كانت الصورة المولّدة المقابلة تحتوي على محتوى "غير آمن للعمل" (nsfw).

دالة الاستدعاء call لخط الأنابيب pipeline للتوليد باستخدام HunyuanDiT.

أمثلة:
```py
>>> import torch
>>> from diffusers import HunyuanDiTPipeline

>>> pipe = HunyuanDiTPipeline.from_pretrained(
...     "Tencent-Hunyuan/HunyuanDiT-Diffusers", torch_dtype=torch.float16
... )
>>> pipe.to("cuda")

>>> # You may also use English prompt as HunyuanDiT supports both English and Chinese
>>> # prompt = "An astronaut riding a horse"
>>> prompt = "一个宇航员在骑马"
>>> image = pipe(prompt).images[0]
```

#### encode_prompt[[diffusers.HunyuanDiTPipeline.encode_prompt]]

```python
encode_prompt(prompt: str, device: device = None, dtype: dtype = None, num_images_per_prompt: int = 1, do_classifier_free_guidance: bool = True, negative_prompt: str | None = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask: typing.Optional[torch.Tensor] = None, max_sequence_length: int | None = None, text_encoder_index: int = 0)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/hunyuandit/pipeline_hunyuandit.py#L248)

**المعاملات:**

prompt (`str` أو `list[str]`، *اختياري*) : النص الذي سيتم ترميزه

device : (`torch.device`): جهاز torch

dtype (`torch.dtype`) : نوع torch

num_images_per_prompt (`int`) : عدد الصور التي يجب توليدها لكل موجه

do_classifier_free_guidance (`bool`) : ما إذا كان سيتم استخدام التوجيه الحر للتصنيف أم لا

negative_prompt (`str` أو `list[str]`، *اختياري*) : الموجه أو الموجهات التي لا ينبغي توجيه توليد الصورة بها. إذا لم يُعرَّف، يجب تمرير `negative_prompt_embeds` بدلاً من ذلك. يتم تجاهله عند عدم استخدام التوجيه (أي يتم تجاهله إذا كان `guidance_scale` أقل من `1`).

prompt_embeds (`torch.Tensor`، *اختياري*) : تمثيلات نصية مُولّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، *مثلًا* وزن الأوامر. إذا لم تُقدَّم، فسيتم توليد تمثيلات النص من معامل الإدخال `prompt`.

negative_prompt_embeds (`torch.Tensor`, *اختياري*) : تمثيلات نصية سالبة مُولّدة مسبقًا. يمكن استخدامها لتعديل مدخلات النص بسهولة، *مثلًا* وزن الأوامر. إذا لم تُقدَّم، فسيتم توليد negative_prompt_embeds من معامل الإدخال `negative_prompt`.

prompt_attention_mask (`torch.Tensor`، *اختياري*) : قناع الانتباه للموجّه. مطلوب عند تمرير `prompt_embeds` مباشرة.

negative_prompt_attention_mask (`torch.Tensor`، *اختياري*) : قناع الانتباه (Attention mask) الخاص بالموجّه السلبي. مطلوب عند تمرير `negative_prompt_embeds` مباشرةً.

max_sequence_length (`int`، *اختياري*) : أقصى طول تسلسل يُستخدم للموجّه.

text_encoder_index (`int`, *اختياري*) : فهرس مُشفِّر النص الذي سيتم استخدامه. `0` لـ clip و`1` لـ T5.

يقوم بتشفير الموجه إلى حالات مخفية لمشفّر النص.