# ConsisIDTransformer3DModel

Un modelo Diffusion Transformer para datos 3D de [ConsisID](https://github.com/PKU-YuanGroup/ConsisID) fue introducido en [Identity-Preserving Text-to-Video Generation by Frequency Decomposition](https://huggingface.co/papers/2411.17440) por Peking University & University of Rochester & etc.

El modelo se puede cargar con el siguiente fragmento de código.

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

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

**Parámetros:**

num_attention_heads (`int`, por defecto `30`) : El número de cabezas a utilizar para la atención multi-cabeza.

attention_head_dim (`int`, por defecto `64`) : El número de canales en cada cabeza.

in_channels (`int`, por defecto `16`) : El número de canales en la entrada.

out_channels (`int`, *opcional*, valor predeterminado `16`) : El número de canales en la salida.

flip_sin_to_cos (`bool`, por defecto `True`) : Si se debe cambiar el sin por el cos en la incrustación temporal.

time_embed_dim (`int`, por defecto `512`) : Dimensión de salida de las incrustaciones de paso de tiempo.

text_embed_dim (`int`, por defecto `4096`) : Dimensión de entrada de las incrustaciones de texto del codificador de texto.

num_layers (`int`, por defecto `30`) : El número de bloques de Transformer a utilizar.

dropout (`float`, por defecto `0.0`) : La probabilidad de dropout a utilizar.

attention_bias (`bool`, por defecto `True`) : Si se debe usar sesgo en las capas de proyección de atención.

sample_width (`int`, por defecto `90`) : El ancho de los latentes de entrada.

sample_height (`int`, por defecto `60`) : La altura de los latentes de entrada.

sample_frames (`int`, por defecto `49`) : El número de fotogramas en los latentes de entrada. Tenga en cuenta que este parámetro se inicializó incorrectamente en 49 en lugar de 13, ya que ConsisID procesaba 13 fotogramas latentes a la vez en su configuración predeterminada y recomendada, pero no puede cambiarse al valor correcto para garantizar la compatibilidad hacia atrás. Para crear un transformer con K fotogramas latentes, el valor correcto que debe pasarse aquí sería: ((K - 1) * temporal_compression_ratio + 1).

patch_size (`int`, por defecto `2`) : El tamaño de los parches a utilizar en la capa de incrustación de parches.

temporal_compression_ratio (`int`, por defecto `4`) : La relación de compresión a lo largo de la dimensión temporal. Consulte la documentación de `sample_frames`.

max_text_seq_length (`int`, por defecto `226`) : La longitud máxima de la secuencia de las incrustaciones de texto de entrada.

activation_fn (`str`, por defecto `"gelu-approximate"`) : Función de activación a utilizar en la red feed-forward.

timestep_activation_fn (`str`, por defecto `"silu"`) : Función de activación a utilizar al generar las incrustaciones de paso temporal.

norm_elementwise_affine (`bool`, por defecto `True`) : Si se debe usar afinidad elementwise en las capas de normalización.

norm_eps (`float`, por defecto `1e-5`) : El valor de epsilon a utilizar en las capas de normalización.

spatial_interpolation_scale (`float`, por defecto `1.875`) : Factor de escala a aplicar en los embeddings posicionales 3D a lo largo de las dimensiones espaciales.

temporal_interpolation_scale (`float`, por defecto `1.0`) : Factor de escala a aplicar en las incrustaciones posicionales 3D a lo largo de las dimensiones temporales.

is_train_face (`bool`, por defecto `False`) : Si se debe habilitar el módulo de preservación de identidad durante el proceso de entrenamiento. Cuando se establece en `True`, el modelo se centrará en tareas de preservación de identidad.

is_kps (`bool`, por defecto `False`) : Si se habilita el punto clave para el extractor facial global. Si es `True`, los puntos clave estarán en el modelo.

cross_attn_interval (`int`, por defecto `2`) : El intervalo entre las capas de atención cruzada en la arquitectura Transformer. Un valor mayor puede reducir la frecuencia de los cálculos de atención cruzada, lo que ayuda a disminuir la sobrecarga computacional.

cross_attn_dim_head (`int`, opcional, valor predeterminado `128`) : La dimensionalidad de cada cabeza de atención en las capas de atención cruzada de la arquitectura Transformer. Un valor mayor aumenta la capacidad de atender a patrones más complejos, pero también incrementa los costos de memoria y computación.

cross_attn_num_heads (`int`, opcional, valor predeterminado `16`) : El número de cabezas de atención en las capas de atención cruzada. Más cabezas permiten mecanismos de atención más paralelos, capturando relaciones diversas entre los distintos componentes de la entrada, pero también pueden aumentar los requisitos computacionales.

LFE_id_dim (`int`, opcional, valor predeterminado `1280`) : La dimensionalidad del vector de identidad utilizado en el Local Facial Extractor (LFE). Este vector representa las características de identidad de un rostro, que son importantes para tareas como el reconocimiento facial y la preservación de la identidad a través de diferentes fotogramas.

LFE_vit_dim (`int`, opcional, valor predeterminado `1024`) : La dimensión de la salida del vision transformer (ViT) utilizada en el Local Facial Extractor (LFE). Este valor determina el tamaño de los vectores de características generados por el transformer que se procesarán para la extracción de rasgos faciales.

LFE_depth (`int`, opcional, valor predeterminado `10`) : El número de capas en el Extractor Facial Local (LFE). Aumentar la profundidad permite que el modelo capture representaciones más complejas de las características faciales, pero también aumenta la carga computacional.

LFE_dim_head (`int`, opcional, valor predeterminado `64`) : La dimensionalidad de cada cabeza de atención en el Local Facial Extractor (LFE). Este parámetro afecta la precisión con la que el modelo puede procesar y enfocarse en diferentes partes de las facciones faciales durante el proceso de extracción.

LFE_num_heads (`int`, opcional, valor predeterminado `16`) : El número de cabezas de atención en el Local Facial Extractor (LFE). Más cabezas pueden mejorar la capacidad del modelo para capturar diversas características faciales, pero a costa de una mayor complejidad computacional.

LFE_num_id_token (`int`, opcional, valor predeterminado `5`) : El número de tokens de identidad utilizados en el Local Facial Extractor (LFE). Esto define cuántos tokens relacionados con la identidad procesará el modelo para garantizar la preservación de la identidad facial durante la extracción de características.

LFE_num_querie (`int`, opcional, valor predeterminado `32`) : El número de tokens de consulta utilizados en el Local Facial Extractor (LFE). Estos tokens se usan para capturar información de alta frecuencia relacionada con el rostro que ayuda a extraer las facciones faciales con precisión.

LFE_output_dim (`int`, opcional, valor predeterminado `2048`) : La dimensión de salida del Local Facial Extractor (LFE). Esta dimensión determina el tamaño de los vectores de características producidos por el módulo LFE, que se utilizarán para tareas posteriores como el reconocimiento o el seguimiento de rostros.

LFE_ff_mult (`int`, opcional, valor predeterminado `4`) : El factor de multiplicación aplicado al tamaño de la capa oculta de la red feed-forward en el Local Facial Extractor (LFE). Un valor más alto aumenta la capacidad del modelo para aprender transformaciones más complejas de rasgos faciales, pero también aumenta los requisitos de cómputo y memoria.

LFE_num_scale (`int`, opcional, valor predeterminado `5`) : El número de escalas diferentes de la característica visual. Un valor más alto aumenta la capacidad del modelo para aprender transformaciones más complejas de características faciales, pero también aumenta los requisitos de cómputo y memoria.

local_face_scale (`float`, por defecto `1.0`) : Un factor de escala utilizado para ajustar la importancia de las facciones faciales locales en el modelo. Esto puede influir en la intensidad con la que el modelo se centra en el contenido facial de alta frecuencia.

Un modelo Transformer para datos similares a video en [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)
```

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

**Parámetros:**

hidden_states (`torch.Tensor` de forma `(batch_size, num_frames, channels, height, width)`) : `hidden_states` de entrada.

encoder_hidden_states (`torch.Tensor` de forma `(batch_size, sequence_len, embed_dims)`) : Embeddings condicionales (embeddings calculados a partir de las condiciones de entrada, como los prompts) a utilizar.

timestep (`torch.LongTensor`) : Se utiliza para indicar el paso de desruido.

timestep_cond (`torch.Tensor`, *opcional*) : Incrustaciones condicionales para el paso de tiempo. Si se proporcionan, las incrustaciones se sumarán con las muestras que pasan por la capa `self.time_embedding` para obtener las incrustaciones finales del paso de tiempo.

image_rotary_emb (`tuple` de `torch.Tensor`, *opcional*) : Incrustaciones posicionales rotatorias precalculadas.

attention_kwargs (`dict`, *opcional*) : Un diccionario de kwargs que, si se especifica, se pasa al `AttentionProcessor` tal como se define bajo `self.processor` en [diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py).

id_cond (`torch.Tensor`, *opcional*) : El embedding facial extraído por el extractor facial local utilizado para la condicionamiento de identidad.

id_vit_hidden (`torch.Tensor`, *opcional*) : Los estados ocultos de ViT extraídos de las imágenes faciales utilizados para la condicionamiento de identidad.

return_dict (`bool`, *opcional*, valor predeterminado `True`) : Indica si se debe devolver un `~models.transformer_2d.Transformer2DModelOutput` en lugar de una tupla simple.

**Devuelve:**

Si `return_dict` es True, se devuelve un `~models.transformer_2d.Transformer2DModelOutput`; en caso contrario, se devuelve una `tuple` cuyo primer elemento es el tensor de la muestra.

El método forward de [ConsisIDTransformer3DModel](/docs/diffusers/v0.43.0/es/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)
```

[Fuente](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/modeling_outputs.py#L21)

**Parámetros:**

sample (`torch.Tensor` de forma `(batch_size, num_channels, height, width)` o `(batch size, num_vector_embeds - 1, num_latent_pixels)` si [Transformer2DModel](/docs/diffusers/v0.43.0/es/api/models/transformer2d#diffusers.Transformer2DModel) es discreto): las salidas de estados ocultos condicionadas a la entrada `encoder_hidden_states`. Si es discreto, devuelve distribuciones de probabilidad para los píxeles latentes sin ruido.

La salida de [Transformer2DModel](/docs/diffusers/v0.43.0/es/api/models/transformer2d#diffusers.Transformer2DModel).