# ConsisIDTransformer3DModel

Model Diffusion Transformer untuk data 3D dari [ConsisID](https://github.com/PKU-YuanGroup/ConsisID) diperkenalkan dalam [Identity-Preserving Text-to-Video Generation by Frequency Decomposition](https://huggingface.co/papers/2411.17440) oleh Peking University & University of Rochester & lainnya.

Model dapat dimuat dengan potongan kode berikut.

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

[Sumber](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/consisid_transformer_3d.py#L351)

**Parameter:**

num_attention_heads (`int`, defaultnya `30`) : Jumlah head yang digunakan untuk multi-head attention.

attention_head_dim (`int`, defaultnya `64`) : Jumlah channel di setiap head.

in_channels (`int`, defaultnya `16`) : Jumlah channel pada input.

out_channels (`int`, *opsional*, defaultnya `16`) : Jumlah channel pada output.

flip_sin_to_cos (`bool`, defaultnya `True`) : Apakah akan membalik sin menjadi cos dalam time embedding.

time_embed_dim (`int`, defaultnya `512`) : Dimensi output dari embedding timestep.

text_embed_dim (`int`, defaultnya `4096`) : Dimensi input dari embedding teks yang berasal dari text encoder.

num_layers (`int`, defaultnya `30`) : Jumlah lapisan blok Transformer yang akan digunakan.

dropout (`float`, defaultnya `0.0`) : Probabilitas dropout yang digunakan.

attention_bias (`bool`, defaultnya `True`) : Apakah akan menggunakan bias pada lapisan proyeksi perhatian.

sample_width (`int`, defaultnya `90`) : Lebar dari latens input.

sample_height (`int`, defaultnya `60`) : Tinggi dari latens input.

sample_frames (`int`, defaultnya `49`) : Jumlah frame pada latens input. Perhatikan bahwa parameter ini diinisialisasi secara keliru ke 49 alih-alih 13 karena ConsisID memproses 13 frame latens sekaligus pada pengaturan default dan yang direkomendasikannya, namun tidak dapat diubah ke nilai yang benar untuk memastikan kompatibilitas mundur. Untuk membuat transformer dengan K frame latens, nilai yang benar untuk dilewatkan di sini adalah: ((K - 1) * temporal_compression_ratio + 1).

patch_size (`int`, defaultnya `2`) : Ukuran patch yang akan digunakan di lapisan patch embedding.

temporal_compression_ratio (`int`, defaultnya `4`) : Rasio kompresi di sepanjang dimensi temporal. Lihat dokumentasi untuk `sample_frames`.

max_text_seq_length (`int`, defaultnya `226`) : Panjang maksimum urutan dari embedding teks input.

activation_fn (`str`, defaultnya `"gelu-approximate"`) : Fungsi aktivasi yang digunakan dalam feed-forward.

timestep_activation_fn (`str`, defaultnya `"silu"`) : Fungsi aktivasi yang digunakan saat menghasilkan embedding timestep.

norm_elementwise_affine (`bool`, defaultnya `True`) : Apakah akan menggunakan elementwise affine di lapisan normalisasi.

norm_eps (`float`, defaultnya `1e-5`) : Nilai epsilon yang digunakan dalam lapisan normalisasi.

spatial_interpolation_scale (`float`, defaultnya `1.875`) : Faktor skala yang diterapkan pada embedding posisional 3D di sepanjang dimensi spasial.

temporal_interpolation_scale (`float`, defaultnya `1.0`) : Faktor penskalaan yang diterapkan pada embedding posisi 3D di sepanjang dimensi temporal.

is_train_face (`bool`, defaultnya `False`) : Apakah akan mengaktifkan modul pelestarian identitas selama proses pelatihan. Jika diatur ke `True`, model akan berfokus pada tugas pelestarian identitas.

is_kps (`bool`, defaultnya `False`) : Apakah akan mengaktifkan keypoint untuk ekstraktor wajah global. Jika `True`, keypoint akan ada di dalam model.

cross_attn_interval (`int`, defaultnya `2`) : Interval antara lapisan cross-attention dalam arsitektur Transformer. Nilai yang lebih besar dapat mengurangi frekuensi komputasi cross-attention, yang dapat membantu mengurangi beban komputasi.

cross_attn_dim_head (`int`, opsional, default `128`) : Dimensi dari setiap kepala perhatian (attention head) pada lapisan cross-attention dalam arsitektur Transformer. Nilai yang lebih besar meningkatkan kapasitas untuk memperhatikan pola yang lebih kompleks, tetapi juga meningkatkan biaya memori dan komputasi.

cross_attn_num_heads (`int`, opsional, default `16`) : Jumlah kepala perhatian pada lapisan cross-attention. Semakin banyak kepala, semakin banyak mekanisme perhatian paralel yang dapat dijalankan, sehingga mampu menangkap hubungan yang beragam antar komponen input, namun juga dapat meningkatkan kebutuhan komputasi.

LFE_id_dim (`int`, opsional, default `1280`) : Dimensi dari vektor identitas yang digunakan dalam Local Facial Extractor (LFE). Vektor ini merepresentasikan fitur identitas dari wajah, yang penting untuk tugas seperti pengenalan wajah dan pelestarian identitas di berbagai frame.

LFE_vit_dim (`int`, opsional, default `1024`) : Dimensi dari output vision transformer (ViT) yang digunakan dalam Local Facial Extractor (LFE). Nilai ini menentukan ukuran vektor fitur yang dihasilkan transformer yang akan diproses untuk ekstraksi fitur wajah.

LFE_depth (`int`, opsional, default `10`) : Jumlah lapisan dalam Local Facial Extractor (LFE). Meningkatkan kedalaman memungkinkan model menangkap representasi fitur wajah yang lebih kompleks, tetapi juga meningkatkan beban komputasi.

LFE_dim_head (`int`, opsional, default `64`) : Dimensi dari setiap kepala perhatian (attention head) dalam Local Facial Extractor (LFE). Parameter ini memengaruhi seberapa halus model dapat memproses dan memfokuskan pada bagian-bagian berbeda dari fitur wajah selama proses ekstraksi.

LFE_num_heads (`int`, opsional, default `16`) : Jumlah kepala perhatian dalam Local Facial Extractor (LFE). Semakin banyak kepala, semakin baik kemampuan model untuk menangkap fitur wajah yang beragam, namun dengan biaya kompleksitas komputasi yang meningkat.

LFE_num_id_token (`int`, opsional, default `5`) : Jumlah token identitas yang digunakan dalam Local Facial Extractor (LFE). Ini menentukan berapa banyak token terkait identitas yang akan diproses oleh model untuk memastikan pelestarian identitas wajah selama ekstraksi fitur.

LFE_num_querie (`int`, opsional, default `32`) : Jumlah token query yang digunakan dalam Local Facial Extractor (LFE). Token-token ini digunakan untuk menangkap informasi wajah berfrekuensi tinggi yang membantu dalam ekstraksi fitur wajah yang akurat.

LFE_output_dim (`int`, opsional, default `2048`) : Dimensi output dari Local Facial Extractor (LFE). Dimensi ini menentukan ukuran vektor fitur yang dihasilkan oleh modul LFE, yang akan digunakan untuk tugas-tugas selanjutnya seperti pengenalan wajah atau pelacakan.

LFE_ff_mult (`int`, opsional, default `4`) : Faktor perkalian yang diterapkan pada ukuran lapisan tersembunyi jaringan feed-forward dalam Local Facial Extractor (LFE). Nilai yang lebih tinggi meningkatkan kapasitas model untuk mempelajari transformasi fitur wajah yang lebih kompleks, tetapi juga meningkatkan persyaratan komputasi dan memori.

LFE_num_scale (`int`, opsional, default `5`) : Jumlah skala fitur visual yang berbeda. Nilai yang lebih tinggi meningkatkan kapasitas model untuk mempelajari transformasi fitur wajah yang lebih kompleks, tetapi juga meningkatkan persyaratan komputasi dan memori.

local_face_scale (`float`, defaultnya `1.0`) : Faktor penskalaan yang digunakan untuk menyesuaikan pentingnya fitur wajah lokal dalam model. Hal ini dapat memengaruhi seberapa kuat model berfokus pada konten terkait wajah dengan frekuensi tinggi.

Model Transformer untuk data seperti video di [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)
```

[Sumber](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/consisid_transformer_3d.py#L623)

**Parameter:**

hidden_states (`torch.Tensor` dengan bentuk `(batch_size, num_frames, channels, height, width)`) : `hidden_states` masukan.

encoder_hidden_states (`torch.Tensor` dengan bentuk `(batch_size, sequence_len, embed_dims)`) : Embedding kondisional (embedding yang dihitung dari kondisi input seperti prompt) yang akan digunakan.

timestep (`torch.LongTensor`) : Digunakan untuk menunjukkan langkah denoising.

timestep_cond (`torch.Tensor`, *opsional*) : Embedding kondisional untuk timestep. Jika disediakan, embedding akan dijumlahkan dengan sampel yang melewati lapisan `self.time_embedding` untuk mendapatkan embedding timestep akhir.

image_rotary_emb (`tuple` dari `torch.Tensor`, *opsional*) : Embedding posisi rotasi yang telah dihitung sebelumnya.

attention_kwargs (`dict`, *opsional*) : Kamus kwargs yang jika ditentukan akan diteruskan ke `AttentionProcessor` seperti yang didefinisikan di bawah `self.processor` dalam [diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py).

id_cond (`torch.Tensor`, *opsional*) : Embedding wajah yang diekstrak oleh ekstraktor wajah lokal yang digunakan untuk kondisioning identitas.

id_vit_hidden (`torch.Tensor`, *opsional*) : State tersembunyi ViT yang diekstrak dari gambar wajah dan digunakan untuk kondisioning identitas.

return_dict (`bool`, *opsional*, defaultnya `True`) : Apakah akan mengembalikan `~models.transformer_2d.Transformer2DModelOutput` alih-alih tuple biasa.

**Mengembalikan:**

Jika `return_dict` bernilai True, sebuah `~models.transformer_2d.Transformer2DModelOutput` akan dikembalikan, selain itu sebuah `tuple` di mana elemen pertama adalah tensor sampel.

Metode forward dari [ConsisIDTransformer3DModel](/docs/diffusers/main/id/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)
```

[Sumber](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/modeling_outputs.py#L21)

**Parameter:**

sample (`torch.Tensor` dengan bentuk `(batch_size, num_channels, height, width)` atau `(batch size, num_vector_embeds - 1, num_latent_pixels)` jika [Transformer2DModel](/docs/diffusers/main/id/api/models/transformer2d#diffusers.Transformer2DModel) bersifat diskrit) : Output hidden states yang dikondisikan pada input `encoder_hidden_states`. Jika diskrit, mengembalikan distribusi probabilitas untuk piksel laten yang tidak berisik.

Output dari [Transformer2DModel](/docs/diffusers/main/id/api/models/transformer2d#diffusers.Transformer2DModel).