Transformers documentation
Pixio
Este modelo fue aportado a Hugging Face Transformers el 2025-12-17. Este modelo será anunciado próximamente
Pixio
Pixio es un modelo de visión de base que utiliza ViT como extractor de características para múltiples tareas posteriores, como la estimación de profundidad, la segmentación semántica, la reconstrucción 3D feed-forward, la robótica y la clasificación de imágenes. Se basa en el marco de preentrenamiento de Autoencoder enmascarado (MAE), con cuatro actualizaciones mínimas pero críticas: 1) decodificador más profundo, 2) mayor granularidad de enmascarado, 3) más tokens de clase y 4) datos de entrenamiento curados a escala web.
Puedes encontrar todos los puntos de control originales de Pixio en la colección Pixio.
El siguiente ejemplo demuestra cómo obtener un embedding de imagen con la clase AutoModel.
<hfoptions id="usage"> <hfoption id="AutoModel">import requests
from PIL import Image
from transformers import AutoImageProcessor, AutoModel
url = "http://images.cocodataset.org/val2017/000000039769.jpg"
image = Image.open(requests.get(url, stream=True).raw)
processor = AutoImageProcessor.from_pretrained("facebook/pixio-vith16")
model = AutoModel.from_pretrained("facebook/pixio-vith16", device_map="auto")
inputs = processor(images=image, return_tensors="pt").to(model.device)
outputs = model(**inputs)
features_norm = outputs.last_hidden_state # class tokens + patch tokens after last LayerNorm
features = outputs.hidden_states[-1] # class tokens + patch tokens before last LayerNormNotas
El siguiente ejemplo muestra cómo dividir el tensor de salida en:
- un conjunto de embeddings globales para toda la imagen, comúnmente referidos como token
CLS, útiles para clasificación y recuperación. Puedes promediarlos (recomendado) o concatenarlos a lo largo de la dimensión de canal. - un conjunto de embeddings locales, uno para cada parche de
16x16de la imagen de entrada, útil para tareas densas, como la estimación de profundidad y la segmentación semántica.
from transformers import AutoImageProcessor, AutoModel from PIL import Image import requests url = 'http://images.cocodataset.org/val2017/000000039769.jpg' image = Image.open(requests.get(url, stream=True).raw) print(image.height, image.width) # [480, 640] processor = AutoImageProcessor.from_pretrained('facebook/pixio-vith16') model = AutoModel.from_pretrained('facebook/pixio-vith16', device_map="auto") patch_size = model.config.patch_size inputs = processor(images=image, return_tensors="pt").to(model.device) print(inputs.pixel_values.shape) # [1, 3, 256, 256] batch_size, rgb, img_height, img_width = inputs.pixel_values.shape num_patches_height, num_patches_width = img_height // patch_size, img_width // patch_size num_patches_flat = num_patches_height * num_patches_width outputs = model(**inputs) last_hidden_states = outputs.last_hidden_state print(last_hidden_states.shape) # [1, 8 + 256, 1280] assert last_hidden_states.shape == (batch_size, model.config.n_cls_tokens + num_patches_flat, model.config.hidden_size) cls_tokens = last_hidden_states[:, :model.config.n_cls_tokens, :] patch_features = last_hidden_states[:, model.config.n_cls_tokens:, :].unflatten(1, (num_patches_height, num_patches_width))- un conjunto de embeddings globales para toda la imagen, comúnmente referidos como token
Usa torch.compile para acelerar la inferencia.
import torch from transformers import AutoImageProcessor, AutoModel from PIL import Image import requests url = 'http://images.cocodataset.org/val2017/000000039769.jpg' image = Image.open(requests.get(url, stream=True).raw) processor = AutoImageProcessor.from_pretrained('facebook/pixio-vith16') model = AutoModel.from_pretrained('facebook/pixio-vith16', device_map="auto") compiled_model = torch.compile(model) inputs = processor(images=image, return_tensors="pt").to(model.device) outputs = compiled_model(**inputs) last_hidden_states = outputs.last_hidden_state
PixioConfig
clase transformers.PixioConfig
< source >( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonehidden_size: int = 1280num_hidden_layers: int = 32num_attention_heads: int = 16mlp_ratio: int = 4hidden_act: str = 'gelu'hidden_dropout_prob: float | int = 0.0attention_probs_dropout_prob: float | int = 0.0initializer_range: float = 0.02layer_norm_eps: float = 1e-06image_size: int | list[int] | tuple[int, int] = 256patch_size: int | list[int] | tuple[int, int] = 16num_channels: int = 3qkv_bias: bool = Truedrop_path_rate: float | int = 0.0_out_features: list[str] | None = None_out_indices: list[int] | None = Noneapply_layernorm: bool = Truereshape_hidden_states: bool = Truen_cls_tokens: int = 8 )
Parámetros
- hidden_size (
int, opcional, valor predeterminado1280) — Dimensión de las representaciones ocultas. - num_hidden_layers (
int, opcional, valor predeterminado32) — Número de capas ocultas en el decodificador del Transformer. - num_attention_heads (
int, opcional, valor predeterminado16) — Número de cabezas de atención para cada capa de atención en el decodificador Transformer. - mlp_ratio (
int, opcional, valor predeterminado4) — Relación entre la dimensión oculta del MLP y la dimensión de la incrustación. - hidden_act (
str, opcional, valor predeterminadogelu) — La función de activación no lineal (función o cadena) en el decodificador. Por ejemplo,"gelu","relu","silu", etc. - hidden_dropout_prob (
Union[float, int], opcional, valor predeterminado0.0) — La probabilidad de dropout para todas las capas totalmente conectadas en las incrustaciones, el codificador y el pooler. - attention_probs_dropout_prob (
Union[float, int], opcional, valor predeterminado0.0) — La proporción de dropout para las probabilidades de atención. - initializer_range (
float, opcional, valor predeterminado0.02) — La desviación estándar del truncated_normal_initializer para inicializar todas las matrices de pesos. - layer_norm_eps (
float, opcional, valor predeterminado1e-06) — La epsilon utilizada por las capas de normalización de capa. - image_size (
Union[int, list[int], tuple[int, int]], opcional, valor predeterminado256) — El tamaño (resolución) de cada imagen. - patch_size (
Union[int, list[int], tuple[int, int]], opcional, valor predeterminado16) — El tamaño (resolución) de cada parche. - num_channels (
int, opcional, valor predeterminado3) — El número de canales de entrada. - qkv_bias (
bool, opcional, valor predeterminadoTrue) — Si se debe añadir un sesgo a las consultas, claves y valores. - drop_path_rate (
Union[float, int], opcional, valor predeterminado0.0) — Tasa de drop path para la fusión de parches. - apply_layernorm (
bool, opcional, valor predeterminadoTrue) — Si se aplica la normalización de capas a los mapas de características en caso de que el modelo se utilice como backbone. - reshape_hidden_states (
bool, opcional, valor predeterminadoTrue) — Si se deben redimensionar los mapas de características a tensores 4D de forma(batch_size, hidden_size, height, width)en caso de que el modelo se utilice como backbone. Si esFalse, los mapas de características serán tensores 3D de forma(batch_size, seq_len, hidden_size). - n_cls_tokens (
int, opcional, valor predeterminado 8) — Número de tokens de clase en el codificador Transformer.
Esta es la clase de configuración para almacenar la configuración de un PixioModel. Se utiliza para instanciar un modelo Pixio según los argumentos especificados, definiendo la arquitectura del modelo. Instanciar una configuración con los valores predeterminados producirá una configuración similar a la de facebook/pixio-huge
Los objetos de configuración heredan de PreTrainedConfig y se pueden usar para controlar las salidas del modelo. Lea la documentación de PreTrainedConfig para obtener más información.
Ejemplo:
>>> from transformers import PixioConfig, PixioModel
>>> # Initializing a Pixio pixio-huge style configuration
>>> configuration = PixioConfig()
>>> # Initializing a model (with random weights) from the pixio-huge style configuration
>>> model = PixioModel(configuration)
>>> # Accessing the model configuration
>>> configuration = model.configPixioModel
clase transformers.PixioModel
< source >( config: PixioConfig )
Parámetros
- config (PixioConfig) — Clase de configuración del modelo con todos los parámetros del modelo. Inicializar con un archivo de configuración no carga los pesos asociados con el modelo, solo la configuración. Consulte el método from_pretrained() para cargar los pesos del modelo.
El modelo Pixio básico que emite estados ocultos sin ningún cabezal específico en la parte superior.
Este modelo hereda de PreTrainedModel. Consulta la documentación de la clase superior para los métodos genéricos que la biblioteca implementa para todos sus modelos (como la descarga o el guardado, el redimensionamiento de las incrustaciones de entrada, la poda de cabezas, etc.).
Este modelo también es una subclase de torch.nn.Module de PyTorch. Úsalo como un módulo de PyTorch regular y consulta la documentación de PyTorch para todo lo relacionado con el uso y el comportamiento generales.
forward
< source >( pixel_values: typing.Optional[torch.Tensor] = Noneattention_mask: typing.Optional[torch.Tensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → BaseModelOutputWithPooling or tuple(torch.Tensor)
Parámetros
- pixel_values (
torch.Tensorde forma(batch_size, num_channels, image_size, image_size), opcional) — Los tensores correspondientes a las imágenes de entrada. Los valores de píxeles se pueden obtener utilizando BitImageProcessor. Consulte BitImageProcessor.call() para más detalles (processor_classutiliza BitImageProcessor para procesar las imágenes). - attention_mask (
torch.Tensorde forma(batch_size, sequence_length), opcional) — Máscara para evitar realizar atención en los índices de tokens de relleno. Valores de máscara seleccionados en[0, 1]:- 1 para los tokens que no están enmascarados,
- 0 para los tokens que están enmascarados.
Devuelve
BaseModelOutputWithPooling o tuple(torch.Tensor)
Un BaseModelOutputWithPooling o una tupla de
torch.Tensor (si se pasa return_dict=False o cuando config.return_dict=False) que comprende varios
elementos según la configuración (PixioConfig) y las entradas.
El método forward de PixioModel sobrescribe el método especial __call__.
Aunque la receta para la pasada hacia adelante debe definirse dentro de esta función, se debe llamar a la instancia de
Moduledespués en lugar de a esta, ya que la primera se encarga de ejecutar los pasos de pre y postprocesamiento, mientras que la segunda los ignora silenciosamente.
last_hidden_state (
torch.Tensorde forma(batch_size, sequence_length, hidden_size)) — Secuencia de estados ocultos en la salida de la última capa del modelo.pooler_output (
torch.Tensorde forma(batch_size, hidden_size)) — Estado oculto de la última capa del primer token de la secuencia (token de clasificación) después de un procesamiento adicional a través de las capas utilizadas para la tarea de preentrenamiento auxiliar. Por ejemplo, para la familia de modelos BERT, esto devuelve el token de clasificación después de procesarlo a través de una capa lineal y una función de activación tanh. Los pesos de la capa lineal se entrenan a partir del objetivo de predicción de la siguiente oración (clasificación) durante el preentrenamiento.hidden_states (
tuple(torch.Tensor), opcional, devuelto cuando se pasaoutput_hidden_states=Trueo cuandoconfig.output_hidden_states=True) — Tupla detorch.Tensor(una para la salida de las incrustaciones, si el modelo tiene una capa de incrustaciones, + una para la salida de cada capa) de forma(batch_size, sequence_length, hidden_size).Estados ocultos del modelo en la salida de cada capa más las salidas opcionales de la incrustación inicial.
attentions (
tuple(torch.Tensor), opcional, se devuelve cuando se pasaoutput_attentions=Trueo cuandoconfig.output_attentions=True) — Tupla detorch.Tensor(una por cada capa) de forma(batch_size, num_heads, sequence_length, sequence_length).Pesos de atención tras el softmax de atención, utilizados para calcular la media ponderada en las cabezas de autoatención.
PixioBackbone
clase transformers.PixioBackbone
< source >( config: PixioConfig )
Parámetros
- config (PixioConfig) — Clase de configuración del modelo con todos los parámetros del modelo. Inicializar con un archivo de configuración no carga los pesos asociados con el modelo, solo la configuración. Consulte el método from_pretrained() para cargar los pesos del modelo.
Backbone de Pixio, para usar con frameworks como DETR y MaskFormer.
Este modelo hereda de PreTrainedModel. Consulta la documentación de la clase superior para los métodos genéricos que la biblioteca implementa para todos sus modelos (como la descarga o el guardado, el redimensionamiento de las incrustaciones de entrada, la poda de cabezas, etc.).
Este modelo también es una subclase de torch.nn.Module de PyTorch. Úsalo como un módulo de PyTorch regular y consulta la documentación de PyTorch para todo lo relacionado con el uso y el comportamiento generales.
forward
< source >( pixel_values: Tensorattention_mask: typing.Optional[torch.Tensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → BackboneOutput or tuple(torch.Tensor)
Parámetros
- pixel_values (
torch.Tensorde forma(batch_size, num_channels, image_size, image_size)) — Los tensores correspondientes a las imágenes de entrada. Los valores de píxeles se pueden obtener utilizando BitImageProcessor. Consulte BitImageProcessor.call() para más detalles (processor_classutiliza BitImageProcessor para procesar las imágenes). - attention_mask (
torch.Tensorde forma(batch_size, sequence_length), opcional) — Máscara para evitar realizar atención en los índices de tokens de relleno. Valores de máscara seleccionados en[0, 1]:- 1 para los tokens que no están enmascarados,
- 0 para los tokens que están enmascarados.
Devuelve
BackboneOutput o tuple(torch.Tensor)
Un BackboneOutput o una tupla de
torch.Tensor (si se pasa return_dict=False o cuando config.return_dict=False) que comprende varios
elementos según la configuración (PixioConfig) y las entradas.
El método forward de PixioBackbone sobrescribe el método especial __call__.
Aunque la receta para la pasada hacia adelante debe definirse dentro de esta función, se debe llamar a la instancia de
Moduledespués en lugar de a esta, ya que la primera se encarga de ejecutar los pasos de pre y postprocesamiento, mientras que la segunda los ignora silenciosamente.
feature_maps (
tuple(torch.Tensor)de forma(batch_size, num_channels, height, width)) — Mapas de características de las etapas.hidden_states (
tuple(torch.Tensor), opcional, devuelto cuando se pasaoutput_hidden_states=Trueo cuandoconfig.output_hidden_states=True) — Tupla detorch.Tensor(una para la salida de los embeddings + una para la salida de cada capa) de forma(batch_size, sequence_length, hidden_size)o(batch_size, num_channels, height, width), según el backbone.Estados ocultos del modelo en la salida de cada etapa más las salidas de la incrustación inicial.
attentions (
tuple(torch.Tensor), opcional, se devuelve cuando se pasaoutput_attentions=Trueo cuandoconfig.output_attentions=True) — Tupla detorch.Tensor(una por cada capa) de forma(batch_size, num_heads, sequence_length, sequence_length). Solo aplicable si el backbone usa atención.Pesos de atención tras el softmax de atención, utilizados para calcular la media ponderada en las cabezas de autoatención.
Ejemplos:
>>> from transformers import AutoImageProcessor, AutoBackbone
>>> import torch
>>> from PIL import Image
>>> from huggingface_hub.utils import httpx
>>> from io import BytesIO
>>> url = "http://images.cocodataset.org/val2017/000000039769.jpg"
>>> with httpx.stream("GET", url) as response:
... image = Image.open(BytesIO(response.read()))
>>> processor = AutoImageProcessor.from_pretrained("facebook/pixio-huge")
>>> model = AutoBackbone.from_pretrained(
... "facebook/pixio-huge", out_features=["stage7", "stage15", "stage23", "stage31"]
... )
>>> inputs = processor(image, return_tensors="pt")
>>> outputs = model(**inputs)
>>> feature_maps = outputs.feature_maps
>>> list(feature_maps[-1].shape)
[1, 1280, 16, 16]