Transformers documentation

Pixio

Transformers

Comece agora

Transformers Instalação Início rápido

Classes base

Modelos

Pré-processadores

Inferência

Pipeline API

API de geração

Otimização

Conversar com modelos

Serving

Treinamento

Comece agora

Personalização

Ajuste fino de parâmetros eficientes

Desempenho

Treinamento distribuído

Hardware

Quantização

Integrações com o ecossistema

Recursos

API

Principais classes

Modelos

Modelos de texto

Modelos de visão

Modelos de áudio

Modelos de vídeo

Modelos multimodais

Modelos de aprendizado por reforço

Modelos de séries temporais

Helpers internos

Referência

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.1).

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Este modelo foi contribuído para o Hugging Face Transformers em 2025-12-17. Este modelo será anunciado em breve

Pixio

Pixio é um modelo de fundação para visão computacional que utiliza ViT como extrator de características para diversas tarefas de nível inferior, como estimativa de profundidade, segmentação semântica, reconstrução 3D feed-forward, robótica e classificação de imagens. Ele é construído sobre o framework de pré-treinamento Masked Autoencoder (MAE), com quatro atualizações mínimas, porém críticas: 1) decodificador mais profundo, 2) granularidade de mascaramento maior, 3) mais tokens de classe e 4) dados de treinamento curados em escala web.

Você pode encontrar todos os checkpoints originais do Pixio na coleção Pixio.

O exemplo abaixo demonstra como obter um embedding de imagem com a classe 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 LayerNorm

Observações

O exemplo abaixo mostra como dividir o tensor de saída em:

um conjunto de embeddings globais para a imagem inteira, comumente referidos como token CLS, úteis para classificação e recuperação. Você pode fazer a média deles (recomendado) ou concatená-los ao longo da dimensão de canal.
um conjunto de embeddings locais, um para cada patch 16x16 da imagem de entrada, útil para tarefas densas, como estimativa de profundidade e segmentação 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))

Use torch.compile para acelerar a inferência.

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

classe 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, padrão 1280) — Dimensão das representações ocultas.
num_hidden_layers (int, opcional, padrão 32) — Número de camadas ocultas no decodificador do Transformer.
num_attention_heads (int, opcional, padrão 16) — Número de cabeças de atenção para cada camada de atenção no decodificador do Transformer.
mlp_ratio (int, opcional, padrão 4) — Proporção entre a dimensão oculta do MLP e a dimensão de incorporação.
hidden_act (str, opcional, padrão gelu) — A função de ativação não linear (função ou string) no decodificador. Por exemplo, "gelu", "relu", "silu", etc.
hidden_dropout_prob (Union[float, int], opcional, padrão 0.0) — A probabilidade de dropout para todas as camadas totalmente conectadas nos embeddings, no encoder e no pooler.
attention_probs_dropout_prob (Union[float, int], opcional, padrão 0.0) — A taxa de dropout para as probabilidades de atenção.
initializer_range (float, opcional, padrão 0.02) — O desvio padrão do truncated_normal_initializer para inicializar todas as matrizes de pesos.
layer_norm_eps (float, opcional, padrão 1e-06) — O epsilon usado pelas camadas de normalização de camada.
image_size (Union[int, list[int], tuple[int, int]], opcional, padrão 256) — O tamanho (resolução) de cada imagem.
patch_size (Union[int, list[int], tuple[int, int]], opcional, padrão 16) — O tamanho (resolução) de cada patch.
num_channels (int, opcional, padrão 3) — O número de canais de entrada.
qkv_bias (bool, opcional, padrão True) — Se deve adicionar um viés às queries, keys e values.
drop_path_rate (Union[float, int], opcional, padrão 0.0) — Taxa de drop path para a fusão de patches.
apply_layernorm (bool, opcional, padrão True) — Se a normalização de camada deve ser aplicada aos mapas de características caso o modelo seja usado como backbone.
reshape_hidden_states (bool, opcional, padrão True) — Indica se os mapas de características devem ser redimensionados para tensores 4D de forma (batch_size, hidden_size, height, width) caso o modelo seja usado como backbone. Se False, os mapas de características serão tensores 3D de forma (batch_size, seq_len, hidden_size).
n_cls_tokens (int, opcional, padrão 8) — Número de tokens de classe no codificador Transformer.

Esta é a classe de configuração para armazenar a configuração de um PixioModel. Ela é usada para instanciar um modelo Pixio de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do facebook/pixio-huge

Os objetos de configuração herdam de PreTrainedConfig e podem ser usados para controlar as saídas do modelo. Consulte a documentação de PreTrainedConfig para mais informações.

Exemplo:

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

PixioModel

classe transformers.PixioModel

< source >

( config: PixioConfig )

Parâmetros

config (PixioConfig) — Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método from_pretrained() para carregar os pesos do modelo.

O modelo Pixio puro, que produz estados ocultos brutos sem nenhum cabeçalho específico no topo.

