# ConsisIDTransformer3DModel

A Diffusion Transformer model for 3D data from [ConsisID](https://github.com/PKU-YuanGroup/ConsisID) was introduced in [Identity-Preserving Text-to-Video Generation by Frequency Decomposition](https://huggingface.co/papers/2411.17440) by Peking University & University of Rochester & etc.

يمكن تحميل النموذج باستخدام مقتطف الشيفرة التالي.

```python
from diffusers import ConsisIDTransformer3DModel

transformer = ConsisIDTransformer3DModel.from_pretrained("BestWishYsh/ConsisID-preview", subfolder="transformer", dtype=torch.bfloat16).to("cuda")  # or "mps", "xpu", "cpu"
```

## ConsisIDTransformer3DModel[[diffusers.ConsisIDTransformer3DModel]]

#### diffusers.ConsisIDTransformer3DModel[[diffusers.ConsisIDTransformer3DModel]]

```python
diffusers.ConsisIDTransformer3DModel(num_attention_heads: int = 30, attention_head_dim: int = 64, in_channels: int = 16, out_channels: int | None = 16, flip_sin_to_cos: bool = True, freq_shift: int = 0, time_embed_dim: int = 512, text_embed_dim: int = 4096, num_layers: int = 30, dropout: float = 0.0, attention_bias: bool = True, sample_width: int = 90, sample_height: int = 60, sample_frames: int = 49, patch_size: int = 2, temporal_compression_ratio: int = 4, max_text_seq_length: int = 226, activation_fn: str = 'gelu-approximate', timestep_activation_fn: str = 'silu', norm_elementwise_affine: bool = True, norm_eps: float = 1e-05, spatial_interpolation_scale: float = 1.875, temporal_interpolation_scale: float = 1.0, use_rotary_positional_embeddings: bool = False, use_learned_positional_embeddings: bool = False, is_train_face: bool = False, is_kps: bool = False, cross_attn_interval: int = 2, cross_attn_dim_head: int = 128, cross_attn_num_heads: int = 16, LFE_id_dim: int = 1280, LFE_vit_dim: int = 1024, LFE_depth: int = 10, LFE_dim_head: int = 64, LFE_num_heads: int = 16, LFE_num_id_token: int = 5, LFE_num_querie: int = 32, LFE_output_dim: int = 2048, LFE_ff_mult: int = 4, LFE_num_scale: int = 5, local_face_scale: float = 1.0)
```

[المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/consisid_transformer_3d.py#L351)

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

num_attention_heads (`int`، القيمة الافتراضية `30`) : عدد الرؤوس المستخدمة في الانتباه متعدد الرؤوس.

attention_head_dim (`int`، القيمة الافتراضية `64`) : عدد القنوات في كل رأس.

in_channels (`int`، القيمة الافتراضية `16`) : عدد القنوات في المدخلات.

out_channels (`int`، *اختياري*، القيمة الافتراضية `16`) : عدد القنوات في المخرجات.

flip_sin_to_cos (`bool`، القيمة الافتراضية `True`) : ما إذا كان يجب عكس sin إلى cos في تضمين الوقت.

time_embed_dim (`int`، القيمة الافتراضية `512`) : بُعد المخرجات لتضمينات خطوات الزمن.

text_embed_dim (`int`، القيمة الافتراضية `4096`) : بُعد الإدخال لتضمينات النص من مُشفِّر النص.

num_layers (`int`، القيمة الافتراضية `30`) : عدد طبقات كتل Transformer المستخدمة.

dropout (`float`، القيمة الافتراضية `0.0`) : احتمال الإسقاط (dropout) المستخدم.

attention_bias (`bool`، القيمة الافتراضية `True`) : ما إذا كان سيتم استخدام الانحياز في طبقات الإسقاط الانتباه.

sample_width (`int`، القيمة الافتراضية `90`) : عرض الكامنات المدخلة.

sample_height (`int`، القيمة الافتراضية `60`) : ارتفاع الكامنات المدخلة.

sample_frames (`int`، القيمة الافتراضية `49`) : عدد الإطارات في المتغيرات الكامنة المدخلة. لاحظ أن هذا المعامل تم تهيئته بشكل غير صحيح إلى 49 بدلاً من 13 لأن ConsisID كان يعالج 13 إطارًا كامنًا دفعة واحدة في إعداداته الافتراضية والموصى بها، لكن لا يمكن تغييره إلى القيمة الصحيحة لضمان التوافق مع الإصدارات السابقة. لإنشاء محول (transformer) يحتوي على K إطارًا كامنًا، فإن القيمة الصحيحة التي يجب تمريرها هنا هي: ((K - 1) * temporal_compression_ratio + 1).

patch_size (`int`، القيمة الافتراضية `2`) : حجم البقع المستخدمة في طبقة تضمين البقع.

temporal_compression_ratio (`int`، القيمة الافتراضية `4`) : نسبة الضغط عبر البُعد الزمني. راجع التوثيق الخاص بـ`sample_frames`.

max_text_seq_length (`int`، القيمة الافتراضية `226`) : الحد الأقصى لطول تسلسل مدخلات تمثيلات النص.

activation_fn (`str`، القيمة الافتراضية `"gelu-approximate"`) : دالة التنشيط المستخدمة في الشبكة العصبية الأمامية.

timestep_activation_fn (`str`، الافتراضي `"silu"`) : دالة التنشيط المستخدمة عند توليد تضمينات خطوة الزمن.

norm_elementwise_affine (`bool`، القيمة الافتراضية `True`) : ما إذا كان سيتم استخدام تحويل أفيني عنصرًا بعنصر في طبقات التطبيع.

norm_eps (`float`، القيمة الافتراضية `1e-5`) : قيمة الإيبسلون المستخدمة في طبقات التطبيع.

spatial_interpolation_scale (`float`، القيمة الافتراضية `1.875`) : معامل التوسيع الذي يُطبَّق في التضمينات الموضعية ثلاثية الأبعاد عبر الأبعاد المكانية.

temporal_interpolation_scale (`float`، القيمة الافتراضية `1.0`) : معامل التوسيع الذي يُطبَّق في التضمينات الموضعية ثلاثية الأبعاد عبر الأبعاد الزمنية.

is_train_face (`bool`، القيمة الافتراضية `False`) : ما إذا كان سيتم تفعيل وحدة الحفاظ على الهوية أثناء عملية التدريب. عند ضبطها على `True`، سيركز النموذج على مهام الحفاظ على الهوية.

is_kps (`bool`، القيمة الافتراضية `False`) : ما إذا كان سيتم تفعيل نقطة الوصل (keypoint) لاستخراج الوجه العام. إذا كانت `True`، فستكون نقاط الوصل موجودة في النموذج.

cross_attn_interval (`int`، القيمة الافتراضية `2`) : الفترة بين طبقات الانتباه المتقاطع في بنية Transformer. قد يؤدي استخدام قيمة أكبر إلى تقليل تكرار عمليات حساب الانتباه المتقاطع، مما يساعد في تقليل العبء الحسابي.

cross_attn_dim_head (`int`، اختياري، القيمة الافتراضية `128`) : بُعد كل رأس انتباه في طبقات الانتباه المتقاطع من بنية Transformer. تزيد القيمة الأكبر من القدرة على الانتباه إلى أنماط أكثر تعقيدًا، لكنها تزيد أيضًا من تكاليف الذاكرة والحساب.

cross_attn_num_heads (`int`، اختياري، القيمة الافتراضية `16`) : عدد رؤوس الانتباه في طبقات الانتباه المتقاطع. تتيح الرؤوس الإضافية آليات انتباه متوازية أكثر، مما يساعد على التقاط علاقات متنوعة بين المكونات المختلفة للمدخل، لكنها قد تزيد أيضًا من المتطلبات الحسابية.

LFE_id_dim (`int`، اختياري، القيمة الافتراضية `1280`) : بُعد متجه الهوية المستخدم في مستخرج الوجوه المحلي (LFE). يمثل هذا المتجه سمات الهوية للوجه، وهي مهمة لمهام مثل التعرف على الوجوه والحفاظ على الهوية عبر إطارات مختلفة.

LFE_vit_dim (`int`، اختياري، القيمة الافتراضية `1024`) : بُعد مخرج محوّل الرؤية (ViT) المستخدم في مستخرج الملامح الوجهية المحلية (LFE). يحدد هذا الحجم حجم متجهات الميزات التي يولدها المحوّل والتي ستُعالج لاستخراج ملامح الوجه.

LFE_depth (`int`، اختياري، القيمة الافتراضية `10`) : عدد الطبقات في مستخرج الوجه المحلي (LFE). زيادة العمق تتيح للنموذج التقاط تمثيلات أكثر تعقيدًا لميزات الوجه، لكنها تزيد أيضًا من العبء الحسابي.

LFE_dim_head (`int`، اختياري، القيمة الافتراضية `64`) : بُعد كل رأس انتباه في مستخرج الوجه المحلي (LFE). يؤثر هذا المعامل على مدى دقة معالجة النموذج والتركيز على الأجزاء المختلفة من ملامح الوجه أثناء عملية الاستخراج.

LFE_num_heads (`int`، اختياري، القيمة الافتراضية `16`) : عدد رؤوس الانتباه في مستخرج الوجوه المحلي (LFE). يمكن أن يؤدي زيادة عدد الرؤوس إلى تحسين قدرة النموذج على التقاط ميزات وجهية متنوعة، ولكن على حساب زيادة التعقيد الحسابي.

LFE_num_id_token (`int`، اختياري، القيمة الافتراضية `5`) : عدد رموز الهوية المستخدمة في مستخرج الوجوه المحلي (LFE). يحدد هذا العدد كمية الرموز المتعلقة بالهوية التي ستعالجها النموذج لضمان الحفاظ على هوية الوجه أثناء استخراج الميزات.

LFE_num_querie (`int`، اختياري، القيمة الافتراضية `32`) : عدد رموز الاستعلام المستخدمة في مستخرج الوجه المحلي (LFE). تُستخدم هذه الرموز لالتقاط المعلومات عالية التردد المتعلقة بالوجه، مما يساعد في استخراج ملامح الوجه بدقة.

LFE_output_dim (`int`، اختياري، القيمة الافتراضية `2048`) : بُعد المخرج لاستخراج الوجه المحلي (LFE). يحدد هذا البُعد حجم متجهات الميزات التي ينتجها وحدة LFE، والتي ستُستخدم في المهام اللاحقة مثل التعرف على الوجه أو التتبع.

LFE_ff_mult (`int`, اختياري، القيمة الافتراضية `4`) : عامل الضرب المطبّق على حجم الطبقة المخفية في الشبكة العصبية الأمامية (feed-forward) في مستخرج الملامح الوجهية المحلي (LFE). تزيد القيمة الأعلى من قدرة النموذج على تعلّم تحويلات أكثر تعقيدًا للملامح الوجهية، لكنها تزيد أيضًا من متطلبات الحساب والذاكرة.

LFE_num_scale (`int`، اختياري، القيمة الافتراضية `5`) : عدد المقاييس المختلفة للميزة البصرية. تزيد القيمة الأعلى من قدرة النموذج على تعلّم تحويلات أكثر تعقيدًا للميزات الوجهية، لكنها تزيد أيضًا من متطلبات الحساب والذاكرة.

local_face_scale (`float`، القيمة الافتراضية `1.0`) : معامل مقياس يُستخدم لضبط أهمية الميزات الوجهية المحلية في النموذج. يمكن أن يؤثر هذا على مدى تركيز النموذج على المحتوى المرتبط بالوجه ذي التردد العالي.

نموذج Transformer لبيانات تشبه الفيديو في [ConsisID](https://github.com/PKU-YuanGroup/ConsisID).

#### forward[[diffusers.ConsisIDTransformer3DModel.forward]]

```python
forward(hidden_states: Tensor, encoder_hidden_states: Tensor, timestep: typing.Union[int, float, torch.LongTensor], timestep_cond: typing.Optional[torch.Tensor] = None, image_rotary_emb: tuple[torch.Tensor, torch.Tensor] | None = None, attention_kwargs: dict[str, typing.Any] | None = None, id_cond: typing.Optional[torch.Tensor] = None, id_vit_hidden: typing.Optional[torch.Tensor] = None, return_dict: bool = True)
```

[المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/consisid_transformer_3d.py#L623)

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

hidden_states (`torch.Tensor` من الشكل `(batch_size, num_frames, channels, height, width)`) : مدخلات `hidden_states`.

encoder_hidden_states (`torch.Tensor` من الشكل `(batch_size, sequence_len, embed_dims)`) : التضمينات الشرطية (التضمينات المحسوبة من الشروط المدخلة مثل الأوامر) للاستخدام.

timestep (`torch.LongTensor`) : يُستخدم للإشارة إلى خطوة إزالة الضوضاء.

timestep_cond (`torch.Tensor`، *اختياري*) : تضمينات شرطية لخطوة الزمن. إذا تم توفيرها، سيتم جمع التضمينات مع العينات المارة عبر طبقة `self.time_embedding` للحصول على تضمينات خطوة الزمن النهائية.

image_rotary_emb (`tuple` من `torch.Tensor`، *اختياري*) : تمثيلات موضعية دوّارة محسوبة مسبقًا.

attention_kwargs (`dict`، *اختياري*) : قاموس kwargs يُمرَّر إلى `AttentionProcessor` إذا تم تحديده، كما هو معرَّف تحت `self.processor` في [diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py).

id_cond (`torch.Tensor`، *اختياري*) : تمثيل الوجه المستخرج بواسطة مستخرج الوجوه المحلي المستخدم لتكييف الهوية.

id_vit_hidden (`torch.Tensor`، *اختياري*) : حالات ViT المخفية المستخرجة من صور الوجوه المستخدمة لتكييف الهوية.

return_dict (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان يجب إرجاع `~models.transformer_2d.Transformer2DModelOutput` بدلاً من tuple عادي.

**يعيد:**

إذا كان `return_dict` صحيحًا، يُعاد `~models.transformer_2d.Transformer2DModelOutput`، وإلا يُعاد `tuple` يكون عنصره الأول هو تينسور العينة.

طريقة [ConsisIDTransformer3DModel](/docs/diffusers/v0.43.0/ar/api/models/consisid_transformer3d#diffusers.ConsisIDTransformer3DModel) الأمامية.

## Transformer2DModelOutput[[diffusers.models.modeling_outputs.Transformer2DModelOutput]]

#### diffusers.models.modeling_outputs.Transformer2DModelOutput[[diffusers.models.modeling_outputs.Transformer2DModelOutput]]

```python
diffusers.models.modeling_outputs.Transformer2DModelOutput(sample: torch.Tensor)
```

[المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/modeling_outputs.py#L21)

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

sample (`torch.Tensor` من الشكل `(batch_size, num_channels, height, width)` أو `(batch size, num_vector_embeds - 1, num_latent_pixels)` إذا كان [Transformer2DModel](/docs/diffusers/v0.43.0/ar/api/models/transformer2d#diffusers.Transformer2DModel) منفصلاً): مخرجات الحالات المخفية المشروطة على مدخل `encoder_hidden_states`. إذا كان منفصلاً، يعيد توزيعات الاحتمال للبكسلات الكامنة غير الملوثة.

مخرجات [Transformer2DModel](/docs/diffusers/v0.43.0/ar/api/models/transformer2d#diffusers.Transformer2DModel).