# CogVideoXTransformer3DModel

A Diffusion Transformer model for 3D data from [CogVideoX](https://github.com/THUDM/CogVideo) was introduced in [CogVideoX: Text-to-Video Diffusion Models with An Expert Transformer](https://huggingface.co/papers/2408.06072) by Tsinghua University & ZhipuAI.

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

```python
from diffusers import CogVideoXTransformer3DModel

transformer = CogVideoXTransformer3DModel.from_pretrained("THUDM/CogVideoX-2b", subfolder="transformer", dtype=torch.float16).to("cuda")  # or "mps", "xpu", "cpu"
```

## CogVideoXTransformer3DModel[[diffusers.CogVideoXTransformer3DModel]]

#### diffusers.CogVideoXTransformer3DModel[[diffusers.CogVideoXTransformer3DModel]]

```python
diffusers.CogVideoXTransformer3DModel(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, ofs_embed_dim: int | None = None, 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, patch_size_t: int | None = None, 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, patch_bias: bool = True)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/cogvideox_transformer_3d.py#L160)

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

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`) : بُعد المخرجات لتضمينات خطوات الزمن.

ofs_embed_dim (`int`، القيمة الافتراضية `512`) : بُعد المخرجات لتضمينات "ofs" المستخدمة في CogVideoX-5b-I2B في الإصدار 1.5

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، لأن CogVideoX كان يعالج 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`) : معامل التوسيع الذي يُطبَّق في التضمينات الموضعية ثلاثية الأبعاد عبر الأبعاد الزمنية.

نموذج Transformer لبيانات تشبه الفيديو في [CogVideoX](https://github.com/THUDM/CogVideo).

#### forward[[diffusers.CogVideoXTransformer3DModel.forward]]

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

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/cogvideox_transformer_3d.py#L366)

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

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` للحصول على تضمينات خطوة الزمن النهائية.

ofs (`torch.Tensor`، *اختياري*) : تضمينات الإزاحة المستخدمة في CogVideoX-5b-I2V.

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

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

**يعيد:**

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

طريقة [CogVideoXTransformer3DModel](/docs/diffusers/main/ar/api/models/cogvideox_transformer3d#diffusers.CogVideoXTransformer3DModel) الأمامية.

#### fuse_qkv_projections[[diffusers.CogVideoXTransformer3DModel.fuse_qkv_projections]]

```python
fuse_qkv_projections()
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/cogvideox_transformer_3d.py#L335)

…

> [!WARNING] > هذه الواجهة البرمجية 🧪 تجريبية.

#### unfuse_qkv_projections[[diffusers.CogVideoXTransformer3DModel.unfuse_qkv_projections]]

```python
unfuse_qkv_projections()
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/cogvideox_transformer_3d.py#L357)

يعطّل إسقاط QKV المدمج إذا كان مفعّلًا.

> [!WARNING] > هذه الواجهة البرمجية 🧪 تجريبية.

## 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/main/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/main/ar/api/models/transformer2d#diffusers.Transformer2DModel) منفصلاً): مخرجات الحالات المخفية المشروطة على مدخل `encoder_hidden_states`. إذا كان منفصلاً، يعيد توزيعات الاحتمال للبكسلات الكامنة غير الملوثة.

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