Este modelo herda de PreTrainedModel. Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.)

Este modelo também é uma subclasse de torch.nn.Module do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso geral e ao comportamento.

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.Tensor de forma (batch_size, num_channels, image_size, image_size), opcional) — Os tensores correspondentes às imagens de entrada. Os valores de pixels podem ser obtidos usando BitImageProcessor. Consulte BitImageProcessor.call() para mais detalhes (processor_class usa BitImageProcessor para processar imagens).
attention_mask (torch.Tensor de forma (batch_size, sequence_length), opcional) — Máscara para evitar a execução de atenção nos índices de tokens de preenchimento. Valores de máscara selecionados em [0, 1]:
- 1 para tokens que não estão mascarados,
- 0 para tokens que estão mascarados.
O que são máscaras de atenção?

Retorna

BaseModelOutputWithPooling ou tuple(torch.Tensor)

Um BaseModelOutputWithPooling ou uma tupla de torch.Tensor (se return_dict=False for passado ou quando config.return_dict=False) contendo vários elementos, dependendo da configuração (PixioConfig) e das entradas.

O método forward do PixioModel substitui o método especial __call__.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de Module em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

last_hidden_state (torch.Tensor de forma (batch_size, sequence_length, hidden_size)) — Sequência de estados ocultos na saída da última camada do modelo.
pooler_output (torch.Tensor de forma (batch_size, hidden_size)) — Estado oculto da última camada do primeiro token da sequência (token de classificação) após processamento adicional através das camadas usadas para a tarefa de pré-treinamento auxiliar. Por exemplo, para a família de modelos BERT, isso retorna o token de classificação após o processamento através de uma camada linear e uma função de ativação tanh. Os pesos da camada linear são treinados a partir do objetivo de previsão da próxima frase (classificação) durante o pré-treinamento.
hidden_states (tuple(torch.Tensor), opcional, retornado quando output_hidden_states=True é passado ou quando config.output_hidden_states=True) — Tupla de torch.Tensor (um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um para a saída de cada camada) de forma (batch_size, sequence_length, hidden_size).

Estados ocultos do modelo na saída de cada camada, além das saídas opcionais do embedding inicial.
attentions (tuple(torch.Tensor), opcional, retornado quando output_attentions=True é passado ou quando config.output_attentions=True) — Tupla de torch.Tensor (um para cada camada) com forma (batch_size, num_heads, sequence_length, sequence_length).

Pesos de atenção após o softmax de atenção, usados para calcular a média ponderada nos cabeçalhos de autoatenção.

Exemplo:

PixioBackbone

classe transformers.PixioBackbone

< source >

( config: PixioConfig )

Parâmetros

config (PixioConfig) — Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método from_pretrained() para carregar os pesos do modelo.

Backbone Pixio, para ser usado com frameworks como DETR e MaskFormer.

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.Tensor de forma (batch_size, num_channels, image_size, image_size)) — Os tensores correspondentes às imagens de entrada. Os valores de pixels podem ser obtidos usando BitImageProcessor. Consulte BitImageProcessor.call() para mais detalhes (processor_class usa BitImageProcessor para processar imagens).
attention_mask (torch.Tensor de forma (batch_size, sequence_length), opcional) — Máscara para evitar a execução de atenção nos índices de tokens de preenchimento. Valores de máscara selecionados em [0, 1]:
- 1 para tokens que não estão mascarados,
- 0 para tokens que estão mascarados.
O que são máscaras de atenção?

Retorna

BackboneOutput ou tuple(torch.Tensor)

Um BackboneOutput ou uma tupla de torch.Tensor (se return_dict=False for passado ou quando config.return_dict=False) contendo vários elementos, dependendo da configuração (PixioConfig) e das entradas.

O método forward da PixioBackbone substitui o método especial __call__.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de Module em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

feature_maps (tuple(torch.Tensor) de forma (batch_size, num_channels, height, width)) — Mapas de características dos estágios.
hidden_states (tuple(torch.Tensor), opcional, retornado quando output_hidden_states=True é passado ou quando config.output_hidden_states=True) — Tupla de torch.Tensor (um para a saída dos embeddings + um para a saída de cada camada) de forma (batch_size, sequence_length, hidden_size) ou (batch_size, num_channels, height, width), dependendo do backbone.

Estados ocultos do modelo na saída de cada estágio, além das saídas do embedding inicial.
attentions (tuple(torch.Tensor), opcional, retornado quando output_attentions=True é passado ou quando config.output_attentions=True) — Tupla de torch.Tensor (um para cada camada) com forma (batch_size, num_heads, sequence_length, sequence_length). Aplicável apenas se o backbone usar atenção.

Pesos de atenção após o softmax de atenção, usados para calcular a média ponderada nos cabeçalhos de autoatenção.

Exemplos:

>>> 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]

Update on GitHub

←MobileViTV2 PoolFormer→